validate

Why a value was rejected: a stable, machine-readable code (such as too_long or bad_char) and a human-readable message.

A rejection tied to the name of the field it came from, as on_field builds it.

The failure of r, if any, as a list of one FieldError named name; an ok gives []. Concatenate the lists of several fields, or pass them to errors.

Every failure of several fields, in order: errors([on_field("email", check_email(f.email)), on_field("age", check_range(f.age, 0, 150))]). An empty result means the record is valid.

The failures as field: message lines, for showing to a person.

Checks an optional value: none is valid and stays none, some(s) is checked with check.

The reason r failed, or none when it passed.

r with its failure message replaced by msg (the code stays), for messages in your own words.

s when its length in characters is within lo to hi (both inclusive); codes too_short and too_long.

n when it is within lo to hi (both inclusive); codes too_small and too_large.

The integer s spells: an optional + or - and ASCII digits, nothing else (no spaces, no _). Codes empty, not_integer and out_of_range (outside the 64-bit range).

The trimmed s when it has a character other than white space; code blank.

s when it is one of options (exact, case-sensitive); code not_allowed.

s when re matches somewhere in it (anchor the pattern with ^ and $ to match the whole text); code no_match.

A host name by RFC 1123: dot-separated labels of 1 to 63 ASCII letters, digits and hyphens, not starting or ending with a hyphen, at most 253 characters in all. One trailing dot (the root) is allowed and removed. Internationalized names are accepted in their ASCII (xn--) form only. The result is lower-cased. Codes empty, too_long, empty_label, label_too_long, bad_char, hyphen_edge.

Whether s is a host name (check_hostname).

A domain name: a host name (check_hostname) whose last label is not all digits, so an IPv4 address is never a domain. With require_tld it needs at least two labels and a top-level label of 2 or more letters or an xn-- label (example.com, not localhost). Codes of check_hostname, and no_tld, bad_tld.

Whether s is a domain with a top-level domain (check_domain(s, true)).

An IP address: family 4 or 6, its 4 or 16 octets (0 to 255) in network order, and the zone (scope) of an IPv6 address such as fe80::1%eth0.

An address block: an address and a prefix length (0 to 32 for IPv4, 0 to 128 for IPv6).

What an address is for, from the IANA special-purpose registries. SharedAddress is the carrier-grade NAT block 100.64.0.0/10, UniqueLocal is IPv6 fc00::/7, Reserved covers the remaining special blocks (0.0.0.0/8, 192.0.0.0/24, 198.18.0.0/15, 240.0.0.0/4, ::/8, 100::/64, 2001::/23), and Global is everything else.

An IPv4 address in dotted-decimal form: exactly four parts from 0 to 255, decimal digits only, no leading zeros (010.0.0.1 is rejected, since other parsers read it as octal), no other shorthand (127.1, hex). Codes ipv4_parts, ipv4_number, leading_zero, ipv4_range.

Whether s is an IPv4 address (check_ipv4).

An IPv6 address in any RFC 4291 text form: eight groups of 1 to 4 hex digits, :: once for one or more zero groups, an embedded IPv4 address in the last 32 bits (::ffff:192.0.2.1), and an optional zone after % (letters, digits and -._~, as in fe80::1%eth0). Codes ipv6_group, double_colon, ipv6_groups, zone, and the IPv4 codes for an embedded address.

Whether s is an IPv6 address (check_ipv6).

An IPv4 or IPv6 address (check_ipv4 when s has no :, else check_ipv6).

Whether s is an IPv4 or IPv6 address.

The canonical text of an address: dotted decimal for IPv4, and RFC 5952 for IPv6 (lower-case hex, no leading zeros, the longest run of two or more zero groups as ::, the first on a tie, and ::ffff:a.b.c.d for IPv4-mapped addresses), then %zone if there is one.

What ip is for (see IpKind). An IPv4-mapped IPv6 address (::ffff:10.0.0.1) is classified as its IPv4 address.

Whether ip is in a private block: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or IPv6 unique local fc00::/7.

Whether ip is a loopback address (127.0.0.0/8, ::1).

Whether ip is globally routable: not in any special-purpose block.

A CIDR block such as 192.168.0.0/16 or 2001:db8::/32. The address may have bits set after the prefix (192.168.1.7/16, as in interface configuration); cidr_network clears them. Codes no_prefix, prefix, zone and the address codes.

A CIDR block whose address is its network address, so 192.168.1.7/16 is rejected with host_bits.

Whether s is a CIDR block (check_cidr).

The first address of the block (the address with every bit after the prefix cleared).

The last address of the block (every bit after the prefix set; the broadcast address for IPv4).

The number of addresses in the block, 2 to the power of the bits after the prefix.

Whether ip is inside the block c. Addresses of the other family are never inside, and the zone is ignored.

The text of a block, format_ip of its address, / and the prefix length.

What check_email_with accepts besides plain local@domain.tld addresses.

The defaults of check_email: no quoted local parts, no IP literals, and a top-level domain.

