edlio package#

Module contents#

Module to work with data in an Experiment Directory Layout (EDL) structure

class edlio.EDLCollection(name=None)#

Bases: EDLGroup

An EDL Collection

__init__(name=None)#

Create a new EDL collection.

If the collection has no name and path set, it can not be saved to disk.

Parameters:

name (str | None) – Name of this collection, or None

property collection_idname: str#

Retrieve a human-readable string for this collection which is most likely (but not guaranteed to be) unique. If this collection has no properties set, the value of this property may be None or empty. The format of the returned string is arbitrary and should not be parsed.

property generator_id: str | None#

Identification string of the software which generated this EDL unit.

class edlio.EDLDataFile(base_path, media_type=None, file_type=None, unit_attrs=None)#

Bases: object

A data file, associated with a dataset

property base_path: Path | None#

Directory that the file parts are stored in, relative to which part names resolve.

property data_type: tuple[str | None, str | None]#
property file_type: str | None#

The filetype, in case no media type was available.

property media_type: str | None#

The media (MIME) type of this data.

new_part(fname, index=-1, *, allow_exists=False)#
Return type:

tuple[EDLDataPart, Path]

part_paths()#

Return a generator for the path of each file-part, in their correct sorting order.

Return type:

Iterator[PathLike[str]]

parts: list[EDLDataPart]#
read(aux_data_entries=None, **kwargs)#

Read all data parts in this set.

This returns a generator which reads all the individual data parts in this data file. The data reader may take auxiliary data into account, if :aux_data is passed.

Return type:

Any

property summary: str | None#

A human-readable summary of what this data is about.

class edlio.EDLDataPart(fname, index=-1)#

Bases: object

Describes a part of a data block that has been split into multiple files.

fname: Path#
index: int = -1#
class edlio.EDLDataset(name=None)#

Bases: EDLUnit

An EDL Dataset

__init__(name=None)#

Create a new EDL dataset.

If the dataset has no name and path set, it can not be saved to disk.

Parameters:

name (str | None) – Name of this dataset, or None

add_aux_data(adf)#
Return type:

None

property aux_data: list[EDLDataFile]#
property data: EDLDataFile#
load(path, mf=None)#

Load an EDL dataset from a path.

Parameters:
Return type:

None

read_aux_data(key=None, **kwargs)#

Read auxiliary data from this dataset.

Parameters:

  • key (str | None) – Identifier key for the auxiliary dataset to load. Will look for a substring match in file_type/media_type properties of the data first, then look for a summary text match to determine which data was requested. If not set, the first dataset is loaded.

  • kwargs (Any) – Additional keyword arguments forwarded to the data loader (e.g. as_dataframe for CSV/JSON aux data).

Return type:

Any | None

read_data(**kwargs)#

Read data from this dataset.

Returns a generator to read data from this dataset by individual chunks, taking auxiliary data into account.

Return type:

Any

property root_path: Path | None#
save()#

Save dataset changes to their current location on disk.

Return type:

None

exception edlio.EDLError(message)#

Bases: Exception

Exception raised for errors in the input.

Attributes:

message – explanation of the error

class edlio.EDLGroup(name=None)#

Bases: EDLUnit

An EDL Group

__init__(name=None)#

Create a new EDL group.

If the group has no name and path set, it can not be saved to disk.

Parameters:

name (str | None) – Name of this group, or None

add_child(child)#
Return type:

None

change_name(new_name)#
Return type:

None

property children: list[EDLUnit]#
property collection_id: UUID#
dataset_by_name(name, *, create=False)#
Return type:

EDLDataset | None

property datasets: Iterator[EDLDataset]#
group_by_name(name, *, create=False)#
Return type:

EDLGroup | None

property groups: Iterator[EDLGroup]#
load(path, mf=None)#

Load an EDL unit from a path or path/data combination.

Parameters:
Return type:

None

property root_path: Path | None#
save()#
Return type:

None

edlio.Q_#

alias of Quantity

edlio.load(path)#

Open an EDL unit via its filesystem path.

This function will read an EDL unit on the filesystem and return an object representing it. Depending on the type of the EDL unit, the returned datatype may be a collection, group or dataset.

Parameters:

path (str | PathLike[str]) – The filesystem location of the EDL unit.

Returns:

An EDL unit.

Return type:

EDLCollection | EDLGroup | EDLDataset

Submodules#

edlio.collection module#

class edlio.collection.EDLCollection(name=None)#

Bases: EDLGroup

An EDL Collection

__init__(name=None)#

Create a new EDL collection.

If the collection has no name and path set, it can not be saved to disk.

Parameters:

name (str | None) – Name of this collection, or None

property collection_idname: str#

