API Reference

This page is the concise reference for the public Python surface you import. For the mental model behind these types, see Concepts.

---

Installation and imports

import paxman
from paxman.capabilities import (
    Country,
    Currency,
    Date,
    Email,
    IP,
    ISBN,
    Money,
    Phone,
    SIUnit,
    URL,
)
from paxman.core.domain import Resolution
from paxman.core.errors import (
    PaxmanError,
    CapabilityError,
    ContractError,
    MultipleMentionsError,
    RecognitionError,
    ValidationError,
)

Paxman has no runtime dependencies. import paxman is side-effect free — nothing runs until you register and call canonicalize().

---

Registration

Registration tells the engine which capabilities exist. It must complete from one thread before the first canonicalize() call; afterwards the registry freezes and reads are safe from any thread.

Function	Signature	What it does
paxman.register_all_shipped()	() -> tuple[str, ...]	Registers every capability shipped in this release. Idempotent by name. Returns the names newly registered by this call.
paxman.register_capability(cap)	(cap: Capability) -> None	Registers one capability instance, e.g. Email(). Fails if the name already exists or the registry is frozen.
paxman.register_grammar(name, cls)	(capability_name: str, grammar_cls: type[Grammar]) -> None	Registers a community grammar (see Extending). Must happen before the first call.
paxman.register_rule(name, cls)	(capability_name: str, rule_cls: type[Rule]) -> None	Registers a community rule. Must happen before the first call.

# Quick exploration — everything
paxman.register_all_shipped()

# Explicit — only what you depend on
paxman.register_capability(Email())
paxman.register_capability(Date())

---

paxman.canonicalize()

The sole entry point.

def canonicalize(text: str, contract: CapabilityContract) -> ExecutionResult

Parameter	Type	Description
text	str	Raw input. One presumed mention per call (see Segmentation).
contract	CapabilityContract	Created via SomeCapability.create_contract(...). Carries capability_name so no separate name argument is needed.

Returns ExecutionResult — always, for every domain outcome including missing or invalid input. Domain outcomes are statuses, not exceptions.

Raises

Exception	Cause
CapabilityError	No capability matches contract.capability_name
ContractError	Malformed contract (unknown pinned_rules, unknown output_format, unknown semantics, missing required feature)
MultipleMentionsError	Two or more non-overlapping mentions resolved to different values — caller must split first
RecognitionError	Grammar raised or returned a malformed match (rule, original_error)
ValidationError	Rule raised inside matches()/normalize() (rule, original_error)

MISSING / INVALID / AMBIGUOUS do not raise — they are ExecutionResult.status values (see Execution Result and Candidates & Ambiguity).

---

paxman.scan()

Batch scan — one ScanContext substrate pass, per-capability Mention records.

def scan(text: str, contracts: Sequence[CapabilityContract]) -> ScanResult

Parameter	Type	Description
text	str	Input text to scan (may contain many mentions).
contracts	Sequence[CapabilityContract]	One contract per capability to scan; each carries its suppress_common_words and other flags.

Returns ScanResult — per-capability mentions dict sharing one substrate.

Raises

Exception	Cause
TypeError	text is not str or contracts is not a Sequence
CapabilityError	A contract names an unregistered capability

The scan shares one ScanContext (word spans and lazy views) across all contracts, so querying many capabilities costs one substrate build. Suppression (suppress_common_words) is honored per-contract: a Country contract with suppress_common_words=True drops word-bounded hits like to → TO (Tonga) via COMMON_WORDS (67), while the same text scanned with False keeps them. For the honest F1 path on prose, scan() is the preferred successor to MultipleMentionsError on canonicalize() — see docs/user/migration.md and docs/recipes/segmentation.md.

import paxman
from paxman.capabilities.Country import Country
from paxman.core.errors import MultipleMentionsError

paxman.register_all_shipped()
contract = Country.create_contract()

# Prose with embedded values — the new honest path:
try:
    result = paxman.canonicalize("Ship to United States please", contract)
except MultipleMentionsError:
    # scan() shares one ScanContext substrate across all contracts in the batch
    mentions = paxman.scan("Ship to United States please", [contract])
    # mentions.mentions["country"] == [
    #   Mention(span=(5, 7), grammar="alpha2_recognition", notation=...),
    #   Mention(span=(8, 21), grammar="name_recognition", notation=...),
    # ]
    for m in mentions.mentions["country"]:
        print(m.span, m.grammar, m.notation)

See Segmentation for when to use scan() vs caller-owned split-then-canonicalize.

---

Contracts — SomeCapability.create_contract()

Every capability exposes a keyword-only factory. Common parameters come first, capability-specific ones after.