An email address by the practical subset of RFC 5321 and 5322 that mail systems accept: at most 254 characters; a local part (before the last @) of 1 to 64 characters, a dot-atom of ASCII letters, digits and !#$%&'*+-/=?^_{|}~ with single dots not at either end, or with allow_quoted a quoted string ("john doe"@example.com, with \ escapes); and a domain by check_domain (with require_tld), or with allow_ip_literal an address literal such as [192.0.2.1] or [IPv6:2001:db8::1]. Comments, folding white space, obsolete syntax and non-ASCII (SMTPUTF8) addresses are rejected. The result has the domain lower-cased and the local part unchanged. It says nothing about whether mail can be delivered. Codes too_long, no_at, empty_local, local_too_long, local_char, local_dot, quoted_local, ip_literal`, and the domain and address codes.

check_email_with(s, email_defaults()).

Whether s is an email address with the defaults (check_email).

A TCP or UDP port number, 0 to 65535, in decimal with no sign and no leading zeros. Codes port.

Whether s is a port number (check_port).

The parts of a URL. host is lower-cased, and an IPv6 host is written without its brackets; path is "" when the URL has none; query and fragment exclude the ? and #.

What check_url_with accepts: schemes (lower case; [] allows any scheme), credentials before the host, single-label hosts such as localhost (when require_tld is false), and IP address hosts.

The defaults of check_url: http and https only, no credentials, a domain with a top-level domain or an IP address.

A URL with an authority, scheme://[userinfo@]host[:port][/path][?query][#fragment], by RFC 3986: the scheme is a letter then letters, digits, +, - or .; the host a domain (check_domain), an IPv4 address or a bracketed IPv6 address without a zone; the port 0 to 65535; path, query and fragment only RFC 3986 characters with valid %XX escapes. Spaces, control characters and non-ASCII text (IRIs) are rejected, and so are URLs without // (mailto:, urn:). The result is the parsed Url. Codes empty, bad_char, no_scheme, scheme, scheme_not_allowed, no_authority, userinfo, empty_host, host, ip_host, zone, port, path, query, fragment, and the host codes.

check_url_with(s, url_defaults()).

Whether s is an http or https URL with the defaults (check_url).

A UUID in the canonical 8-4-4-4-12 hex form, either case, of any version and variant (including the nil and max UUIDs). The result is lower case. Code uuid.

A UUID in the canonical form or one of the other common forms: in braces ({...}), with a urn:uuid: prefix (any case), or as 32 hex digits without hyphens. The result is the canonical lower-case form. Code uuid.

Whether s is a canonical UUID (check_uuid).

The version of a UUID in any form check_uuid_loose accepts: the hex digit that starts the third group (4 for random, 7 for time-ordered, 0 for nil, 15 for max).

The variant of a UUID, from the first hex digit of its fourth group: ncs (0 to 7), rfc9562 (8 to b, the RFC 4122 and 9562 layout), microsoft (c, d) or future (e, f).

A canonical UUID of version v with the RFC 9562 variant, as generators of that version write it. Codes uuid, uuid_version, uuid_variant.

Whether s is the nil UUID, all zeros (any form check_uuid_loose accepts).

Whether s is the max UUID, all f (any form check_uuid_loose accepts).

A calendar date in ISO 8601 extended form, YYYY-MM-DD, that exists (2024-02-29 but not 2023-02-29); the result is midnight UTC of that day. Years are 0000 to 9999; basic (20240229), week and ordinal forms are rejected. Codes date_form, month, day.

Whether s is an ISO 8601 date (check_date).

A time of day, HH:MM, HH:MM:SS or HH:MM:SS.fff (any number of fraction digits, kept to the millisecond), hours 00 to 23; the result is milliseconds after midnight. 24:00 and leap seconds are rejected. Codes time_form, hour, minute, second.

Whether s is a time of day (check_time).

An ISO 8601 date and time: a date, T (or t, or a space), a time as check_time reads it, and an optional offset (Z, +HH:MM, +HHMM or +HH); a time without an offset is read as UTC. The result is the instant. Codes of check_date and check_time, datetime_form and offset.

Whether s is an ISO 8601 date and time (check_datetime).

An RFC 3339 timestamp, the strict profile of ISO 8601 used on the internet: T (or t) between date and time, seconds required, and an offset required (Z, z or +HH:MM), as in 2026-10-16T09:30:00.250+05:30. The result is the instant. Codes as check_datetime.

Whether s is an RFC 3339 timestamp (check_rfc3339).

A 48-bit MAC address as six pairs of hex digits separated by : or - (one kind throughout), or as three groups of four separated by . (0123.4567.89ab). The result is lower case with colons, 01:23:45:67:89:ab. Code mac.

Whether s is a MAC address (check_mac).

Whether s is two or more ASCII digits whose Luhn (mod 10) checksum is valid, as on payment cards and IMEI numbers.

The Luhn check digit to append to the digits s, or none unless s is one or more digits.

A GTIN: an EAN-8, UPC-A (12 digits), EAN-13 or GTIN-14 number with a valid check digit. Digits only, no separators. Codes gtin_form, check_digit.

