hikari.internal.collections#

Custom data structures used within Hikari’s core implementation.

Module Contents#

class hikari.internal.collections.ExtendedMutableMapping[source]#

Bases: MutableMapping[KeyT, ValueT], abc.ABC

The abstract class of mutable mappings used within Hikari.

These are mutable mappings that have a couple of extra methods to allow for further optimised copy operations, as well as the ability to freeze the implementation of a mapping to make it read-only.

abstract copy()[source]#

Return a copy of this mapped collection.

Unlike simply doing dict(mapping), this may rely on internal detail around how the data is being stored to allow for a more efficient copy. This may look like calling dict.copy and wrapping the result in a mapped collection.

Note

Any removal policy on this mapped collection will be copied over.

Returns:
MapT[KeyT, ValueT]

A copy of this mapped collection.

abstract freeze()[source]#

Return a frozen mapping view of the items in this mapped collection.

Unlike simply doing dict(mapping), this may rely on internal detail around how the data is being stored to allow for a more efficient copy. This may look like calling dict.copy.

Note

Unlike ExtendedMutableMapping.copy, this should return a pure mapping with no removal policy at all.

Returns:
typing.MutableMapping[KeyT, ValueT]

A frozen mapping view of the items in this mapped collection.

class hikari.internal.collections.FreezableDict(source=None, /)[source]#

Bases: ExtendedMutableMapping[KeyT, ValueT]

A mapping that wraps a dict, but can also be frozen.

clear()[source]#

D.clear() -> None. Remove all items from D.

copy()[source]#

Return a copy of this mapped collection.

Unlike simply doing dict(mapping), this may rely on internal detail around how the data is being stored to allow for a more efficient copy. This may look like calling dict.copy and wrapping the result in a mapped collection.

Note

Any removal policy on this mapped collection will be copied over.

Returns:
MapT[KeyT, ValueT]

A copy of this mapped collection.

freeze()[source]#

Return a frozen mapping view of the items in this mapped collection.

Unlike simply doing dict(mapping), this may rely on internal detail around how the data is being stored to allow for a more efficient copy. This may look like calling dict.copy.

Note

Unlike ExtendedMutableMapping.copy, this should return a pure mapping with no removal policy at all.

Returns:
typing.MutableMapping[KeyT, ValueT]

A frozen mapping view of the items in this mapped collection.

class hikari.internal.collections.LimitedCapacityCacheMap(source=None, /, *, limit, on_expire=None)[source]#

Bases: ExtendedMutableMapping[KeyT, ValueT]

Implementation of a capacity-limited most-recently-inserted mapping.

This will start removing the oldest entries after it’s maximum capacity is reached as new entries are added.

Parameters:
sourcetyping.Optional[typing.Dict[KeyT, ValueT]]

A source dictionary of keys to values to create this from.

limitint

The limit for how many objects should be stored by this mapping before it starts removing the oldest entries.

on_expiretyping.Optional[typing.Callable[[ValueT], None]]

A function to call each time an item is garbage collected from this map. This should take one positional argument of the same type stored in this mapping as the value and should return None.

This will always be called after the entry has been removed.

clear()[source]#

D.clear() -> None. Remove all items from D.

copy()[source]#

Return a copy of this mapped collection.

Unlike simply doing dict(mapping), this may rely on internal detail around how the data is being stored to allow for a more efficient copy. This may look like calling dict.copy and wrapping the result in a mapped collection.

Note

Any removal policy on this mapped collection will be copied over.

Returns:
MapT[KeyT, ValueT]

A copy of this mapped collection.

freeze()[source]#

Return a frozen mapping view of the items in this mapped collection.

Unlike simply doing dict(mapping), this may rely on internal detail around how the data is being stored to allow for a more efficient copy. This may look like calling dict.copy.

Note

Unlike ExtendedMutableMapping.copy, this should return a pure mapping with no removal policy at all.

Returns:
typing.MutableMapping[KeyT, ValueT]

A frozen mapping view of the items in this mapped collection.

class hikari.internal.collections.SnowflakeSet(*ids)[source]#

Bases: MutableSet[hikari.snowflakes.Snowflake]

Set of hikari.snowflakes.Snowflake objects.

This internally uses a sorted bisect-array of 64 bit integers to represent the information. This reduces the space needed to store these objects significantly down to the size of 8 bytes per item.

In contrast, a regular list would take generally 8 bytes per item just to store the memory address, and then a further 28 bytes or more to physically store the integral value if it does not get interned by the Python implementation you are using. A regular set would consume even more space, being a hashtable internally.

The detail of this implementation has the side effect that searches will take $$ mathcal{O} left( log n right) $$ operations in the worst case, and $$ Omega left (k right) $$ in the best case. Average case will be $$ mathcal{O} left( log n right) $$

Insertions and removals will take $$ mathcal{O} left( log n right) $$ operations in the worst case, due to bisect using a binary insertion sort algorithm internally. Average case will be $$ mathcal{O} left( log n right) $$ and best case will be $$ Omega left( k right) $$

Warning

This is not thread-safe and must not be iterated across whilst being concurrently modified.

Other Parameters:
*idsint

The IDs to fill this table with.

add(value, /)[source]#

Add a snowflake to this set.

add_all(sfs, /)[source]#

Add a collection of snowflakes to this set.

clear()[source]#

Clear all items from this collection.

discard(value, /)[source]#

Remove a snowflake from this set if it’s present.

hikari.internal.collections.get_index_or_slice(mapping, index_or_slice)[source]#

Get a mapping’s entry at a given index as if it’s a sequence of it’s values.

Parameters:
mappingtyping.Mapping[KeyT, ValueT]

The mapping of entries to treat as a sequence.

index_or_slicetyping.Sequence[KeyT, ValueT]

The index to get an entry to get or slice of multiple entries to get.

Returns:
ValueT or typing.Sequence[ValueT]

The value found at the given integer index or a sequence of the values found based on the given slice’s rules.

Raises:
IndexError

If index_or_slice is an int and is outside the range of the mapping’s contents.

hikari.internal.collections.KeyT[source]#

Type-hint A type hint used for the type of a mapping’s key.

hikari.internal.collections.ValueT[source]#

Type-hint A type hint used for the type of a mapping’s value.