assertionlib.functions

Various functions related to the AssertionManager class.

Index

`get_sphinx_domain`(func[, module_mapping])	Create a Sphinx domain for func.
`create_assertion_doc`(func)	Create a new NumPy style assertion docstring from the docstring of func.
`bind_callable`(class_type, func[, name, warn])	Take a callable and use it to create a new assertion method for class_type.
`to_positional`(func)	Decorate a function's `__signature__` such that all positional-or-keyword arguments are changed to either positional- or keyword-only.

API

assertionlib.functions.get_sphinx_domain(func: Callable[[...], Any], module_mapping: Mapping[str, str] = mappingproxy({'genericpath': 'os.path', 'posixpath': 'os.path', '_operator': 'operator'})) → str[source]

Create a Sphinx domain for func.

Examples

>>> from collections import OrderedDict
>>> from assertionlib.functions import get_sphinx_domain

>>> value1: str = get_sphinx_domain(int)
>>> print(value1)
:class:`int<python:int>`

>>> value2: str = get_sphinx_domain(list.count)
>>> print(value2)
:meth:`list.count()<python:list.count>`

>>> value3: str = get_sphinx_domain(OrderedDict)
>>> print(value3)
:class:`~collections.OrderedDict`

>>> value4: str = get_sphinx_domain(OrderedDict.keys)
>>> print(value4)
:meth:`~collections.OrderedDict.keys`

Parameters:

func (Callable) – A class or (builtin) method or function.
module_mapping (dict [str, str]) – A dictionary for mapping __module__ values to actual module names. Useful for whenever there is a discrepancy between the two, e.g. the genericpath module of os.path.join().

Returns:

A string with a valid Sphinx refering to func.

Return type:

str

Raises:

TypeError – Raised if func is neither a class or a (builtin) function or method.

assertionlib.functions.create_assertion_doc(func: Callable[[...], Any]) → str[source]

Create a new NumPy style assertion docstring from the docstring of func.

The summary of funcs’ docstring, if available, is added to the "See also" section, in addition with an intersphinx-compatible link to func.

Examples

>>> from assertionlib.functions import create_assertion_doc

>>> docstring: str = create_assertion_doc(isinstance)
>>> print(docstring)
Perform the following assertion: :code:`assert isinstance(obj, class_or_tuple)`.

Parameters
----------
obj
    The positional-only argument ``obj`` of :func:`isinstance()<python:isinstance>`.

class_or_tuple
    The positional-only argument ``class_or_tuple`` of :func:`isinstance()<python:isinstance>`.


Keyword Arguments
-----------------
invert : :class:`bool`
    If :data:`True`, invert the output of the assertion: :code:`assert not isinstance(obj, class_or_tuple)`.

exception : :class:`type` [:exc:`Exception`], optional
    Assert that **exception** is raised during/before the assertion operation.

post_process : :data:`Callable[[Any], bool]<typing.Callable>`, optional
    Apply post-processing to the to-be asserted data before asserting aforementioned data.
    Example values would be the likes of :func:`any()<python:any>` and :func:`all()<python:all>`.

message : :class:`str`, optional
    A custom error message to-be passed to the ``assert`` statement.


:rtype: :data:`None`

See also
--------
:func:`isinstance()<python:isinstance>`
        Return whether an object is an instance of a class or of a subclass thereof.

    A tuple, as in ``isinstance(x, (A, B, ...))``, may be given as the target to
    check against. This is equivalent to ``isinstance(x, A) or isinstance(x, B)
    or ...`` etc.

Parameters:: func (Callable) – A callable whose output is to-be asserted.
Returns:: A new docstring constructed from funcs’ docstring.
Return type:: str

assertionlib.functions.bind_callable(class_type: type | Any, func: Callable[[...], Any], name: str | None = None, warn: bool = True) → None[source]

Take a callable and use it to create a new assertion method for class_type.

The created callable will have the same signature as func except for one additional keyword argument by the name of func (default value: False). Setting this keyword argument to True will invert the output of the assertion, i.e. it changes assert func(...) into assert not func(...).

Examples

Supplying the builtin len() function will create (and bind) a callable which performs the assert len(obj) assertion.

Parameters:

class_type (type or Any) – A class (i.e. a type instance) or class instance.
func (Callable) – A callable object whose output will be asserted by the created method.
name (str, optional) – The name of the name of the new method. If None, use the name of func.

Return type:

None

assertionlib.functions.to_positional(func: FT) → FT[source]

Decorate a function’s __signature__ such that all positional-or-keyword arguments are changed to either positional- or keyword-only.

Example

>>> from inspect import signature
>>> from assertionlib.functions import to_positional

>>> def func1(a: int, b: int = 0) -> int:
...     pass

>>> @to_positional
... def func2(a: int, b: int = 0) -> int:
...     pass

>>> print(signature(func1), signature(func2), sep='\n')
(a: int, b: int = 0) -> int
(a: int, /, *, b: int = 0) -> int