validators

Python Data Validation for Humans™.

Why?

Python has all kinds of validation tools, but every one of them requires defining a schema. I wanted to create a simple validation library where validating a simple value does not require defining a form or a schema. Apparently some other guys have felt the same way.

Often I’ve had for example a case where I just wanted to check if given string is an email. With validators this use case becomes as easy as:

>>> import validators

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

Installation

You can install validators using pip:

pip install validators

Currently validators supports python versions 2.7, 3.3, 3.4, 3.5, 3.6, 3.7 and PyPy.

Basic validators

Each validator in validators is a simple function that takes the value to validate and possibly some additional key-value arguments. Each function returns True when validation succeeds and ValidationFailure object when validation fails.

ValidationFailure class implements __bool__ method so you can easily check if validation failed:

>>> if not validators.email('some_bogus_email@@@'):
...     # Do something here
...     pass

ValidationFailure object also holds all the arguments passed to original function:

>>> result = validators.between(3, min=5)
>>> result.value
3
>>> result.min
5

between

validators.between.between(value, min=None, max=None)[source]

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.

Examples:

>>> from datetime import datetime

>>> between(5, min=2)
True

>>> between(13.2, min=13, max=14)
True

>>> between(500, max=400)
ValidationFailure(func=between, args=...)

>>> between(
...     datetime(2000, 11, 11),
...     min=datetime(1999, 11, 11)
... )
True
Parameters
  • min – The minimum required value of the number. If not provided, minimum value will not be checked.

  • max – The maximum value of the number. If not provided, maximum value will not be checked.

New in version 0.2.

domain

validators.domain.domain(value)[source]

Return whether or not given value is a valid domain.

If the value is valid domain name this function returns True, otherwise ValidationFailure.

Examples:

>>> domain('example.com')
True

>>> domain('example.com/')
ValidationFailure(func=domain, ...)

Supports IDN domains as well:

>>> domain('xn----gtbspbbmkef.xn--p1ai')
True

New in version 0.9.

Changed in version 0.10: Added support for internationalized domain name (IDN) validation.

Parameters

value – domain string to validate

email

validators.email.email(value, whitelist=None)[source]

Validate an email address.

This validator is based on Django’s email validator. Returns True on success and ValidationFailure when validation fails.

Examples:

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

>>> email('bogus@@')
ValidationFailure(func=email, ...)

New in version 0.1.

Parameters
  • value – value to validate

  • whitelist – domain names to whitelist

Copyright
  1. Django Software Foundation and individual contributors.

License

BSD

iban

validators.iban.iban(value)[source]

Return whether or not given value is a valid IBAN code.

If the value is a valid IBAN this function returns True, otherwise ValidationFailure.

Examples:

>>> iban('DE29100500001061045672')
True

>>> iban('123456')
ValidationFailure(func=iban, ...)

New in version 0.8.

Parameters

value – IBAN string to validate

ipv4

validators.ip_address.ipv4(value)[source]

Return whether or not given value is a valid IP version 4 address.

This validator is based on WTForms IPAddress validator

Examples:

>>> ipv4('123.0.0.7')
True

>>> ipv4('900.80.70.11')
ValidationFailure(func=ipv4, args={'value': '900.80.70.11'})

New in version 0.2.

Parameters

value – IP address string to validate

ipv6

validators.ip_address.ipv6(value)[source]

Return whether or not given value is a valid IP version 6 address (including IPv4-mapped IPv6 addresses).

This validator is based on WTForms IPAddress validator.

Examples:

>>> ipv6('abcd:ef::42:1')
True

>>> ipv6('::ffff:192.0.2.128')
True

>>> ipv6('::192.0.2.128')
True

>>> ipv6('abc.0.0.1')
ValidationFailure(func=ipv6, args={'value': 'abc.0.0.1'})

New in version 0.2.

Parameters

value – IP address string to validate

length

validators.length.length(value, min=None, max=None)[source]

