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 callingdict.copy
and wrapping the result in a mapped collection.Note
Any removal policy on this mapped collection will be copied over.
- 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 callingdict.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.
- 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 callingdict.copy
and wrapping the result in a mapped collection.Note
Any removal policy on this mapped collection will be copied over.
- 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 callingdict.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:
- source
typing.Optional
[typing.Dict
[KeyT
,ValueT
]] A source dictionary of keys to values to create this from.
- limit
int
The limit for how many objects should be stored by this mapping before it starts removing the oldest entries.
- on_expire
typing.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.
- source
- 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 callingdict.copy
and wrapping the result in a mapped collection.Note
Any removal policy on this mapped collection will be copied over.
- 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 callingdict.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:
- *ids
int
The IDs to fill this table with.
- *ids
- 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:
- mapping
typing.Mapping
[KeyT
,ValueT
] The mapping of entries to treat as a sequence.
- index_or_slice
typing.Sequence
[KeyT
,ValueT
] The index to get an entry to get or slice of multiple entries to get.
- mapping
- Returns:
ValueT
ortyping.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.