VALIDATORS(1)

NAME
validators - Python Data Validation for Humans™

PyCQA SAST Docs Version Downloads

Python has all kinds of data validation tools, but every one of them seems to require defining a schema or form. I wanted to create a simple validation library where validating a simple value does not require defining a form or a schema.

pip install validators

Then,

>>> import validators
>>>
>>> validators.email('someone@example.com')
True

RESOURCES

•   Documentation

•   Bugtracker

•   Security

•   Code

    ----

    Python 3.9 reaches EOL in October 2025.

  Install and Use

  Installation

Execute the following command:

pip install validators
It's preferable to use pip within a virtual environment.

  Usage

import validators
print(validators.email('someone@example.com'))

  To raise validation error

1.  Either set the environment variable RAISE_VALIDATION_ERROR to True

    $ export RAISE_VALIDATION_ERROR=True
    $ python -c "from validators import url; print(url('https//bad_url'))"
    Traceback (most recent call last):
    File "<string>", line 1, in <module>
    File "/path/to/lib/validators/utils.py", line 87, in wrapper
        raise ValidationError(func, _func_args_as_dict(func, *args, **kwargs))
    validators.utils.ValidationError: ValidationError(func=url, args={'value': 'https//bad_url'})

2.  Or pass r_ve=True to each caller function:

    $ python -c "from validators.card import visa; print(visa('bad_visa_number', r_ve=True))"
    Traceback (most recent call last):
    File "<string>", line 1, in <module>
    File "/path/to/lib/validators/utils.py", line 87, in wrapper
        raise ValidationError(func, _func_args_as_dict(func, *args, **kwargs))
    validators.utils.ValidationError: ValidationError(func=visa, args={'value': 'bad_visa_number'})

  between

validators.between.between(value: PossibleValueTypes, /, *, min_val: PossibleValueTypes | AbsMin | None = None, max_val: PossibleValueTypes | AbsMax | None = None)
    Validate that a number is between minimum and/or maximum value.

    This will work with any comparable type, such as floats, decimals and dates not just integers. This validator is originally based on [WTForms-NumberRange-Validator][1].

    [1]: https://github.com/wtforms/wtforms/blob/master/src/wtforms/validators.py#L166-L220

    Examples

    >>> from datetime import datetime
    >>> between(5, min_val=2)
    True
    >>> between(13.2, min_val=13, max_val=14)
    True
    >>> between(500, max_val=400)
    ValidationError(func=between, args={'value': 500, 'max_val': 400})
    >>> between(
    ...     datetime(2000, 11, 11),
    ...     min_val=datetime(1999, 11, 11)
    ... )
    True

Parameters

•   value -- Value which is to be compared.

•   min_val -- The minimum required value of the number. If not provided, minimum value will not be checked.

•   max_val -- The maximum value of the number. If not provided, maximum value will not be checked.

Returns
    If value is in between the given conditions. (ValidationError): If value is not in between the given conditions.

Return type
    (Literal[True])

Raises

•   (ValueError) -- If min_val is greater than max_val.

•   (TypeError) -- If there's a type mismatch during comparison.

    NOTE:

•   PossibleValueTypes = TypeVar("PossibleValueTypes", int, float, str, datetime)

•   If neither min_val nor max_val is provided, result will always be True.

  card

validators.card.amex(value: str, /)
    Return whether or not given value is a valid American Express card number.

    Examples

    >>> amex('378282246310005')
    True
    >>> amex('4242424242424242')
    ValidationError(func=amex, args={'value': '4242424242424242'})

Parameters
    value -- American Express card number string to validate

Returns
    If value is a valid American Express card number. (ValidationError): If value is an invalid American Express card number.

Return type
    (Literal[True])

