wojtek-uk-postcodes 0.1.1

UK Postcodes validator package - under `wojtek` namespace

wojtek-uk-postcodes

Small, typed utilities for working with UK postcodes. It ships with a strict parser that produces a structured UKPostcode value object and companion helpers for validation and formatting.

Features

• Parse raw strings into a frozen UKPostcode with outward/inward, area, district, sector, and unit parts.
• Validate standard postcodes and optional special cases such as BFPO, GIR, Overseas Territories, and Santa codes.
• Produce formatted strings with FormatStyle or JSON-ready dictionaries via to_dict().
• Pure Python, zero external runtime dependencies, requires Python 3.10+.

Validation scope and limitations

Validation checks only that inputs match UK postcode formats using regular-expression patterns (including known special-case rules). It does not verify whether a postcode actually exists, is allocated, is currently valid, or is deliverable.

Installation

Install the package from PyPI:

pip install wojtek-uk-postcodes

Quick start

from wojtek.uk_postcodes import FormatStyle, parse_postcode, is_valid_postcode

postcode = parse_postcode("SW1A 1AA")
print(postcode.outward)          # 'SW1A'
print(postcode.format())         # 'SW1A 1AA'
print(postcode.format(FormatStyle.NO_SPACES))  # 'SW1A1AA'

is_valid_postcode("GIR 0AA", allow_special=True)  # True
postcode.to_dict()

Development

• Run the test suite: uv run pytest or make test (which also reports coverage).
• Type-check and lint: make mypy and make format.