us

library3.2.0pypypi✓ verified 28d ago

The 'us' library provides an easy way to work with US state and territory meta information, offering data such as names, abbreviations, FIPS codes, and contiguous status. It also includes functions for looking up states by various criteria. The current version is 3.2.0, and it generally follows an active release cadence, with updates for Python version compatibility and dependency upgrades.

data

pip install us

github ↗package ↗

INSTALL

IMPORT

SIG · US

datapythonv3.2.0

Install

1.7s avg

Import

27ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.028s · 19.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.026s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import us

Imports the main 'us' module, providing access to submodules like `us.states` and `us.territories`.

states

✓ import us.states

Directly imports the `states` submodule for state-specific operations.

territories

✓ import us.territories

Directly imports the `territories` submodule for territory-specific operations.

The quickstart demonstrates how to import the `us` library and access state and territory objects. It shows direct access by abbreviation, lookup by name, fuzzy matching, and accessing lists of all entities. It also includes accessing the `unitedstatesofamerica` object and its new `birthday` attribute.

import us # Access state objects directly california = us.states.CA print(f"California FIPS: {california.fips}") # Look up states by name, abbreviation, or FIPS code new_york = us.states.lookup('New York') print(f"New York abbr: {new_york.abbr}") # Fuzzy matching (requires 'jellyfish' library) matched_states = us.states.match('Kanzus') if matched_states: print(f"Did you mean: {matched_states.name} ({matched_states.abbr})?") # Access a list of all states and territories print(f"Total states and territories: {len(us.states.all) + len(us.territories.all)}") # Access special objects like 'unitedstatesofamerica' usa = us.unitedstatesofamerica print(f"USA name: {usa.name}, Birthday: {usa.birthday}")

Debug

Known issues

breakingPython 3.6 and 3.7 support has been officially dropped starting with 'us' version 3.2.0. Projects using these older Python versions must upgrade their Python interpreter or pin 'us' to a version prior to 3.2.0.

fix

Upgrade your Python environment to 3.8 or newer. If unable to upgrade Python, pin 'us' to '<3.2.0' in your project's dependencies (e.g., `us<3.2.0`).

affects: >=3.2.0

breakingThe `jellyfish` dependency, used for fuzzy matching in functions like `us.states.match()`, was upgraded to `jellyfish` 1.x in 'us' version 3.2.0. If your project has a direct dependency on an older `jellyfish` version, this upgrade might introduce conflicts or require adjustments.

fix

Ensure your project's `jellyfish` dependency is compatible with `jellyfish` 1.x. Review `jellyfish`'s changelog for any breaking changes if you directly use `jellyfish` functions.

affects: >=3.2.0

gotchaFunctions like `us.states.match()` return a list of potentially matching state objects, even if only one match is found. Always account for this when processing the results, as direct access (e.g., `[0]`) might lead to `IndexError` if no matches are found.

fix

Always check if the returned list from `match()` or similar functions is not empty before accessing elements (e.g., `if matched_states: state = matched_states[0]`).

affects: All

gotchaThe `us.states.lookup()` function is more strict and returns `None` if no exact match is found (after an optional fuzzy search). Always check for `None` before accessing attributes of the returned object.

fix

When using `us.states.lookup()`, always perform a `None` check (e.g., `state = us.states.lookup('NotAState'); if state: print(state.name)`).

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'us'

The 'us' package is not installed in the current Python environment or there is a typo in the import statement.

fix

Run `pip install us` to install the library, then ensure your import statement is `import us`.

AttributeError: module 'us' has no attribute 'lookup'

The `lookup` method for states is part of the `us.states` collection, not directly on the top-level `us` module.

fix

Access the `lookup` method through the `states` attribute, for example: `us.states.lookup('Maryland')`.

TypeError: 'StateCollection' object is not subscriptable

The `us.states` object is a custom collection and does not support dictionary-style item access using square brackets (`[]`).

fix

Access state objects by their attributes (e.g., `us.states.MD`) or use the `lookup` method (e.g., `us.states.lookup('Maryland')`).

AttributeError: 'NoneType' object has no attribute 'name'

The `us.states.lookup()` method returned `None` because no matching state was found, and you attempted to access an attribute on this `None` object.

fix

Always check if the result of `us.states.lookup()` is not `None` before attempting to access its attributes, for example: `state = us.states.lookup('Invalid'); if state: print(state.name)`.

Upgrade

Version history

3.2.0latest on PyPI · released Jul 22, 2024

Audit

Dependencies

pythonrequiredRequires Python 3.8 or newer.

jellyfishrequiredUsed for fuzzy string matching in lookup/match functions. Upgraded to 1.x in v3.2.0.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/unitedstates/python-us ↗

packagehttps://pypi.org/project/us/ ↗