Sloppy Python project that can grab source tables from the internet, extract relationships between SSA Country Codes and ZIPs through intermediary relationship to FIPS county codes.
SSA County Codes are used in some CMS databases, like NCH Part A, rather than FIPS county codes. This is an attempt to create tables that show a mapping of USPS ZIP-5 Codes to SSA County Codes, along with other location information associated with ZIP Codes.
TODO: - project-ify it for pip. - convert to Poetry
Before running the Python, you need to download some input files from the internet.
Run the fetch_batch.bat
file if running from Windows.
If running from *nix, you will need to curl the three files by hand and unzip the one.
The first time you run the python -m ssacc.cli
, run with the -r 1
option to generate
data/source/zipcodes.csv
intermediate file. The goal is to create
data/ssa_cnty_zip.csv
which maps ZIP-5 to SSA Country Code, including the
3-digit county-only value and the 5-digit value that includes the state code.
If you want to iterate over the data without regenerating data/sources/zipcodes.csv
run with the -r 0
or no -r
command line argument.
The column headers are:
- zip - 5-digit ZIP code
- ssacnty - SSA 3-digit country code
- ssastco - SSA 5-digit county code, with 2-digit state code prepended
- countyname - Text name of the county, title case
- city - Text name of city, title case
- stabbr - Postal 2-character state code
- state - Text name of state, title case
Python 3.10+.
Developed on Windows 10, initially (Note the batch file). More recently with WSL. No longer tested on Windows.
Dependencies are defined in:
requirements.in
-- requirements for the applicationdev-requirements.in
-- requirements for developing the application
The Python packaging reads requirements.txt
and dev-requirements.txt
, which are generated by running
(venv) $ pip-compile requirements.in > requirements.txt
(venv) $ pip-compile dev-requirements.in > dev-requirements.txt
It is best practice during development to create an isolated
Python virtual environment using the
venv
standard library module. This will keep dependant Python packages from interfering
with other Python projects on your system. I let PyCharm magically take care of this.
To setup the virtual environment locally, as in the travis.yml
:
(venv) $ pip install --upgrade virtualenv
(venv) $ pip install nox
(venv) $ pip install codecov
(venv) $ pip install pytest
python3 -m venv env
source env/bin/activate
Automated testing is performed using nox. nox will automatically create virtual environments for unit testing, PEP8 style guide checking, and documentation generation.
To run all the tests:
(venv) $ nox
To Do: Add meaningful unit tests and refactor into more testable code.
Unit testing is performed with pytest. pytest has become the de facto Python unit testing framework.
pytest will automatically discover and run tests by recursively searching for folders and .py
files prefixed with test
for any functions prefixed by test
.
The tests
folder is created as a Python package (i.e. there is an __init__.py
file
within it) because this helps pytest
uniquely namespace the test files. Without this,
two test files cannot be named the same, even if they are in different sub-directories.
Code coverage is provided by the pytest-cov plugin.
Code coverage is configured in pyproject.toml
.
Use the IBM fork of detect-secrets. This will run in the pre-commit hooks. If secrets are detected in the scan, then you need to run an audit and correct findings or indicate false positives in the scan results. To audit:
(venv) $ detect-secrets audit .secrets.baseline
Code is automatically formatted using black. Imports are automatically sorted and grouped using isort.
These tools are configured by:
pyproject.toml
To automatically format code, run:
(venv) $ nox -s format
The project directory structure is like:
ssacnt ├── ssacnt │ ├── __init__.py │ ├── cli.py │ └── <lib>.py ├── tests │ ├── __init__.py | |── unit │ ├── __init__.py │ └── test_<lib>.py │── data │ ├── ssa_cnty_zip.csv <<-- This is the final output generated │ └── <ephemeral folders> ├── tox.ini └── setup.py
- ``` code-block::
- python3 -m ssacc.external.cli
Licensing for the project is defined in:
LICENSE.txt
setup.py
This project uses a common permissive license, the MIT license.
Thanks to Brian Gruber for the head start from https://github.com/bgruber/zip2fips, from which I shamelessly borrowed.