orionis.support.types.Collection

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class Collection(ICollection): (source)

Constructor: Collection(items)

View In Hierarchy

Undocumented

Class Method	`__getItems`	Extract the underlying items from a Collection or return the input as-is.
Method	`__checkIsCallable`	Check if the given callback is callable.
Method	`__dataGet`	Retrieve a value from an item using a nested key notation.
Method	`__delitem__`	Delete an item from the collection at the specified key.
Method	`__eq__`	Compare the collection with another object for equality.
Method	`__ge__`	Compare if the current collection is greater than or equal to another object.
Method	`__getitem__`	Retrieve an item or a slice from the collection.
Method	`__getValue`	Retrieve values from items using a key or callback.
Method	`__gt__`	Compare if the current collection is greater than another object.
Method	`__hash__`	Compute the hash value of the collection.
Method	`__init__`	Initialize a new Collection instance.
Method	`__iter__`	Iterate over the items in the collection.
Method	`__le__`	Compare if the current collection is less than or equal to another object.
Method	`__len__`	Return the number of items in the collection.
Method	`__lt__`	Compare if the current collection is less than another object.
Method	`__makeComparison`	Compare two values using the specified operator.
Method	`__ne__`	Determine if the collection is not equal to another object.
Method	`__setitem__`	Set the value at the specified key in the collection.
Method	`__value`	Return the evaluated value if callable, otherwise return the value itself.
Method	`_addUniqueItem`	Add a unique item to the collection based on the comparison value.
Method	`_getUniqueItemsByKey`	Get unique items from the collection based on a specified key.
Method	`_getUniqueItemsWithoutKey`	Return unique items from the collection without using a key.
Method	`addRelation`	Add relation data to the collection.
Method	`all`	Return all items in the collection.
Method	`avg`	Compute the average of the items.
Method	`chunk`	Divide the collection into smaller collections of a specified size.
Method	`collapse`	Collapse the collection of arrays into a single, flat collection.
Method	`contains`	Check if the collection contains a given item.
Method	`count`	Return the number of items in the collection.
Method	`diff`	Return items not present in the given collection.
Method	`each`	Iterate over items and apply the callback to each.
Method	`every`	Determine whether all items satisfy the given callback condition.
Method	`filter`	Filter items in the collection using a callback.
Method	`first`	Return the first item in the collection, optionally filtered by a callback.
Method	`flatten`	Flatten the collection into a single dimension.
Method	`forget`	Remove items from the collection by their keys.
Method	`forPage`	Slice the collection for pagination.
Method	`get`	Retrieve an item from the collection by key.
Method	`groupBy`	Group items in the collection by a specified key.
Method	`implode`	Join all items in the collection into a single string.
Method	`isEmpty`	Check if the collection is empty.
Method	`last`	Return the last item in the collection, optionally filtered by a callback.
Method	`map`	Apply a function to each item in the collection.
Method	`mapInto`	Map items into instances of the given class.
Method	`max`	Return the maximum value from the items.
Method	`merge`	Merge the collection with the given items.
Method	`min`	Return the minimum value from the items.
Method	`pluck`	Extract values for a given key from all items.
Method	`pop`	Remove and return the last item from the collection.
Method	`prepend`	Prepend an item to the beginning of the collection.
Method	`pull`	Remove and return an item from the collection by key.
Method	`push`	Add an item to the end of the collection.
Method	`put`	Insert or update an item in the collection at the specified key.
Method	`random`	Return one or more random items from the collection.
Method	`reduce`	Reduce the collection to a single value using a callback.
Method	`reject`	Reject items that pass a given truth test.
Method	`reverse`	Reverse the order of items in the collection.
Method	`serialize`	Serialize the collection items as a list.
Method	`setAppends`	Set the attributes to append to the Collection.
Method	`shift`	Remove and return the first item from the collection.
Method	`sort`	Sort the items in the collection.
Method	`sum`	Compute the sum of the given values.
Method	`take`	Take a specific number of items from the collection.
Method	`toJson`	Return the collection items as a JSON string.
Method	`transform`	Transform each item in the collection using a callback.
Method	`unique`	Return unique items from the collection.
Method	`where`	Filter items by a given key-value pair or comparison.
Method	`whereIn`	Filter items where a given key's value is in a list of values.
Method	`whereNotIn`	Filter items where a given key's value is not in a list of values.
Method	`zip`	Zip the collection with the given items by index.
Instance Variable	`__appends__`	Undocumented
Instance Variable	`_items`	Undocumented