Whether s is an EAN-13 number with a valid check digit.

Whether s is a UPC-A number (12 digits) with a valid check digit.

An ISBN-10: nine digits and a check digit or X, with optional hyphens or spaces between them. The result is the ten characters without separators (X upper case). Codes isbn_form, check_digit.

An ISBN-13: 13 digits starting 978 or 979 with a valid check digit, with optional hyphens or spaces. The result has no separators. Codes isbn_form, check_digit.

An ISBN-10 or ISBN-13 (by the number of digits), without separators in the result.

Whether s is an ISBN-10 or ISBN-13 (check_isbn).

The ISBN-13 of a valid ISBN-10 (978, its first nine digits and a new check digit).

A card network, from the number's leading digits (IIN ranges).

A checked card number (digits only) and its network.

The network of a card number (digits only) by its leading digits: Visa 4; Mastercard 51 to 55 and 2221 to 2720; American Express 34, 37; Discover 6011, 644 to 649, 65, 622126 to 622925; UnionPay other 62; Diners Club 300 to 305, 36, 38, 39; JCB 3528 to 3589; Maestro 50, 56 to 69; Mir 2200 to 2204; otherwise UnknownBrand.

A payment card number: digits with optional spaces or hyphens, 12 to 19 digits, a valid Luhn checksum, and a length its network uses (16 for Mastercard, 15 for American Express, 13, 16 or 19 for Visa). Numbers of unknown networks are accepted with UnknownBrand. Codes card_form, card_length, check_digit.

Whether s is a payment card number (check_card).

The IBAN length of a country (ISO 3166 alpha-2, upper case) from the SWIFT IBAN registry, or none for a country without IBANs.

An IBAN: a country code, two check digits and the account number (BBAN) of the length the registry gives for that country, upper-case letters and digits, with the ISO 7064 mod 97 checksum equal to 1. Spaces are ignored and letters may be lower case. The result is the electronic form, upper case without spaces. Codes iban_form, iban_country, iban_length, check_digit.

Whether s is an IBAN (check_iban).

The print form of a valid IBAN: groups of four characters separated by spaces.

A Semantic Versioning 2.0.0 version, exactly as the specification's grammar: MAJOR.MINOR.PATCH without leading zeros, an optional - and dot-separated pre-release identifiers (ASCII letters, digits and hyphens; numeric ones without leading zeros), and an optional + and build identifiers (the same characters, leading zeros allowed). No v prefix. Codes semver, prerelease, build.

Whether s is a Semantic Versioning 2.0.0 version (check_semver).

A CSS hex color: # and 3, 4, 6 or 8 hex digits (#rgb, #rgba, #rrggbb, #rrggbbaa). The result is the long lower-case form, #rrggbb or #rrggbbaa. Code hex_color.

Whether s is a CSS hex color (check_hex_color).

A phone number in E.164 form: +, then 7 to 15 digits starting with 1 to 9 (the country code first), with no spaces or punctuation. Whether the number exists is out of scope. Code e164.

Whether s is an E.164 phone number (check_e164).

Standard base64 (RFC 4648 section 4: A-Z a-z 0-9 + /) with the = padding that makes the length a multiple of 4, and unused bits zero; "" is the empty value. The result is the decoded bytes. Codes base64.

URL-safe base64 (RFC 4648 section 5: - and _ in place of + and /), with or without padding. The result is the decoded bytes. Code base64.

Whether s is standard base64 (check_base64).

Whether s is URL-safe base64 (check_base64url).

Hex-encoded bytes: an even number of hex digits in either case; "" is the empty value. The result is the decoded bytes. Code hex.

Whether s is hex-encoded bytes (check_hex).

A URL slug: lower-case ASCII letters and digits in groups joined by single hyphens, as in my-first-post. Code slug.

Whether s is a URL slug (check_slug).

Whether s is one well-formed JSON text by RFC 8259: any value at the top, white space around it, strings with valid escapes and no raw control characters, numbers in JSON's grammar (no leading zeros, +, NaN or hex), and nesting at most 512 deep. Duplicate member names are allowed, as the RFC allows. On failure the message names the character position. Code json.

Whether s is well-formed JSON (check_json).

A password policy. max_run limits how often one character may repeat in a row (0 for no limit), and banned lists passwords that are refused whatever their shape (compared ignoring case), such as a list of common passwords.

A common policy: 12 to 128 characters, a lower-case and an upper-case letter, a digit and a symbol, spaces allowed, at most 3 equal characters in a row, nothing banned. NIST SP 800-63B recommends length and a banned list over composition rules: set the need_* fields to false and fill banned to follow it.

Every rule of p that pw breaks, in the order too_short, too_long, need_lower, need_upper, need_digit, need_symbol, spaces, repeated, banned; [] means it passes. Letters are Unicode letters with case (é is lower case), digits are ASCII digits, and a symbol is any other non-space character.

pw when it passes p, else the first rule it breaks (password_problems lists them all).