Return whether or not the length of given string is within a specified range.

Examples:

>>> length('something', min=2)
True

>>> length('something', min=9, max=9)
True

>>> length('something', max=5)
ValidationFailure(func=length, ...)
Parameters
  • value – The string to validate.

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

  • max – The maximum length of the string. If not provided, maximum length will not be checked.

New in version 0.2.

mac_address

validators.mac_address.mac_address(value)[source]

Return whether or not given value is a valid MAC address.

If the value is valid MAC address this function returns True, otherwise ValidationFailure.

This validator is based on WTForms MacAddress validator.

Examples:

>>> mac_address('01:23:45:67:ab:CD')
True

>>> mac_address('00:00:00:00:00')
ValidationFailure(func=mac_address, args={'value': '00:00:00:00:00'})

New in version 0.2.

Parameters

value – Mac address string to validate

md5

validators.hashes.md5(value)[source]

Return whether or not given value is a valid MD5 hash.

Examples:

>>> md5('d41d8cd98f00b204e9800998ecf8427e')
True

>>> md5('900zz11')
ValidationFailure(func=md5, args={'value': '900zz11'})
Parameters

value – MD5 string to validate

sha1

validators.hashes.sha1(value)[source]

Return whether or not given value is a valid SHA1 hash.

Examples:

>>> sha1('da39a3ee5e6b4b0d3255bfef95601890afd80709')
True

>>> sha1('900zz11')
ValidationFailure(func=sha1, args={'value': '900zz11'})
Parameters

value – SHA1 string to validate

sha224

validators.hashes.sha224(value)[source]

Return whether or not given value is a valid SHA224 hash.

Examples:

>>> sha224('d14a028c2a3a2bc9476102bb288234c415a2b01f828ea62ac5b3e42f')
True

>>> sha224('900zz11')
ValidationFailure(func=sha224, args={'value': '900zz11'})
Parameters

value – SHA224 string to validate

sha256

validators.hashes.sha256(value)[source]

Return whether or not given value is a valid SHA256 hash.

Examples:

>>> sha256(
...     'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b'
...     '855'
... )
True

>>> sha256('900zz11')
ValidationFailure(func=sha256, args={'value': '900zz11'})
Parameters

value – SHA256 string to validate

sha512

validators.hashes.sha512(value)[source]

Return whether or not given value is a valid SHA512 hash.

Examples:

>>> sha512(
...     'cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce'
...     '9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af9'
...     '27da3e'
... )
True

>>> sha512('900zz11')
ValidationFailure(func=sha512, args={'value': '900zz11'})
Parameters

value – SHA512 string to validate

slug

validators.slug.slug(value)[source]

Validate whether or not given value is valid slug.

Valid slug can contain only alphanumeric characters, hyphens and underscores.

Examples:

>>> slug('my.slug')
ValidationFailure(func=slug, args={'value': 'my.slug'})

>>> slug('my-slug-2134')
True

New in version 0.6.

Parameters

value – value to validate

truthy

validators.truthy.truthy(value)[source]

Validate that given value is not a falsey value.

This validator is based on WTForms DataRequired validator.

Examples:

>>> truthy(1)
True

>>> truthy('someone')
True

>>> truthy(0)
ValidationFailure(func=truthy, args={'value': 0})

>>> truthy('    ')
ValidationFailure(func=truthy, args={'value': '    '})

>>> truthy(False)
ValidationFailure(func=truthy, args={'value': False})

>>> truthy(None)
ValidationFailure(func=truthy, args={'value': None})

New in version 0.2.

url

validators.url.url(value, public=False)[source]

Return whether or not given value is a valid URL.

If the value is valid URL this function returns True, otherwise ValidationFailure.

This validator is based on the wonderful URL validator of dperini.

Examples:

>>> url('http://foobar.dk')
True

>>> url('ftp://foobar.dk')
True

>>> url('http://10.0.0.1')
True

