Project Status: Active — The project has reached a stable, usable state and is being actively developed. CI Status https://codecov.io/gh/jwodder/anys/branch/master/graph/badge.svg https://img.shields.io/pypi/pyversions/anys.svg MIT License

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.

Installation

anys requires Python 3.6 or higher. Just use pip for Python 3 (You have pip, right?) to install it:

python3 -m pip install anys

API

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.

Classes

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)

Constants

The following constants match values of the given type:

  • ANY_BOOL

  • ANY_BYTES

  • ANY_COMPLEX

  • ANY_DATE — Matches date instances. You may not be aware, but datetime is a subclass of date, and so this also matches datetimes. If you only want to match actual dates, use ANY_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 of date that is not an instance of datetime

  • 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 false

  • ANY_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.

Caveat: Custom Classes

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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jwodder from gravatar.com jwodder

Credits

Author: John Thorvald Wodder II

License

MIT License (MIT)

Requires

Python ~=3.6

Tags

comparison matchers pytest testing unit test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

anys-0.2.1.tar.gz (17.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

anys-0.2.1-py3-none-any.whl (9.6 kB view details)

Uploaded Python 3

File details

Details for the file anys-0.2.1.tar.gz.

File metadata

  • Download URL: anys-0.2.1.tar.gz
  • Upload date:
  • Size: 17.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

File hashes

Hashes for anys-0.2.1.tar.gz
Algorithm Hash digest
SHA256 f32e16ead49b0a96c530fe43aa4e69ffa68df1fd63042866a994618a08ae9725
MD5 bd44b1ef71c6577e6ab0a434eb348916
BLAKE2b-256 408081f88a0a678b387bc85376c914c2843a42c548aa4ab0161f5e1d8647f73c

See more details on using hashes here.

File details

Details for the file anys-0.2.1-py3-none-any.whl.

File metadata

  • Download URL: anys-0.2.1-py3-none-any.whl
  • Upload date:
  • Size: 9.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7

File hashes

Hashes for anys-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 b946ff447008d00125a2c437fb06f06aaad006ea798127efc2cae7dd217402b2
MD5 b5029b3928d2e183f0d81cdb0ed94646
BLAKE2b-256 7410f0a4b9e36a6742cae1009c090d3c551f9c0f7b4eefca763fce97452e483a

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page