### Run Project Tests

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Instructions for installing the development dependencies and executing the test suite using pytest to ensure project integrity.

```bash
pip install -e .[dev]
pytest .
```

--------------------------------

### Install the 'us' Python Package

Source: https://github.com/unitedstates/python-us/blob/main/README.md

This snippet shows the command to install the 'us' Python package using pip. It's a straightforward installation process.

```bash
pip install us
```

--------------------------------

### Get US State Shapefile URLs

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Demonstrates how to obtain a dictionary of shapefile URLs for a specific state using the `shapefile_urls()` method. The URLs are for 2010 Census Tiger/Line shapefiles and cover various geographic granularities.

```python
>>> 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'
```

--------------------------------

### Create Mappings Between State Attributes

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Shows how to use the `mapping()` method to generate dictionaries that map one state attribute to another (e.g., FIPS code to abbreviation, or abbreviation to name). This is useful for data transformation and lookups.

```python
>>> 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', ...
>>> us.states.mapping('fips', 'abbr', states=[us.states.DC])
{'11': 'DC'}
```

--------------------------------

### Use the 'states' Command Line Interface

Source: https://context7.com/unitedstates/python-us/llms.txt

The package provides a `states` CLI command for quick state lookups directly from the terminal. It supports lookups by abbreviation, FIPS code, or name (with phonetic matching).

```bash
# Lookup by abbreviation
$ 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.zip

# Lookup by FIPS code
$ states 06
*** The great state of California (CA) ***
...

# Lookup by name (with phonetic matching)
$ states california
*** The great state of California (CA) ***
...
```

--------------------------------

### Lookup Territories in Python

Source: https://context7.com/unitedstates/python-us/llms.txt

Demonstrates how to look up territories using the 'us' package. It takes an abbreviation and returns the full territory name.

```python
import us

# Lookup a territory by abbreviation
territory = us.lookup('PR')

# Print the full name of the territory
if territory:
    print(f"*** The great territory of {territory.name} ({territory.abbr}) ***")
else:
    print("Territory not found.")
```

--------------------------------

### List All US States and Territories

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Shows how to retrieve lists of all US states, territories, and a combined list of both using the 'us' package. These lists are useful for iterating or displaying all available regions.

```python
>>> us.states.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...
>>> us.states.TERRITORIES
[<State:American Samoa>, <State:Guam>, <State:Northern Mariana Islands>, ...
>>> us.states.STATES_AND_TERRITORIES
[<State:Alabama>, <State:Alaska>, <State:American Samoa>, ...
>>> us.STATES
[<State:Alabama>, <State:Alaska>, <State:Arizona>, <State:Arkansas>, ...
>>> us.states.COMMONWEALTHS
[<State:Kentucky>, <State:Massachusetts>, <State:Pennsylvania>, <State:Virginia>]
>>> us.states.OBSOLETE
[<State:Dakota>, <State:Orleans>, <State:Philippine Islands>]
```

--------------------------------

### Enable DC Statehood Inclusion

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Explains how to include Washington D.C. in state lists and mappings by setting the `DC_STATEHOOD` environment variable to a truthy value before importing the 'us' package. This is a configuration step for specific use cases.

```bash
DC_STATEHOOD=1
```

--------------------------------

### Access state and territory collections

Source: https://context7.com/unitedstates/python-us/llms.txt

Demonstrates how to access pre-defined lists of states and territories for iteration, validation, and filtering. Includes groupings like contiguous, continental, and historical territories.

```python
import us

# All 50 states
print(len(us.STATES))

# All US territories
print(len(us.TERRITORIES))

# States and territories combined
print(len(us.STATES_AND_TERRITORIES))

# Contiguous states
print(len(us.STATES_CONTIGUOUS))

# Continental states
print(len(us.STATES_CONTINENTAL))

# Iterate over all states
for state in us.STATES:
    if state.statehood_year and state.statehood_year < 1800:
        print(f"{state.name}: {state.statehood_year}")
```