@classmethod

def __getItems(cls, items: list[Any] | Collection | object) -> list[Any] | object: (source) ¶

Extract the underlying items from a Collection or return the input as-is.

Parameters
items:`list[Any] \| Collection \| object`	The input to extract items from. If a Collection, its items are returned; otherwise, the input is returned unchanged.

Returns
`list[Any] \| object`	The extracted items if `items` is a Collection, otherwise the original input.

def __checkIsCallable(self, callback: object, *, raise_exception: bool = True) -> bool: (source) ¶

Check if the given callback is callable.

Parameters
callback:`Any`	The callback to check.
raise_exception:`bool, optional`	Whether to raise an exception if not callable. Default is True.

Returns
`bool`	True if the callback is callable, otherwise False.

Raises
`ValueError`	If callback is not callable and raise_exception is True.

def __dataGet(self, item: object, key: str, default: object = None) -> object: (source) ¶

Retrieve a value from an item using a nested key notation.

Parameters
item:`Any`	The item to extract data from.
key:`str`	The key to look for, supports nested notation.
default:`Any, optional`	The value to return if the key is not found. Defaults to None.

Returns
`Any`	The extracted value if found, otherwise the default value.

def __delitem__(self, key: int | str): (source) ¶

Delete an item from the collection at the specified key.

Parameters
key:`Any`	The index or key of the item to remove.

Returns
`None`	This method does not return a value.

def __eq__(self, other: object) -> bool: (source) ¶

Compare the collection with another object for equality.

Parameters
other:`object`	The object to compare with the current collection.

Returns
`bool`	True if the collections are equal, False otherwise.

def __ge__(self, other: object) -> bool: (source) ¶

Compare if the current collection is greater than or equal to another object.

Parameters
other:`object`	Object to compare with the current collection.

Returns
`bool`	True if the current collection is greater than or equal to the other object, otherwise False.

def __getitem__(self, item: int | slice) -> object | Collection: (source) ¶

Retrieve an item or a slice from the collection.

Parameters
item:`int or slice`	The index or slice to retrieve.

Returns
`Any or Collection`	The item at the given index, or a new Collection for a slice.

def __getValue(self, key: str | Callable | None) -> list[Any] | None: (source) ¶

Retrieve values from items using a key or callback.

Parameters
key:`str \| Callable \| None`	The key to extract or callback to apply.

Returns
`list[Any] \| None`	List of extracted values, or None if key is not provided.

def __gt__(self, other: object) -> bool: (source) ¶

Compare if the current collection is greater than another object.

Parameters
other:`object`	The object to compare with the current collection.

Returns
`bool`	True if the current collection is greater than the other object, otherwise False.

def __hash__(self) -> int: (source) ¶

Compute the hash value of the collection.

Returns
`int`	Hash value of the collection based on its items.

def __init__(self, items: list[Any] | None = None): (source) ¶

Initialize a new Collection instance.

Parameters
items:`list[Any] or None, optional`	Initial items for the collection (default is None).

Returns
`None`	This method does not return a value.

def __iter__(self) -> Iterator[Any]: (source) ¶

Iterate over the items in the collection.

Yields
`Any`	Each item in the collection.

def __le__(self, other: object) -> bool: (source) ¶

Compare if the current collection is less than or equal to another object.

Parameters
other:`object`	The object to compare with the current collection.

Returns
`bool`	True if the current collection is less than or equal to the other object, False otherwise.

def __len__(self) -> int: (source) ¶

Return the number of items in the collection.

Returns
`int`	The total number of items in the collection.

def __lt__(self, other: object) -> bool: (source) ¶

Compare if the current collection is less than another object.

Parameters
other:`object`	Object to compare with the current collection.

Returns
`bool`	True if the current collection is less than the other object, otherwise False.

def __makeComparison(self, a: object, b: object, op: str) -> bool: (source) ¶

Compare two values using the specified operator.

Parameters
a:`Any`	The first value to compare.
b:`Any`	The second value to compare.
op:`str`	The comparison operator as a string.