validators.card.card_number(value: str, /)
    Return whether or not given value is a valid generic card number.

    This validator is based on [Luhn's algorithm][1].

    [1]: https://github.com/mmcloughlin/luhn

    Examples

    >>> card_number('4242424242424242')
    True
    >>> card_number('4242424242424241')
    ValidationError(func=card_number, args={'value': '4242424242424241'})

Parameters
    value -- Generic card number string to validate

Returns
    If value is a valid generic card number. (ValidationError): If value is an invalid generic card number.

Return type
    (Literal[True])

validators.card.diners(value: str, /)
    Return whether or not given value is a valid Diners Club card number.

    Examples

    >>> diners('3056930009020004')
    True
    >>> diners('4242424242424242')
    ValidationError(func=diners, args={'value': '4242424242424242'})

Parameters
    value -- Diners Club card number string to validate

Returns
    If value is a valid Diners Club card number. (ValidationError): If value is an invalid Diners Club card number.

Return type
    (Literal[True])

validators.card.discover(value: str, /)
    Return whether or not given value is a valid Discover card number.

    Examples

    >>> discover('6011111111111117')
    True
    >>> discover('4242424242424242')
    ValidationError(func=discover, args={'value': '4242424242424242'})

Parameters
    value -- Discover card number string to validate

Returns
    If value is a valid Discover card number. (ValidationError): If value is an invalid Discover card number.

Return type
    (Literal[True])

validators.card.jcb(value: str, /)
    Return whether or not given value is a valid JCB card number.

    Examples

    >>> jcb('3566002020360505')
    True
    >>> jcb('4242424242424242')
    ValidationError(func=jcb, args={'value': '4242424242424242'})

Parameters
    value -- JCB card number string to validate

Returns
    If value is a valid JCB card number. (ValidationError): If value is an invalid JCB card number.

Return type
    (Literal[True])

validators.card.mastercard(value: str, /)
    Return whether or not given value is a valid Mastercard card number.

    Examples

    >>> mastercard('5555555555554444')
    True
    >>> mastercard('4242424242424242')
    ValidationError(func=mastercard, args={'value': '4242424242424242'})

Parameters
    value -- Mastercard card number string to validate

Returns
    If value is a valid Mastercard card number. (ValidationError): If value is an invalid Mastercard card number.

Return type
    (Literal[True])

validators.card.mir(value: str, /)
    Return whether or not given value is a valid Mir card number.

    Examples

    >>> mir('2200123456789019')
    True
    >>> mir('4242424242424242')
    ValidationError(func=mir, args={'value': '4242424242424242'})

Parameters
    value -- Mir card number string to validate.

Returns
    If value is a valid Mir card number. (ValidationError): If value is an invalid Mir card number.

Return type
    (Literal[True])

validators.card.unionpay(value: str, /)
    Return whether or not given value is a valid UnionPay card number.

    Examples

    >>> unionpay('6200000000000005')
    True
    >>> unionpay('4242424242424242')
    ValidationError(func=unionpay, args={'value': '4242424242424242'})

Parameters
    value -- UnionPay card number string to validate

Returns
    If value is a valid UnionPay card number. (ValidationError): If value is an invalid UnionPay card number.

Return type
    (Literal[True])

validators.card.visa(value: str, /)
    Return whether or not given value is a valid Visa card number.

    Examples

    >>> visa('4242424242424242')
    True
    >>> visa('2223003122003222')
    ValidationError(func=visa, args={'value': '2223003122003222'})

Parameters
    value -- Visa card number string to validate

Returns
    If value is a valid Visa card number. (ValidationError): If value is an invalid Visa card number.

Return type
    (Literal[True])

  country

validators.country.calling_code(value: str, /)
    Validates given calling code.

    This performs country's calling code validation.

    Examples

    >>> calling_code('+91')
    True
    >>> calling_code('-31')
    ValidationError(func=calling_code, args={'value': '-31'})

Parameters
    value -- Country's calling code string to validate.

Returns
    If value is a valid calling code. (ValidationError): If value is an invalid calling code.

Return type
    (Literal[True])

validators.country.country_code(value: str, /, *, iso_format: str = 'auto', ignore_case: bool = False)
    Validates given country code.

    This performs a case-sensitive [ISO 3166][1] country code validation.

    [1]: https://www.iso.org/iso-3166-country-codes.html

    Examples

    >>> country_code('GB', iso_format='alpha3')
    ValidationError(func=country_code, args={'value': 'GB', 'iso_format': 'alpha3'})
    >>> country_code('USA')
    True
    >>> country_code('840', iso_format='numeric')
    True
    >>> country_code('iN', iso_format='alpha2')
    ValidationError(func=country_code, args={'value': 'iN', 'iso_format': 'alpha2'})
    >>> country_code('ZWE', iso_format='alpha3')
    True

Parameters

•   value -- Country code string to validate.

•   iso_format -- ISO format to be used. Available options are: auto, alpha2, alpha3 and numeric.

•   ignore_case -- Enable/Disable case-sensitive matching.

Returns
    If value is a valid country code. (ValidationError): If value is an invalid country code.

Return type
    (Literal[True])

validators.country.currency(value: str, /, *, skip_symbols: bool = True, ignore_case: bool = False)
    Validates given currency code.

    This performs [ISO 4217][1] currency code/symbol validation.

    [1]: https://www.iso.org/iso-4217-currency-codes.html

    Examples

    >>> currency('USD')
    True
    >>> currency('ZWX')
    ValidationError(func=currency, args={'value': 'ZWX'})

Parameters

•   value -- Currency code/symbol string to validate.

•   skip_symbols -- Skip currency symbol validation.

•   ignore_case -- Enable/Disable case-sensitive matching.

Returns
    If value is a valid currency code. (ValidationError): If value is an invalid currency code.

Return type
    (Literal[True])

  cron

validators.cron.cron(value: str, /)
    Return whether or not given value is a valid cron string.

    Examples

    >>> cron('*/5 * * * *')
    True
    >>> cron('30-20 * * * *')
    ValidationError(func=cron, args={'value': '30-20 * * * *'})

Parameters
    value -- Cron string to validate.

Returns
    If value is a valid cron string. (ValidationError): If value is an invalid cron string.

Return type
    (Literal[True])

  crypto_addresses

validators.crypto_addresses.bsc_address(value: str, /)
    Return whether or not given value is a valid binance smart chain address.

    Full validation is implemented for BSC addresses.

    Examples

    >>> bsc_address('0x4e5acf9684652BEa56F2f01b7101a225Ee33d23f')
    True
    >>> bsc_address('0x4g5acf9684652BEa56F2f01b7101a225Eh33d23z')
    ValidationError(func=bsc_address, args={'value': '0x4g5acf9684652BEa56F2f01b7101a225Eh33d23z'})

Parameters
    value -- BSC address string to validate.

Returns
    If value is a valid bsc address. (ValidationError): If value is an invalid bsc address.

Return type
    (Literal[True])

validators.crypto_addresses.btc_address(value: str, /)
    Return whether or not given value is a valid bitcoin address.

    Full validation is implemented for P2PKH and P2SH addresses. For segwit addresses a regexp is used to provide a reasonable estimate on whether the address is valid.

    Examples

    >>> btc_address('3Cwgr2g7vsi1bXDUkpEnVoRLA9w4FZfC69')
    True
    >>> btc_address('1BvBMsEYstWetqTFn5Au4m4GFg7xJaNVN2')
    ValidationError(func=btc_address, args={'value': '1BvBMsEYstWetqTFn5Au4m4GFg7xJaNVN2'})

Parameters
    value -- Bitcoin address string to validate.

Returns
    If value is a valid bitcoin address. (ValidationError): If value is an invalid bitcoin address.

Return type
    (Literal[True])

validators.crypto_addresses.eth_address(value: str, /)
    Return whether or not given value is a valid ethereum address.

    Full validation is implemented for ERC20 addresses.

    Examples

    >>> eth_address('0x9cc14ba4f9f68ca159ea4ebf2c292a808aaeb598')
    True
    >>> eth_address('0x8Ba1f109551bD432803012645Ac136ddd64DBa72')
    ValidationError(func=eth_address, args={'value': '0x8Ba1f109551bD432803012645Ac136ddd64DBa72'})

Parameters
    value -- Ethereum address string to validate.

Returns
    If value is a valid ethereum address. (ValidationError): If value is an invalid ethereum address.

Return type
    (Literal[True])

validators.crypto_addresses.trx_address(value: str, /)
    Return whether or not given value is a valid tron address.

    Full validation is implemented for TRC20 tron addresses.

    Examples

    >>> trx_address('TLjfbTbpZYDQ4EoA4N5CLNgGjfbF8ZWz38')
    True
    >>> trx_address('TR2G7Rm4vFqF8EpY4U5xdLdQ7XgJ2U8Vd')
    ValidationError(func=trx_address, args={'value': 'TR2G7Rm4vFqF8EpY4U5xdLdQ7XgJ2U8Vd'})

Parameters
    value -- Tron address string to validate.

Returns
    If value is a valid tron address. (ValidationError): If value is an invalid tron address.

Return type
    (Literal[True])

  domain

validators.domain.domain(value: str, /, *, consider_tld: bool = False, rfc_1034: bool = False, rfc_2782: bool = False)
    Return whether or not given value is a valid domain.

    Examples

    >>> domain('example.com')
    True
    >>> domain('example.com/')
    ValidationError(func=domain, args={'value': 'example.com/'})
    >>> # Supports IDN domains as well::
    >>> domain('xn----gtbspbbmkef.xn--p1ai')
    True

Parameters

•   value -- Domain string to validate.

•   consider_tld -- Restrict domain to TLDs allowed by IANA.

•   rfc_1034 -- Allows optional trailing dot in the domain name. Ref: [RFC 1034](https://www.rfc-editor.org/rfc/rfc1034).

•   rfc_2782 -- Domain name is of type service record. Allows optional underscores in the domain name. Ref: [RFC 2782](https://www.rfc-editor.org/rfc/rfc2782).

Returns
    If value is a valid domain name. (ValidationError): If value is an invalid domain name.

Return type
    (Literal[True])

Raises
    (UnicodeError) -- If value cannot be encoded into idna or decoded into utf-8.

  email

validators.email.email(value: str, /, *, ipv6_address: bool = False, ipv4_address: bool = False, simple_host: bool = False, rfc_1034: bool = False, rfc_2782: bool = False)
    Validate an email address.

    This was inspired from [Django's email validator][1]. Also ref: [RFC 1034][2], [RFC 5321][3] and [RFC 5322][4].

    [1]: https://github.com/django/django/blob/main/django/core/validators.py#L174 [2]: https://www.rfc-editor.org/rfc/rfc1034 [3]: https://www.rfc-editor.org/rfc/rfc5321 [4]: https://www.rfc-editor.org/rfc/rfc5322

    Examples

    >>> email('someone@example.com')
    True
    >>> email('bogus@@')
    ValidationError(func=email, args={'value': 'bogus@@'})

Parameters

•   value -- eMail string to validate.

•   ipv6_address -- When the domain part is an IPv6 address.

•   ipv4_address -- When the domain part is an IPv4 address.

•   simple_host -- When the domain part is a simple hostname.

•   rfc_1034 -- Allow trailing dot in domain name. Ref: [RFC 1034](https://www.rfc-editor.org/rfc/rfc1034).

•   rfc_2782 -- Domain name is of type service record. Ref: [RFC 2782](https://www.rfc-editor.org/rfc/rfc2782).

Returns
    If value is a valid eMail. (ValidationError): If value is an invalid eMail.

Return type
    (Literal[True])

  encoding

validators.encoding.base16(value: str, /)
    Return whether or not given value is a valid base16 encoding.

    Examples

    >>> base16('a3f4b2')
    True
    >>> base16('a3f4Z1')
    ValidationError(func=base16, args={'value': 'a3f4Z1'})

Parameters
    value -- base16 string to validate.

Returns
    If value is a valid base16 encoding. (ValidationError): If value is an invalid base16 encoding.

Return type
    (Literal[True])

validators.encoding.base32(value: str, /)
    Return whether or not given value is a valid base32 encoding.

    Examples

    >>> base32('MFZWIZLTOQ======')
    True
    >>> base32('MfZW3zLT9Q======')
    ValidationError(func=base32, args={'value': 'MfZW3zLT9Q======'})

Parameters
    value -- base32 string to validate.

Returns
    If value is a valid base32 encoding. (ValidationError): If value is an invalid base32 encoding.

Return type
    (Literal[True])

validators.encoding.base58(value: str, /)
    Return whether or not given value is a valid base58 encoding.

    Examples

    >>> base58('14pq6y9H2DLGahPsM4s7ugsNSD2uxpHsJx')
    True
    >>> base58('cUSECm5YzcXJwP')
    True

Parameters
    value -- base58 string to validate.

Returns
    If value is a valid base58 encoding. (ValidationError): If value is an invalid base58 encoding.

Return type
    (Literal[True])

validators.encoding.base64(value: str, /)
    Return whether or not given value is a valid base64 encoding.

    Examples

    >>> base64('Y2hhcmFjdGVyIHNldA==')
    True
    >>> base64('cUSECm5YzcXJwP')
    ValidationError(func=base64, args={'value': 'cUSECm5YzcXJwP'})

Parameters
    value -- base64 string to validate.

Returns
    If value is a valid base64 encoding. (ValidationError): If value is an invalid base64 encoding.

Return type
    (Literal[True])

  finance

validators.finance.cusip(value: str)
    Return whether or not given value is a valid CUSIP.

    Checks if the value is a valid [CUSIP][1]. [1]: https://en.wikipedia.org/wiki/CUSIP

    Examples

    >>> cusip('037833DP2')
    True
    >>> cusip('037833DP3')
    ValidationError(func=cusip, args={'value': '037833DP3'})

Parameters
    value -- CUSIP string to validate.

Returns
    If value is a valid CUSIP string. (ValidationError): If value is an invalid CUSIP string.

Return type
    (Literal[True])

validators.finance.isin(value: str)
    Return whether or not given value is a valid ISIN.

    Checks if the value is a valid [ISIN][1]. [1]: https://en.wikipedia.org/wiki/International_Securities_Identification_Number

    Examples

    >>> isin('037833DP2')
    ValidationError(func=isin, args={'value': '037833DP2'})
    >>> isin('037833DP3')
    ValidationError(func=isin, args={'value': '037833DP3'})

Parameters
    value -- ISIN string to validate.

Returns
    If value is a valid ISIN string. (ValidationError): If value is an invalid ISIN string.

Return type
    (Literal[True])

validators.finance.sedol(value: str)
    Return whether or not given value is a valid SEDOL.

    Checks if the value is a valid [SEDOL][1]. [1]: https://en.wikipedia.org/wiki/SEDOL

    Examples

    >>> sedol('2936921')
    True
    >>> sedol('29A6922')
    ValidationError(func=sedol, args={'value': '29A6922'})

Parameters
    value -- SEDOL string to validate.

Returns
    If value is a valid SEDOL string. (ValidationError): If value is an invalid SEDOL string.

Return type
    (Literal[True])

  hashes

validators.hashes.md5(value: str, /)
    Return whether or not given value is a valid MD5 hash.

    Examples

    >>> md5('d41d8cd98f00b204e9800998ecf8427e')
    True
    >>> md5('900zz11')
    ValidationError(func=md5, args={'value': '900zz11'})

Parameters
    value -- MD5 string to validate.

Returns
    If value is a valid MD5 hash. (ValidationError): If value is an invalid MD5 hash.

Return type
    (Literal[True])

validators.hashes.sha1(value: str, /)
    Return whether or not given value is a valid SHA1 hash.

    Examples

    >>> sha1('da39a3ee5e6b4b0d3255bfef95601890afd80709')
    True
    >>> sha1('900zz11')
    ValidationError(func=sha1, args={'value': '900zz11'})

Parameters
    value -- SHA1 string to validate.

Returns
    If value is a valid SHA1 hash. (ValidationError): If value is an invalid SHA1 hash.

Return type
    (Literal[True])

validators.hashes.sha224(value: str, /)
    Return whether or not given value is a valid SHA224 hash.

    Examples

    >>> sha224('d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f')
    True
    >>> sha224('900zz11')
    ValidationError(func=sha224, args={'value': '900zz11'})

Parameters
    value -- SHA224 string to validate.

Returns
    If value is a valid SHA224 hash. (ValidationError): If value is an invalid SHA224 hash.

Return type
    (Literal[True])

validators.hashes.sha256(value: str, /)
    Return whether or not given value is a valid SHA256 hash.

    Examples

    >>> sha256(
    ...     'e3b0c44298fc1c149afbf4c8996fb924'
    ...     '27ae41e4649b934ca495991b7852b855'
    ... )
    True
    >>> sha256('900zz11')
    ValidationError(func=sha256, args={'value': '900zz11'})

Parameters
    value -- SHA256 string to validate.

Returns
    If value is a valid SHA256 hash. (ValidationError): If value is an invalid SHA256 hash.

Return type
    (Literal[True])

validators.hashes.sha384(value: str, /)
    Return whether or not given value is a valid SHA384 hash.

    Examples

    >>> sha384(
    ...     'cb00753f45a35e8bb5a03d699ac65007272c32ab0eded163'
    ...     '1a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7'
    ... )
    True
    >>> sha384('900zz11')
    ValidationError(func=sha384, args={'value': '900zz11'})

Parameters
    value -- SHA384 string to validate.

Returns
    If value is a valid SHA384 hash. (ValidationError): If value is an invalid SHA384 hash.

Return type
    (Literal[True])

validators.hashes.sha512(value: str, /)
    Return whether or not given value is a valid SHA512 hash.

    Examples

    >>> sha512(
    ...     'cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce'
    ...     '9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af9'
    ...     '27da3e'
    ... )
    True
    >>> sha512('900zz11')
    ValidationError(func=sha512, args={'value': '900zz11'})

Parameters
    value -- SHA512 string to validate.

Returns
    If value is a valid SHA512 hash. (ValidationError): If value is an invalid SHA512 hash.

Return type
    (Literal[True])

  hostname

validators.hostname.hostname(value: str, /, *, skip_ipv6_addr: bool = False, skip_ipv4_addr: bool = False, may_have_port: bool = True, maybe_simple: bool = True, consider_tld: bool = False, private: bool | None = None, rfc_1034: bool = False, rfc_2782: bool = False)
    Return whether or not given value is a valid hostname.

    Examples

    >>> hostname("ubuntu-pc:443")
    True
    >>> hostname("this-pc")
    True
    >>> hostname("xn----gtbspbbmkef.xn--p1ai:65535")
    True
    >>> hostname("_example.com")
    ValidationError(func=hostname, args={'value': '_example.com'})
    >>> hostname("123.5.77.88:31000")
    True
    >>> hostname("12.12.12.12")
    True
    >>> hostname("[::1]:22")
    True
    >>> hostname("dead:beef:0:0:0:0000:42:1")
    True
    >>> hostname("[0:0:0:0:0:ffff:1.2.3.4]:-65538")
    ValidationError(func=hostname, args={'value': '[0:0:0:0:0:ffff:1.2.3.4]:-65538'})
    >>> hostname("[0:&:b:c:@:e:f::]:9999")
    ValidationError(func=hostname, args={'value': '[0:&:b:c:@:e:f::]:9999'})

Parameters

•   value -- Hostname string to validate.

•   skip_ipv6_addr -- When hostname string cannot be an IPv6 address.

•   skip_ipv4_addr -- When hostname string cannot be an IPv4 address.

•   may_have_port -- Hostname string may contain port number.

•   maybe_simple -- Hostname string maybe only hyphens and alpha-numerals.

•   consider_tld -- Restrict domain to TLDs allowed by IANA.

•   private -- Embedded IP address is public if False, private/local if True.

•   rfc_1034 -- Allow trailing dot in domain/host name. Ref: [RFC 1034](https://www.rfc-editor.org/rfc/rfc1034).

•   rfc_2782 -- Domain/Host name is of type service record. Ref: [RFC 2782](https://www.rfc-editor.org/rfc/rfc2782).

Returns
    If value is a valid hostname. (ValidationError): If value is an invalid hostname.

Return type
    (Literal[True])

  i18n

validators.i18n.es_cif(value: str, /)
    Validate a Spanish CIF.

    Each company in Spain prior to 2008 had a distinct CIF and has been discontinued. For more information see [wikipedia.org/cif][1].

    The new replacement is to use NIF for absolutely everything. The issue is that there are "types" of NIFs now: company, person [citizen or resident] all distinguished by the first character of the DOI. For this reason we will continue to call CIFs NIFs, that are used for companies.

    This validator is based on [generadordni.es][2].

    [1]: https://es.wikipedia.org/wiki/C%C3%B3digo_de_identificaci%C3%B3n_fiscal [2]: https://generadordni.es/

    Examples

    >>> es_cif('B25162520')
    True
    >>> es_cif('B25162529')
    ValidationError(func=es_cif, args={'value': 'B25162529'})

Parameters
    value -- DOI string which is to be validated.

Returns
    If value is a valid DOI string. (ValidationError): If value is an invalid DOI string.

Return type
    (Literal[True])

validators.i18n.es_doi(value: str, /)
    Validate a Spanish DOI.

    A DOI in spain is all NIF / CIF / NIE / DNI -- a digital ID. For more information see [wikipedia.org/doi][1]. This validator is based on [generadordni.es][2].

    [1]: https://es.wikipedia.org/wiki/Identificador_de_objeto_digital [2]: https://generadordni.es/

    Examples

    >>> es_doi('X0095892M')
    True
    >>> es_doi('X0095892X')
    ValidationError(func=es_doi, args={'value': 'X0095892X'})

Parameters
    value -- DOI string which is to be validated.

Returns
    If value is a valid DOI string. (ValidationError): If value is an invalid DOI string.

Return type
    (Literal[True])

validators.i18n.es_nie(value: str, /)
    Validate a Spanish NIE.

    The NIE is a tax identification number in Spain, known in Spanish as the NIE, or more formally the Número de identidad de extranjero. For more information see [wikipedia.org/nie][1]. This validator is based on [generadordni.es][2].

    [1]: https://es.wikipedia.org/wiki/N%C3%BAmero_de_identidad_de_extranjero [2]: https://generadordni.es/

    Examples

    >>> es_nie('X0095892M')
    True
    >>> es_nie('X0095892X')
    ValidationError(func=es_nie, args={'value': 'X0095892X'})

Parameters
    value -- DOI string which is to be validated.

Returns
    If value is a valid DOI string. (ValidationError): If value is an invalid DOI string.

Return type
    (Literal[True])

validators.i18n.es_nif(value: str, /)
    Validate a Spanish NIF.

    Each entity, be it person or company in Spain has a distinct NIF. Since we've designated CIF to be a company NIF, this NIF is only for person. For more information see [wikipedia.org/nif][1]. This validator is based on [generadordni.es][2].

    [1]: https://es.wikipedia.org/wiki/N%C3%BAmero_de_identificaci%C3%B3n_fiscal [2]: https://generadordni.es/

    Examples

    >>> es_nif('26643189N')
    True
    >>> es_nif('26643189X')
    ValidationError(func=es_nif, args={'value': '26643189X'})

Parameters
    value -- DOI string which is to be validated.

Returns
    If value is a valid DOI string. (ValidationError): If value is an invalid DOI string.

Return type
    (Literal[True])

validators.i18n.fi_business_id(value: str, /)
    Validate a Finnish Business ID.

    Each company in Finland has a distinct business id. For more information see [Finnish Trade Register][1]

    [1]: http://en.wikipedia.org/wiki/Finnish_Trade_Register

    Examples

    >>> fi_business_id('0112038-9')  # Fast Monkeys Ltd
    True
    >>> fi_business_id('1234567-8')  # Bogus ID
    ValidationError(func=fi_business_id, args={'value': '1234567-8'})

Parameters
    value -- Business ID string to be validated.

Returns
    If value is a valid finnish business id. (ValidationError): If value is an invalid finnish business id.

Return type
    (Literal[True])

validators.i18n.fi_ssn(value: str, /, *, allow_temporal_ssn: bool = True)
    Validate a Finnish Social Security Number.

    This validator is based on [django-localflavor-fi][1].

    [1]: https://github.com/django/django-localflavor-fi/

    Examples

    >>> fi_ssn('010101-0101')
    True
    >>> fi_ssn('101010-0102')
    ValidationError(func=fi_ssn, args={'value': '101010-0102'})

Parameters

•   value -- Social Security Number to be validated.

•   allow_temporal_ssn -- Whether to accept temporal SSN numbers. Temporal SSN numbers are the ones where the serial is in the range [900-999]. By default temporal SSN numbers are valid.

Returns
    If value is a valid finnish SSN. (ValidationError): If value is an invalid finnish SSN.

Return type
    (Literal[True])

validators.i18n.fr_department(value: str | int)
    Validate a french department number.

    Examples

    >>> fr_department(20)  # can be an integer
    ValidationError(func=fr_department, args={'value': 20})
    >>> fr_department("20")
    ValidationError(func=fr_department, args={'value': '20'})
    >>> fr_department("971")  # Guadeloupe
    True
    >>> fr_department("00")
    ValidationError(func=fr_department, args={'value': '00'})
    >>> fr_department('2A')  # Corsica
    True
    >>> fr_department('2B')
    True
    >>> fr_department('2C')
    ValidationError(func=fr_department, args={'value': '2C'})

Parameters
    value -- French department number to validate.

Returns
    If value is a valid french department number. (ValidationError): If value is an invalid french department number.

Return type
    (Literal[True])

validators.i18n.fr_ssn(value: str)
    Validate a french Social Security Number.

    Each french citizen has a distinct Social Security Number. For more information see [French Social Security Number][1] (sadly unavailable in english).

    [1]: https://fr.wikipedia.org/wiki/Num%C3%A9ro_de_s%C3%A9curit%C3%A9_sociale_en_France

    Examples

    >>> fr_ssn('1 84 12 76 451 089 46')
    True
    >>> fr_ssn('1 84 12 76 451 089')  # control key is optional
    True
    >>> fr_ssn('3 84 12 76 451 089 46')  # wrong gender number
    ValidationError(func=fr_ssn, args={'value': '3 84 12 76 451 089 46'})
    >>> fr_ssn('1 84 12 76 451 089 47')  # wrong control key
    ValidationError(func=fr_ssn, args={'value': '1 84 12 76 451 089 47'})

Parameters
    value -- French Social Security Number string to validate.

Returns
    If value is a valid french Social Security Number. (ValidationError): If value is an invalid french Social Security Number.

Return type
    (Literal[True])

validators.i18n.ind_aadhar(value: str)
    Validate an indian aadhar card number.

    Examples

    >>> ind_aadhar('3675 9834 6015')
    True
    >>> ind_aadhar('3675 ABVC 2133')
    ValidationError(func=ind_aadhar, args={'value': '3675 ABVC 2133'})

Parameters
    value -- Aadhar card number string to validate.

Returns
    If value is a valid aadhar card number. (ValidationError): If value is an invalid aadhar card number.

Return type
    (Literal[True])

validators.i18n.ind_pan(value: str)
    Validate a pan card number.

    Examples

    >>> ind_pan('ABCDE9999K')
    True
    >>> ind_pan('ABC5d7896B')
    ValidationError(func=ind_pan, args={'value': 'ABC5d7896B'})

Parameters
    value -- PAN card number string to validate.

Returns
    If value is a valid PAN card number. (ValidationError): If value is an invalid PAN card number.

Return type
    (Literal[True])

validators.i18n.ru_inn(value: str)
    Validate a Russian INN (Taxpayer Identification Number).

    The INN can be either 10 digits (for companies) or 12 digits (for individuals). The function checks both the length and the control digits according to Russian tax rules.

    Examples

    >>> ru_inn('500100732259')  # Valid 12-digit INN
    True
    >>> ru_inn('7830002293')    # Valid 10-digit INN
    True
    >>> ru_inn('1234567890')    # Invalid INN
    ValidationError(func=ru_inn, args={'value': '1234567890'})

Parameters
    value -- Russian INN string to validate. Can contain only digits.

Returns
    If value is a valid Russian INN. (ValidationError): If value is an invalid Russian INN.

Return type
    (Literal[True])

    NOTE: The validation follows the official algorithm: - For 10-digit INN: checks 10th control digit - For 12-digit INN: checks both 11th and 12th control digits

  iban

validators.iban.iban(value: str, /)
    Return whether or not given value is a valid IBAN code.

    Examples

    >>> iban('DE29100500001061045672')
    True
    >>> iban('123456')
    ValidationError(func=iban, args={'value': '123456'})

Parameters
    value -- IBAN string to validate.

Returns
    If value is a valid IBAN code. (ValidationError): If value is an invalid IBAN code.

Return type
    (Literal[True])

  ip_address

validators.ip_address.ipv4(value: str, /, *, cidr: bool = True, strict: bool = False, private: bool | None = None, host_bit: bool = True)
    Returns whether a given value is a valid IPv4 address.

    From Python version 3.9.5 leading zeros are no longer tolerated and are treated as an error. The initial version of ipv4 validator was inspired from [WTForms IPAddress validator][1].

    [1]: https://github.com/wtforms/wtforms/blob/master/src/wtforms/validators.py

    Examples

    >>> ipv4('123.0.0.7')
    True
    >>> ipv4('1.1.1.1/8')
    True
    >>> ipv4('900.80.70.11')
    ValidationError(func=ipv4, args={'value': '900.80.70.11'})

Parameters

•   value -- IP address string to validate.

•   cidr -- IP address string may contain CIDR notation.

•   strict -- IP address string is strictly in CIDR notation.

•   private -- IP address is public if False, private/local/loopback/broadcast if True.

•   host_bit -- If False and host bits (along with network bits) _are_ set in the supplied address, this function raises a validation error. ref [IPv4Network][2]. [2]: https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Network

Returns
    If value is a valid IPv4 address. (ValidationError): If value is an invalid IPv4 address.

Return type
    (Literal[True])

validators.ip_address.ipv6(value: str, /, *, cidr: bool = True, strict: bool = False, host_bit: bool = True)
    Returns if a given value is a valid IPv6 address.

    Including IPv4-mapped IPv6 addresses. The initial version of ipv6 validator was inspired from [WTForms IPAddress validator][1].

    [1]: https://github.com/wtforms/wtforms/blob/master/src/wtforms/validators.py

    Examples

    >>> ipv6('::ffff:192.0.2.128')
    True
    >>> ipv6('::1/128')
    True
    >>> ipv6('abc.0.0.1')
    ValidationError(func=ipv6, args={'value': 'abc.0.0.1'})

Parameters

•   value -- IP address string to validate.

•   cidr -- IP address string may contain CIDR annotation.

•   strict -- IP address string is strictly in CIDR notation.

•   host_bit -- If False and host bits (along with network bits) _are_ set in the supplied address, this function raises a validation error. ref [IPv6Network][2]. [2]: https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Network

Returns
    If value is a valid IPv6 address. (ValidationError): If value is an invalid IPv6 address.

Return type
    (Literal[True])

  length

validators.length.length(value: str, /, *, min_val: int | None = None, max_val: int | None = None)
    Return whether or not the length of given string is within a specified range.

    Examples

    >>> length('something', min_val=2)
    True
    >>> length('something', min_val=9, max_val=9)
    True
    >>> length('something', max_val=5)
    ValidationError(func=length, args={'value': 'something', 'max_val': 5})

Parameters

•   value -- The string to validate.

•   min_val -- The minimum required length of the string. If not provided, minimum length will not be checked.

•   max_val -- The maximum length of the string. If not provided, maximum length will not be checked.

Returns
    If len(value) is in between the given conditions. (ValidationError): If len(value) is not in between the given conditions.

Return type
    (Literal[True])

Raises
    (ValueError) -- If either min_val or max_val is negative.

  mac_address

validators.mac_address.mac_address(value: str, /)
    Return whether or not given value is a valid MAC address.

    This validator is based on [WTForms MacAddress validator][1].

    [1]: https://github.com/wtforms/wtforms/blob/master/src/wtforms/validators.py#L482

    Examples

    >>> mac_address('01:23:45:67:ab:CD')
    True
    >>> mac_address('00:00:00:00:00')
    ValidationError(func=mac_address, args={'value': '00:00:00:00:00'})

Parameters
    value -- MAC address string to validate.

Returns
    If value is a valid MAC address. (ValidationError): If value is an invalid MAC address.

Return type
    (Literal[True])

  slug

validators.slug.slug(value: str, /)
    Validate whether or not given value is valid slug.

    Valid slug can contain only lowercase alphanumeric characters and hyphens. It starts and ends with these lowercase alphanumeric characters.

    Examples

    >>> slug('my-slug-2134')
    True
    >>> slug('my.slug')
    ValidationError(func=slug, args={'value': 'my.slug'})

Parameters
    value -- Slug string to validate.

Returns
    If value is a valid slug. (ValidationError): If value is an invalid slug.

Return type
    (Literal[True])

  url

validators.url.url(value: str, /, *, skip_ipv6_addr: bool = False, skip_ipv4_addr: bool = False, may_have_port: bool = True, simple_host: bool = False, strict_query: bool = True, consider_tld: bool = False, private: bool | None = None, rfc_1034: bool = False, rfc_2782: bool = False, validate_scheme: ~typing.Callable[[str], bool] = <function _validate_scheme>)
    Return whether or not given value is a valid URL.

    This validator was originally inspired from [URL validator of dperini][1]. The following diagram is from [urlly][2]:

      foo://admin:hunter1@example.com:8042/over/there?name=ferret#nose
      \_/   \___/ \_____/ \_________/ \__/\_________/ \_________/ \__/
       |      |       |       |        |       |          |         |
    scheme username password hostname port    path      query    fragment

    [1]: https://gist.github.com/dperini/729294 [2]: https://github.com/treeform/urlly

    Examples

    >>> url('http://duck.com')
    True
    >>> url('ftp://foobar.dk')
    True
    >>> url('http://10.0.0.1')
    True
    >>> url('http://example.com/">user@example.com')
    ValidationError(func=url, args={'value': 'http://example.com/">user@example.com'})

Parameters

•   value -- URL string to validate.

•   skip_ipv6_addr -- When URL string cannot contain an IPv6 address.

•   skip_ipv4_addr -- When URL string cannot contain an IPv4 address.

•   may_have_port -- URL string may contain port number.

•   simple_host -- URL string maybe only hyphens and alpha-numerals.

•   strict_query -- Fail validation on query string parsing error.

•   consider_tld -- Restrict domain to TLDs allowed by IANA.

•   private -- Embedded IP address is public if False, private/local if True.

•   rfc_1034 -- Allow trailing dot in domain/host name. Ref: [RFC 1034](https://www.rfc-editor.org/rfc/rfc1034).

•   rfc_2782 -- Domain/Host name is of type service record. Ref: [RFC 2782](https://www.rfc-editor.org/rfc/rfc2782).

•   validate_scheme -- Function that validates URL scheme.

Returns
    If value is a valid url. (ValidationError): If value is an invalid url.

Return type
    (Literal[True])

  utils

validators.utils.ValidationError(function: Callable[[...], Any], arg_dict: Dict[str, Any], message: str = '')
    Exception class when validation failure occurs.

validators.utils.validator(func: Callable[[...], Any])
    A decorator that makes given function validator.

    Whenever the given func returns False this decorator returns ValidationError object.

    Examples

    >>> @validator
    ... def even(value):
    ...     return not (value % 2)
    >>> even(4)
    True
    >>> even(5)
    ValidationError(func=even, args={'value': 5})

Parameters
    func -- Function which is to be decorated.

Returns
    A decorator which returns either ValidationError or Literal[True].

Return type
    (Callable[..., ValidationError | Literal[True]])

Raises
    (ValidationError) -- If r_ve or RAISE_VALIDATION_ERROR is True

  uuid

validators.uuid.uuid(value: str | UUID, /)
    Return whether or not given value is a valid UUID-v4 string.

    This validator is based on [WTForms UUID validator][1].

    [1]: https://github.com/wtforms/wtforms/blob/master/src/wtforms/validators.py#L539

    Examples

    >>> uuid('2bc1c94f-0deb-43e9-92a1-4775189ec9f8')
    True
    >>> uuid('2bc1c94f 0deb-43e9-92a1-4775189ec9f8')
    ValidationError(func=uuid, args={'value': '2bc1c94f 0deb-43e9-92a1-4775189ec9f8'})

Parameters
    value -- UUID string or object to validate.

Returns
    If value is a valid UUID. (ValidationError): If value is an invalid UUID.

Return type
    (Literal[True])

AUTHOR
Konsta Vesterinen

COPYRIGHT
2013 - 2025, Konsta Vesterinen