--------------------------------

### Access US State Information with 'us' Package

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Demonstrates how to import the 'us' package and access various attributes of US states, such as FIPS codes, names, and contiguity. It also shows how to access territories.

```python
>>> import us
>>> us.states.MD
<State:Maryland>
>>> us.states.MD.fips
'24'
>>> us.states.MD.name
'Maryland'
>>> us.states.MD.is_contiguous
True
>>> us.states.VI.name
'Virgin Islands'
>>> us.states.VI.is_territory
True
>>> us.states.MD.is_territory
False
```

--------------------------------

### Access US state objects and metadata

Source: https://context7.com/unitedstates/python-us/llms.txt

Demonstrates how to access individual state objects using postal abbreviations as attributes. Each object provides detailed metadata such as FIPS codes, capitals, and time zones.

```python
import us

# Access a state by abbreviation
state = us.states.MD
print(state)
print(state.name)
print(state.abbr)
print(state.fips)
print(state.capital)
print(state.capital_tz)
print(state.statehood_year)
print(state.time_zones)
print(state.ap_abbr)
print(state.is_territory)
print(state.is_contiguous)
print(state.is_continental)

# Access territories the same way
territory = us.states.PR
print(territory.name)
print(territory.is_territory)
print(territory.capital)
```

--------------------------------

### Access State Information via CLI

Source: https://github.com/unitedstates/python-us/blob/main/README.md

The states script allows users to quickly retrieve detailed information about a specific US state by providing its abbreviation. It outputs attributes like FIPS codes, capital cities, time zones, and relevant shapefile URLs.

```bash
$ states md
```

--------------------------------

### Enable DC Statehood Support with Environment Variable

Source: https://context7.com/unitedstates/python-us/llms.txt

Washington, DC can be automatically included in state lists by setting the `DC_STATEHOOD` environment variable to '1' before importing the package. This is useful for applications that treat DC as a state.

```python
import os
os.environ['DC_STATEHOOD'] = '1'

import us

# DC is now included in state lists
print(us.states.DC in us.STATES)  # Output: True
print(us.states.DC in us.STATES_AND_TERRITORIES)  # Output: True
print(us.states.DC in us.STATES_CONTIGUOUS)  # Output: True
print(us.states.DC in us.STATES_CONTINENTAL)  # Output: True

# Without DC_STATEHOOD set (default behavior)
# us.states.DC in us.STATES  # Output: False
```

--------------------------------

### Lookup US States by Various Identifiers

Source: https://github.com/unitedstates/python-us/blob/main/README.md

Illustrates the state lookup functionality in the 'us' package, which allows finding a state object using its FIPS code, postal abbreviation, or name (case-insensitive). It also includes phonetic matching for misspelled names.

```python
>>> us.states.lookup('24')
<State:Maryland>
>>> us.states.lookup('MD')
<State:Maryland>
>>> us.states.lookup('md')
<State:Maryland>
>>> us.states.lookup('maryland')
<State:Maryland>
>>> state = us.states.lookup('maryland')
>>> state.abbr
'MD'
>>> us.states.lookup('misisipi')
<State:Mississippi>
```

--------------------------------

### Create State Mappings with Python

Source: https://context7.com/unitedstates/python-us/llms.txt

The `mapping()` function generates dictionaries to map one state attribute to another, useful for lookups and data transformations. It supports various attributes like FIPS codes, abbreviations, names, and capitals. Obsolete states are excluded by default.