Returns
`bool`	True if the comparison is valid, otherwise False.

def __ne__(self, other: object) -> bool: (source) ¶

Determine if the collection is not equal to another object.

Parameters
other:`object`	The object to compare with the current collection.

Returns
`bool`	True if the collections are not equal, otherwise False.

def __setitem__(self, key: int | str, value: object): (source) ¶

Set the value at the specified key in the collection.

Parameters
key:`Any`	The index or key at which to set the value.
value:`Any`	The value to assign at the specified key.

Returns
`None`	This method does not return a value.

def __value(self, value: object) -> object: (source) ¶

Return the evaluated value if callable, otherwise return the value itself.

Parameters
value:`Any`	The value or callable to evaluate.

Returns
`Any`	The result of calling the value if it is callable, otherwise the value itself.

def _addUniqueItem(self, comparison: Any, item: Any, keys: set[Any], items: list[Any]): (source) ¶

Add a unique item to the collection based on the comparison value.

Parameters
comparison:`Any`	The value used to determine uniqueness.
item:`Any`	The item to potentially add.
keys:`set[Any]`	The set of seen comparison values.
items:`list[Any]`	The list of unique items.

Returns
`None`	This method does not return a value.

def _getUniqueItemsByKey(self, key: str) -> Collection: (source) ¶

Get unique items from the collection based on a specified key.

Parameters
key:`str`	The key to determine uniqueness for each item.

Returns
`Collection`	A new Collection containing only unique items by the given key.

def _getUniqueItemsWithoutKey(self) -> Collection: (source) ¶

Return unique items from the collection without using a key.

Returns
`Collection`	A new Collection containing only unique items.

def addRelation(self, relation_data: dict[str, Any]) -> Collection: (source) ¶

Add relation data to the collection.

Parameters
relation_data:`dict[str, Any]`	The relation data to add.

Returns
`Collection`	The current collection instance.

def all(self) -> list[Any]: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.all

Return all items in the collection.

Returns
`list of Any`	All items contained in the collection.

def avg(self, key: str | None = None) -> float: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.avg

Compute the average of the items.

Parameters
key:`str \| None, optional`	The key to use for calculating the average of values. If None, use all items.

Returns
`float`	The average value of the items. Returns 0 if calculation fails.

def chunk(self, size: int) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.chunk

Divide the collection into smaller collections of a specified size.

Parameters
size:`int`	Number of items in each chunk.

Returns
`Collection`	A new Collection containing sub-collections (chunks) of the specified size.

def collapse(self) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.collapse

Collapse the collection of arrays into a single, flat collection.

Returns
`Collection`	A new Collection containing all items from nested arrays, flattened.

def contains(self, key: str | Callable, value: object = None) -> bool: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.contains

Check if the collection contains a given item.

Parameters
key:`str or Callable`	The key to check for, or a callback function.
value:`Any, optional`	The value to match when key is a string, by default None.

Returns
`bool`	True if the item is found, False otherwise.

def count(self) -> int: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.count

Return the number of items in the collection.

Returns
`int`	The number of items in the collection.

def diff(self, items: list[Any] | Collection) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.diff

Return items not present in the given collection.

Parameters
items:`list[Any] \| Collection`	The items to compare against.

Returns
`Collection`	A new collection containing items not found in the provided collection.

def each(self, callback: Callable) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.each

Iterate over items and apply the callback to each.

Parameters
callback:`Callable`	The callback function to apply to each item.

Returns
`Collection`	The current collection instance.

def every(self, callback: Callable) -> bool: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.every

Determine whether all items satisfy the given callback condition.

Parameters
callback:`Callable`	The callback function to test each item.

Returns
`bool`	True if all items pass the test, otherwise False.

def filter(self, callback: Callable) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.filter

Filter items in the collection using a callback.

Parameters
callback:`Callable`	Function to determine if an item should be included.

Returns
`Collection`	A new Collection containing items for which the callback returns True.

def first(self, callback: Callable | None = None) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.first

Return the first item in the collection, optionally filtered by a callback.

Parameters
callback:`Callable \| None, optional`	A function to filter items before returning the first one, by default None.

Returns
`object`	The first item in the filtered collection, or None if empty.

def flatten(self) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.flatten

Flatten the collection into a single dimension.

