ssacc - Map SSA County Codes and ZIP codes (ZIP-5)

We are archiving this repository. Feel free to fork and bring it back to life.

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

Requirements

Python 3.10+.

Windows Support

Developed on Windows 10, initially (Note the batch file). More recently with WSL. No longer tested on Windows.

Dependencies

Dependencies are defined in:

• requirements.in -- requirements for the application
• dev-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

Virtual Environments

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

Testing

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

Unit Testing

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.

Secret Scanning

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

Automated Code Formatting

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

Project Structure

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

Operation

``` code-block::

python3 -m ssacc.external.cli

```

Licensing

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.