Package: us
US: The Greatest Package in the WorldA package for easily working with US and state metadata.all US states and territoriespostal abbreviationsAssociated Press style abbreviationsFIPS codescapitalsyears of statehoodtime zonesphonetic state name lookupis contiguous or continentalURLs to shapefiles for state, census, congressional districts,
counties, and census tractsInstallationAs per usual:pip install usFeaturesEasy access to state information:>>> import us
>>> us.states.MD
<State:Maryland>
>>> us.states.MD.fips
'24'
>>> us.states.MD.name
'Maryland'
>>> us.states.MD.is_contiguous
TrueIncludes territories too:>>> us.states.VI.name
'Virgin Islands'
>>> us.states.VI.is_territory
True
>>> us.states.MD.is_territory
FalseList of all (actual) states:>>> us.states.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...
>>> us.states.TERRITORIES
[<State:American Samoa>, <State:Guam>, <State:Northern Mariana Islands>, ...And the whole shebang, if you want it:>>> us.states.STATES_AND_TERRITORIES
[<State:Alabama>, <State:Alaska>, <State:American Samoa>, ...For convenience,STATES,TERRITORIES, andSTATES_AND_TERRITORIEScan be
accessed directly from theusmodule:>>> us.states.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...
>>> us.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...Some states like to be fancy and call themselves commonwealths:>>> us.states.COMMONWEALTHS
[<State:Kentucky>, <State:Massachusetts>, <State:Pennsylvania>, <State:Virginia>]There’s also a list of obsolete territories:>>> us.states.OBSOLETE
[<State:Dakota>, <State:Orleans>, <State:Philippine Islands>]The state lookup method allows matching by FIPS code, abbreviation, and name:>>> us.states.lookup('24')
<State:Maryland>
>>> us.states.lookup('MD')
<State:Maryland>
>>> us.states.lookup('md')
<State:Maryland>
>>> us.states.lookup('maryland')
<State:Maryland>Get useful information:>>> state = us.states.lookup('maryland')
>>> state.abbr
'MD'And for those days that you just can’t remember how to spell Mississippi,
we’ve got phonetic name matching too:>>> us.states.lookup('misisipi')
<State:Mississippi>ShapefilesYou want shapefiles too? As long as you want 2010 shapefiles, we’ve gotcha covered.>>> urls = us.states.MD.shapefile_urls()
>>> sorted(urls.keys())
['block', 'blockgroup', 'cd', 'county', 'state', 'tract', 'zcta']
>>> urls['block']
'https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip'Theshapefile_urls()method on the State object generates shapefile URLs for
the following regions:blockblockgroupcensus tract (tract)congressional district (cd)countystatezctaMappingsMappings between various state attributes are a common need. Themapping()method will generate a lookup between two specified fields.>>> us.states.mapping('fips', 'abbr')
{'01': 'AL', '02': 'AK', '04': 'AZ', '05': 'AR', '06': 'CA', ...
>>> us.states.mapping('abbr', 'name')
{'AL': 'Alabama', 'AK': 'Alaska', 'AZ': 'Arizona', 'AR': 'Arkansas', ...This method usesus.STATES_AND_TERRITORIESas the default list of states
it will create a mapping for, but this can be overridden by passing an
additional states argument:>>> us.states.mapping('fips', 'abbr', states=[us.states.DC])
{'11': 'DC'}DC should be granted statehoodWashington, DC does not appear inus.STATESor any of the
related state lists, but is often treated as a state in practice and
should be granted statehood anyway. DC can be automatically included in these
lists by setting aDC_STATEHOODenvironment variable to any truthy value
before importing this package.DC_STATEHOOD=1CLIWhen you need to know state information RIGHT AWAY, there’s thestatesscript.$ states md

*** The great state of Maryland (MD) ***

  FIPS code: 24

  other attributes:
    ap_abbr: Md.
    capital: Annapolis
    capital_tz: America/New_York
    is_contiguous: True
    is_continental: True
    is_obsolete: False
    name_metaphone: MRLNT
    statehood_year: 1788
    time_zones: America/New_York

  shapefiles:
    tract: https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip
    cd: https://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip
    county: https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip
    state: https://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip
    zcta: https://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip
    block: https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip
    blockgroup: https://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_24_bg10.zipRunning TestsGitHub Actions are set up to automatically run unit tests against any new
commits to the repo. To run these tests yourself:pipenv install --dev
pipenv run pytestChangelog3.1.1add support for Python 3.11upgrade to jellyfish 0.11.23.0.0upgrade to jellyfish 0.7.2drop support for Python 2.7add us.states.COMMONWEALTHS list of states that call themselves commonwealths 🎩add DC to STATES, STATES_AND_TERRITORIES, STATES_CONTIGUOUS, or STATES_CONTINENTAL when DC_STATEHOOD environment variable is setremoveregionparameter fromshapefile_urls()methodmapping()no longer includes obsolete statesadded type annotations2.0.2restore DC in lookup() and mapping()2.0.1fix Python 2.7 tests that ran with Python 3revert to jellyfish 0.6.1 to support Python 2.72.0.0add support for Python 3.7 and 3.8remove support for Python 3.4 and 3.5remove pickled objects and database in favor of pure Python codeupgrade jellyfish to 0.7.2 to fix metaphone bugfixes for IN, KY, ND, and NM timezonesset AZ timezone to America/Phoenixobsolete entries are no longer included in STATES_AND_TERRITORIESDC is no longer included in STATES, STATES_AND_TERRITORIES, STATES_CONTIGUOUS, or STATES_CONTINENTAL1.0.0full Python 3.6 supportuse pytest0.10.0upgrade jellyfish to 0.5.3 to fix metaphone bug0.9.0add information on whether a state is contiguous and/or continental,
thanks tochebee7i0.8.0add obsolete territories, thanks toBen Chartofffix packaging error, thanks toAlexander Kulakov0.7.1upgrade to jellyfish 0.5.1 to fix metaphone case bug0.7add time zones, thanks toPaul TagliamontePython 2.6 and 3.2 compatibility0.6add AP-style state abbreviationsuse jellyfish instead of Metaphone packageupdate to requests v1.0.4 for testsPython 3.3 compatibility0.5fix state abbreviation for Nebraska0.4add state capitalsadd years of statehood0.3add mapping method to generate dicts of arbitrary fields0.2add command line script for quick access to state data0.1initial releasestate names and abbreviationsFIPS codeslookup() methodshapefile URLs for various regions