Dsposal - Digital Waste Tracking helper scripts

Lightweight helpers used by Dsposal to validate and surface licence/permit reference formats (primarily to assist discussion with DEFRA's Waste Tracking Service: https://github.com/DEFRA/waste-tracking-service).

What this repository contains

• permits.py - the core permit/license pattern matcher (public API match_permit(permit: str) -> list[str]).
• registration_numbers.py - carrier & broker/dealer registration number pattern matcher for multiple nation formats (public API match_registration(registration: str) -> list[str]).
• main.py - small CLI wrapper that demonstrates match_permit and can validate files of permits or write results to JSON.
• data.txt, data.json - example input files used by main.py.
• tests/ - unit tests (use pytest).

Quickstart

1. Create and activate a virtual environment (recommended):

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate   # Windows

2. Install minimal tooling (optional but recommended for development):

python -m pip install --upgrade pip
python -m pip install ruff pytest mypy

3. Run the example script:

python main.py

4. Match a single permit or registration number from the CLI:

# For permits
python main.py --permit "EPR/AB1234CD"

# For registration numbers
python main.py --registration "CBDU123456"

# To check all permits/registrations in a file
python main.py --file data.txt
python main.py --file data.json

# To output results to a file
python main.py --file data.txt --output example_output.json
python main.py --file data.txt --output example_output.txt

Testing

• Run the full test suite with pytest: pytest -q.
• Run a single test with pytest (example): pytest tests/test_permits.py::TestPermitMatching::test_epa_permits -q.

Style & development notes

• permits.py and registration_numbers.py store compiled regular expressions under the _PATTERNS constant. Keep those patterns readable and add unit tests when modifying or extending them.
• Public functions should be typed. Prefer clarity over clever regexes; add short docstrings for public functions.

Reporting mismatches to DEFRA

1. Collect representative example strings which do not match any pattern in _PATTERNS.
2. For each example include the raw input and which documented format you expected (if any) with a short rationale.
3. Add examples to the relevant discussion on the Waste Tracking Service repo (DEFRA/waste-tracking-service#80 or DEFRA/waste-tracking-service#84).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

• Keep changes small and well-tested. If a change alters pattern behaviour include tests that demonstrate the old vs new behaviour and the reason for the change.
• Run python -m ruff check . and python -m mypy . to lint and type-check code before committing to keep a consistent style.

Contact

For repository-specific questions reach out to Dsposal or open an issue/discussion in this repository. If you have questions about waste tracking more generally, create a new discussion on DEFRA's Waste Tracking Service repository: https://github.com/DEFRA/waste-tracking-service/discussions/