```python
import us

# Map FIPS codes to abbreviations
fips_to_abbr = us.states.mapping('fips', 'abbr')
print(fips_to_abbr['24'])  # Output: MD
print(fips_to_abbr['06'])  # Output: CA
print(fips_to_abbr['48'])  # Output: TX

# Map abbreviations to full names
abbr_to_name = us.states.mapping('abbr', 'name')
print(abbr_to_name['MD'])  # Output: Maryland
print(abbr_to_name['CA'])  # Output: California

# Map names to FIPS codes
name_to_fips = us.states.mapping('name', 'fips')
print(name_to_fips['Texas'])  # Output: 48

# Custom mapping with specific states
dc_md_mapping = us.states.mapping('fips', 'abbr', states=[us.states.DC, us.states.MD])
print(dc_md_mapping)  # Output: {'11': 'DC', '24': 'MD'}

# Map to capitals
abbr_to_capital = us.states.mapping('abbr', 'capital')
print(abbr_to_capital['CA'])  # Output: Sacramento
print(abbr_to_capital['NY'])  # Output: Albany

# Obsolete states are excluded from default mappings
mapping = us.states.mapping('abbr', 'fips')
print('DK' in mapping)  # Output: False (Dakota is obsolete)
```

--------------------------------

### Lookup states by identifier or phonetic name

Source: https://context7.com/unitedstates/python-us/llms.txt

Uses the lookup() function to retrieve state objects via FIPS codes, abbreviations, or names. It supports case-insensitive matching and fuzzy phonetic matching via the Metaphone algorithm.

```python
import us

# Lookup by FIPS code
state = us.states.lookup('24')
print(state.name)

# Lookup by abbreviation (case-insensitive)
state = us.states.lookup('MD')
print(state.name)

# Lookup by name (case-insensitive)
state = us.states.lookup('maryland')
print(state.name)

# Phonetic matching for misspelled names
state = us.states.lookup('misisipi')
print(state.name)

# Exact field matching (case-sensitive)
state = us.states.lookup('Maryland', field='name')
print(state.name)

# Handle non-existent states
state = us.states.lookup('XX')
print(state)
```

--------------------------------

### Access USA Module Constants in Python

Source: https://context7.com/unitedstates/python-us/llms.txt

Shows how to access constants related to the United States from the 'us' module. This includes the country name, abbreviation, and independence day.

```python
import us

# Country name and abbreviation
print(us.name)  # Output: United States of America
print(us.abbr)  # Output: US

# Independence Day
print(us.birthday)  # Output: 1776-07-04
print(type(us.birthday))  # Output: <class 'datetime.date'>
```

--------------------------------

### Access US State Shapefile URLs with Python

Source: https://context7.com/unitedstates/python-us/llms.txt

Each state object provides URLs to US Census Bureau TIGER/Line shapefiles for various geographic regions, including blocks, block groups, census tracts, and counties. These URLs point to 2010 Census shapefiles.

```python
import us
import requests

# Get all shapefile URLs for a state
urls = us.states.MD.shapefile_urls()
print(sorted(urls.keys()))
# Output: ['block', 'blockgroup', 'cd', 'county', 'state', 'tract', 'zcta']

# Access specific shapefile URLs
print(urls['state'])
# Output: https://www2.census.gov/geo/tiger/TIGER2010/STATE/2010/tl_2010_24_state10.zip

print(urls['county'])
# Output: https://www2.census.gov/geo/tiger/TIGER2010/COUNTY/2010/tl_2010_24_county10.zip

print(urls['tract'])
# Output: https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_24_tract10.zip

print(urls['cd'])  # Congressional districts
# Output: https://www2.census.gov/geo/tiger/TIGER2010/CD/111/tl_2010_24_cd111.zip

print(urls['block'])
# Output: https://www2.census.gov/geo/tiger/TIGER2010/TABBLOCK/2010/tl_2010_24_tabblock10.zip

print(urls['blockgroup'])
# Output: https://www2.census.gov/geo/tiger/TIGER2010/BG/2010/tl_2010_24_bg10.zip

print(urls['zcta'])  # ZIP Code Tabulation Areas
# Output: https://www2.census.gov/geo/tiger/TIGER2010/ZCTA5/2010/tl_2010_24_zcta510.zip

# Download shapefiles programmatically
state = us.states.CA
shapefile_url = state.shapefile_urls()['county']
# response = requests.get(shapefile_url)
# with open('ca_counties.zip', 'wb') as f:
#     f.write(response.content)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.