<commit_before>******
verify
******

|version| |travis| |coveralls| |license|

Verify is a painless assertion library for Python.


Links
=====

- Project: https://github.com/dgilland/verify
- Documentation: http://verify.readthedocs.org
- PyPI: https://pypi.python.org/pypi/verify/
- TravisCI: https://travis-ci.org/dgilland/verify


Quickstart
==========

Install using pip:


::

    pip install verify


Verify some value using multiple assertions:


.. code-block:: python

    from verify import expect, Not, Truthy, Falsy, Less, Greater

    expect(5 * 5,
           Truthy(),
           Not(Falsy),
           Greater(15),
           Less(30))


Verify using your own assert functions:


.. code-block:: python

    def is_just_right(value):
        assert value == 'just right', 'Not just right!'

    # Passes
    expect('just right', is_just_right)

    # Fails
    try:
        expect('too cold', is_just_right)
    except AssertionError:
        raise

**NOTE:** The assert function should return a truthy value, otherwise, ``expect`` will treat the falsy return from the function as an indication that it failed and subsequently raise it's own ``AssertionError``.

Or your own predicate functions:


.. code-block:: python

    def is_awesome(value):
        return 'awesome' in value

    def is_more_awesome(value):
        return value > 'awesome'

    expect('so awesome', is_awesome, is_more_awesome)


Or use chaining syntax:

.. code-block:: python

    expect(1).Truthy().Number().NotBoolean().Not(is_awesome)


But you don't have to use ``expect`` since the ``verify`` assertions can also be used on their own:


.. code-block:: python

    import verify

    # These would pass.
    verify.Truthy(1)
    verify.Equal(2, 2)
    verify.Greater(3, 2)

    # These would fail with an AssertionError
    verify.Truthy(0)
    verify.Equal(2, 3)
    verify.Greater(2, 3)


And if you'd prefer to see ``assert`` being used, all ``verify`` assertions will return truthy if no ``AssertionError`` is raised:


.. code-block:: python

    assert Truthy(1)
    assert expect(1, Truthy(), Number())

More natural syntax
===================

You can also use more natural syntax using ``ensure`` alias for ``expect`` and
prefixes ``to_be_*`` or ``is_*``:

.. code-block:: python

    expect(some_var).to_be_int().to_be_less_or_equal(5).to_be_not_list()
    ensure(some_var).is_int().is_less_or_equal(5).is_not_list()
    # Both above lines are the same as:
    expect(some_var).Int().LessOrEqual(5).NotList()

All assertions can be also used in snake case format:

.. code-block:: python

    expect(value).contains(5)
    # The same as:
    expect(value).Contains(5)

    expect(value).not_in(some_set)
    # The same as:
    expect(value).NotIn(some_set)

There are few special cases:

* ``Not`` is available through ``does_not``, ``fails`` and ``to_fail``
* ``Predicate`` is available through ``does``, ``passes`` and ``to_pass``
* ``Is`` is available through ``is_``
* ``In`` is available through ``in_``

.. code-block:: python

    def have_access_rights(user):
        return user.is_admin is True

    expect(user).does(have_access_rights)
    expect(user).to_pass(have_access_rights)
    ensure(user).passes(have_access_rights)
    # Equal to:
    expect(user).Predicate(have_access_rights)

    expect(user).does_not(have_access_rights)
    expect(user).to_fail(have_access_rights)
    ensure(user).fails(have_access_rights)
    # Equal to:
    expect(user).Not(have_access_rights)

    ensure(some_value).in_(some_set)
    # Equal to:
    ensure(some_value).In(some_set)

    ensure(result).is_(MyClass)
    # Equal to:
    ensure(result).Is(MyClass)


Reserved names
--------------

Things that don't work as expected:

.. code-block:: python

    expect(value).is_not(predicate)  # translated into IsNot assertion
    expect('v').in('verify')  # syntax error, try `to_be_in`

Validators
==========

All of the validators in ``verify`` are callables that can be used in two contexts:
<commit_msg>Update README with expanded description of alternative syntaxes.<commit_after>******
verify
******

|version| |travis| |coveralls| |license|

Verify is a painless assertion library for Python.


Links
=====

- Project: https://github.com/dgilland/verify
- Documentation: http://verify.readthedocs.org
- PyPI: https://pypi.python.org/pypi/verify/
- TravisCI: https://travis-ci.org/dgilland/verify


Quickstart
==========

Install using pip:


::

    pip install verify


Verify some value using multiple assertions:


