{"id":2839,"library":"us","title":"US State Meta Information","description":"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.","status":"active","version":"3.2.0","language":"en","source_language":"en","source_url":"https://github.com/unitedstates/python-us/","tags":["US states","geography","data","metadata","utility","government"],"install":[{"cmd":"pip install us","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.8 or newer.","package":"python","optional":false},{"reason":"Used for fuzzy string matching in lookup/match functions. Upgraded to 1.x in v3.2.0.","package":"jellyfish","optional":false}],"imports":[{"note":"Imports the main 'us' module, providing access to submodules like `us.states` and `us.territories`.","symbol":"us","correct":"import us"},{"note":"Directly imports the `states` submodule for state-specific operations.","symbol":"states","correct":"import us.states"},{"note":"Directly imports the `territories` submodule for territory-specific operations.","symbol":"territories","correct":"import us.territories"}],"quickstart":{"code":"import us\n\n# Access state objects directly\ncalifornia = us.states.CA\nprint(f\"California FIPS: {california.fips}\")\n\n# Look up states by name, abbreviation, or FIPS code\nnew_york = us.states.lookup('New York')\nprint(f\"New York abbr: {new_york.abbr}\")\n\n# Fuzzy matching (requires 'jellyfish' library)\nmatched_states = us.states.match('Kanzus')\nif matched_states:\n    print(f\"Did you mean: {matched_states.name} ({matched_states.abbr})?\")\n\n# Access a list of all states and territories\nprint(f\"Total states and territories: {len(us.states.all) + len(us.territories.all)}\")\n\n# Access special objects like 'unitedstatesofamerica'\nusa = us.unitedstatesofamerica\nprint(f\"USA name: {usa.name}, Birthday: {usa.birthday}\")","lang":"python","description":"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."},"warnings":[{"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`).","message":"Python 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.","severity":"breaking","affected_versions":">=3.2.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=3.2.0"},{"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]`).","message":"Functions 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.","severity":"gotcha","affected_versions":"All"},{"fix":"When using `us.states.lookup()`, always perform a `None` check (e.g., `state = us.states.lookup('NotAState'); if state: print(state.name)`).","message":"The `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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}