Types¶

Base classes¶

Use Phantom to create arbitrary phantom types using boolean predicates.

import phantom

def is_big(value: int) -> bool:
    return value > 5

class Big(int, Phantom, predicate=is_big):
    ...

assert isinstance(10, Big)  # this passes

class phantom.Phantom(instance)[source]¶

Bases: phantom.base.PhantomBase, typing.Generic

Base class for predicate-based phantom types.

Class arguments

predicate: Predicate[T] | None - Predicate function used for instance checks. Can be None if the type is abstract.
bound: type[T] | None - Bound used to check values before passing them to the type’s predicate function. This will often but not always be the same as the runtime type that values of the phantom type are represented as. If this is not provided as a class argument, it’s attempted to be resolved in order from an implicit bound (any bases of the type that come before Phantom), or inherited from super phantom types that provide a bound. Can be None if the type is abstract.
abstract: bool - Set to True to create an abstract phantom type. This allows deferring definitions of predicate and bound to concrete subtypes.

__bound__: ClassVar[NotKnownMutable]¶

classmethod __get_validators__()¶: Hook that makes phantom types compatible with pydantic.

classmethod __modify_schema__(field_schema)¶

This final method is called by pydantic and collects overrides from Phantom.__schema__(). Override __schema__() to provide custom schema representations for phantom types.

Parameters: field_schema (dict) –
Return type: None

classmethod __schema__()¶

Hook for providing schema metadata. Override in subclasses to customize a types schema representation. See pydantic’s documentation on __modify_schema__() for more information. This hook differs to pydantic’s __modify_schema__() and expects subclasses to instantiate new dicts instead of mutating a given one.

Example:

class Name(str, Phantom, predicate=...):
    @classmethod
    def __schema__(cls):
        return {**super().__schema__(), "description": "A name type"}

Return type: phantom.schema.Schema

classmethod parse(instance)¶

Parse an arbitrary value into a phantom type.

Raises: TypeError –

Boolean¶

Types describing objects that coerce to either True or False respectively when calling bool() on them.

class phantom.boolean.Truthy(instance)[source]¶

Bases: phantom.base.Phantom

>>> isinstance("Huzzah!", Truthy)
True
>>> isinstance((), Truthy)
False

class phantom.boolean.Falsy(instance)[source]¶

Bases: phantom.base.Phantom

>>> isinstance((), Falsy)
True
>>> isinstance("Hej!", Falsy)
False

Country codes¶

Exposes a CountryCode type that is a union of a Literal containing all ISO3166 alpha-2 codes, and a phantom type that parses alpha-2 codes at runtime. This allows mixing statically known values with runtime-parsed values, like so:

countries: tuple[CountryCode] = ("SE", "DK", ParsedAlpha2.parse("FR"))

phantom.iso3166.LiteralAlpha2¶

Literal of all ISO3166 alpha-2 codes.

alias of Literal[AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW]

class phantom.iso3166.ParsedAlpha2(instance)[source]¶

Bases: str, phantom.base.Phantom

classmethod parse(instance)[source]¶

Normalize mixed case country code.

Raises: InvalidCountryCode –
Parameters: instance (object) –
Return type: phantom.iso3166.ParsedAlpha2

phantom.iso3166.Alpha2¶

The central part of internal API.

This represents a generic version of type ‘origin’ with type arguments ‘params’. There are two kind of these aliases: user defined and special. The special ones are wrappers around builtin collections and ABCs in collections.abc. These must have ‘name’ always set. If ‘inst’ is False, then the alias can’t be instantiated, this is used by e.g. typing.List and typing.Dict.

alias of Union[Literal[AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW], phantom.iso3166.ParsedAlpha2]

phantom.iso3166.CountryCode¶

The central part of internal API.

phantom.iso3166.is_alpha2_country_code(value)¶

Parameters: value (object) –
Return type: bool

phantom.iso3166.normalize_alpha2_country_code(country_code)[source]¶

Normalize mixed case country code.

Raises: InvalidCountryCode –
Parameters: country_code (str) –
Return type: phantom.iso3166.ParsedAlpha2

exception phantom.iso3166.InvalidCountryCode[source]¶: Bases: TypeError

Datetime¶

Types for narrowing on the builtin datetime types.

class phantom.datetime.TZAware(instance)[source]¶

Bases: datetime.datetime, phantom.base.Phantom

A type for helping ensure that datetime objects are always timezone aware.

>>> isinstance(datetime.datetime.now(), TZAware)
False
>>> isinstance(datetime.datetime.now(tz=datetime.timezone.utc), TZAware)
True

class phantom.datetime.TZNaive(instance)[source]¶

Bases: datetime.datetime, phantom.base.Phantom

>>> isinstance(datetime.datetime.now(), TZNaive)
True
>>> isinstance(datetime.datetime.now(tz=datetime.timezone.utc), TZNaive)
False

Numeric intervals¶

Base classes¶

Concrete interval types¶

Regular expressions¶

Types for representing strings that match a pattern.

class Greeting(Match, pattern=r"^(Hi|Hello)"):
    ...


assert isinstance("Hello Jane!", Greeting)

class phantom.re.Match(instance)[source]¶

Bases: str, phantom.base.Phantom

Takes pattern: Pattern[str] | str as class argument as either a compiled Pattern or a str to be compiled. Uses the phantom.predicate.re.is_match() predicate.

class phantom.re.FullMatch(instance)[source]¶

Bases: str, phantom.base.Phantom

Takes pattern: Pattern[str] | str as class argument as either a compiled Pattern or a str to be compiled. Uses the phantom.predicate.re.is_full_match() predicate.

Types¶

Base classes¶

Boolean¶

Country codes¶

Datetime¶

Numeric intervals¶

Base classes¶

Concrete interval types¶

Regular expressions¶

Sized collections¶