API Reference¶
The verify module is composed of various assertion callables (in this case, callable classes) that can be called in two contexts:
- By themselves as in
Equal(a, b)which will raise anAssertionErrorifadoes not equalb. - In combination with
expect()as inexpect(a, Equal(b))which could also raise anAssertionError.
Thus, for all assertion classes below, the value argument defaults to
NotSet which is a custom singleton to indicate that nothing was passed in
for value. Whether value is set or NotSet is used to indicate which
context the assertion class is being used. Whenever value is set, the
comparable is swapped with value (internally inside the class’ __init__
method). This allows the assertion to be used in the two contexts above.
This module’s main focus is on testing, which is why all assertions raise an
AssertionError on failure. Therefore, all assertion classes function
similarly:
- If the evaluation of value with comparable returns
False, then anAssertionErroris raised with a custom message. - If the evaluation of value with comparable returns
Trueand the class was only created (e.g.Equal(a, b)), then nothing is raised or returned (obviously, since all we did was create a class instance). - If the evaluation of value with comparable returns
Trueand the class was called (e.g.expect(a, Equal(b))orEqual(b)(a)), thenTrueis returned from the class call.
There are two general types of assertions within this module:
- Assertions that evaulate a single object: value. Referred to here as a plain assertion.
- Assertions that evaulate two objects: value and comparable. Referred to here as a comparator assertion.
When using plain assertions with expect(), you can pass the bare
assertion or initialize it.
>>> expect(True, Truthy)
<expect(True)>
>>> expect(True, Truthy())
<expect(True)>
When using any of the assertions, inserting assert in front is optional as
each assertion will raise if the evaluation is false. However, having that
assert in front may be aesthetically appealing to you, but keep in mind
that any assert message included will not be shown since the assertion error
will occur within the class itself and raised with it’s own custom error
message.
>>> Truthy(True)
<Truthy()>
>>> assert Truthy(True)
# Both of these would raise an assertion error.
>>> Falsy(True)
Traceback (most recent call last):
...
AssertionError: True is not falsy
>>> assert Falsy(True)
Traceback (most recent call last):
...
AssertionError: True is not falsy
# But assert messages will not make it to the traceback.
>>> assert Falsy(True), 'this message will not be shown'
Traceback (most recent call last):
...
AssertionError: True is not falsy
Assertion Runner¶
The expect class is basically an assertion runner that takes an input value and passes it through any number of assertions or predicate functions. If all assertions pass and return truthy, then all is well and True is returned. Otherwise, either one of the assertion functions will raise an AssertionError or no exceptiosn were raised but at least one of the functions returned a non-truthy value which means that expect() will return False.
The expect has alias in the same module under name of ensure, so
you can use both of these names according to your needs.
-
class
verify.runners.expect(value, *assertions)[source]¶ Pass value through a set of assertable functions.
There are two styles for invoking
expect:- Pass value and all assertions as arguments to the
__init__method ofexpect. - Pass value to the
__init__method ofexpectand invoke assertions via method chaining.
Examples
Passing value and assertions to
expect.__init__:>>> from verify import * >>> expect(5, Truthy(), Greater(4)) <expect(5)> >>> expect(5, Falsy()) Traceback (most recent call last): ... AssertionError...
Using method chaining:
>>> expect(5).Truthy().Greater(4) <expect(5)> >>> expect(5).Falsy() Traceback (most recent call last): ... AssertionError...
Parameters: - value (mixed) – Value to test.
- *assertions (callable, optional) – Callable objects that accept value as its first argument. It’s expected that these callables assert something.
Returns: Allows for method assertion chaining.
Return type: self
Raises: AssertionError– If the evaluation of all assertions returnsFalse.- Aliases:
ensure
New in version 0.0.1.
-
Changed in version 0.1.0:
Rename from
Expecttoexpectand change implementation from a class to a function.Passed in value is no longer called if it’s a callable.
Return
Trueif all assertions pass.
-
Changed in version 0.6.0:
Re-implement as class.
Support method chaining of assertion classes.
Wrap assertions that are not derived from Assertion in
Predicatefor consistent behavior from external assertion functions.
- Pass value and all assertions as arguments to the
Assertions¶
For all assertion classes, the value argument is optional, but when provided the assertion will be evaluated immediately. When passing both the value and comparable arguments, be sure that value comes first even though comparable is listed as the first argument. Internally, when both variables are passed in, value and comparable are swapped in order to support late evaulation, i.e., all of the following are equivalent ways to assert validity:
>>> Less(5, 10)
<Less()>
>>> Less(10)(5)
True
>>> expect(5, Less(10))
<expect(5)>
>>> Truthy(5)
<Truthy()>
>>> Truthy()(5)
True
>>> expect(5, Truthy())
<expect(5)>
Below are the various assertion classes that can be used for validation.
Base Classes¶
Base classes and mixins.
-
class
verify.base.Assertion(value=NotSet, **opts)[source]¶ Base class for assertions.
If value is not provided, then assertion isn’t executed. This style of usage is used in conjuction with
expect.If value is provided, then assertion is executed immediately. This style of usage is used when making assertions using only the class and not an assertion runner like
expect.Keyword Arguments: msg (str, optional) – Override assert message to use when performing assertion. -
__call__(*args, **opts)[source]¶ Execute validation.
Keyword Arguments: msg (str, optional) – Override assert message to use when performing assertion. Returns: Trueif comparison passes, otherwise, anAssertionErroris raised.Return type: bool Raises: AssertionError– If comparison returnsFalse.
-
format_msg(*args, **kargs)[source]¶ Return formatted assert message. This is used to generate the assert message during
__call__(). If nomsgkeyword argument is provided, thenreasonwill be used as the format string. By default, passed inargsandkargsalong with the classes__dict__dictionary are given to the format string. In all cases,arg[0]will be the value that is being validated.
-
op= None¶ Operation to perform to determine whether value is valid. This must be set in subclass.
-
reason= ''¶ Default format string used for assert message.
-
-
class
verify.base.Comparator(comparable, value=NotSet, **opts)[source]¶ Base class for assertions that compare two values.
-
class
verify.base.Negate[source]¶ Mixin class that negates the results of
compare()from the parent class.
-
verify.base.NotSet= NotSet¶ Singleton to indicate that a keyword argument was not provided.
Logic¶
Assertions related to logical operations.
-
class
verify.logic.Truthy(value=NotSet, **opts)[source]¶ Asserts that value is truthy.
- Aliases:
to_be_truthyis_truthy
New in version 0.0.1.
-
reason= '{0} is not truthy'¶
-
class
verify.logic.Falsy(value=NotSet, **opts)[source]¶ Asserts that value is falsy.
- Aliases:
to_be_falsyis_falsy
New in version 0.0.1.
-
reason= '{0} is not falsy'¶
-
class
verify.logic.Not(comparable, value=NotSet, **opts)[source]¶ Asserts that comparable doesn’t raise an
AssertionError. Can be used to create “opposite” comparators.Examples
>>> from verify import * >>> expect(5, Not(In([1, 2, 3]))) <expect(5)> >>> Not(5, In([1, 2, 3])) <Not()> >>> Not(In([1, 2, 3]))(5) True
- Aliases:
not_does_notto_failfails
New in version 0.0.1.
-
reason= 'The negation of {comparable} should not be true when evaluated with {0}'¶
-
class
verify.logic.Predicate(comparable, value=NotSet, **opts)[source]¶ Asserts that value evaluated by the predicate comparable is
True.- Aliases:
doesto_passpasses
New in version 0.1.0.
Changed in version 0.6.0: Catch
AssertionErrorthrown by comparable and returnFalseas comparison value instead.-
reason= 'The evaluation of {0} using {comparable} is false'¶
-
class
verify.logic.All(comparable, value=NotSet, **opts)[source]¶ Asserts that value evaluates as truthy for all predicates in comparable.
- Aliases:
all_does_allpasses_all
New in version 0.2.0.
-
reason= '{0} is not true for all {comparable}'¶
-
class
verify.logic.NotAll(comparable, value=NotSet, **opts)[source]¶ Asserts that value evaluates as falsy for all predicates in comparable.
- Aliases:
to_be_not_alldoes_not_allfails_all
New in version 0.5.0.
-
reason= '{0} is true for all {comparable}'¶
Equality¶
Assertions related to equality.
-
class
verify.equality.Equal(comparable, value=NotSet, **opts)[source]¶ Asserts that two values are equal.
- Aliases:
to_be_equalis_equal
New in version 0.0.1.
-
reason= '{0} is not equal to {comparable}'¶
-
class
verify.equality.NotEqual(comparable, value=NotSet, **opts)[source]¶ Asserts that two values are not equal.
- Aliases:
to_not_be_equalis_not_equal
New in version 0.5.0.
-
reason= '{0} is equal to {comparable}'¶
-
class
verify.equality.Match(comparable, value=NotSet, **opts)[source]¶ Asserts that value matches the regular expression comparable.
Parameters: - value (mixed, optional) – Value to compare.
- comparable (str|RegExp) – String or RegExp object used for matching.
Keyword Arguments: flags (int, optional) – Used when compiling regular expression when regular expression is a string. Defaults to
0.- Aliases:
to_matchis_matchmatches
New in version 0.3.0.
-
reason= '{0} does not match the regular expression {comparable}'¶
-
class
verify.equality.NotMatch(comparable, value=NotSet, **opts)[source]¶ Asserts that value does not match the regular expression comparable.
- Aliases:
to_not_be_matchis_not_matchnot_matches
New in version 0.5.0.
-
reason= '{0} matches the regular expression {comparable}'¶
-
class
verify.equality.Is(comparable, value=NotSet, **opts)[source]¶ Asserts that value is comparable.
- Aliases:
to_beis_
New in version 0.0.1.
-
reason= '{0} is not {comparable}'¶
-
class
verify.equality.IsNot(comparable, value=NotSet, **opts)[source]¶ Asserts that value is not comparable.
- Aliases:
to_not_beis_not
New in version 0.5.0.
-
reason= '{0} is {comparable}'¶
-
class
verify.equality.IsTrue(value=NotSet, **opts)[source]¶ Asserts that value is
True.- Aliases:
to_be_trueis_true
New in version 0.1.0.
-
reason= '{0} is not True'¶
-
class
verify.equality.IsNotTrue(value=NotSet, **opts)[source]¶ Asserts that value is not
True.- Aliases:
to_not_be_trueis_not_true
New in version 0.5.0.
-
reason= '{0} is True'¶
-
class
verify.equality.IsFalse(value=NotSet, **opts)[source]¶ Asserts that value is
False.- Aliases:
to_be_falseis_false
New in version 0.1.0.
-
reason= '{0} is not False'¶
-
class
verify.equality.IsNotFalse(value=NotSet, **opts)[source]¶ Asserts that value is not
False.- Aliases:
to_not_be_falseis_not_false
New in version 0.5.0.
-
reason= '{0} is False'¶
Types¶
Assertions related to types.
-
class
verify.types.Type(comparable, value=NotSet, **opts)[source]¶ Asserts that value is an instance of comparable.
- Aliases:
to_be_typeis_type
New in version 0.0.1.
Changed in version 0.6.0: Renamed from
InstanceOftoType-
reason= '{0} is not an instance of {comparable}'¶
-
class
verify.types.NotType(comparable, value=NotSet, **opts)[source]¶ Asserts that value is a not an instance of comparable.
- Aliases:
to_be_not_typeis_not_type
New in version 0.5.0.
Changed in version 0.6.0: Renamed from
NotInstanceOftoNotType-
reason= '{0} is an instance of {comparable}'¶
-
class
verify.types.Boolean(value=NotSet, **opts)[source]¶ Asserts that value is a boolean.
- Aliases:
to_be_booleanis_boolean
New in version 0.1.0.
-
reason= '{0} is not a boolean'¶
-
class
verify.types.NotBoolean(value=NotSet, **opts)[source]¶ Asserts that value is a not a boolean.
- Aliases:
to_be_not_booleanis_not_boolean
New in version 0.5.0.
-
reason= '{0} is a boolean'¶
-
class
verify.types.String(value=NotSet, **opts)[source]¶ Asserts that value is a string (
strorunicodeon Python 2).- Aliases:
to_be_stringis_string
New in version 0.1.0.
-
reason= '{0} is not a string'¶
-
class
verify.types.NotString(value=NotSet, **opts)[source]¶ Asserts that value is a not a string.
- Aliases:
to_be_not_stringis_not_string
New in version 0.5.0.
-
reason= '{0} is a string'¶
-
class
verify.types.Dict(value=NotSet, **opts)[source]¶ Asserts that value is a dictionary.
- Aliases:
to_be_dictis_dict
New in version 0.1.0.
-
reason= '{0} is not a dictionary'¶
-
class
verify.types.NotDict(value=NotSet, **opts)[source]¶ Asserts that value is a not a dict.
- Aliases:
to_be_not_dictis_dict
New in version 0.5.0.
-
reason= '{0} is a dict'¶
-
class
verify.types.List(value=NotSet, **opts)[source]¶ Asserts that value is a list.
- Aliases:
to_be_listis_list
New in version 0.1.0.
-
reason= '{0} is not a list'¶
-
class
verify.types.NotList(value=NotSet, **opts)[source]¶ Asserts that value is a not a list.
- Aliases:
to_be_not_listis_not_list
New in version 0.5.0.
-
reason= '{0} is a list'¶
-
class
verify.types.Tuple(value=NotSet, **opts)[source]¶ Asserts that value is a tuple.
- Aliases:
to_be_tupleis_tuple
New in version 0.1.0.
-
reason= '{0} is not a tuple'¶
-
class
verify.types.NotTuple(value=NotSet, **opts)[source]¶ Asserts that value is a not a tuple.
- Aliases:
to_be_not_tupleis_not_tuple
New in version 0.5.0.
-
reason= '{0} is a tuple'¶
-
class
verify.types.Date(value=NotSet, **opts)[source]¶ Asserts that value is an instance of
datetime.dateordatetime.datetime.- Aliases:
to_be_dateis_date
New in version 0.3.0.
-
reason= '{0} is not a date or datetime object'¶
-
class
verify.types.NotDate(value=NotSet, **opts)[source]¶ Asserts that value is a not a date or datetime object.
- Aliases:
to_be_not_dateis_not_date
New in version 0.5.0.
-
reason= '{0} is a date or datetime object'¶
-
class
verify.types.DateString(comparable, value=NotSet, **opts)[source]¶ Asserts that value is matches the datetime format string comparable.
- Aliases:
to_be_date_stringis_date_string
New in version 0.3.0.
-
reason= '{0} does not match the datetime format {comparable}'¶
-
class
verify.types.NotDateString(comparable, value=NotSet, **opts)[source]¶ Asserts that value does not match datetime format string comparable.
- Aliases:
to_be_not_date_stringis_not_date_string
New in version 0.5.0.
-
reason= '{0} matches the datetime format {comparable}'¶
-
class
verify.types.Int(value=NotSet, **opts)[source]¶ Asserts that value is an integer.
- Aliases:
to_be_intis_int
New in version 0.1.0.
-
reason= '{0} is not an integer'¶
-
class
verify.types.NotInt(value=NotSet, **opts)[source]¶ Asserts that value is a not an integer.
- Aliases:
to_be_not_intis_not_int
New in version 0.5.0.
-
reason= '{0} is an integer'¶
-
class
verify.types.NotFloat(value=NotSet, **opts)[source]¶ Asserts that value is a not a float.
- Aliases:
to_be_not_floatis_not_float
New in version 0.5.0.
-
reason= '{0} is a float'¶
-
class
verify.types.Float(value=NotSet, **opts)[source]¶ Asserts that value is a float.
- Aliases:
to_be_floatis_float
New in version 0.1.0.
-
reason= '{0} is not a float'¶
Containers¶
Assertions related to containers/iterables.
-
class
verify.containers.In(comparable, value=NotSet, **opts)[source]¶ Asserts that value is in comparable.
- Aliases:
to_be_inis_in
New in version 0.0.1.
-
reason= '{0} is not in {comparable}'¶
-
class
verify.containers.NotIn(comparable, value=NotSet, **opts)[source]¶ Asserts that value is not in comparable.
- Aliases:
to_not_be_inis_not_in
New in version 0.5.0.
-
reason= '{0} is in {comparable}'¶
-
class
verify.containers.Contains(comparable, value=NotSet, **opts)[source]¶ Asserts that value is an iterable and contains comparable.
- Aliases:
to_containcontains
New in version 0.2.0.
-
reason= '{0} does not contain {comparable}'¶
-
class
verify.containers.NotContains(comparable, value=NotSet, **opts)[source]¶ Asserts that value does not contain comparable.
- Aliases:
to_not_containdoes_not_contain
New in version 0.5.0.
-
reason= '{0} contains {comparable}'¶
-
class
verify.containers.ContainsOnly(comparable, value=NotSet, **opts)[source]¶ Asserts that value is an iterable and only contains comparable.
- Aliases:
to_contain_onlycontains_only
New in version 0.2.0.
-
reason= '{0} does not only contain values in {comparable}'¶
-
class
verify.containers.NotContainsOnly(comparable, value=NotSet, **opts)[source]¶ Asserts that value does not contain only comparable.
- Aliases:
to_not_contain_onlydoes_not_contain_only
New in version 0.5.0.
-
reason= '{0} contains only {comparable}'¶
-
class
verify.containers.Subset(comparable, value=NotSet, **opts)[source]¶ Asserts that value is a subset of comparable. Comparison supports nested
dict,list, andtupleobjects.- Aliases:
to_be_subsetis_subset
New in version 0.3.0.
-
reason= '{0} is not a subset of {comparable}'¶
-
class
verify.containers.NotSubset(comparable, value=NotSet, **opts)[source]¶ Asserts that value is a not a subset of comparable.
- Aliases:
to_not_be_subsetis_not_subset
New in version 0.5.0.
-
reason= '{0} is a subset of {comparable}'¶
-
class
verify.containers.Superset(comparable, value=NotSet, **opts)[source]¶ Asserts that value is a superset of comparable. Comparison supports nested
dict,list, andtupleobjects.- Aliases:
to_be_supersetis_superset
New in version 0.3.0.
-
reason= '{0} is not a supserset of {comparable}'¶
-
class
verify.containers.NotSuperset(comparable, value=NotSet, **opts)[source]¶ Asserts that value is a not a superset of comparable.
- Aliases:
to_not_be_supersetis_not_superset
New in version 0.5.0.
-
reason= '{0} is a superset of {comparable}'¶
-
class
verify.containers.Unique(value=NotSet, **opts)[source]¶ Asserts that value contains only unique values. If value is a
dict, then itsvalues()will be compared.- Aliases:
to_be_uniqueis_unique
New in version 0.3.0.
-
reason= '{0} contains duplicate items'¶
-
class
verify.containers.NotUnique(value=NotSet, **opts)[source]¶ Asserts that value is a not a unique.
- Aliases:
to_not_be_uniqueis_not_unique
New in version 0.5.0.
-
reason= '{0} is unique'¶
-
class
verify.containers.Length(value=NotSet, **opts)[source]¶ Asserts that value is an iterable with length between min and max inclusively.
Examples
These will pass:
>>> assert Length([1, 2, 3], min=3, max=3) # 3 <= len(a) <= 3 >>> assert Length([1, 2, 3, 4, 5], min=5, max=6) # 5 <= len(a) <= 6 >>> assert Length([1, 2, 3], max=6) # len(a) <= 6 >>> assert Length([1, 2, 3, 4], min=4) # len(a) >= 4
This will fail:
>>> Length([1, 2, 4], max=2) # len(a) <= 2 Traceback (most recent call last): ... AssertionError...
Parameters: value (mixed, optional) – Value to compare.
Keyword Arguments: - min (int, optional) – Minimum value that value must be greater than or equal to.
- max (int, optional) – Maximum value that value must be less than or equal to.
- Aliases:
to_have_lengthhas_length
New in version 0.2.0.
-
Changed in version 0.4.0:
Change comparison to function like
Betweenmeaning length is compared to min and max values.Allow keyword arguments
minandmaxto be used in place of positional tuple
Changed in version 1.0.0: Removed positional tuple argument and only support
minandmaxkeyword arguments.-
reason= '{0} does not have length between {min} and {max}'¶
Numbers¶
Assertions related to numbers.
-
class
verify.numbers.Greater(comparable, value=NotSet, **opts)[source]¶ Asserts that value is greater than comparable.
- Aliases:
GreaterThanto_be_greaterto_be_greater_thanis_greateris_greater_than
New in version 0.0.1.
-
reason= '{0} is not greater than {comparable}'¶
-
class
verify.numbers.GreaterEqual(comparable, value=NotSet, **opts)[source]¶ Asserts that value is greater than or equal to comparable.
- Aliases:
GreaterThanEqualto_be_greater_equalto_be_greater_or_equalis_greater_equalis_greater_or_equal
New in version 0.0.1.
-
reason= '{0} is not greater than or equal to {comparable}'¶
-
verify.numbers.GreaterOrEqual¶ alias of
GreaterEqual
-
class
verify.numbers.Less(comparable, value=NotSet, **opts)[source]¶ Asserts that value is less than comparable.
- Aliases:
LessThanto_be_lessto_be_less_thanis_lessis_less_than
New in version 0.0.1.
-
reason= '{0} is not less than {comparable}'¶
-
class
verify.numbers.LessEqual(comparable, value=NotSet, **opts)[source]¶ Asserts that value is less than or equal to comparable.
- Aliases:
LessThanEqualto_be_less_equalto_be_less_or_equalis_less_equalis_less_or_equal
New in version 0.0.1.
-
reason= '{0} is not less than or equal to {comparable}'¶
-
class
verify.numbers.Between(value=NotSet, **opts)[source]¶ Asserts that value is between min and max inclusively.
Examples
These will pass:
>>> assert Between(5, min=4, max=6) # 4 <= 5 <= 6 >>> assert Between(5, min=5, max=6) # 5 <= 5 <= 6 >>> assert Between(5, max=6) # 5 <= 6 >>> assert Between(5, min=4) # 5 >= 4
This will fail:
>>> Between(5, max=4) # 5 <= 4 Traceback (most recent call last): ... AssertionError...
Parameters: value (mixed, optional) – Value to compare.
Keyword Arguments: - min (int, optional) – Minimum value that value must be greater than or equal to.
- max (int, optional) – Maximum value that value must be less than or equal to.
- Aliases:
to_be_betweenis_between
New in version 0.2.0.
Changed in version 0.4.0: Allow keyword arguments
minandmaxto be used in place of positional tuple.Changed in version 1.0.0: Removed positional tuple argument and only support
minandmaxkeyword arguments.-
reason= '{0} is not between {min} and {max}'¶
-
class
verify.numbers.NotBetween(value=NotSet, **opts)[source]¶ Asserts that value is not between min and max inclusively.
- Aliases:
to_not_be_betweenis_not_between
New in version 0.5.0.
-
reason= '{0} is between {min} and {max}'¶
-
class
verify.numbers.Positive(value=NotSet, **opts)[source]¶ Asserts that value is a positive number.
- Aliases:
to_be_positiveis_positive
New in version 0.3.0.
-
reason= '{0} is not a positive number'¶
-
class
verify.numbers.Negative(value=NotSet, **opts)[source]¶ Asserts that value is a negative number.
- Aliases:
to_be_negativeis_negative
New in version 0.3.0.
-
reason= '{0} is not a negative number'¶
-
class
verify.numbers.Even(value=NotSet, **opts)[source]¶ Asserts that value is an even number.
- Aliases:
to_be_evenis_even
New in version 0.3.0.
-
reason= '{0} is not an even number'¶
-
class
verify.numbers.Odd(value=NotSet, **opts)[source]¶ Asserts that value is an odd number.
- Aliases:
to_be_oddis_odd
New in version 0.3.0.
-
reason= '{0} is not an odd number'¶
-
class
verify.numbers.Monotone(comparable, value=NotSet, **opts)[source]¶ Asserts that value is a monotonic with respect to comparable.
- Aliases:
to_be_monotoneis_monotone
New in version 0.3.0.
-
reason= '{0} is not monotonic as evaluated by {comparable}'¶
-
class
verify.numbers.Increasing(value=NotSet, **opts)[source]¶ Asserts that value is monotonically increasing.
- Aliases:
to_be_increasingis_increasing
New in version 0.3.0.
-
reason= '{0} is not monotonically increasing'¶
-
class
verify.numbers.StrictlyIncreasing(value=NotSet, **opts)[source]¶ Asserts that value is strictly increasing.
- Aliases:
to_be_strictly_increasingis_strictly_increasing
New in version 0.3.0.
-
reason= '{0} is not strictly increasing'¶