helakit.postal

helakit.postal

Sri Lankan postal-code validation.

PostalDecoded dataclass

PostalDecoded(district: str, province: str, post_office: str | None = None)

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.

PostalError

Bases: HelakitError

Raised for unrecoverable postal-code-related programmer errors.

PostalResult dataclass

PostalResult(is_valid: bool, value: str, normalized: str | None = None, errors: list[ValidationError] = list(), data: dict[str, Any] = dict())

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.

decoded property

decoded: PostalDecoded | None

Full :class:PostalDecoded payload. None if invalid.

district property

district: str | None

District name. None if invalid.

post_office property

post_office: str | None

Post office name, when known. None otherwise.

province property

province: str | None

Province name. None if invalid.

is_valid_postal

is_valid_postal(value: str) -> bool

Return True if value is a valid Sri Lankan postal code.

Raises:

Type	Description
NotImplementedError	Postal-code validation has not been implemented yet.

validate_postal

validate_postal(value: str) -> PostalResult

Validate a Sri Lankan postal code.

Parameters:

Name	Type	Description	Default
value	str	A five-digit postal code.	required

Returns:

Name	Type	Description
A	PostalResult	class:~helakit.postal.PostalResult with the matching
	PostalResult	district and province populated when valid. Accessible as
	PostalResult	result.district / result.province or via
	PostalResult	result["district"].

Raises:

Type	Description
NotImplementedError	Postal-code validation has not been implemented yet.