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.

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

RESOURCES

•   Documentation

•   Bugtracker

•   Security

•   Code

    ----

    Python 3.8 reaches EOL in October 2024.

  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)
    # Output: True
    >>> between(13.2, min_val=13, max_val=14)
    # Output: True
    >>> between(500, max_val=400)
    # Output: ValidationError(func=between, args=...)
    >>> between(
    ...     datetime(2000, 11, 11),
    ...     min_val=datetime(1999, 11, 11)
    ... )
    # Output: 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')
    # Output: True
    >>> amex('4242424242424242')
    # Output: 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')
    # Output: True
    >>> card_number('4242424242424241')
    # Output: 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')
    # Output: True
    >>> diners('4242424242424242')
    # Output: 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')
    # Output: True
    >>> discover('4242424242424242')
    # Output: 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')
    # Output: True
    >>> jcb('4242424242424242')
    # Output: 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')
    # Output: True
    >>> mastercard('4242424242424242')
    # Output: 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.unionpay(value: str, /)
    Return whether or not given value is a valid UnionPay card number.

    Examples

    >>> unionpay('6200000000000005')
    # Output: True
    >>> unionpay('4242424242424242')
    # Output: 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')
    # Output: True
    >>> visa('2223003122003222')
    # Output: 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')
    # Output: True
    >>> calling_code('-31')
    # Output: 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')
    # Output: False
    >>> country_code('USA')
    # Output: True
    >>> country_code('840', iso_format='numeric')
    # Output: True
    >>> country_code('iN', iso_format='alpha2')
    # Output: False
    >>> country_code('ZWE', iso_format='alpha3')
    # Output: 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')
    # Output: True
    >>> currency('ZWX')
    # Output: 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 * * * *')
    # Output: True
    >>> cron('30-20 * * * *')
    # Output: ValidationError(func=cron, ...)

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')
    # Output: True
    >>> bsc_address('0x4g5acf9684652BEa56F2f01b7101a225Eh33d23z')
    # Output: ValidationError(func=bsc_address, args=...)

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')
    # Output: True
    >>> btc_address('1BvBMsEYstWetqTFn5Au4m4GFg7xJaNVN2')
    # Output: ValidationError(func=btc_address, args=...)

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')
    # Output: True
    >>> eth_address('0x8Ba1f109551bD432803012645Ac136ddd64DBa72')
    # Output: ValidationError(func=eth_address, args=...)

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')
    # Output: True
    >>> trx_address('TR2G7Rm4vFqF8EpY4U5xdLdQ7XgJ2U8Vd')
    # Output: ValidationError(func=trx_address, args=...)

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')
    # Output: True
    >>> domain('example.com/')
    # Output: ValidationError(func=domain, ...)
    >>> # Supports IDN domains as well::
    >>> domain('xn----gtbspbbmkef.xn--p1ai')
    # Output: 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')
    # Output: True
    >>> email('bogus@@')
    # Output: ValidationError(email=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')
    # Output: True
    >>> base16('a3f4Z1')
    # Output: 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======')
    # Output: True
    >>> base32('MfZW3zLT9Q======')
    # Output: 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')
    # Output: True
    >>> base58('cUSECm5YzcXJwP')
    # Output: ValidationError(func=base58, args={'value': 'cUSECm5YzcXJwP'})

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==')
    # Output: True
    >>> base64('cUSECm5YzcXJwP')
    # Output: 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')
    ValidationFailure(func=cusip, ...)

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')
    True
    >>> isin('037833DP3')
    ValidationFailure(func=isin, ...)

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')
    ValidationFailure(func=sedol, ...)

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')
    # Output: True
    >>> md5('900zz11')
    # Output: 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')
    # Output: True
    >>> sha1('900zz11')
    # Output: 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')
    # Output: True
    >>> sha224('900zz11')
    # Output: 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'
    ... )
    # Output: True
    >>> sha256('900zz11')
    # Output: 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'
    ... )
    # Output: True
    >>> sha384('900zz11')
    # Output: 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'
    ... )
    # Output: True
    >>> sha512('900zz11')
    # Output: 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")
    # Output: True
    >>> hostname("this-pc")
    # Output: True
    >>> hostname("xn----gtbspbbmkef.xn--p1ai:65535")
    # Output: True
    >>> hostname("_example.com")
    # Output: True
    >>> hostname("123.5.77.88:31000")
    # Output: True
    >>> hostname("12.12.12.12")
    # Output: True
    >>> hostname("[::1]:22")
    # Output: True
    >>> hostname("dead:beef:0:0:0:0000:42:1")
    # Output: True
    >>> hostname("[0:0:0:0:0:ffff:1.2.3.4]:-65538")
    # Output: ValidationError(func=hostname, ...)
    >>> hostname("[0:&:b:c:@:e:f::]:9999")
    # Output: ValidationError(func=hostname, ...)

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')
    # Output: True
    >>> es_cif('B25162529')
    # Output: ValidationError(func=es_cif, args=...)

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')
    # Output: True
    >>> es_doi('X0095892X')
    # Output: ValidationError(func=es_doi, args=...)

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')
    # Output: True
    >>> es_nie('X0095892X')
    # Output: ValidationError(func=es_nie, args=...)

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')
    # Output: True
    >>> es_nif('26643189X')
    # Output: ValidationError(func=es_nif, args=...)

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
    # Output: True
    >>> fi_business_id('1234567-8')  # Bogus ID
    # Output: ValidationError(func=fi_business_id, ...)

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')
    # Output: True
    >>> fi_ssn('101010-0102')
    # Output: ValidationError(func=fi_ssn, args=...)

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
    # Output: True
    >>> fr_department("20")
    # Output: True
    >>> fr_department("971")  # Guadeloupe
    # Output: True
    >>> fr_department("00")
    # Output: ValidationError(func=fr_department, args=...)
    >>> fr_department('2A')  # Corsica
    # Output: True
    >>> fr_department('2B')
    # Output: True
    >>> fr_department('2C')
    # Output: ValidationError(func=fr_department, args=...)

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')
    # Output: True
    >>> fr_ssn('1 84 12 76 451 089')  # control key is optional
    # Output: True
    >>> fr_ssn('3 84 12 76 451 089 46')  # wrong gender number
    # Output: ValidationError(func=fr_ssn, args=...)
    >>> fr_ssn('1 84 12 76 451 089 47')  # wrong control key
    # Output: ValidationError(func=fr_ssn, args=...)

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')
    ValidationFailure(func=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')
    ValidationFailure(func=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])

  iban

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

    Examples

    >>> iban('DE29100500001061045672')
    # Output: True
    >>> iban('123456')
    # Output: ValidationError(func=iban, ...)

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')
    # Output: True
    >>> ipv4('1.1.1.1/8')
    # Output: True
    >>> ipv4('900.80.70.11')
    # Output: 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')
    # Output: True
    >>> ipv6('::1/128')
    # Output: True
    >>> ipv6('abc.0.0.1')
    # Output: 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)
    # Output: True
    >>> length('something', min_val=9, max_val=9)
    # Output: True
    >>> length('something', max_val=5)
    # Output: ValidationError(func=length, ...)

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')
    # Output: True
    >>> mac_address('00:00:00:00:00')
    # Output: 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')
    # Output: True
    >>> slug('my.slug')
    # Output: 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)
    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')
    # Output: True
    >>> url('ftp://foobar.dk')
    # Output: True
    >>> url('http://10.0.0.1')
    # Output: True
    >>> url('http://example.com/">user@example.com')
    # Output: ValidationError(func=url, ...)

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).

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)
    # Output: True
    >>> even(5)
    # Output: 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')
    # Output: True
    >>> uuid('2bc1c94f 0deb-43e9-92a1-4775189ec9f8')
    # Output: ValidationError(func=uuid, ...)

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 - 2024, Konsta Vesterinen