nvflare.apis.storage module

exception StorageException[source]

Bases: Exception

Base class for Storage exceptions.

class StorageSpec[source]

Bases: ABC

Functional spec of object storage.

An object is identified by a URI (unique resource identifier). Each object contains:

  • content (data)

  • meta info that describes the control info of the object.

abstract clone_object(from_uri: str, to_uri: str, meta: dict, overwrite_existing: bool = False)[source]

Create a new object by cloning an existing one

Parameters:
  • from_uri – the existing object’s uri

  • to_uri – the uri for the new object

  • meta – meta info for the new object

  • overwrite_existing – whether to overwrite the new uri if already exists

Returns:

abstract create_object(uri: str, data, meta: dict, overwrite_existing: bool)[source]

Creates an object.

Examples of URI:

/state/engine/… /runs/approved/covid_exam.3 /runs/pending/spleen_seg.1

Parameters:
  • uri – URI of the object

  • data – content of the object. bytes or file name.

  • meta – meta info of the object

  • overwrite_existing – whether to overwrite the object if already exists

Raises StorageException when:
  • invalid args

  • object already exists and overwrite_existing is False

  • error creating the object

abstract delete_object(uri: str)[source]

Deletes specified object.

Parameters:

uri – URI of the object

abstract get_data(uri: str, component_name: str = 'data') bytes[source]

Gets data of the specified object.

Parameters:
  • uri – URI of the object

  • component_name – storage component name

Returns:

data of the object. if object does not exist, return None

Raises StorageException when:
  • invalid args

abstract get_data_for_download(uri: str, component_name: str = 'data', download_file: str | None = None)[source]

Gets data of the specified object.

Parameters:
  • uri – URI of the object

  • component_name – storage component name

  • download_file – component file_name for download

Raises StorageException when:
  • invalid args

abstract get_detail(uri: str) Tuple[dict, bytes][source]

Gets both data and meta of the specified object.

Parameters:

uri – URI of the object

Returns:

meta info and data of the object.

Raises StorageException when:
  • invalid args

  • no such object

abstract get_meta(uri: str) dict[source]

Gets user defined meta info of the specified object.

Parameters:

uri – URI of the object

Returns:

meta info of the object. if object does not exist, return empty dict {}

Raises StorageException when:
  • invalid args

static is_valid_component(component_name)[source]
abstract list_objects(path: str, without_tag=None) List[str][source]

Lists all objects in the specified path.

Parameters:
  • path – the path to the objects

  • without_tag – skip the objects with this specified tag

Returns:

list of URIs of objects

abstract tag_object(uri: str, tag: str, data=None)[source]

Tag an object with specified tag and data.

Parameters:
  • uri – URI of the object

  • tag – tag to be placed on the object

  • data – data associated with the tag.

Returns: None

abstract update_meta(uri: str, meta: dict, replace: bool)[source]

Updates the meta info of the specified object.

Parameters:
  • uri – URI of the object

  • meta – value of new meta info

  • replace – whether to replace the current meta completely or partial update

Raises StorageException when:
  • invalid args

  • no such object

  • error updating the object

abstract update_object(uri: str, data, component_name: str)[source]

Update the object

Parameters:
  • uri – URI of the object

  • data – content data of the component, or the content file location

  • component_name – component name

Raises StorageException when the object does not exit.