>>> url('http://foobar.d')
ValidationFailure(func=url, ...)

>>> url('http://10.0.0.1', public=True)
ValidationFailure(func=url, ...)

New in version 0.2.

Changed in version 0.10.2: Added support for various exotic URLs and fixed various false positives.

Changed in version 0.10.3: Added public parameter.

Changed in version 0.11.0: Made the regular expression this function uses case insensitive.

Changed in version 0.11.3: Added support for URLs containing localhost

Parameters
  • value – URL address string to validate

  • public – (default=False) Set True to only allow a public IP address

uuid

validators.uuid.uuid(value)[source]

Return whether or not given value is a valid UUID.

If the value is valid UUID this function returns True, otherwise ValidationFailure.

This validator is based on WTForms UUID validator.

Examples:

>>> uuid('2bc1c94f-0deb-43e9-92a1-4775189ec9f8')
True

>>> uuid('2bc1c94f 0deb-43e9-92a1-4775189ec9f8')
ValidationFailure(func=uuid, ...)

New in version 0.2.

Parameters

value – UUID string to validate

i18n validators

Spanish

es_doi

validators.i18n.es.es_doi(doi)[source]

Validate a Spanish DOI.

A DOI in spain is all NIF / CIF / NIE / DNI – a digital ID. For more information see wikipedia.org/doi.

This validator is based on generadordni.es.

Examples:

>>> es_doi('X0095892M')
True

>>> es_doi('X0095892X')
ValidationFailure(func=es_doi, args=...)

New in version 0.13.0.

Parameters

doi – DOI to validate

es_nif

validators.i18n.es.es_nif(doi)[source]

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.

This validator is based on generadordni.es.

Examples:

>>> es_nif('26643189N')
True

>>> es_nif('26643189X')
ValidationFailure(func=es_nif, args=...)

New in version 0.13.0.

Parameters

doi – DOI to validate

es_nie

validators.i18n.es.es_nie(doi)[source]

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.

This validator is based on generadordni.es.

Examples:

>>> es_nie('X0095892M')
True

>>> es_nie('X0095892X')
ValidationFailure(func=es_nie, args=...)

New in version 0.13.0.

Parameters

doi – DOI to validate

es_cif

validators.i18n.es.es_cif(doi)[source]

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.

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

This validator is based on generadordni.es.

Examples:

>>> es_cif('B25162520')
True

>>> es_cif('B25162529')
ValidationFailure(func=es_cif, args=...)

New in version 0.13.0.

Parameters

doi – DOI to validate

Finnish

fi_business_id

validators.i18n.fi.fi_business_id(business_id)[source]

Validate a Finnish Business ID.

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

Examples:

>>> fi_business_id('0112038-9')  # Fast Monkeys Ltd
True

>>> fi_business_id('1234567-8')  # Bogus ID
ValidationFailure(func=fi_business_id, ...)

New in version 0.4.

Changed in version 0.5: Method renamed from finnish_business_id to fi_business_id

Parameters

business_id – business_id to validate

fi_ssn

validators.i18n.fi.fi_ssn(ssn, allow_temporal_ssn=True)[source]

Validate a Finnish Social Security Number.

This validator is based on django-localflavor-fi.

Examples:

>>> fi_ssn('010101-0101')
True

>>> fi_ssn('101010-0102')
ValidationFailure(func=fi_ssn, args=...)

New in version 0.5.

Parameters
  • ssn – Social Security Number to validate

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

Internals

validator

class validators.utils.ValidationFailure(func, args)[source]
validators.utils.validator(func, *args, **kwargs)[source]

A decorator that makes given function validator.

Whenever the given function is called and returns False value this decorator returns ValidationFailure object.

Example:

>>> @validator
... def even(value):
...     return not (value % 2)

>>> even(4)
True

>>> even(5)
ValidationFailure(func=even, args={'value': 5})
Parameters
  • func – function to decorate

  • args – positional function arguments

  • kwargs – key value function arguments