hikari.undefined#

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

Module Contents#

class hikari.undefined.UndefinedType[source]#

The type of the UNDEFINED singleton sentinel value.

hikari.undefined.all_undefined(*items)[source]#

Get if all of the provided items are UNDEFINED.

hikari.undefined.any_undefined(*items)[source]#

Get if any of the provided items are UNDEFINED.

hikari.undefined.count(*items)[source]#

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

hikari.undefined.UNDEFINED[source]#

A sentinel singleton that denotes a missing or omitted value.

hikari.undefined.UndefinedNoneOr[source]#

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

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

hikari.undefined.UndefinedOr[source]#

Type hint to mark a type as being semantically optional.

NOTE THAT THIS IS NOT THE SAME AS `typing.Optional` BY DEFINITION.

If you see a type with this marker, it may be UNDEFINED or the value it wraps. For example, UndefinedOr[float] would mean the value could be a float, or the literal 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 edit 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 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 versus null in Java and C#.

If in doubt, remember:

  • UNDEFINED means there is no value present, or that it has been left to

    the default value.

  • 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.