cascade.base#

class cascade.base.Traceable(*args: Any, description: str | None = None, tags: Iterable[str] | None = None, **kwargs: Any)[source]#

Base class for everything that has metadata in Cascade Handles the logic of getting and updating internal meta prefix

__init__(*args: Any, description: str | None = None, tags: Iterable[str] | None = None, **kwargs: Any) → None[source]#
Parameters:

  • description – String description of an object

  • tags (Iterable[str], optional) – The list of tags to be added

See also

cascade.base.MetaHandler

__repr__() → str[source]#
Returns:

repr – Representation of a Traceable. This repr used as a name for get_meta() method by default gives the name of class from basic repr

Return type:

str

See also

cascade.data.Traceable.get_meta

comment(message: str) → None[source]#
describe(desc: str)[source]#

Add description to an object

Parameters:

desc (str) – String description of an object

Raises:

TypeError – If the input is not None and not a string either

from_meta(meta: List[Dict[Any, Any]] | Dict[Any, Any]) → None[source]#

Overwrites special fields like description, comments, tags and links from the given metadata

Updates meta_prefix too

Parameters:

meta (Meta)

get_meta() → List[Dict[Any, Any]][source]#
Returns:

meta – A list where first element is this object’s metadata. All other elements represent the other stages of pipeline if present.

Meta can be anything that is worth to document about the object and its properties.

Meta is a list (see Meta type alias) to allow the formation of pipelines.

Return type:

Meta

Links another object to this object. Links can contain name, URI and meta of the object.

To create the link the Traceable can be passed - if include is True (by default) object’s meta and string representation will be taken and saved with the link.

If include is False get_meta will still be called, but only small set of specific fields will be taken.

Link can be initialized without meta for example with only name or only URI. If path exists locally then it is automatically will be made absolute.

If name or meta passed with the object at the same time they will override values from the object.

The get_meta() of an object is resolved in the link method to prevent circular calls and other problems.

Parameters:

  • obj (Optional[Traceable]) – The object to link

  • name (Optional[str]) – Name of the object, overrides obj name if passed, by default None

  • uri (Optional[str]) – URI of the object, by default None

  • meta (Optional[Meta]) – Meta of the object, overrides obj meta if passed, by default None

  • include (bool, default is True) – Whether to include full meta of the object, by default True

remove_comment(id: int) → None[source]#
remove_description() → None[source]#

Empties object’s description

Removes a link given an index

Parameters:

idx (int) – Link’s index

remove_tag(tag: str | Iterable[str]) → None[source]#

Removes a tag from the existing set if tag is a string, else removes a list of tags in one call

Parameters:

tag (str) – A tag to remove

tag(tag: str | Iterable[str]) → None[source]#

If tag is a string: Adds a tag to existing set Makes no duplicates since tags are set If tag is an iterable of strings: Adds a list of tags in one call Makes no duplicates since tags are set

Parameters:

tag (str) – A tag to add

update_meta(meta: List[Dict[Any, Any]] | Dict[Any, Any]) → None[source]#

Updates _meta_prefix, which then updates dataset’s meta when get_meta() is called

Parameters:

meta (Meta) – The object to update with

Raises:

ValueError – If the list passed and it is not of the unit length

class cascade.base.MetaHandler[source]#

Encapsulates the logic of reading and writing metadata to disk.

Supported read-write formats are .json and .yml or .yaml. Other formats are supported as read-only. For example one can read meta from txt or md file.

Examples

>>> from cascade.base import MetaHandler
>>> MetaHandler.write('meta.json', {'hello': 'world'})
>>> obj = MetaHandler.read('meta.json')
>>> MetaHandler.write('meta.yml', {'hello': 'world'})
>>> obj = MetaHandler.read('meta.yml')
classmethod determine_meta_fmt(path: str, template: str) → str | None[source]#
classmethod read(path: str) → List[Dict[Any, Any]][source]#

Reads object from path.

Parameters:

path (str) – Path to the object.

Returns:

obj

Return type:

Meta

Raises:

MetaIOError – when decoding errors occur

classmethod read_dir(path: str, meta_template: str = 'meta.*') → List[Dict[Any, Any]][source]#

Reads a single meta file from a given directory

Parameters:

  • path (str) – Path to a directory

  • meta_template (str, optional) – The template to identify meta file, by default “meta.*”

Returns:

Meta

Return type:

Meta

Raises:

  • ZeroMetaError – If there is no files satisfying the template in the directory provided

  • MultipleMetaError – If the number of files filtered by the template are more than 1

classmethod write(path: str, obj: Any, overwrite: bool = True) → None[source]#

Writes object to path.

Parameters:

  • path (str) – Path where to write object with name and extension

  • obj – An object to be serialized and saved

  • overwrite (bool, optional) – Whether to overwrite the file if it already exists. If False and file already exists will silently return without saving.

Raises:

MetaIOError – when encoding errors occur

classmethod write_dir(path: str, obj: Any, overwrite: bool = True, meta_template: str = 'meta.*') → None[source]#

Writes meta to directory without specifying file name

Automatically determines extension and overwrites of file exists

Parameters:

  • path (str) – Directory to write meta

  • obj (Any) – Meta object

  • overwrite (bool, optional) – See MetaHandler.write, by default True

  • meta_template (str, optional) – The template for meta files, by default “meta.*”

On this page
Show Source