1. Install uv (a Python package and project manager), following the instructions outlined on their website.

2. Ensure you have Python 3.14 installed. If you don't already have a means of managing Python versions, this can be accomplished directly with uv:

   uv python install 3.14

1. Install all project dependencies, as outlined in pyproject.toml:

   uv sync --frozen

2. (Optional) Create a .env file from the sample.env, if you'd like to configure the application's port or host during local development (particularly helpful if you're running outside of Docker). NOTE: You'll need to manually load the env (export $(xargs <.env)), add --env-file .env to uv commands, or install and configure direnv (or an equivalent shell extension) in order to make these environment variables available to the application.

   cp sample.env .env

3. Have the NBS MSSQL database running and make sure the env vars in this workspace are correct for that DB (sample.env values should match). Using the cdc-sandbox docker compose is a good/opinionated way to do this

   # from a dedicated terminal at the repo root
   cd cdc-sandbox
   # create .env if it doesn't exist
   ./check_env.sh
   # run the database
   docker compose up nbs-mssql

4. Start the FastAPI development server with Uvicorn (the default ASGI server program shipped with FastAPI):

   uv run uvicorn src.main:app

The application will be available at:

• API: http://localhost:8001
• Interactive API docs (Swagger UI): http://localhost:8001/docs
• Alternative API docs (ReDoc): http://localhost:8001/redoc

Sample curl:

curl -X POST 'http://localhost:8001/report/execute' -H "accept: application/json" -H "Content-Type: application/json" -d '{
            "version": 1,
            "is_export": true,
            "is_builtin": true,
            "report_title": "Test Report",
            "library_name": "nbs_custom",
            "data_source_name": "random_db_table_0",
            "subset_query": "SELECT * FROM test"
}'

Unit testing for this project is currently handled with pytest. To invoke the unit test suite, simply run the following:

uv run pytest -m "not integration"

Or something similar to the following, if you're looking to run a specific test suite:

uv run pytest src/main_test.py

To run integration tests, ensure the .env is loaded or passed to uv, ensure host networking mode in docker is enabled, and run

uv run pytest # all tests
uv run pytest -m integration # just integration tests
uv run --env-file .env pytest # pass env file to uv

A pair of scripts are available to load the data used in integration testing to a DB. This can be useful for debugging SQL, exploration, or comparison testing new and old libraries against the same data.

The DATABASE_CONN_STRING environment variable is used to connect to the database (already running) where you want to load the fake data and must be set when running the script (or in an env file and the --env-file uv functionality used).

Example:

# load data
uv run ./scripts/load_fake_data.py phc_demographic.yaml
# restore data
uv run ./scripts/restore_original_data.py phc_demographic.yaml

As part of the testing we need to be comparing the output of the SAS version of the script and the Python library version. While using the standard diff is perfectly reasonable in most cases there is also a script which will compare the unique lines in each CSV against one another, confirming that all of the contents found in one are found in the other.

This is especially useful when the explicit ordering from the SAS output can't be guaranteed in the Python library. In cases like this it's crucial that we ensure that the data in each file are identical regardless of ordering.

Example:

# qa06_sas.csv is the SAS output, qa06_py.csv is the Python library output
uv run ./scripts/uniq_line_csvs.py qa06_sas.csv qa06_py.csv

This script will list each unique line in each file that differs from the other and no lines at all when the contents are identical in both.

Additionally, this project uses Ruff (also created by Astral, the makers of uv) for linting and formatting and Pyrefly for type checking.

In order to check for existing linter issues, run:

uv run ruff check

To automatically address any auto-fixable linter issues, run:

uv run ruff check --fix

Run the formatter with the following:

uv run ruff format

Run the type checker with the following:

uv run pyrefly check

The NEDSS Custom Library Example repository has been created as documentation for STLTs who want to create custom Python libraries. It includes library examples, instructions on how to install new libraries, and how to use the new libraries in reports.

• FastAPI Documentation
• uv Documentation
• pytest Documentation