contract = Email.create_contract(
    # common — every capability
    excluded_rules=(),  # Sequence[str]
    pinned_rules=None,  # Sequence[str] | None — when not None, only these run
    year=None,  # int | None — only rules with publication_year <= year
    output_format=None,  # str | None — None / "default" / default / offered, else ContractError
    extra_grammars=(),  # tuple[str, ...] — opt-in community grammars
    suppress_common_words=False,  # bool — suppress word-bounded short-code hits in COMMON_WORDS (67)
    # capability-specific — varies by capability
    include_obfuscated=False,  # example: Email only
)

The contract is a frozen dataclass — construct it, pass it, inspect it, but do not mutate it. See Contracts for the full common-plus-specific table.

output_format policy (identical for every capability)

• None, "default", and the capability’s DEFAULT_OUTPUT_FORMAT all resolve to the default.
• Any value in OFFERED_OUTPUT_FORMATS resolves to itself.
• Anything else raises ContractError immediately. Validation never consults output_format.

Current defaults and offered alternatives:

Capability	Default (DEFAULT_OUTPUT_FORMAT)	Offered (OFFERED_OUTPUT_FORMATS)
Country	alpha2	alpha3, numeric, name
Currency	code	(none — single format)
Date	ISO	US
DOI	doi	url
Email	email	(none)
IP	ip	(none)
ISBN	isbn13	hyphenated
Money	code_amount	compact
Phone	e164	rfc3966, split
SI Unit	symbol	(none)
URL	url	(none)
BIC	bic	grouped, bic11
Coordinates	decimal	iso6709, geo_uri, geojson_pair, dms, dm
ChemicalElement	symbol	name
IBAN	electronic	paper
ISSN	hyphenated	compact, urn
ISIN	isin	grouped
ISNI	isni	compact, urn
LEI	lei	urn
UNSPSC	unspsc	labeled, native
GTIN	gtin14	native
CreditCard	pan	grouped
Language	bcp47	alpha2, alpha3, alpha3-bib, name
MacAddress	colon	hyphen, bare, cisco, eui64
MinorPlanet	designation	packed
ORCID	orcid	uri, compact
Timezone	iana	(none — single format)
UtcOffset	extended	basic
UUID	hyphenated	compact, braced, urn
Domain	ascii	unicode

The set of capabilities — and their offered formats — grows over time. Treat this table as the current release, not a closed list.

Capability-specific flag summary (current release)

Capability	Flag	Type	Default	Purpose
Email	include_obfuscated	bool	False	user at domain dot com
Email	include_localhost	bool	True	admin@localhost
Country	include_localized	bool	False	CLDR multilingual names
Country	include_historical	bool	False	Deprecated names
Currency	default_currency	str | None	None	Resolve shared bare symbol ($) to this alpha-3 code
IP	include_ipv6	bool	True	IPv6
ISBN	include_isbn10	bool	True	Legacy ISBN-10
ISBN	include_range_validation	bool	False	Registrant-range provenance
Language	include_localized	bool	False	CLDR localized display-name validation
Language	include_collective	bool	False	ISO 639-5 collective-code validation
Language	include_private	bool	False	Private-use subtag validation
GTIN	include_verified	bool	False	Verified-by-GS1 liveness lookup
CreditCard	include_brand_validation	bool	False	Brand IIN/length membership
Money	dollar_sign_currency	str | None	None	Resolve bare $ amount to this alpha-3 code
Money	precision	str	"strict"	strict / truncate / round for over-precision amounts
Phone	default_country	str | None	None	Interpret national numbers as if in this alpha-2 country
SI Unit	allow_split_word_prefixes	bool	False	kilo gram → kg
SI Unit	allow_multi_solidus	bool	False	kg/m/s preserved
Date	two_digit_base_year	int | None	None	Base for 2-digit year expansion
Timezone	include_systemv	bool	False	Validate SystemV zones (EST5EDT and kin)
common	suppress_common_words	bool	False	suppress word-bounded short-code hits in COMMON_WORDS (67)

Validation: default_currency / dollar_sign_currency must be uppercase alpha-3; default_country must be uppercase alpha-2; precision must be one of the three values — otherwise ContractError at construction time.

---

Execution result

@dataclass(frozen=True)
class ExecutionResult:
    status: Resolution  # MISSING | INVALID | SUCCESS | AMBIGUOUS
    canonicalized_value: str | None  # str on SUCCESS, None otherwise
    candidates: tuple[Candidate, ...]  # all validated evidence, deduplicated
    contract: CapabilityContract  # the contract you passed in
    version_stamp: VersionStamp  # .paxman_version
    span: tuple[int, int] | None  # [start, end) of resolved value on SUCCESS, else None
    suppressed_count: int = 0  # hits dropped by suppress_common_words (ADR-0009 §16, #122)
    suppressed_spans: tuple[tuple[int, int], ...] = ()  # [start, end) of each suppressed hit