Retrieve a human-readable string for this collection which is most likely (but not guaranteed to be) unique. If this collection has no properties set, the value of this property may be None or empty. The format of the returned string is arbitrary and should not be parsed.

property generator_id: str | None#

Identification string of the software which generated this EDL unit.

edlio.dataset module#

class edlio.dataset.EDLDataFile(base_path, media_type=None, file_type=None, unit_attrs=None)#

Bases: object

A data file, associated with a dataset

property base_path: Path | None#

Directory that the file parts are stored in, relative to which part names resolve.

property data_type: tuple[str | None, str | None]#
property file_type: str | None#

The filetype, in case no media type was available.

property media_type: str | None#

The media (MIME) type of this data.

new_part(fname, index=-1, *, allow_exists=False)#
Return type:

tuple[EDLDataPart, Path]

part_paths()#

Return a generator for the path of each file-part, in their correct sorting order.

Return type:

Iterator[PathLike[str]]

parts: list[EDLDataPart]#
read(aux_data_entries=None, **kwargs)#

Read all data parts in this set.

This returns a generator which reads all the individual data parts in this data file. The data reader may take auxiliary data into account, if :aux_data is passed.

Return type:

Any

property summary: str | None#

A human-readable summary of what this data is about.

class edlio.dataset.EDLDataPart(fname, index=-1)#

Bases: object

Describes a part of a data block that has been split into multiple files.

fname: Path#
index: int = -1#
class edlio.dataset.EDLDataset(name=None)#

Bases: EDLUnit

An EDL Dataset

__init__(name=None)#

Create a new EDL dataset.

If the dataset has no name and path set, it can not be saved to disk.

Parameters:

name (str | None) – Name of this dataset, or None

add_aux_data(adf)#
Return type:

None

property aux_data: list[EDLDataFile]#
property data: EDLDataFile#
load(path, mf=None)#

Load an EDL dataset from a path.

Parameters:
Return type:

None

read_aux_data(key=None, **kwargs)#

Read auxiliary data from this dataset.

Parameters:

  • key (str | None) – Identifier key for the auxiliary dataset to load. Will look for a substring match in file_type/media_type properties of the data first, then look for a summary text match to determine which data was requested. If not set, the first dataset is loaded.

  • kwargs (Any) – Additional keyword arguments forwarded to the data loader (e.g. as_dataframe for CSV/JSON aux data).

Return type:

Any | None

read_data(**kwargs)#

Read data from this dataset.

Returns a generator to read data from this dataset by individual chunks, taking auxiliary data into account.

Return type:

Any

property root_path: Path | None#
save()#

Save dataset changes to their current location on disk.

Return type:

None

edlio.group module#

class edlio.group.EDLGroup(name=None)#

Bases: EDLUnit

An EDL Group

__init__(name=None)#

Create a new EDL group.

If the group has no name and path set, it can not be saved to disk.

Parameters:

name (str | None) – Name of this group, or None

add_child(child)#
Return type:

None

change_name(new_name)#
Return type:

None

property children: list[EDLUnit]#
property collection_id: UUID#
dataset_by_name(name, *, create=False)#
Return type:

EDLDataset | None

property datasets: Iterator[EDLDataset]#
group_by_name(name, *, create=False)#
Return type:

EDLGroup | None

property groups: Iterator[EDLGroup]#
load(path, mf=None)#

Load an EDL unit from a path or path/data combination.

Parameters:
Return type:

None

property root_path: Path | None#
save()#
Return type:

None

edlio.unit module#

exception edlio.unit.EDLError(message)#

Bases: Exception

Exception raised for errors in the input.

Attributes:

message – explanation of the error

class edlio.unit.EDLUnit(name=None)#

Bases: object

Generic base class for all EDL unit types.

property attributes: dict#
property authors: list[Any]#
change_name(new_name)#
Return type:

None

property collection_id: UUID#
load(path, mf=None)#

Load an EDL unit from a path or path/data combination.

Parameters:
Return type:

None

property name: str | None#
property parent: EDLUnit | None#
property path: Path#
property root_path: Path | None#
save()#
Return type:

None

property time_created: datetime#
property unit_type: str#
edlio.unit.make_collection_uuid()#

Create an UUID for use in an EDL collection.

Return type:

UUID

edlio.utils module#

edlio.utils.listify(item)#
Overloads:

  • item (list[_T]) → list[_T]

  • item (_T) → list[_T]

Return a list of :item, unless :item already is a list.

edlio.utils.sanitize_name(name)#

Sanitize a string for use as an EDL unit name, by stripping or replacing invalid characters.

Parameters:

name (str | None) – A string to sanitize.

Returns:

The sanitized name.

Return type:

str | None

Subpackages#

On this page
Show Source