Skip to content
Paxman
Search limited to v0.3.1. Switch to the latest version for up-to-date results.

Paxman — User Documentation

This content is for v0.3.1. Switch to the latest version for up-to-date documentation.

Paxman is a canonicalization library: you give it messy, human-written text and it tells you what that text means according to the specification that defines it — not a guess, a cited answer.

Example: "user@Example.COM" → "user@example.com" (lowercased per RFC 5322), "01/02/2026" → either AMBIGUOUS (US vs European date) or a single ISO date if you pin the rules. Every answer comes with the specification that produced it.

Who is this for?

Section titled “Who is this for?”

These docs are written for everyone who needs reliable identifiers — not just Python experts:

You are…You will use Paxman to…
A Python developer integrating validation into an app or APICall paxman.canonicalize() with a typed contract; handle ExecutionResult in code
A researcher or analyst cleaning data in a Jupyter notebookNormalize one column at a time — emails, country names, URLs — with two lines of Python per cell
A non-Python operator running a data pipelineUse Paxman from any Python environment (uv, pip, notebooks, scripts) with no extra services — it is a pure library with zero runtime dependencies

If you can run pip install paxman and write a few lines of Python, you can use Paxman. No servers, no network calls, no configuration files.

What Paxman does and does not do

Section titled “What Paxman does and does not do”
DoesDoes not
Resolves one mention per call to a single canonical value when the specifications agreeExtract all mentions from a paragraph — you split the text first (see the Segmentation Recipe)
Returns the same output for the same input every time (deterministic)Learn from data or make probabilistic guesses
Tells you which specification validated the answer (provenance)Contact a network service or clock to decide

At a glance

Section titled “At a glance”
import paxman
from paxman.capabilities import Email
from paxman.core.domain import Resolution


paxman.register_all_shipped()  # once, before your first call


contract = Email.create_contract()
result = paxman.canonicalize("Contact user@Example.com", contract)


if result.status == Resolution.SUCCESS:
    print(result.canonicalized_value)  # "user@example.com"
else:
    print(result.status)  # MISSING | INVALID | AMBIGUOUS

Three steps, every time: register → create a contract → canonicalize.

Where to go next

Section titled “Where to go next”
DocWhat you will learn
Getting StartedInstall with pip or uv, run your first call in a script or notebook
ConceptsThe mental model — capabilities, contracts, pipeline, results, provenance
CapabilitiesPer-capability guides — one page per kind of identifier
API ReferenceSignatures, types, and error table for every public import
ExtendingAdd your own grammars & rules via extra_grammars
MigrationVersioning and upgrade checklist (SemVer)
Segmentation RecipeHow to handle text with more than one entity

Concepts in detail

Section titled “Concepts in detail”

The Concepts hub is the place to build your mental model before diving into reference docs. Each page is self-contained and includes a Mermaid diagram:

  • Capabilities — what a capability is and how it is chosen
  • Contracts — how you configure what Paxman recognizes and validates
  • Pipeline — what happens inside a canonicalize() call
  • Execution Result — how to read status, canonicalized_value, span, and candidates
  • Provenance — what “authoritative” means and how to cite it
  • Candidates & Ambiguity — why two answers can be correct
  • Errors — what raises an exception vs what returns a status

Capability guides

Section titled “Capability guides”

Each guide under Capabilities is also self-contained: what it recognizes, canonical output & output_format, contract flags, status examples, notebook snippet, and provenance.

Capabilities available today

Section titled “Capabilities available today”

Paxman ships with capabilities that each cover one kind of identifier. The set is growing over time — the list below reflects what is available in this release, not a fixed ceiling. Each capability is independently selectable via its contract:

  • Country — country codes and names (ISO 3166, CLDR)
  • Currency — currency codes, symbols, and display names (ISO 4217, CLDR)
  • Date — calendar dates in ISO, US, European, and slash-ISO formats
  • Email — standard, obfuscated, and localhost addresses (RFC 5322, RFC 6761)
  • IP — IPv4 and IPv6 addresses (RFC 791, RFC 5952)
  • ISBN — ISBN-10 and ISBN-13 with check-digit and hyphenation support
  • Money — amounts paired with currency identifiers (ISO 4217, CLDR)
  • Phone — international and national phone numbers (E.164, RFC 3966, NANP)
  • SI Unit — SI unit expressions and compounds (BIPM SI Brochure, ISO 80000-1)
  • URL — absolute URIs and IRIs (WHATWG URL Standard)

You only load what you use — importing paxman.capabilities.Email does not load the others.

Note on the count: do not treat the number of capabilities as fixed. New capabilities are added in minor releases. Always check paxman.capabilities or the latest release notes for the current set.

Requirements

Section titled “Requirements”
  • Python 3.11 or newer
  • No runtime dependencies — pip install paxman is enough

Next: Getting Started →