.. code-block:: python

    from verify import expect, Not, Truthy, Falsy, Less, Greater

    expect(5 * 5,
           Truthy(),
           Not(Falsy),
           Greater(15),
           Less(30))


Verify using your own assert functions:


.. code-block:: python

    def is_just_right(value):
        assert value == 'just right', 'Not just right!'

    # Passes
    expect('just right', is_just_right)

    # Fails
    try:
        expect('too cold', is_just_right)
    except AssertionError:
        raise

**NOTE:** The assert function should return a truthy value, otherwise, ``expect`` will treat the falsy return from the function as an indication that it failed and subsequently raise it's own ``AssertionError``.


Verify using your own predicate functions:


.. code-block:: python

    def is_awesome(value):
        return 'awesome' in value

    def is_more_awesome(value):
        return value > 'awesome'

    expect('so awesome', is_awesome, is_more_awesome)


Verify using chaining syntax:


.. code-block:: python

    expect(1).Truthy().Number().NotBoolean().Not(is_awesome)


Verify without ``expect`` since the ``verify`` assertions can be used on their own:


.. code-block:: python

    import verify

    # These would pass.
    verify.Truthy(1)
    verify.Equal(2, 2)
    verify.Greater(3, 2)

    # These would fail with an AssertionError
    verify.Truthy(0)
    verify.Equal(2, 3)
    verify.Greater(2, 3)


If you'd prefer to see ``assert`` being used, all ``verify`` assertions will return ``True`` if no ``AssertionError`` is raised:


.. code-block:: python

    assert Truthy(1)
    assert expect(1, Truthy(), Number())


Multiple Syntax Styles
======================

There are several syntax styles available to help construct more natural sounding assertion chains.


Expect...To Be
--------------

Use ``expect`` with the ``to_be`` aliases. All Pascal case assertions have ``to_be_*`` and ``to_not_be_*`` prefixes (with a few expections).

.. code-block:: python

    expect(something).to_be_int().to_be_less_or_equal(5).to_be_greater_or_equal(1)
    expect(something_else).to_not_be_float().to_be_number()


Ensure...Is
-----------

Use ``ensure`` with ``is`` aliases. All Pascal case assertions have ``is_*`` and ``is_not_*`` prefixes (with a few expections).


.. code-block:: python

    ensure(something).is_int().is_less_or_equal(5).is_greater_or_equal(1)
    ensure(something_else).is_not_float().is_number()


Classical
---------

Use ``expect`` or ``ensure`` with the Pascal case assertions.

.. code-block:: python

    ensure(something).Int().LessOrEqual(5).GreaterOrEqual(1)
    expect(something_else).Float().Number()


**NOTE:** While it's suggested to not mix styles, each of the assertion syntaxes are available with both ``expect`` and ``ensure``. So you can call ``expect(..).is_int()`` as well as ``ensure(..).to_be_int()``.


Naming Convention Exceptions
----------------------------

As mentioned above, there are some assertions that have nonstandard aliases:

- ``Not``:  ``not_``, ``does_not``, ``to_fail``, and ``fails``
- ``Predicate``: ``does``, ``to_pass``, and ``passes``
- ``All``: ``all_``, ``does_all``, and ``passes_all``
- ``NotAll``: ``not_all``, ``does_not_all``, and ``fails_all``
- ``Any``: ``any_``, ``does_any``, and ``passes_any``
- ``NotAny``: ``not_any``, ``does_not_any``, and ``fails_any``
- ``Match``: ``to_match``, ``is_match`` and ``matches``
- ``NotMatch``: ``to_not_match``, ``is_not_match`` and ``does_not_match``
- ``Is``: ``to_be`` and ``is_``
- ``Contains``: ``to_contain`` and ``contains``
- ``NotContains``: ``to_not_contain`` and ``does_not_contain``
- ``ContainsOnly``: ``to_contain_only`` and ``contains_only``
- ``NotContainsOnly``: ``to_not_contain_only`` and ``does_not_contain_only``
- ``Length``: ``to_have_length`` and ``has_length``
- ``NotLength``: ``to_not_have_length`` and ``does_not_have_length``


Validators
==========

All of the validators in ``verify`` are callables that can be used in two contexts:

{'fraction_non_alphanumeric': 0.15883040935672516, 'fraction_numerical': 0.005730994152046784, 'mean_word_length': 3.7112947658402202, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1108449', 'n_tokens_mistral': 2854, 'n_tokens_neox': 2715, 'n_words': 780}