:py:mod:`anod.store.component` ============================== .. py:module:: anod.store.component .. autoapi-nested-parse:: Handling of Store components. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: anod.store.component.Component Attributes ~~~~~~~~~~ .. autoapisummary:: anod.store.component.ComponentType anod.store.component.logger .. py:data:: ComponentType .. py:data:: logger .. py:class:: Component(build_id: str, name: str, platform: str, version: str, specname: str | None = None, files: list[e3.anod.store.file.File] | None = None, sources: list[e3.anod.store.file.File] | None = None, readme: e3.anod.store.file.File | None = None, attachments: dict[str, e3.anod.store.file.File] | list[ComponentAttachmentDict] | None = None, releases: list[str] | None = None, is_valid: bool = True, is_published: bool = False, component_id: str | None = None, creation_date: datetime.datetime | None = None, build_info: e3.anod.store.buildinfo.BuildInfo | None = None, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None, metadata: dict[str, object] | None = None) A Store component. A component is an entity that regroups binaries, sources and additional metadata. :ivar str build_id: build id :ivar str name: component name :ivar str platform: platform :ivar str version: version :ivar str | None specname: the name of the spec that created the component :ivar list[anod.store.file.File] | None files: list of binary files :ivar list[anod.store.file.File] | None sources: list of sources :ivar anod.store.file.File | None readme: readme file if present :ivar list[str] | None releases: list of releases :ivar bool is_valid: True if the component is valid :ivar bool is_published: True if published :ivar str | None component_id: ID of the component if defined :ivar datetime.datetime | None creation_date: component creation date :ivar BuildInfo | None build_info: build info :ivar StoreReadInterface | StoreRWInterface | None | None store: The store instance defined for this component .. py:attribute:: __hash__ .. py:method:: set_metadata_statement(name: str, data: e3.dsse.DSSE) -> None Set additional metadata statement. :param name: Statement name :param data: The Dead Simple Signature envelope of the data associated with *name*. .. py:method:: get_metadata_statement(name: str) -> e3.dsse.DSSE | None Get metadata statement. :param name: statement name :return: a DSSE envelope .. py:method:: add_attachment(key: str, file: e3.anod.store.file.File, overwrite_existing: bool = False) -> str | None Add a file in this component's attachments. Add given *file* to this component's attachments. A key made of *key*,*file.filename* is returned if the file was actually attached. If ``key,file.filename`` is already in the list of attachments, and *overwrite_existing* is **False**, **None** is returned. :param key: The key defining the type of attachment. For instance, ``"acats"``. A coma and the *file*'s ``filename`` is appended to this key to populate the attachment's dictionary. :param file: The file to be appended to this component's attachments. :param overwrite_existing: If *True*, the given *file* is added to this component's attachments, even if a file with the same *key* and *file.filename* is already attached. :return: The key of the attached file, or **None** if the file could not be attached. .. py:method:: get_attachments(key: str | None = None) -> dict[str, e3.anod.store.file.File] Get the list of attachments matching *key*. If an attachment key starts with ``,``, it is added to the returned list. If *key* is set to **None**, all elements are returned. :param key: The attachment key to match. If set to **None**, all attachments are returned. :return: A list of dictionaries. Each dictionary is simply made of the matching key and the attached file. .. py:method:: metadata_path(dest_dir: str, name: str) -> str :classmethod: Return path to file containing component metadata. :param dest_dir: directory in which the metadata file can be found :param name: file basename :return: a path to the metadata file .. py:method:: remove_attachment(key: str | None = None) -> bool Remove an attachment by key. To remove all `"spdx"` attachments (for instance), use `component.remove_attachment("spdx")`. :param key: The attachment key to match. If **None**, all attachments are removed. :return: **True** if an attachment is actually removed, **False** if no attachment matching *key* could be removed. .. py:method:: save_to_meta_file(dest_dir: str, name: str | None = None) -> 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:: submit_attachment(key: str, file: e3.anod.store.file.File) -> ComponentDict Submit an attachment to a store component. Add an attachment to an existing component, upload the file to Store, and update the list of attachments for that component. :param key: The type of attachment (`"spdx"` for instance). :param file: The file to be uploaded and attached to this component. :return: The updated component. :raise e3.anod.store.interface.StoreError: If the current store is not a writable instance :raise e3.anod.store.interface.StoreError: If submitting *file* did not return a valid ID :raise FileNotFoundError: If *file* has no valid `download_as` field (meaning the file does not exist on the file system) :raise ValueError: If this component is invalid (no valid ID) :raise ValueError: If *file* has no resource ID :raise ValueError: If the file could not be added to the attachments .. py:method:: load_from_meta_file(dest_dir: str, name: str, store: e3.anod.store.interface.StoreReadInterface | None = None, ignore_errors: Literal[False] = False) -> ComponentType load_from_meta_file(dest_dir: str, name: str, store: e3.anod.store.interface.StoreReadInterface | None = None, ignore_errors: Literal[True] = True) -> ComponentType | None :classmethod: Load components 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 component instance .. py:method:: as_dict() -> ComponentDict Return a dictionary representation of self. Feeding to this class' "load" method the value returned by this method creates a new Component value that is equal to self. :return: The dictionary representation of self. :rtype: dict .. py:method:: load(data: ComponentDict, store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface | None = None) -> typing_extensions.Self :classmethod: Create a Component from the result of a Store request. :param data: The dictionary returned by Store. :param store: a Store instance .. py:method:: latest(store: e3.anod.store.interface.StoreReadInterface | e3.anod.store.interface.StoreRWInterface, setup: str, date: str | None = None, platform: str = 'all', component: str = 'all', specname: str | None = None, build_id: str = 'all') -> list[typing_extensions.Self] :classmethod: Get a list of latest components. :param store: a store instance :param setup: setup name :param date: a build date. If not None then this means that only components from a given build date are considered. :param platform: a platform name. If set to ```all``` then latest component for each platform is returned. :param component: a component name. If set to ```all``` then latest component for each component name is returned. :param specname: the name of the spec that produced the component. If not None then this means that only components generated from the given specname are considered. :param build_id: the build id to use or "all". :return: a list of Components .. 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 | None Download the binary file associated with a component. :param dest_dir: directory in which the archive is kept. 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 binary '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. :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. :return: None if there are no binary associated, True if the file has been downloaded, or False if the file was already downloaded .. py:method:: push() -> typing_extensions.Self Push the component to store, using self.store to do so. This operation requires self.store to be a StoreRWInterface; otherwise, this method will crash. :raise AttributeError: If self.store is not a StoreRWInterface interface. :return: A newly created Component instance of the final component. The current instance is also updated accordingly. .. py:method:: __update(component: Component) -> None Update this component data. This method is used to update the value of the current component from another. This is especially used after a component is pushed to our store to update this component with the uploaded one, because after pushing a component, some internal values may change (for example, a component_id will be generated). :param component: The component object used to update the current one. .. py:method:: __eq__(other: object) -> bool Compare two component object. :param other: the other object to compare with the current one. :return: False if other is not a component or if other is different to the current component. .. py:method:: __ne__(other: object) -> bool Inverse of self.__eq__. :param other: the object to compare with :return: True if not self.__eq__(other).