@dataclass(frozen=True)
class Candidate:
    value: str
    recognition_rule: str  # grammar name, e.g. "standard_recognition"
    validation_rule: str  # rule name, e.g. "Section 3.4.1-addr-spec"
    span: tuple[int, int] | None  # half-open [start, end) in the input
    provenance: tuple[
        Provenance, ...
    ]  # one or more authority citations (read-only property)


@dataclass(frozen=True)
class Provenance:
    authority: str  # "IETF", "ISO", "BIPM", "WHATWG", "CLDR", ...
    specification_name: str  # "RFC 5322", "ISO 3166-1", ...
    kind: str  # "specification" / "standard" / ...
    reference_url: str
    version: str | None
    lifecycle: str  # "active" / "deprecated" / ...
    publication_year: int


@dataclass(frozen=True)
class VersionStamp:
    paxman_version: str
    recognition_revision: str  # kernel recognition revision (default "0")


class Resolution(Enum):
    MISSING = "missing"
    INVALID = "invalid"
    SUCCESS = "success"
    AMBIGUOUS = "ambiguous"

Reading the result (see also Execution Result):

from paxman.core.domain import Resolution

if result.status == Resolution.SUCCESS:
    value = result.canonicalized_value  # str, span is set
else:
    # MISSING / INVALID / AMBIGUOUS — no single value, span is None
    # inspect result.candidates and their provenance/spans
    ...

span semantics: on SUCCESS it is the span of the single resolved value; on AMBIGUOUS use each candidate.span; on MISSING/INVALID it is None and candidates is empty.

suppressed_count / suppressed_spans: populated whenever suppress_common_words=True suppression fires, on any status (ADR-0009 §16, A0 #122) — 0/() when the flag is off or nothing was suppressed. Spans are in sorted positional order. A whole-input suppressible hit is never suppressed (A0 exemption), so canonicalize("to", Country suppress on) → SUCCESS "TO" with 0/(), while canonicalize("in/", …) → MISSING with suppressed_count == 1, suppressed_spans == ((0, 2),).

---

Errors

All exceptions inherit from PaxmanError. See Errors for handling patterns.

Exception	Signal type	Typical cause
CapabilityError	setup	Unknown capability, duplicate name, registry already frozen
ContractError	setup	Bad pinned_rules, bad output_format, unknown semantics, missing required feature, bad default_currency/default_country/precision
MultipleMentionsError	usage	Two separate mentions with different values in one call — split first
RecognitionError	internal bug	Grammar raised or returned a bad span/raw_text. Fields: rule, original_error (None on structural failure)
ValidationError	internal bug	Rule raised inside matches()/normalize(). Fields: rule, original_error

Statuses vs exceptions: statuses are domain answers returned inside ExecutionResult; exceptions mean the call was not valid to attempt. Catch exceptions at setup and at the outer edge of a batch loop; branch on statuses in normal flow.

---

Quick lookup — choose the right capability

Kind of text you have	Capability to use	Factory
Email addresses	Email	Email.create_contract(...)
Dates	Date	Date.create_contract(...)
Country codes or names	Country	Country.create_contract(...)
Currency codes / symbols / names (no amount)	Currency	Currency.create_contract(...)
IP addresses	IP	IP.create_contract(...)
ISBNs	ISBN	ISBN.create_contract(...)
Money amounts with currency	Money	Money.create_contract(...)
Phone numbers	Phone	Phone.create_contract(...)
SI unit expressions	SI Unit	SIUnit.create_contract(...)
Absolute URLs / IRIs	URL	URL.create_contract(...)
Business identifier codes	BIC	BIC.create_contract(...)
WGS 84 coordinates	Coordinates	Coordinates.create_contract(...)
Chemical elements	ChemicalElement	ChemicalElement.create_contract(...)
Bank account numbers	IBAN	IBAN.create_contract(...)
Serial identifiers	ISSN	ISSN.create_contract(...)
Securities identification numbers	ISIN	ISIN.create_contract(...)
Researcher/organization identifiers	ISNI	ISNI.create_contract(...)
Product/service codes	UNSPSC	UNSPSC.create_contract(...)
Legal entity identifiers	LEI	LEI.create_contract(...)
Trade item identifiers	GTIN	GTIN.create_contract(...)
Payment card numbers (PANs)	CreditCard	CreditCard.create_contract(...)
Language identifiers	Language	Language.create_contract(...)
MAC addresses	MacAddress	MacAddress.create_contract(...)
Researcher identifiers	ORCID	ORCID.create_contract(...)
Time zone identifiers	Timezone	Timezone.create_contract(...)
UTC offset values	UtcOffset	UtcOffset.create_contract(...)
UUIDs	UUID	UUID.create_contract(...)
Digital object identifiers	DOI	DOI.create_contract(...)
Hostnames	Domain	Domain.create_contract(...)

New capabilities appear in minor releases — check paxman.capabilities for the current set. Each per-capability guide under Capabilities details its recognized forms, output formats, contract flags, and provenance.