# 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:

```bash
pip install wojtek-uk-postcodes
```

## Quick start
```python
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`.
