validators

Validators is a Python library built around a single idea: checking whether one value is valid shouldn’t require defining a form or a schema. Each validator is a small, focused function — validators.email('someone@example.com') returns True or a ValidationError object that is falsy but carries the failure reason, so failed checks can be used directly in conditionals or inspected for detail.

The library covers a wide surface of everyday validation needs: emails, URLs, domains, hostnames, IP addresses, MAC addresses, UUIDs, IBANs, credit card numbers, cron expressions, hashes, slugs, and country/finance codes, plus a growing set of internationalized checks (Spanish CIF/DOI/NIF, Finnish business IDs and SSNs, French department codes and SSNs, Indian Aadhar and PAN numbers, Russian INN). An optional extra adds cryptocurrency address validation for Bitcoin, Ethereum, BSC, and Tron.

Because every validator is a plain function rather than part of a schema object, the library slots into existing code without ceremony — call the function you need, check the boolean-like result, and move on. It has no runtime dependencies of its own (only an opt-in extra for crypto address hashing), keeping it lightweight for scripts, APIs, and form-processing code alike.

What You Get

• Dozens of ready-made validators for common formats — email, URL, domain, hostname, IP/MAC address, UUID, IBAN, credit card numbers, cron expressions, hashes, and slugs
• Internationalized validators for country-specific identifiers (Spanish CIF/NIF/NIE/DOI, Finnish business ID/SSN, French department/SSN, Indian Aadhar/PAN, Russian INN)
• Optional cryptocurrency address validation (BTC, ETH, BSC, TRX) via the crypto-eth-addresses extra
• A @validator decorator that turns any boolean-returning function into a validator with consistent ValidationError semantics
• A ValidationError object that is falsy in boolean context but retains the offending arguments and failure reason for inspection
• An opt-in RAISE_VALIDATION_ERROR mode (env var or r_ve kwarg) for callers who prefer exceptions over falsy return values

Common Use Cases

• Form and API input checks - validating email addresses, URLs, or phone-adjacent fields submitted through a web form or JSON API without writing a full schema
• Data cleaning pipelines - filtering or flagging malformed IBANs, card numbers, or IP addresses before they reach downstream processing
• CLI and script argument validation - quick sanity checks on user-supplied strings (domains, UUIDs, slugs) in one-off scripts and tools
• Localized identity verification - confirming country-specific identifiers such as Indian Aadhar/PAN or Spanish NIF numbers in region-specific applications
• Custom validator composition - using the @validator decorator to wrap project-specific boolean checks with the same ValidationError contract the built-ins use

Under The Hood

Architecture The codebase is organized as one flat package (src/validators/) with one module per validation domain — email.py, url.py, domain.py, iban.py, card.py, ip_address.py, and so on — plus an i18n/ and crypto_addresses/ subpackage for the internationalized and crypto-specific checks. Every validator function is wrapped with the @validator decorator defined in utils.py, which is the one piece of shared machinery in the whole library: it catches ValueError/TypeError/UnicodeError, converts a falsy return into a ValidationError carrying the original call’s arguments, and optionally re-raises when RAISE_VALIDATION_ERROR is set. Because each validator is a standalone function with no shared state or class hierarchy, adding a new validator means adding a new module and re-exporting it from __init__.py — a design that scales linearly and keeps blast radius from any one change extremely small.

Tech Stack The library targets Python 3.9+ and declares zero runtime dependencies in pyproject.toml, with a single optional extra (crypto-eth-addresses, pulling in eth-hash[pycryptodome]) for cryptocurrency address checks. It builds via setuptools with a src/-layout package, and development tooling is managed through PDM dependency groups covering docs (mkdocs/sphinx), linting (ruff, pyright in strict mode), testing (pytest), and security scanning (bandit). Tox orchestrates lint/type/format/sast/test matrices across Python 3.9-3.13.

Code Quality Every validation module has a matching test file under tests/, exercised with pytest using heavily parametrized valid/invalid input tables (seen directly in tests/test_email.py). The suite also runs with --doctest-modules, so the Examples: blocks embedded in each function’s docstring double as executable tests. Type checking runs under pyright in strict mode, and ruff enforces both style and pydocstyle (Google convention) docstring rules, with bandit running as a separate SAST pass in CI (.github/workflows/pycqa.yaml, sast.yaml). Docstrings consistently document Args, Returns, and often Raises, which is unusually thorough for a library this size.

API Design The public surface is deliberately minimal and uniform: import a name from validators, call it with the value to check, and get back True or an object that evaluates falsy. There is no configuration object, registry, or class to instantiate — the @validator decorator is the only abstraction a user of the library needs to understand, and it’s optional (users can apply it to their own functions too). This buys very low ceremony for the common case at the cost of some flexibility that a schema-based validator (e.g. Pydantic) would offer for validating whole structured objects rather than one value at a time.