{"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":"python","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,"search_vec":"'3.2.0':47 'abbrevi':26 'activ':53 'also':33 'cadenc':55 'code':28 'compat':61 'contigu':30 'criteria':42 'current':44 'data':22,68 'depend':63 'easi':10 'fip':27 'follow':51 'function':35 'general':50 'geographi':67 'govern':71 'includ':34 'inform':4,20 'librari':7 'look':37 'meta':3,19 'metadata':69 'name':25 'offer':21 'provid':8 'python':59 'releas':54 'state':2,16,39,66 'status':31 'territori':18 'updat':57 'upgrad':64 'us':1,6,15,65 'util':70 'various':41 'version':45,60 'way':11 'work':13","created_at":"2026-04-11T01:44:57.447174+00:00","updated_at":"2026-04-17T00:01:31.084125+00:00","problems":[{"fix":"Run `pip install us` to install the library, then ensure your import statement is `import us`.","cause":"The 'us' package is not installed in the current Python environment or there is a typo in the import statement.","error":"ModuleNotFoundError: No module named 'us'"},{"fix":"Access the `lookup` method through the `states` attribute, for example: `us.states.lookup('Maryland')`.","cause":"The `lookup` method for states is part of the `us.states` collection, not directly on the top-level `us` module.","error":"AttributeError: module 'us' has no attribute 'lookup'"},{"fix":"Access state objects by their attributes (e.g., `us.states.MD`) or use the `lookup` method (e.g., `us.states.lookup('Maryland')`).","cause":"The `us.states` object is a custom collection and does not support dictionary-style item access using square brackets (`[]`).","error":"TypeError: 'StateCollection' object is not subscriptable"},{"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)`.","cause":"The `us.states.lookup()` method returned `None` because no matching state was found, and you attempted to access an attribute on this `None` object.","error":"AttributeError: 'NoneType' object has no attribute 'name'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/unitedstates/python-us","docs":null,"changelog":null,"pypi":"https://pypi.org/project/us/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}