GitHub | PyPI | Issues | Changelog
anys
provides matchers for pytest-style assertions. What's a "matcher," you say? Well, say you're writing a unit test and you want to assert that a given object contains the correct values. Normally, you'd just write:
assert foo == {
"widgets": 42,
"name": "Alice",
"subfoo": {
"created_at": "2021-06-24T18:41:59Z",
"name": "Bob",
"widgets": 23,
}
}
But wait! What if the value of foo["subfoo"]["created_at"]
can't be determined in advance, but you still need to check that it's a valid timestamp? You'd have to compare everything in foo
other than that one field to the expected values and then separately check the timestamp field for validity. This is where matchers come in: they're magic objects that compare equal to any & all values that meet given criteria. For the case above, anys
allows you to just write:
from anys import ANY_DATETIME_STR
assert foo == {
"widgets": 42,
"name": "Alice",
"subfoo": {
"created_at": ANY_DATETIME_STR,
"name": "Bob",
"widgets": 23,
}
}
and the assertion will do what you mean.
anys
requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install it:
python3 -m pip install anys
anys
provides the following classes & constants for matching against values meeting certain criteria. Matching is performed by comparing a value against an anys
matcher with ==
, either directly or as a result of comparing two larger structures with ==
.
If a comparison raises a TypeError
or ValueError
(say, because you evaluated 42 == AnyMatch(r'\d+')
, which tries to match a regex against an integer), the exception is suppressed, and the comparison evaluates to False
; all other exceptions are propagated out.
anys
matchers can be combined using the &
operator to produce new matchers that require both operands to succeed; for example, AnyGT(23) & AnyLT(42)
will match any number between 23 and 42, exclusive, and nothing else.
anys
matchers can be combined using the |
operator to produce new matchers that require at least one of the operands to succeed; for example, ANY_INT | ANY_STR
will match any value that is an int
or a str
.
Note that, unless stated otherwise, anys
class constructors cannot take anys
matchers as arguments.
AnyContains(key: Any, /)
A matcher that matches any value for which key in value
is true. If key
is an anys
matcher, value == AnyContains(key)
will instead be evaluated by iterating through the elements of value
and checking whether any match key
.
AnyFullmatch(pattern: Union[AnyStr, re.Pattern[AnyStr]], /)
A matcher that matches any string s
for which re.fullmatch(pattern, s)
succeeds
AnyFunc(func: Callable, /)
A matcher that matches any value x
for which func(x)
is true. If func(x)
raises a TypeError
or ValueError
, it will be suppressed, and x == AnyFunc(func)
will evaluate to False
. All other exceptions are propagated out.
AnyGE(bound: Any, /)
A matcher that matches any value greater than or equal to bound
AnyGT(bound: Any, /)
A matcher that matches any value greater than bound
AnyIn(iterable: Iterable, /)
A matcher that matches any value that equals or matches an element of iterable
(which may contain anys
matchers). Note that, if iterable
is a string, only individual characters in the string will match; to match substrings, use AnySubstr()
instead.
AnyInstance(classinfo, /)
A matcher that matches any value that is an instance of classinfo
. classinfo
can be either a type or a tuple of types (or, starting in Python 3.10, a Union
of types).
A number of pre-composed AnyInstance()
values are provided as constants for your convenience; see "Constants" below.
AnyLE(bound: Any, /)
A matcher that matches any value less than or equal to bound
AnyLT(bound: Any, /)
A matcher that matches any value less than bound
AnyMatch(pattern: Union[AnyStr, re.Pattern[AnyStr]], /)
A matcher that matches any string s
for which re.match(pattern, s)
succeeds
AnySearch(pattern: Union[AnyStr, re.Pattern[AnyStr]], /)
A matcher that matches any string s
for which re.search(pattern, s)
succeeds
AnySubstr(s: AnyStr, /)
A matcher that matches any substring of s
AnyWithAttrs(mapping: Mapping, /)
A matcher that matches any object obj
such that getattr(obj, k) == v
for all k,v
in mapping.items()
.
The values (but not the keys) of mapping
can be anys
matchers.
AnyWithEntries(mapping: Mapping, /)
A matcher that matches any object obj
such that obj[k] == v
for all k,v
in mapping.items()
.
The values (but not the keys) of mapping
can be anys
matchers.
Maybe(arg: Any, /)
A matcher that matches None
and any value that equals or matches arg
(which can be an anys
matcher)
Not(arg: Any, /)
A matcher that matches anything that does not equal or match arg
(which can be an anys
matcher)
The following constants match values of the given type:
ANY_BOOL
ANY_BYTES
ANY_COMPLEX
ANY_DATE
— Matchesdate
instances. You may not be aware, butdatetime
is a subclass ofdate
, and so this also matchesdatetime
s. If you only want to match actualdate
s, useANY_STRICT_DATE
.ANY_DATETIME
ANY_DICT
ANY_FLOAT
ANY_INT
ANY_ITERABLE
ANY_ITERATOR
ANY_LIST
ANY_MAPPING
ANY_NUMBER
ANY_SEQUENCE
ANY_SET
ANY_STR
ANY_STRICT_DATE
— Matches any instance ofdate
that is not an instance ofdatetime
ANY_TUPLE
The following constants match aware or naïve datetime
or time
values:
ANY_AWARE_DATETIME
ANY_AWARE_TIME
ANY_NAIVE_DATETIME
ANY_NAIVE_TIME
The following constants match ISO 8601-style date, time, & datetime strings. "Aware" matchers require timezone information, while "naïve" matchers forbid it.
ANY_AWARE_DATETIME_STR
ANY_AWARE_TIME_STR
ANY_DATETIME_STR
ANY_DATE_STR
ANY_NAIVE_DATETIME_STR
ANY_NAIVE_TIME_STR
ANY_TIME_STR
Other constants:
ANY_FALSY
— Matches anything considered falseANY_TRUTHY
— Matches anything considered true
Note: If you're after a matcher that matches absolutely everything, Python already provides that as the unittest.mock.ANY constant.
When a well-behaved class defines an __eq__
method, it will only test against values of the same class, returning NotImplemented
for other types, 1 which signals Python to evaluate x == y
by instead calling y
's __eq__
method. Thus, when comparing an anys
matcher against an instance of a well-behaved class, the matcher can be on either the left or the right of the ==
. All of the classes in the Python standard library are well-behaved, as are classes that don't define __eq__
methods, but some custom classes in third-party code are not well-behaved. In order to successfully compare an anys
matcher against an ill-behaved class, the matcher must be on the left side of the ==
operator; if it is on the right, only the custom class's __eq__
method will be consulted, which usually means that the comparison will always evaluate to false.
In order to work their magic,
anys
matchers do not follow this rule, and so they are not well-behaved. "Do as I say, not as I do," as they say.↩