Skip to content

hikari.undefined#

Singleton used throughout the library to denote values that are not present.

T_co module-attribute #

T_co = typing.TypeVar('T_co', covariant=True)

UNDEFINED module-attribute #

UNDEFINED: Literal[UNDEFINED] = UndefinedType()

A sentinel singleton that denotes a missing or omitted value.

UndefinedNoneOr module-attribute #

UndefinedNoneOr: TypeAlias = UndefinedOr[__T_co] | None

Type hint for a value that may be [hikari.undefined.UNDEFINED], or None.

UndefinedNoneOr[T] is simply an alias for UndefinedOr[typing.Optional[T]], which would expand to typing.Union[UndefinedType, T, None].

UndefinedOr module-attribute #

UndefinedOr: TypeAlias = __T_co | UndefinedType

Type hint to mark a type as being semantically optional.

THIS IS NOT THE SAME AS typing.Optional BY DEFINITION!

If you see a type with this marker, it may be hikari.undefined.UNDEFINED or the value it wraps. For example, UndefinedOr[float] would mean the value could be a float, or the literal hikari.undefined.UNDEFINED value.

On the other hand, typing.Optional[float] would mean the value could be a float, or the literal None value.

The reason for using this is in some places, there is a semantic difference between specifying something as being None, i.e. "no value", and having a default to specify that the value has just not been mentioned. The main example of this is in hikari.api.rest.RESTClient.edit_message endpoints where the contents will only be changed if they are explicitly mentioned in the call. Editing a message content and setting it to None would be expected to clear the content, whereas setting it to hikari.undefined.UNDEFINED would be expected to leave the value as it is without changing it.

Consider UndefinedOr[T] semantically equivalent to undefined versus null in JavaScript, or Optional<T> versus null in Java and C#.

Note

If in doubt, remember:

  • hikari.undefined.UNDEFINED means there is no value present, or that it has been left to the default value, whatever that would be.
  • None means the value is present and explicitly empty/null/void, where this has a deterministic documented behaviour and no differentiation is made between a None value, and one that has been omitted.

UndefinedType #

The type of the hikari.undefined.UNDEFINED singleton sentinel value.

UNDEFINED class-attribute instance-attribute #

UNDEFINED = __enum.auto()

all_undefined #

all_undefined(*items: object) -> bool

Get if all of the provided items are hikari.undefined.UNDEFINED.

any_undefined #

any_undefined(*items: object) -> bool

Get if any of the provided items are hikari.undefined.UNDEFINED.

count #

count(*items: object) -> int

Count the number of items that are provided that are hikari.undefined.UNDEFINED.