Returns
`Collection`	A new Collection containing all items, flattened to a single dimension.

def forget(self, *keys: int | str) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.forget

Remove items from the collection by their keys.

Parameters
*keys:`Any`	The keys of the items to remove from the collection.

Returns
`Collection`	The current collection instance after removal.

def forPage(self, page: int, number: int) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.forPage

Slice the collection for pagination.

Parameters
page:`int`	The page number to retrieve.
number:`int`	The number of items per page.

Returns
`Collection`	A new Collection containing the paginated items.

def get(self, key: int | str, default: object = None) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.get

Retrieve an item from the collection by key.

Parameters
key:`Any`	The key or index to retrieve from the collection.
default:`Any, optional`	The value to return if the key is not found. Defaults to None.

Returns
`Any`	The item at the specified key, or the default value if not found.

def groupBy(self, key: str) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.groupBy

Group items in the collection by a specified key.

Parameters
key:`str`	The key to group items by.

Returns
`Collection`	A new Collection instance containing a dictionary where each key is a unique value from the specified key, and each value is a list of items sharing that key.

def implode(self, glue: str = ',', key: str | None = None) -> str: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.implode

Join all items in the collection into a single string.

Parameters
glue:`str, optional`	String used to join the items. Default is ",".
key:`str \| None, optional`	Key to extract from each item before joining. Default is None.

Returns
`str`	A string with all items joined by the specified glue.

def isEmpty(self) -> bool: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.isEmpty

Check if the collection is empty.

Returns
`bool`	True if the collection is empty, otherwise False.

def last(self, callback: Callable | None = None) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.last

Return the last item in the collection, optionally filtered by a callback.

Parameters
callback:`Callable \| None, optional`	Function to filter items before returning the last one, by default None.

Returns
`object`	The last item in the filtered collection, or None if empty.

def map(self, callback: Callable) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.map

Apply a function to each item in the collection.

Parameters
callback:`Callable`	Function to apply to each item.

Returns
`Collection`	A new Collection containing the mapped items.

def mapInto(self, cls: type, method: str | None = None, **kwargs: object) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.mapInto

Map items into instances of the given class.

Parameters
cls:`type`	The class to map items into.
method:`str \| None, optional`	The method to call on the class, by default None.
**kwargs:`Any`	Additional keyword arguments to pass to the constructor or method.

Returns
`Collection`	A new collection with the mapped instances.

def max(self, key: str | None = None) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.max

Return the maximum value from the items.

Parameters
key:`str \| None, optional`	The key to use for finding the maximum value. If None, use all items.

Returns
`object`	The maximum value found, or 0 if not found or on error.

def merge(self, items: list[Any] | Collection) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.merge

Merge the collection with the given items.

Parameters
items:`list[Any] \| Collection`	The items to merge into the collection.

Returns
`Collection`	The current collection instance with merged items.

Raises
`TypeError`	If items cannot be merged due to incompatible types.

def min(self, key: str | None = None) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.min

Return the minimum value from the items.

Parameters
key:`str \| None, optional`	The key to use for finding the minimum value. If None, use all items.

Returns
`object`	The minimum value found, or 0 if not found or on error.

def pluck(self, value: str, key: str | None = None) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.pluck

Extract values for a given key from all items.

Parameters
value:`str`	The key to extract from each item.
key:`str \| None, optional`	The key to use as the result key, by default None.

Returns
`Collection`	A new collection containing the plucked values.

def pop(self) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.pop

Remove and return the last item from the collection.

Returns
`Any`	The last item from the collection, or None if empty.

def prepend(self, value: object) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.prepend

Prepend an item to the beginning of the collection.

Parameters
value:`Any`	The value to prepend to the collection.

Returns
`Collection`	The current collection instance with the new item prepended.

def pull(self, key: int | str) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.pull

Remove and return an item from the collection by key.

Parameters
key:`Any`	The key of the item to remove.

Returns
`Any`	The removed item, or None if not found.

def push(self, value: object) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.push

Add an item to the end of the collection.

Parameters
value:`Any`	The value to add to the collection.

Returns
`Collection`	The current collection instance with the new item appended.

def put(self, key: int | str, value: object) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.put

Insert or update an item in the collection at the specified key.

Parameters
key:`Any`	The key or index at which to set the value.
value:`Any`	The value to assign at the specified key.

