Predicates and factories

Predicates are functions that return a boolean value given a single argument. These modules contain predicate functions, and functions that return predicates, that can be composed and used for phantom types.

Boolean logic

phantom.predicates.boolean.true(_value)[source]

Always return True.

Parameters

_value (object) –

Return type

typing.Literal[True]

phantom.predicates.boolean.false(_value)[source]

Always return False.

Parameters

_value (object) –

Return type

typing.Literal[False]

phantom.predicates.boolean.negate(predicate)[source]

Negate a given predicate.

Parameters

predicate (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

phantom.predicates.boolean.truthy(value)[source]

Return True for truthy objects.

Parameters

value (object) –

Return type

bool

phantom.predicates.boolean.falsy(value)[source]

Return True for falsy objects.

Parameters

value (object) –

Return type

bool

phantom.predicates.boolean.both(p, q)[source]

Create a new predicate that succeeds when both of the given predicates succeed.

Parameters
  • p (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

  • q (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

phantom.predicates.boolean.either(p, q)[source]

Create a new predicate that succeeds when at least one of the given predicates succeed.

Parameters
  • p (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

  • q (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

phantom.predicates.boolean.xor(p, q)[source]

Create a new predicate that succeeds when one of the given predicates succeed, but not both.

Parameters
  • p (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

  • q (typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

phantom.predicates.boolean.all_of(predicates)[source]

Create a new predicate that succeeds when all of the given predicates succeed.

Parameters

predicates (typing.Iterable[typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

phantom.predicates.boolean.any_of(predicates)[source]

Create a new predicate that succeeds when at least one of the given predicates succeed.

Parameters

predicates (typing.Iterable[typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

phantom.predicates.boolean.one_of(predicates)[source]

Create a new predicate that succeeds when exactly one of the given predicates succeed.

Parameters

predicates (typing.Iterable[typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]]) –

Return type

typing.Callable[[typing.TypeVar(T_contra, bound= object, contravariant=True)], bool]

Collection

phantom.predicates.collection.contains(value)[source]

Create a new predicate that succeeds when its argument contains value.

Parameters

value (object) –

Return type

typing.Callable[[typing.Container], bool]

phantom.predicates.collection.contained(container)[source]

Create a new predicate that succeeds when its argument is contained by container.

Parameters

container (typing.Container) –

Return type

typing.Callable[[object], bool]

phantom.predicates.collection.count(predicate)[source]

Create a predicate that succeeds when the size of its argument satisfies the given predicate.

Parameters

predicate (typing.Callable[[int], bool]) –

Return type

typing.Callable[[typing.Sized], bool]

phantom.predicates.collection.exists(predicate)[source]

Create a predicate that succeeds when one or more items in its argument satisfies predicate.

Parameters

predicate (typing.Callable[[typing.TypeVar(_O, bound= object)], bool]) –

Return type

typing.Callable[[typing.Iterable], bool]

phantom.predicates.collection.every(predicate)[source]

Create a predicate that succeeds when all items in its argument satisfy predicate.

Parameters

predicate (typing.Callable[[typing.TypeVar(_O, bound= object)], bool]) –

Return type

typing.Callable[[typing.Iterable], bool]

Datetime

phantom.predicates.datetime.is_tz_aware(dt)[source]

Return True if dt is timezone aware.

Parameters

dt (datetime.datetime) –

Return type

bool

phantom.predicates.datetime.is_tz_naive(dt)[source]

Return True if dt is timezone naive.

Parameters

dt (datetime.datetime) –

Return type

bool

Generic

phantom.predicates.generic.equal(a)[source]

Create a new predicate that succeeds when its argument is equal to a.

Parameters

a (object) –

Return type

typing.Callable[[object], bool]

phantom.predicates.generic.identical(a)[source]

Create a new predicate that succeeds when its argument is identical to a.

Parameters

a (object) –

Return type

typing.Callable[[object], bool]

phantom.predicates.generic.of_type(t)[source]

Create a new predicate that succeeds when its argument is an instance of t.

Parameters

t (typing.Union[type, typing.Tuple[type, ...]]) –

Return type

typing.Callable[[object], bool]

Numeric intervals

Functions that create new predicates that succeed when their argument is strictly or non strictly between the upper and lower bounds. There are corresponding phantom types that use these predicates in phantom.interval.

phantom.predicates.interval.open(low, high)[source]

Create a predicate that succeeds when its argument is in the range (low, high).

Parameters
  • low (typing.TypeVar(T)) –

  • high (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsLeGe[typing.TypeVar(T)]], bool]

phantom.predicates.interval.open_closed(low, high)[source]

Create a predicate that succeeds when its argument is in the range (low, high].

Parameters
  • low (typing.TypeVar(T)) –

  • high (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsLtGe[typing.TypeVar(T)]], bool]

phantom.predicates.interval.closed_open(low, high)[source]

Create a predicate that succeeds when its argument is in the range [low, high).

Parameters
  • low (typing.TypeVar(T)) –

  • high (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsLeGt[typing.TypeVar(T)]], bool]

phantom.predicates.interval.closed(low, high)[source]

Create a predicate that succeeds when its argument is in the range [low, high].

Parameters
  • low (typing.TypeVar(T)) –

  • high (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsLtGt[typing.TypeVar(T)]], bool]

Numeric

phantom.predicates.numeric.less(n)[source]

Create a new predicate that succeeds when its argument is strictly less than n.

Parameters

n (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsLt[typing.TypeVar(T)]], bool]

phantom.predicates.numeric.le(n)[source]

Create a new predicate that succeeds when its argument is less than or equal to n.

Parameters

n (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsLe[typing.TypeVar(T)]], bool]

phantom.predicates.numeric.greater(n)[source]

Create a new predicate that succeeds when its argument is strictly greater than n.

Parameters

n (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsGt[typing.TypeVar(T)]], bool]

phantom.predicates.numeric.ge(n)[source]

Create a new predicate that succeeds when its argument is greater than or equal to n.

Parameters

n (typing.TypeVar(T)) –

Return type

typing.Callable[[phantom._utils.types.SupportsGe[typing.TypeVar(T)]], bool]

phantom.predicates.numeric.positive(n)[source]

Return True when n is strictly greater than zero.

Parameters

n (phantom._utils.types.SupportsGt[int]) –

Return type

bool

phantom.predicates.numeric.non_positive(n)[source]

Return True when n is less than or equal to zero.

Parameters

n (phantom._utils.types.SupportsLe[int]) –

Return type

bool

phantom.predicates.numeric.negative(n)[source]

Return True when n is strictly less than zero.

Parameters

n (phantom._utils.types.SupportsLt[int]) –

Return type

bool

phantom.predicates.numeric.non_negative(n)[source]

Return True when n is greater than or equal to zero.

Parameters

n (phantom._utils.types.SupportsGe[int]) –

Return type

bool

phantom.predicates.numeric.modulo(n, p)[source]

Create a new predicate that succeeds when its argument modulo n satisfies the given predicate p.

Parameters
  • n (typing.TypeVar(T)) –

  • p (typing.Callable[[typing.TypeVar(U)], bool]) –

Return type

typing.Callable[[phantom._utils.types.SupportsMod[typing.TypeVar(T), typing.TypeVar(U)]], bool]

phantom.predicates.numeric.even(n)[source]

Return True when n is even.

Parameters

n (int) –

Return type

bool

phantom.predicates.numeric.odd(n)[source]

Return True when n is odd.

Parameters

n (int) –

Return type

bool

Regular expressions

phantom.predicates.re.is_match(pattern)[source]

Create a new predicate that succeeds when the start of its argument matches the given pattern.

Parameters

pattern (typing.Pattern[str]) –

Return type

typing.Callable[[str], bool]

phantom.predicates.re.is_full_match(pattern)[source]

Create a new predicate that succeeds when its whole argument matches the given pattern.

Parameters

pattern (typing.Pattern[str]) –

Return type

typing.Callable[[str], bool]