Skip to content

Commit 8933ab2

Browse files
committed
Merge pull request #1 from jpvanhal/doc-improvements
Documentation improvements
2 parents d162526 + 67d081a commit 8933ab2

16 files changed

Lines changed: 183 additions & 158 deletions

‎.travis.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ python:
77
install:
88
- pip install -e ".[test]"
99
script:
10-
- py.test
10+
- py.test --doctest-glob="*.rst" --doctest-modules --ignore=setup.py

‎CHANGES.rst‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,47 @@
11
Changelog
22
---------
33

4+
0.7.0 (not yet released)
5+
^^^^^^^^^^^^^^^^^^^^^^^^
6+
7+
- Fixed errors in code examples.
8+
- Fixed ``TypeError`` when using ``between`` validator with ``datetime`` objects
9+
like in the code example.
10+
- Changed validators to always return ``True`` instead of a truthy object when
11+
the validation succeeds.
12+
- Fixed ``truthy`` validator to work like it's name suggests. Previously it
13+
worked like ``falsy``.
414

515
0.6.0 (2014-06-25)
616
^^^^^^^^^^^^^^^^^^
717

8-
- Added new validator: slug
18+
- Added new validator: ``slug``
919

1020

1121
0.5.0 (2013-10-31)
1222
^^^^^^^^^^^^^^^^^^
1323

14-
- Renamed finnish_business_id to fi_business_id
15-
- Added new validator: fi_ssn
24+
- Renamed ``finnish_business_id`` to ``fi_business_id``
25+
- Added new validator: ``fi_ssn``
1626

1727

1828
0.4.0 (2013-10-29)
1929
^^^^^^^^^^^^^^^^^^
2030

21-
- Added new validator: finnish_business_id
31+
- Added new validator: ``finnish_business_id``
2232

2333

2434
0.3.0 (2013-10-27)
2535
^^^^^^^^^^^^^^^^^^
2636

27-
- number_range -> between
37+
- ``number_range`` -> ``between``
2838

2939

3040
0.2.0 (2013-10-22)
3141
^^^^^^^^^^^^^^^^^^
3242

33-
- Various new validators: ipv4, ipv6, length, number_range, mac_address, url, uuid
43+
- Various new validators: ``ipv4``, ``ipv6``, ``length``, ``number_range``,
44+
``mac_address``, ``url``, ``uuid``
3445

3546

3647
0.1.0 (2013-10-18)

‎README.rst‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,17 @@ validators
33

44
Python data validation for Humans.
55

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

7-
Python has all kinds of data validation tools, but every one of them seems to require defining a schema / form. I wanted to create a simple validation library where validating a simple value does not require defining a form or a schema.
11+
.. code-block:: python
812
13+
>>> import validators
914
10-
::
11-
12-
13-
import validators
14-
15-
16-
validators.email('someone@example.com')
17-
# True
18-
15+
>>> validators.email('someone@example.com')
16+
True
1917
2018
2119
Resources

‎docs/index.rst‎

Lines changed: 27 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -7,60 +7,56 @@ Python Data Validation for Humans™.
77
Why?
88
====
99

10-
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: http://opensourcehacker.com/2011/07/07/generic-python-validation-frameworks/
10+
Python has all kinds of validation tools, but every one of them requires
11+
defining a schema. I wanted to create a simple validation library where
12+
validating a simple value does not require defining a form or a schema.
13+
Apparently `some other guys have felt the same way`_.
1114

12-
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:
15+
.. _some other guys have felt the same way:
16+
http://opensourcehacker.com/2011/07/07/generic-python-validation-frameworks/
1317

14-
::
18+
Often I've had for example a case where I just wanted to check if given string
19+
is an email. With ``validators`` this use case becomes as easy as::
1520

1621
>>> import validators
1722

18-
1923
>>> validators.email('someone@example.com')
2024
True
2125

2226

2327
Installation
2428
============
2529

26-
27-
::
28-
30+
You can install ``validators`` using pip::
2931

3032
pip install validators
3133

32-
33-
Currently validators supports python versions 2.6, 2.7 and 3.3.
34+
Currently ``validators`` supports Python versions 2.6, 2.7 and 3.3.
3435

3536

3637
Basic validators
3738
================
3839

39-
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.
40-
41-
ValidationFailure class implements __bool__ method so you can easily check if validation failed:
42-
43-
::
44-
45-
46-
if not email('some_bogus_email@@@'):
47-
# Do something here
48-
pass
49-
50-
51-
ValidationFailure object also holds all the arguments passed to original function:
52-
53-
::
40+
Each validator in ``validators`` is a simple function that takes the value to
41+
validate and possibly some additional key-value arguments. Each function returns
42+
``True`` when validation succeeds and
43+
:class:`~validators.utils.ValidationFailure` object when validation fails.
5444

45+
:class:`~validators.utils.ValidationFailure` class implements ``__bool__``
46+
method so you can easily check if validation failed::
5547

56-
result = number_range(3, min=5)
57-
if not result:
58-
result.value
59-
# 3
48+
>>> if not validators.email('some_bogus_email@@@'):
49+
... # Do something here
50+
... pass
6051

61-
result.min
62-
# 5
52+
:class:`~validators.utils.ValidationFailure` object also holds all the arguments
53+
passed to original function::
6354

55+
>>> result = validators.between(3, min=5)
56+
>>> result.value
57+
3
58+
>>> result.min
59+
5
6460

6561

6662
between
@@ -165,4 +161,5 @@ validator
165161

166162
.. module:: validators.utils
167163

164+
.. autoclass:: ValidationFailure
168165
.. autofunction:: validator

