rics.types#

Types used by this package.

Module Attributes

AnyPath

Any path-like type; see parse_any_path().

T

A type var with no type bounds.

EnumT

A type var bounded by enum.Enum.

Functions

verify_enum(value, enum_type, *[, name])

Verify enum value.

verify_literal(value, literal_type, *[, ...])

Verify enum value.

Classes

LiteralHelper(literal_type, *[, ...])

Support class for verify_literal().
AnyPath: TypeAlias = str | os.PathLike[str] | pathlib.Path#

Any path-like type; see parse_any_path().

class T#

A type var with no type bounds.

alias of TypeVar(‘T’)

class EnumT#

A type var bounded by enum.Enum.

alias of TypeVar(‘EnumT’, bound=Enum)

verify_enum(value: str | EnumT, enum_type: type[EnumT], *, name: str | None = None) → EnumT[source]#

Verify enum value.

Parameters:

  • value – User input value; either a str or an enum.

  • enum_type – Desired enum type.

  • name – Name of the user-facing argument. Used in error messages. Derive if None.

Returns:

A enum of the given enum_type.

Examples

Basic usage.

>>> from enum import Enum, auto
>>> class Response(Enum):
...     Yes = auto()
...     No = auto()

Matching is case-insensitive when strings are given.

>>> verify_enum("NO", Response)
'<Response.No: 2>'

Enums may also be passed.

>>> verify_enum(Response.Yes, Response)
'<Response.Yes: 1>'

The default variable name used for errors is derived using rics.strings.camel_to_snake().

>>> verify_enum("x", Response)
TypeError: Bad response='x'; expected a Response enum option: Response.Yes | Response.No).

Notes

This function wraps LiteralHelper.from_enum().

verify_literal(value: Any, literal_type: Collection[T] | type[T] | Any, *, name: str = 'value', type_name: str | None = None, exc_type: type[Exception] | None = None, normalizer: Callable[[Any], Any] | None = None) → T[source]#

Verify enum value.

Parameters:

  • value – User input value; either a str or an enum.

  • literal_type – A typing.Literal type alias or a collection of permitted values.

  • name – Name of the user-facing argument. Used in error messages.

  • type_name – Name of the type itself. Used in error messages.

  • exc_type – Exception type to raise. Default is TypeError.

  • normalizer – A callable (value | option) -> new_value to use if value does not match exactly.

Returns:

A valid Literal value.

Examples

Basic usage.

>>> from typing import Literal
>>> verify_literal("no", Literal["yes", "no"])
'no'

Note that the output type will be Any unless a collection is used (a named TypeAlias is not enough). This is due to a limitation in the Python typing machinery. To get around this, you need to use an explicitly typed output variable.

>>> YesOrNot = Literal["yes", "no"]
>>> yes_or_no: YesOrNot = verify_literal("Yes!", YesOrNot)
TypeError: Bad value='Yes!'; expected one of ('yes', 'no').

By default, a TypeError is raised if the input value does not match the literal type.

Hint

See the LiteralHelper class docs for more examples.

class LiteralHelper(literal_type: Collection[T] | type[T] | Any, *, default_name: str = 'value', type_name: str | None = None, exc_type: type[BaseException] | None = None, normalizer: Callable[[Any | T], Any] | None = None)[source]#

Bases: Generic[T]

Support class for verify_literal().

Using this class may improve performance when the same literal type is verified multiple times.

Examples

Basic usage.

>>> from typing import Literal
>>> YesOrNo = Literal["yes", "no"]
>>> helper = LiteralHelper[YesOrNo](YesOrNo, type_name="YesOrNo")

The original value is returned as-is.

>>> helper.check("yes")
'yes'

The helper class itself is callable.

>>> helper("YES")
TypeError: Bad value='YES'; expected a YesOrNo['yes', 'no'].

Pass an explicit name to customize the error message for a single check call.

>>> helper("YES", name="user input")
TypeError: Bad user input='YES'; expected a YesOrNo['yes', 'no'].

Using a normalizer.

>>> normalizing_helper = LiteralHelper(YesOrNo, normalizer=str.lower)
>>> normalizing_helper("YES")
'yes'

The normalizer is applied only if the original value doesn’t match exactly.

Notes

Explicitly typed helpers (e.g. LiteralHelper[YesOrNo](...)) don’t require typed output variables, even when using type aliases instead of collections. This is another advantage of using the helper instead of verify_literal().

classmethod from_enum(enum_type: type[EnumT], *, default_name: str | None = None) → LiteralHelper[EnumT][source]#

Construct helper for an enum.Enum type.

Parameters:

  • enum_type – Desired enum type.

  • default_name – Default name of the user-facing argument. Used in error messages. Derive if None.

Returns:

A LiteralHelper constructor.

read_env(variable: str, *, default: T | None, split: str) → list[T][source]#
read_env(variable: str, *, default: T | None, split: None = None) → T

Read environment value.

Parameters:

  • variable – Environment variable name.

  • default – Value to use is variable is not set or blank. Pass None to raise.

  • split – Character to split on. Returns list[T] when set.

Returns:

A T, or a list thereof (if split is set).

Notes

Use the rics.env.read functions to read primitive types such as booleans.

property options: tuple[T, ...]#

Permitted options as explicit values.

check(value: Any, name: str | None = None) → T[source]#

Alias of __call__.

Parameters:

  • value – User input value.

  • name – Name to use for this call.

Returns:

A valid value.