API reference

Everything public in petrock, version 2.4.1.

parse(text, country=None, strict=False)

Parses a single address string and returns an Address. Raises petrock.ParseError only when strict=True and no field could be assigned; otherwise it returns a low-confidence result.

Argument	Type	Default	Meaning
`text`	str	—	Raw address. Newlines and repeated whitespace are collapsed.
`country`	str \| None	`None`	ISO 3166-1 alpha-2, lowercase. `None` triggers detection.
`strict`	bool	`False`	Raise instead of returning a partial result.

parse_many(rows, country=None, workers=1)

Generator yielding (source, Address) pairs in input order. With workers > 1 the work is split across processes; ordering is still preserved, at the cost of buffering up to workers × 512 results.

Address

Field	Type	Notes
`street`	str	Title-cased, abbreviations expanded (`ul.` → `Ulica`).
`number`	str	Kept as a string — descriptive/orientation pairs like `1149/7` must not be split.
`postcode`	str	Digits only, no spaces, left-padded where the country uses fixed width.
`locality`	str	City or municipality.
`district`	str \| None	Set only where the country’s rule set defines one.
`country`	str	Resolved country code, even when it was detected.
`confidence`	float	Share of input tokens assigned to a field.
`raw`	str	The original input, unmodified.

Address.as_dict()

Returns a plain dict with the fields above. Stable across minor versions — new fields may be added, existing ones are never renamed inside a major version.

Exceptions

Class	Raised when
`ParseError`	`strict=True` and nothing could be assigned.
`UnknownCountry`	A country code has no rule set.
`RuleTableError`	The bundled table is missing or corrupt — reinstall.

All exceptions inherit from petrock.PetrockError, so a single except is enough if you do not care which one fired.