Metadata-Version: 2.4
Name: wojtek-uk-postcodes
Version: 0.1.1
Summary: UK Postcodes validator package - under `wojtek` namespace
License-File: LICENSE.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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`.
