Postal

Sri Lankan postal codes are five digits, with each code mapping to a specific post office, district, and province.

Planned

Postal-code validation has not been implemented yet. The result shape and public API are settled — calling validate_postal today raises NotImplementedError, but the planned API below is what will land. Track progress on GitHub.

Planned API

from helakit import validate_postal, is_valid_postal

result = validate_postal("10100")

result.is_valid       # True
result.normalized     # "10100"
result.district       # "Colombo"
result.province       # "Western"
result.post_office    # "Colombo GPO"

is_valid_postal("10100")  # True

Planned error codes

Code	Triggered by
postal.invalid_length	Not exactly 5 characters.
postal.invalid_characters	Contains non-digit characters.
postal.unknown_code	Five digits but not a code in our table.

PostalResult (planned shape)

Bases: ValidationResult

Validation result returned by :func:~helakit.postal.validate_postal.

Typed property accessors mirror the keys placed in data by the validator. Properties return None on invalid results.

Planned API

Postal-code validation is not implemented yet; this class is wired up in advance so the planned shape can be documented and imported. Calling :func:~helakit.postal.validate_postal currently raises NotImplementedError.

PostalDecoded (planned shape)

Structured metadata about a recognised Sri Lankan postal code.

Returned in PostalResult.data["decoded"] and accessible as PostalResult.decoded.

Attributes:

Name	Type	Description
district	str	The district the code belongs to (e.g. "Colombo").
province	str	The province the district is in (e.g. "Western").
post_office	str | None	The specific post office name, when known.