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.
btc_address¶
- validators.btc_address.btc_address(value)[source]¶
Return whether or not given value is a valid bitcoin address.
If the value is valid bitcoin address this function returns
True
, otherwiseValidationFailure
.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
- Parameters:
value – Bitcoin address string to validate
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
, otherwiseValidationFailure
.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 andValidationFailure
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:
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
, otherwiseValidationFailure
.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 a 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 a 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
, otherwiseValidationFailure
.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¶
sha1¶
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
, otherwiseValidationFailure
.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
, otherwiseValidationFailure
.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 value 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
tofi_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¶
- 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 returnsValidationFailure
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