PetCollection#

class petdb.PetCollection(path: str)#

Bases: PetArray[dict]

Represents a single PetDB collection. It provides methods for accessing, managing and manipulating documents.

Parameters:: path – Path to the json file where collection’s documents are stored. It also used to specify the name of the collection.

classmethod get_instance(path: str) → PetCollection#

classmethod instances() → dict[str, dict]#

replace(data: list[dict])#

Replaces all documents in the collection with the given data.

Parameters:: data – list of documents to replace

dump() → None#: Dumps documents into a collection’s storage file

save() → None#: Alias for PetCollection.dump()

insert(doc: dict) → dict#

Insert a new document into the collection.

Parameters:: doc – the document to insert
Returns:: inserted document

insert_many(docs: Iterable[dict] & Sized) → list[dict]#

Insert multiple documents into the collection.

Parameters:: docs – an Iterable of documents to insert
Returns:: a list containing the inserted documents

update_one(update: dict, query: str | dict | list[str | dict] = None) → None#: Applies update query to a single element matching the given query

update(update: dict, query: dict | list[str | dict] = None) → None#: Applies update query to all elements that match the given query

remove(query: str | dict | list[str | dict]) → list[dict]#

Removes matched documents. Accepts id, query object, list of ids and list of documents. Performs clearing if the query is None. Returns removed documents.

Returns:: removed documents

get(id: str) → dict | None#

Search for the document with the given id.

Parameters:: id – document’s id to search
Returns:: the document with the given id or None

filter(query: dict | Callable[[dict], bool]) → PetMutable#: Perform filter mutation. Accepts only query object.

sort(query: i_sort = None, reverse: bool = False) → PetMutable#: Perform sort mutation. Accepts a path, list of paths and sorting function.

clear() → List[T]#

Removes all elements from the array.

Returns:: Removed elements

contains(query: T | dict | Callable[[T], bool]) → bool#

Check whether the collection contains a document matching a query.

Parameters:: query – the query object

delete(query: dict) → Self#: Calls the remove method and returns self

exists(query: T | dict | Callable[[T], bool]) → bool#: Alias for PetArray.contains()

find(query: dict | Callable[[T], bool]) → T | None#

Returns the first element that satisfies the provided query. If no values satisfy, None is returned.

Parameters:: query – A query object that to match against
Returns:: The first matched element or None

findall(query: dict | Callable[[T], bool]) → List[T]#

Returns all elements that satisfy the provided query. If no values satisfy, the empty list is returned.

Parameters:: query – A query object that selects which documents to include in the result set
Returns:: List of matched documents

foreach(func: Callable[[T], None]) → None#

Go through all elements and call the given function with each.

Parameters:: func – function that takes each element in the array

groupby(key: str | int | Iterable[str | int] | Callable[[T], Any] = None) → PetArray[dict]#

Groups elements by field accessed by a key.

Parameters:: key – The key or keys to access value or values to group elements by.
Returns:: A PetArray of dicts with key and items fields.
Raises:: QueryException – If the key type is not a string, integer or iterable of strings or integers.

join(delimiter: str, adapter: Callable[[T], str] = None) → str#

Compose all elements of a PetArray into the single string with the given delimiter.

Parameters:

delimiter – Separator used to join elements.
adapter – Function to convert each element to string.

Returns:

The concatenated string

length(query: T | dict | Callable[[T], bool] = None) → int#: Returns the amount of all documents in the collection

list() → List[T]#

Returns all documents stored in the collection as a list

Returns:: a list with all documents.

map(func: Callable[[T], TP]) → PetArray[TP]#: Perform map mutation. Accepts only callable object.

omit(*queries: str) → PetArray#

Makes a list of copies of objects without the omitted properties.

Parameters:: queries – Queries to omit keys from objects.

pick(*queries: str | int | Callable[[T], TP]) → PetArray[TP]#

Makes a list of copies of objects consisting of the picked properties.

Parameters:: queries – Queries to pick keys from objects.

reduce(reducer: Callable[[TP, T], TP], init: TP = None) → TP#

Executes the given “reducer” callback function on each element of the array, passing in the return value from the calculation on the preceding element. The final result of running the reducer across all elements of the array is a single value.

Parameters:

reducer – A function to execute for each element in the array with the next signature: reducer(accumulator: TP, item: T) -> TP. Its return value becomes the value of the accumulator parameter on the next invocation of reducer. For the last invocation, the return value becomes the return value of reduce(). The function is called with the following arguments:
init – A value to which accumulator is initialized the first time the callback is called. If init is specified, reducer starts executing with the first value in the array as item. If init is not specified, accumulator is initialized to the first value in the array, and reducer starts executing with the second value in the array as currentValue. In this case, if the array is empty (so that there’s no first value to return as accumulator), a None is returned.

Returns:

The value that results from running the reducer callback to completion over the entire array.

size(query: T | dict | Callable[[T], bool] = None) → int#: Returns the amount of all documents in the collection

unique(query: str | int | Callable[[T], Any] = None) → PetArray[T]#: Removes all repeated elements