:py:mod:`anod.store.file` ========================= .. py:module:: anod.store.file .. autoapi-nested-parse:: File resource management for Anod store. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: anod.store.file.Resource anod.store.file.FileKind anod.store.file.File Attributes ~~~~~~~~~~ .. autoapisummary:: anod.store.file.FileType anod.store.file.logger .. py:data:: FileType .. py:data:: logger .. py:class:: Resource The resource information about a file. :ivar id: The resource id (generaly the sha1 of the file). :ivar path: The resource path (Where the file is located). :ivar size: The file size. :ivar creation_date: The creation date of this resource. .. py:attribute:: id :type: str .. py:attribute:: path :type: os.PathLike[str] | str .. py:attribute:: size :type: int .. py:attribute:: creation_date :type: str .. py:class:: FileKind(*args, **kwds) Bases: :py:obj:`enum.Enum` The kind of file object to be stored. .. py:attribute:: source :value: 'source' .. py:attribute:: readme :value: 'readme' .. py:attribute:: thirdparty :value: 'thirdparty' .. py:attribute:: binary :value: 'binary' .. py:attribute:: attachment :value: 'attachment' .. py:class:: 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. :ivar file_id: file ID. :vartype file_id: str :ivar build_id: build ID under which the File was created. :vartype build_id: str :ivar kind: file type :vartype kind: FileKind :ivar name: name of the resource (this is not the filename). :vartype name: str :ivar resource_id: resource ID of the file content :vartype resource_id: str :ivar filename: expected filename. :vartype filename: str :ivar alias: alternate filename. :vartype alias: str :ivar revision: free form field containing revision information :vartype revision: str :ivar metadata: additional metadata :vartype metadata: dict | None :ivar internal: True if the File can be distributed outside AdaCore, False otherwise. May also be None, if the information is not known. :vartype internal: bool | None :ivar build_info: build info :vartype build: BuildInfo | None .. py:attribute:: __hash__ .. py:method:: push() -> typing_extensions.Self Upload this file to Store, using self.store to do so. :return: A newly created File instance of the final file. The current instance is also updated accordingly. .. py:method:: __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). :param file: The file object or its dict representation used to update the current one. .. py:method:: 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). :param path: the file path on the current computer .. py:method:: set_metadata_statement(name: str, data: e3.dsse.DSSE) -> None Set metadata statement. :param name: statement name :param data: DSSE envelope associated with the statement .. py:method:: get_metadata_statement(name: str) -> e3.dsse.DSSE | None Get metadata statement. :param name: statement name :return: a DSSE envelope or None if not found .. py:method:: update_metadata() -> None Push file updates to Store. .. py:method:: metadata_path(dest_dir: str, name: str) -> str :classmethod: Return the path to the metadata file associated to a File. :param dest_dir: directory where the File is to be downloaded to :param name: the File name attribute :return: the path to the metadata file .. py:method:: 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. :param 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. :param 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. :param 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. :param 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 :param remove_root_dir: see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is True :param unpack_cmd: see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is None :param delete: see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is True :param ignore: see e3.archive.unpack_archive. Relevant only if unpack_dir is not None. Default is None :param 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.). :return: 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. .. py:method:: as_dict() -> FileDict Convert the current File instance into a python dictionary. :return: The dictionary representation of the file instance. .. py:method:: load(data: FileDict, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None) -> typing_extensions.Self :classmethod: Load and create a File class instance from a dictionary. :param data: dictionary representing a file :param store: the store class to use if store operations are needed :return: the File instance .. py:method:: 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 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 :classmethod: Load file from a metadata file. :param dest_dir: directory in which the metadata is located :param name: file basename :param store: a store instance to bind to the returned object :param ignore_errors: if True, in case of errors return None. Otherwise, StoreError is raised. :return: a File instance .. py:method:: save_to_meta_file(dest_dir: str, name: str) -> None Dump as json file component information. :param dest_dir: directory in which the metadata file should be saved :param name: file basename .. py:method:: upload_thirdparty(store: e3.anod.store.interface.StoreRWInterface, path: str, force: bool = False) -> typing_extensions.Self :classmethod: Upload the given file to Store as a third party. :param store: a store read-write object :param path: the path to the file to upload :param force: if True, do not raise an error if the file already exists :raise StoreError: if the file already exists in Store (unless force is True) :return: a File instance corresponding to the uploaded file on Store .. py:method:: upload_thirdparty_from_dir(store: e3.anod.store.interface.StoreRWInterface, path: str, prefix: str, build_dir: str | None = None) -> str :classmethod: 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. :param store: the store class used to interact with the store system :param path: local directory from which an archive will be created :param prefix: prefix of the third party package name to create :param build_dir: where the generated packages will be stored :return: name of the uploaded package .. py:method:: __eq__(other: object) -> bool Compare two file object. :param other: the other object to compare with the current one. :return: False if other is not a file or if other is different to the current file. .. py:method:: __ne__(other: object) -> bool Inverse of self.__eq__. :return: True if not self.__eq__(other). .. py:method:: __str__() -> str Convert a file to a str.