Returns
`Collection`	The current collection instance with the updated item.

def random(self, count: int | None = None) -> object | Collection | None: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.random

Return one or more random items from the collection.

Parameters
count:`int \| None, optional`	The number of items to return. If None, returns a single item.

Returns
`Any \| Collection \| None`	A single random item if count is None, a Collection if count is given, or None if the collection is empty.

Raises
`ValueError`	If count is greater than the number of items in the collection.

def reduce(self, callback: Callable, initial: object = 0) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.reduce

Reduce the collection to a single value using a callback.

Parameters
callback:`Callable`	The function to apply cumulatively to the items.
initial:`Any, optional`	The initial value to start the reduction, by default 0.

Returns
`Any`	The reduced value after applying the callback.

def reject(self, callback: Callable) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.reject

Reject items that pass a given truth test.

Parameters
callback:`Callable`	The callback function to test items.

Returns
`Collection`	The current collection instance with items not passing the test.

def reverse(self) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.reverse

Reverse the order of items in the collection.

Returns
`Collection`	The current collection instance with items in reversed order.

def serialize(self) -> list[Any]: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.serialize

Serialize the collection items as a list.

Returns
`list of Any`	The serialized items in the collection.

def setAppends(self, appends: list[str]) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.setAppends

Set the attributes to append to the Collection.

Parameters
appends:`list[str]`	The attributes to append.

Returns
`Collection`	The current collection instance.

def shift(self) -> object: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.shift

Remove and return the first item from the collection.

Returns
`Any`	The first item from the collection, or None if the collection is empty.

def sort(self, key: str | None = None) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.sort

Sort the items in the collection.

Parameters
key:`str \| None, optional`	The key to sort by. If None, sort items directly.

Returns
`Collection`	The current collection instance with sorted items.

def sum(self, key: str | None = None) -> float: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.sum

Compute the sum of the given values.

Parameters
key:`str \| None, optional`	The key to sum by. If None, sum all items.

Returns
`float`	The sum of the values. Returns 0 if calculation fails.

def take(self, number: int) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.take

Take a specific number of items from the collection.

Parameters
number:`int`	The number of items to take. If negative, takes from the end.

Returns
`Collection`	A new Collection containing the specified number of items.

def toJson(self, **kwargs: object) -> str: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.toJson

Return the collection items as a JSON string.

Parameters
**kwargs:`object`	Additional keyword arguments for json.dumps.

Returns
`str`	JSON string representing the serialized collection items.

def transform(self, callback: Callable) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.transform

Transform each item in the collection using a callback.

Parameters
callback:`Callable`	The callback function to transform items.

Returns
`Collection`	The current collection instance with transformed items.

def unique(self, key: str | None = None) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.unique

Return unique items from the collection.

Parameters
key:`str \| None, optional`	The key to use for uniqueness comparison. If None, use items directly.

Returns
`Collection`	A new Collection containing only unique items.

def where(self, key: str, *args: object) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.where

Filter items by a given key-value pair or comparison.

Parameters
key:`str`	The key to filter by.
*args:`Any`	The operator and value, or just the value.

Returns
`Collection`	A new Collection instance containing filtered items.

def whereIn(self, key: str, values: list[Any] | Collection) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.whereIn

Filter items where a given key's value is in a list of values.

Parameters
key:`str`	The key to filter by.
values:`list[Any] \| Collection`	The list of values to check against.

Returns
`Collection`	A new collection containing items where the key's value is in values.

def whereNotIn(self, key: str, values: list[Any] | Collection) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.whereNotIn

Filter items where a given key's value is not in a list of values.

Parameters
key:`str`	The key to filter by.
values:`list[Any] \| Collection`	The list of values to check against.

Returns
`Collection`	A new Collection containing items where the key's value is not in values.

def zip(self, items: list[Any] | Collection) -> Collection: (source) ¶

overrides orionis.support.types.contracts.collection.ICollection.zip

Zip the collection with the given items by index.

Parameters
items:`list[Any] \| Collection`	The items to zip with.

Returns
`Collection`	A new Collection containing pairs of items from both collections.

Raises
`ValueError`	If the 'items' parameter is not a list or Collection.

__appends__: list = (source) ¶

Undocumented

_items = (source) ¶

Undocumented