DelfiniCollection

class pydelfini.collections.DelfiniCollection(model, core)

Bases: FolderMixin

Represents a collection on a Delfini instance.

Typically created by one of the collection methods in pydelfini.client.DelfiniClient.

In addition to collection-specific attributes and methods, this class also behaves as a folder (representing the top level of the collection’s folder structure). See FolderMixin for those methods.

Attributes

created_on	Datetime when collection was created
description	Collection text description
id	Collection internal ID
metadata	Collection metadata
name	Collection name
path
version_id	Current version ID

Parameters:

• model (Collection)

• core (AuthenticatedClient)

__getitem__(item_path)

Retrieve an item in this folder.

Relative paths are supported, such as folder_a/folder_b/item_c.

Parameters:

item_path (str)

Return type:

DelfiniItem

__iter__()

Iterate over all items in this folder.

Return type:

Iterator[DelfiniItem]

property created_on: datetime

Datetime when collection was created

delete_collection()

Deletes the entire collection, permanently.

You cannot delete the LIVE version of a collection if there exist other versions of the collection.

Return type:

None

property description: str

Collection text description

folder(folder_name)

Open the named folder.

Parameters:

folder_name (str) – the name of the folder to open

Return type:

DelfiniFolder

get_item_by_id(item_id)

Retrieves an item by its unique ID.

Parameters:

item_id (str)

Return type:

DelfiniItem

get_table(item_path)

Retrieve the tabular contents of an item as a pd.DataFrame.

Parameters:

item_path (str) – The path to the item relative to the current folder. Accepts slashes (‘/’) for items in subfolders.

Return type:

DataFrame

property id: str

Collection internal ID

property metadata: dict[str, str]

Collection metadata

property name: str

Collection name

new_empty_file(file_name)

Create a new, empty file.

Parameters:

file_name (str) – the name of the file to create

Return type:

DelfiniItem

new_folder(folder_name)

Create a new folder.

Parameters:

folder_name (str) – the name of the folder to create

Return type:

DelfiniFolder

new_link(target, link_name=None)

Create a new link pointing to a target.

Parameters:

• target (str) – the full URL of the target

• link_name (str) – the name of the newly created link. If not provided, the base name of the target will be used.

Return type:

DelfiniItem

open(item_path: str, mode: Literal['r']) → TextIO

open(item_path: str, mode: Literal['rb']) → BinaryIO

open(item_path: str, mode: Literal['w'], *, type: Literal['file', 'dataview', 'dictionary'] = 'file', parser: None | str | ItemParser = None, columns: None | Series | Schema | list[ItemColumn] = None, metadata: dict[str, str] | None = None) → TextIO

open(item_path: str, mode: Literal['wb'], *, type: Literal['file', 'dataview', 'dictionary'] = 'file', parser: None | str | ItemParser = None, columns: None | Series | Schema | list[ItemColumn] = None, metadata: dict[str, str] | None = None) → BinaryIO

Open an item for reading or writing.

When writing an item, it is important to use the returned file-like object either in a context manager or else call its close() method when writing is complete, otherwise the full contents of the file may not be written.

Suggested usage:

with collection.open('new-item', 'wb') as fp:
    fp.write(b'my item content, as much as I have\n')

Parameters:

• item_path – The path to the item relative to the top level of the collection. Accepts slashes (‘/’) for items located in subfolders.

• mode –

  One of the following values, depending on the desired interaction mode:

  • r - reading, text mode

  • rb - reading, binary mode

  • w - writing, text mode

  • wb - writing, binary mode

• parser – If writing, optionally specify the item parser type. Typical values for this would be csv or parquet.

• columns – If writing, optionally specify the item column schema. Requires parser to be set.

• metadata – If writing, optionally specify the item metadata. Typical values for this would be something like {"content-type": "text-csv"}.

Returns:

A file-like interface, either BinaryIO or TextIO depending on whether the file was to be opened in binary or text mode. When writing, the return will be an instance of item_io.DelfiniItemCreatorBinary or item_io.DelfiniItemCreatorText.

property version_id: str

Current version ID

walk()

Iterate over all items in this folder, and all subfolders.

Return type:

Iterator[DelfiniItem]

write_table(item_path, dataframe, format='csv', overwrite=False, **kwargs)

Write a pd.DataFrame to the named item.

If the item already exists and overwrite is False, an error is raised. If overwrite is True and the item exists, its data is overwritten.

Parameters:

• item_path (str) – The path to the item relative to the current folder. Accepts slashes (‘/’) for items in subfolders.

• dataframe (DataFrame) – The dataframe to be written.

• format (Literal['csv', 'parquet']) – One of the supported formats (csv or parquet).

• overwrite (bool) – If True, overwrite existing item data if it exists. If False (default), raises an error if item already exists.

• **kwargs (Any) – Any other arguments to be passed to the Pandas export function. See the documentation for pd.DataFrame.to_csv() or pd.DataFrame.to_parquet() for valid arguments.

Return type:

None