‎validators/between.py‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
@validator
66
def between(value, min=None, max=None):
77
"""
8-
Validates that a number is between minimum and/or maximum value.
8+
Validate that a number is between minimum and/or maximum value.
9+
910
This will work with any comparable type, such as floats, decimals and dates
1011
not just integers.
1112
@@ -16,21 +17,22 @@ def between(value, min=None, max=None):
1617
1718
Examples::
1819
19-
>>> import validators
20+
>>> from datetime import datetime
2021
21-
>>> assert validators.between(5, min=2)
22+
>>> between(5, min=2)
23+
True
2224
23-
>>> assert validators.between(13.2, min=13, max=14)
25+
>>> between(13.2, min=13, max=14)
26+
True
2427
25-
>>> assert not validators.between(500, max=400)
28+
>>> between(500, max=400)
29+
ValidationFailure(func=between, args=...)
2630
27-
>>> from datetime import datetime
28-
29-
>>> assert validator.between(
31+
>>> between(
3032
... datetime(2000, 11, 11),
3133
... min=datetime(1999, 11, 11)
3234
... )
33-
35+
True
3436
3537
:param min:
3638
The minimum required value of the number. If not provided, minimum
@@ -49,7 +51,11 @@ def between(value, min=None, max=None):
4951
min = Min
5052
if max is None:
5153
max = Max
52-
if min > max:
54+
try:
55+
min_gt_max = min > max
56+
except TypeError:
57+
min_gt_max = max < min
58+
if min_gt_max:
5359
raise AssertionError('`min` cannot be more than `max`.')
5460

55-
return min <= value <= max
61+
return min <= value and max >= value

‎validators/email.py‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,19 @@
2525
@validator
2626
def email(value, whitelist=None):
2727
"""
28-
Validates an email address. This validator is based on `Django's
29-
email validator`_. Returns True on success and `:class:FailedValidation`
30-
when validation fails.
28+
Validate an email address.
3129
30+
This validator is based on `Django's email validator`_. Returns
31+
``True`` on success and :class:`~validators.utils.ValidationFailure`
32+
when validation fails.
3233
3334
Examples::
3435
36+
>>> email('someone@example.com')
37+
True
3538
36-
>>> assert validators.email('someone@example.com')
37-
38-
>>> assert not validators.email('bogus@@')
39-
39+
>>> email('bogus@@')
40+
ValidationFailure(func=email, ...)
4041
4142
.. _Django's email validator:
4243
https://github.com/django/django/blob/master/django/core/validators.py

‎validators/extremes.py‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,16 @@ class Min(object):
1313
Inspired by https://pypi.python.org/pypi/Extremes
1414
1515
Examples::
16-
>>> import validators
16+
1717
>>> import sys
1818
19-
>>> validators.Min < -sys.maxint
19+
>>> Min < -sys.maxint
2020
True
21-
>>> validators.Min < None
21+
22+
>>> Min < None
2223
True
23-
>>> validators.Min < ''
24+
25+
>>> Min < ''
2426
True
2527
2628
.. versionadded:: 0.2
@@ -38,18 +40,17 @@ class Max(object):
3840
3941
Inspired by https://pypi.python.org/pypi/Extremes
4042
41-
4243
Examples::
4344
44-
45-
>>> import validators
4645
>>> import sys
4746
48-
>>> validators.Max > validators.Min
47+
>>> Max > Min
4948
True
50-
>>> validators.Max > sys.maxint
49+
50+
>>> Max > sys.maxint
5151
True
52-
>>> validators.Max > 99999999999999999
52+
53+
>>> Max > 99999999999999999
5354
True
5455
5556
.. versionadded:: 0.2

‎validators/i18n/fi.py‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,25 @@
1919
@validator
2020
def fi_business_id(business_id):
2121
"""
22-
Validates a Finnish Business ID. Each company in Finland has a distinct
23-
business id. For more information see `Finnish Trade Register`_
22+
Validate a Finnish Business ID.
23+
24+
Each company in Finland has a distinct business id. For more
25+
information see `Finnish Trade Register`_
2426
2527
.. _Finnish Trade Register:
2628
http://en.wikipedia.org/wiki/Finnish_Trade_Register
2729
28-
::
30+
Examples::
2931
30-
>>> assert fi_business_id('0112038-9') # Fast Monkeys Ltd
32+
>>> fi_business_id('0112038-9') # Fast Monkeys Ltd
33+
True
3134
32-
>>> assert not fi_business_id('1234567-8') # Bogus ID
35+
>>> fi_business_id('1234567-8') # Bogus ID
36+
ValidationFailure(func=fi_business_id, ...)
3337
3438
.. versionadded:: 0.4
3539
.. versionchanged:: 0.5
36-
Method renamed from finnish_business_id to fi_business_id
40+
Method renamed from ``finnish_business_id`` to ``fi_business_id``
3741
3842
:param business_id: business_id to validate
3943
"""
@@ -50,18 +54,20 @@ def fi_business_id(business_id):
5054
@validator
5155
def fi_ssn(ssn):
5256
"""
53-
Validates a Finnish Social Security Number. This validator is based on
54-
`django-localflavor-fi`_.
57+
Validate a Finnish Social Security Number.
58+
59+
This validator is based on `django-localflavor-fi`_.
5560
5661
.. _django-localflavor-fi:
5762
https://github.com/django/django-localflavor-fi/
5863
59-
::
60-
61-
>>> assert fi_ssn('010101-0101')
64+
Examples::
6265
63-
>>> assert not fi_ssn('101010-0102')
66+
>>> fi_ssn('010101-0101')
67+
True
6468
69+
>>> fi_ssn('101010-0102')
70+
ValidationFailure(func=fi_ssn, args={'ssn': '101010-0102'})
6571
6672
.. versionadded:: 0.5
6773

0 commit comments

Comments
 (0)