anod.store.file

File resource management for Anod store.

Module Contents

Classes

Resource

The resource information about a file.

FileKind

The kind of file object to be stored.

File

A file served by Store.

Attributes

FileType

logger

anod.store.file.FileType
anod.store.file.logger
class anod.store.file.Resource

The resource information about a file.

Variables:

  • id – The resource id (generaly the sha1 of the file).

  • path – The resource path (Where the file is located).

  • size – The file size.

  • creation_date – The creation date of this resource.

id: str
path: os.PathLike[str] | str
size: int
creation_date: str
class anod.store.file.FileKind(*args, **kwds)

Bases: enum.Enum

The kind of file object to be stored.

source = 'source'
readme = 'readme'
thirdparty = 'thirdparty'
binary = 'binary'
attachment = 'attachment'
class anod.store.file.File(build_id: str, kind: FileKind, name: str, filename: str, resource_id: str | None = None, file_id: str | None = None, internal: bool = True, alias: str | None = None, revision: str = '', build_info: e3.anod.store.buildinfo.BuildInfo | None = None, metadata: dict[str, Any] | None = None, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None, resource_path: os.PathLike[str] | str | None = None, unpack_dir: str | None = None, resource: Resource | None = None)

A file served by Store.

Variables:

  • file_id (str) – file ID.

  • build_id (str) – build ID under which the File was created.

  • kind (FileKind) – file type

  • name (str) – name of the resource (this is not the filename).

  • resource_id (str) – resource ID of the file content

  • filename (str) – expected filename.

  • alias (str) – alternate filename.

  • revision (str) – free form field containing revision information

  • metadata (dict | None) – additional metadata

  • internal (bool | None) – True if the File can be distributed outside AdaCore, False otherwise. May also be None, if the information is not known.

  • build_info – build info

__hash__
push() → typing_extensions.Self

Upload this file to Store, using self.store to do so.

Returns:

A newly created File instance of the final file. The current instance is also updated accordingly.

__update(file: typing_extensions.Self) → None

Update this file data.

This method is used to update the value of the current file from another.

This is especially used after a file is pushed to our store to update this file with the uploaded one, because after pushing a file, some internal values may change (for example, a file_id will be generated).

Parameters:

file – The file object or its dict representation used to update the current one.

bind_to_resource(path: os.PathLike[str] | str) → None

Bind this File to the file at the given path.

Unless self.resource_id is already set, this also sets self.resource_id using this file’s contents (see e3.anod.store.interface.resource_id for more info on that).

Parameters:

path – the file path on the current computer

set_metadata_statement(name: str, data: e3.dsse.DSSE) → None

Set metadata statement.

Parameters:

  • name – statement name

  • data – DSSE envelope associated with the statement

get_metadata_statement(name: str) → e3.dsse.DSSE | None

Get metadata statement.

Parameters:

name – statement name

Returns:

a DSSE envelope or None if not found

update_metadata() → None

Push file updates to Store.

classmethod metadata_path(dest_dir: str, name: str) → str

Return the path to the metadata file associated to a File.

Parameters:

  • dest_dir – directory where the File is to be downloaded to

  • name – the File name attribute

Returns:

the path to the metadata file

download(dest_dir: str | None, as_name: str | None = None, unpack_dir: str | None = None, save_metadata: bool = True, remove_root_dir: e3.archive.RemoveRootDirType = True, unpack_cmd: collections.abc.Callable[Ellipsis, None] | None = None, delete: bool = True, ignore: list[str] | None = None, tmp_dir_root: str | None = None) → bool

Download a file.

Note that self.resource_id must be set before this method is called, since the file to download is identified using this identifier. Raise StoreError if this requirement is not met.

In case the current component has unpack_dir or downloaded as set then the local resource is used rather than retrieving it from the store.

Parameters:

  • dest_dir – directory in which we keep the archive. If None then the archive will be downloaded in a temporary location and deleted before the function returns. Having both unpack_dir and dest_dir set to None will result in a dummy operation.

  • as_name – if set to None then the resulting filename is the File ‘name’ + an extension. If not None as_name is used instead. The extension used is the extension of the filename attribute. If the name attribute or as_name already have the same extension as filename then the extension won’t be repeated twice.

  • unpack_dir – if not None a call to unpack_archive is done with destination set to unpack_dir. Note that the directory should exist otherwise StoreError will be raised.

  • save_metadata – if True save a metadata file along with the downloaded file. Note that the option has no effect if dest_dir is set to None

  • remove_root_dir – see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is True

  • unpack_cmd – see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is None

  • delete – see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is True

  • ignore – see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is None

  • tmp_dir_root – see e3.archive.unpack_archive. Relevant only when remove_root_dir is True.

Raise:

StoreError if any error is detected (file does not exist, destination directory does not exist, etc.).

Returns:

True if a file was downloaded, False if the download was skipped because the file has already been downloaded and the local copy is up to date.

as_dict() → FileDict

Convert the current File instance into a python dictionary.

Returns:

The dictionary representation of the file instance.

classmethod load(data: FileDict, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None) → typing_extensions.Self

Load and create a File class instance from a dictionary.

Parameters:

  • data – dictionary representing a file

  • store – the store class to use if store operations are needed

Returns:

the File instance

classmethod load_from_meta_file(dest_dir: str, name: str, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None, ignore_errors: Literal[False] = False) → FileType
classmethod load_from_meta_file(dest_dir: str, name: str, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None, ignore_errors: Literal[True] = True) → FileType | None

Load file from a metadata file.

Parameters:

  • dest_dir – directory in which the metadata is located

  • name – file basename

  • store – a store instance to bind to the returned object

  • ignore_errors – if True, in case of errors return None. Otherwise, StoreError is raised.

Returns:

a File instance

save_to_meta_file(dest_dir: str, name: str) → None

Dump as json file component information.

Parameters:

  • dest_dir – directory in which the metadata file should be saved

  • name – file basename

classmethod upload_thirdparty(store: e3.anod.store.interface.StoreRWInterface, path: str, force: bool = False) → typing_extensions.Self

Upload the given file to Store as a third party.

Parameters:

  • store – a store read-write object

  • path – the path to the file to upload

  • force – if True, do not raise an error if the file already exists

Raises:

StoreError – if the file already exists in Store (unless force is True)

Returns:

a File instance corresponding to the uploaded file on Store

classmethod upload_thirdparty_from_dir(store: e3.anod.store.interface.StoreRWInterface, path: str, prefix: str, build_dir: str | None = None) → str

Generate a third party package from local directory and upload it.

This is meant to generate a tarball from a directory on the local filesystem and upload it as third party to Store. The date of the day is added to the package name. If the package already exists, a suffix is automatically added. If too many packages have been created that day with the same name the function will raise StoreError.

Parameters:

  • store – the store class used to interact with the store system

  • path – local directory from which an archive will be created

  • prefix – prefix of the third party package name to create

  • build_dir – where the generated packages will be stored

Returns:

name of the uploaded package

__eq__(other: object) → bool

Compare two file object.

Parameters:

other – the other object to compare with the current one.

Returns:

False if other is not a file or if other is different to the current file.

__ne__(other: object) → bool

Inverse of self.__eq__.

Returns:

True if not self.__eq__(other).

__str__() → str

Convert a file to a str.