hikari.undefined
#
Singleton used throughout the library to denote values that are not present.
UNDEFINED
module-attribute
#
UNDEFINED: Literal[UNDEFINED] = UndefinedType()
A sentinel singleton that denotes a missing or omitted value.
UndefinedNoneOr
module-attribute
#
UndefinedNoneOr = Union[UndefinedOr[T], 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 = Union[T, 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 aNone
value, and one that has been omitted.
UndefinedType
#
The type of the hikari.undefined.UNDEFINED
singleton sentinel value.
all_undefined
#
Get if all of the provided items are hikari.undefined.UNDEFINED
.
any_undefined
#
Get if any of the provided items are hikari.undefined.UNDEFINED
.
count
#
Count the number of items that are provided that are hikari.undefined.UNDEFINED
.