:py:mod:`anod.store.interface` ============================== .. py:module:: anod.store.interface .. autoapi-nested-parse:: Store interface for Anod binary and source packages. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: anod.store.interface._StoreContextManager anod.store.interface.StoreReadInterface anod.store.interface.StoreWriteInterface anod.store.interface.StoreRWInterface anod.store.interface.LocalStoreInterface Functions ~~~~~~~~~ .. autoapisummary:: anod.store.interface.resource_id Attributes ~~~~~~~~~~ .. autoapisummary:: anod.store.interface.StoreContextManagerType .. py:data:: StoreContextManagerType .. py:exception:: StoreError(message: str | list[str], origin: str | None = None) Bases: :py:obj:`e3.error.E3Error` Exception raised for store operations errors. .. py:exception:: StoreConnectionError(message: str | list[str], origin: str | None = None) Bases: :py:obj:`StoreError` Exception used to indicate a connection error with the online store. Having this special exception allows the user to make distinction between access to the store and request errors (for example when an object cannot be found). .. py:function:: resource_id(path: os.PathLike[str] | str) -> str Given a path to a file return the resource id. :param path: a path to an existing path :return: a resource id .. py:class:: _StoreContextManager A class to define the context manager interface needed by a Store class. .. py:method:: __enter__() -> StoreContextManagerType :abstractmethod: Enter in a new context. This method is called when used with the "with" keyword. For example: .. code-block:: python with _StoreContextManager() as x: pass :return: Self .. py:method:: __exit__(*args: object) -> None :abstractmethod: Exit a context. This method is called when exiting a "with" context. For example: .. code-block:: python with _StoreContextManager() as x: pass # __exit__ is call here .. py:method:: close() -> None :abstractmethod: Close the current context. This method is used to close a context, generally not initiated using the `with` keyword. See `builtin.open` for more example. .. py:class:: StoreReadInterface Bases: :py:obj:`_StoreContextManager` A class that defines the Store read interface. .. py:method:: resource_id(path: str) -> str :classmethod: Given a path to a file return the resource id. :param path: a path to an existing path :return: a resource id .. py:method:: list_release_components(name: str, component: str = 'all', version: str = 'all', platform: str = 'all') -> list[e3.anod.store.component.ComponentDict] :abstractmethod: List components for a given release name. :param name: The release name. :param component: A component name or 'all' to match all components. :param version: A component version or all to match all version. :param platform: A platform name or 'all' to match all platforms. :return: a list of component description. See e3.anod.store.component.Component.load implementation for the description of the expected structure. .. py:method:: list_components(bid: str, component: str = 'all', platform: str = 'all') -> list[e3.anod.store.component.ComponentDict] :abstractmethod: List components for a given build id. :param bid: a build id :param component: a component name or 'all' to match all components :param platform: a platform name or 'all' to match all platforms :return: a list of component description. See e3.anod.store.component.Component.load implementation for the description of the expected structure. .. py:method:: latest_components(setup: str, date: str | None = None, platform: str = 'all', component: str = 'all', specname: str | None = None, build_id: str = 'all') -> list[e3.anod.store.component.ComponentDict] :abstractmethod: Get a list of latest components. :param setup: the setup name :param date: a build date or None :param platform: a platform name or 'all' to match all platforms :param component: a component name or 'all' to get all components :param specname: the name of the spec that generated the component or 'all' to include all "generator" specs :param build_id: a build id :return: a list of component description. See e3.anod.store.file.File.load. Note that no error is raised when no component matching the criteria is found (an empty list is returned). .. py:method:: get_build_data(bid: str) -> BuildDataDict :abstractmethod: Fetch all data corresponding to a build id. :param bid: a build id :return: a dict with two keys: 'components' and 'sources'. If key as a list associated. See e3.anod.store.file.File.load and e3.anod.store.component.Component.load for description of the expected structure .. py:method:: get_build_info(bid: str) -> e3.anod.store.buildinfo.BuildInfoDict :abstractmethod: Get build metadata. :param bid: a build id :return: a dict with the build metadata. See e3.anod.store.buildinfo.BuildInfo.load for description of the structure. .. py:method:: get_build_info_list(date: str | None = 'all', setup: str | None = 'all', version: str | None = 'all', nb_days: int = 1) -> list[e3.anod.store.buildinfo.BuildInfoDict] :abstractmethod: Get latest build metadata for the last *nb_days* days. :param date: a build date to start lookup from :param setup: a setup name :param version: a build version or 'all'. None has the same meaning as 'all' :param nb_days: maximum number of days to get build information for. :return: a dict with the build metadata. See e3.anod.store.buildinfo.BuildInfo.load for description of the structure. .. py:method:: get_latest_build_info(setup: str, date: str | None = 'all', version: str | None = 'all', ready_only: bool = True) -> e3.anod.store.buildinfo.BuildInfoDict :abstractmethod: Get latest build metadata. :param setup: a setup name :param date: a build date or 'all'. None has the same meaning as 'all' :param version: a build version or 'all'. None has the same meaning as 'all' :param ready_only: if True discard build that are not marked 'isready' :return: a dict with the build metadata. See e3.anod.store.buildinfo.BuildInfo.load for description of the structure. .. py:method:: get_source_info(name: str, bid: str, kind: str = 'source') -> e3.anod.store.file.FileDict :abstractmethod: Get source metadata. Important note: if the source does not exist for the required bid then the latest source with a build id anterior to the requested one will be returned for the corresponding setup. :param name: The name of the source to get info for. :param bid: a build id :param kind: source kind. Can be currently 'source' or 'thirdparty'. :return: a dict representing a file structure (see e3.anod.store.file.File.load) .. py:method:: download_resource(rid: str, path: str) -> str :abstractmethod: Download a resource. :param rid: the resource id :param path: destination :return: absolute path to the downloaded resource .. py:method:: latest_thirdparty(name: str, tp_id: str = 'all', rid: str = 'all') -> e3.anod.store.file.FileDict | None :abstractmethod: Get third party metadata. :param name: Third party name. :param tp_id: Third party id or 'all'. :param rid: Third party resource_id or 'all'. :return: a dict representing a file structure or None if the third party does not exist. (See e3.anod.store.file.File.load) .. py:method:: bulk_query(queries: list[dict[str, Any]]) -> list[dict[str, Any]] :abstractmethod: Perform a list of queries (source and components) to Store. Each element of the queries list should conform to the following specifications: Source queries have the following format: .. code-block:: python {'query': 'source', 'name': 'str' # The name of the File to retrieve 'kind': 'str' # 'thirdparty' or 'source' (OPTIONAL) 'bid': 'str' # NECESSARY if kind not is not 'thirdparty'} Component queries have the following format: .. code-block:: python {'query': 'component', 'platform': 'str', 'name': 'str', 'setup': 'str', 'date': 'str' # OPTIONAL} The answer is a JSON array. Each item has the following format: {'query': dict # A copy of the input query 'msg': str # A message in case of error 'response': dict # A query answer (a file or component structure)} :param queries: a list of queries :return: a list of answers .. py:class:: StoreWriteInterface A class that defines the Store write interface. .. py:method:: create_thirdparty(file_info: e3.anod.store.file.FileDict) -> e3.anod.store.file.FileDict :abstractmethod: Upload a new third party. :param file_info: a dict representing a file structure. (see e3.anod.store.file.File.load) :return: a dict representing the final file structure (see e3.anod.store.file.File.load) .. py:method:: submit_component(component_info: e3.anod.store.component.ComponentDict) -> e3.anod.store.component.ComponentDict :abstractmethod: Upload a component to store. :param component_info: a dict representing a component :return: a dict representing the final component .. py:method:: submit_file(file_info: e3.anod.store.file.FileDict) -> e3.anod.store.file.FileDict :abstractmethod: Upload a new file to store. :param file_info: a dict representing a file structure :return: a dict representing the final file structure .. py:method:: mark_build_ready(bid: str) -> bool :abstractmethod: Mark a build id as ready. The mechanism is used to synchronize source packaging with component builds startup :param bid: a build id :return: True if success .. py:method:: create_build_id(setup: str, date: str, version: str) -> e3.anod.store.buildinfo.BuildInfoDict :abstractmethod: Create a new build id. :param setup: the setup name :param date: the build date of the new build id :param version: the version of the new build id :return: a build id dict .. py:method:: copy_build_id(bid: str, dest_setup: str) -> e3.anod.store.buildinfo.BuildInfoDict :abstractmethod: Copy a build id. :param bid: a build id :param dest_setup: setup destination different from source setup :return: a dict representing a build id .. py:method:: update_file_metadata(file_info: e3.anod.store.file.FileDict) -> e3.anod.store.file.FileDict :abstractmethod: Update file resource metadata. :param file_info: a dict representing a file structure :return: a dict representing the updated file .. py:method:: add_component_attachment(component_id: str, file_id: str, name: str) -> None :abstractmethod: Add an attachment to a component. This function attach an ALREADY SUBMITTED file to a component. :param component_id: the component id. :param file_id: the id of the attachment file. :param name: the attachment name. .. py:class:: StoreRWInterface Bases: :py:obj:`StoreReadInterface`, :py:obj:`StoreWriteInterface` Combined read-write interface for store operations. .. py:class:: LocalStoreInterface Interface for local store operations. .. py:method:: raw_add_build_info(build_info_data: e3.anod.store.buildinfo.BuildInfoDict) -> None :abstractmethod: Add a build info to the local store. :param build_info_data: build info data (i.e: result of BuildInfo.as_dict()) .. py:method:: add_build_info_from_store(from_store: StoreReadInterface, bid: str) -> None :abstractmethod: Add a build info to the local store from another store instance. :param from_store: The other store instance where the buildinfo is retrieve. :param bid: The buildinfo ID to retrieve. .. py:method:: raw_add_file(file_info: e3.anod.store.file.FileDict) -> None :abstractmethod: Add a file to the local store. :param file_info: a file dict (i.e: result of File.as_dict()). .. py:method:: add_source_from_store(from_store: StoreReadInterface, name: str, bid: str | None = None, setup: str | None = None, date: str = 'all', kind: Literal[source, thirdparty] = 'source') -> None :abstractmethod: Add a file info and all associated informations to the db. The associated build id is also automatically added. .. note:: If the file information is already present no call to the online store is performed. This method doesn't retrieve the resource pointed by the added file. Trying to download the file without calling `add_resource` will raise an error. :param from_store: instance of an online store to query. :param name: the source name to retrieve. :param bid: a build id. :param setup: a setup name. :param date: a build date. :param kind: kind can be either source or thirdparty. .. py:method:: raw_add_component(component_info: e3.anod.store.component.ComponentDict) -> None :abstractmethod: Add a component to the local store. :param component_info: a Component dict (i.e: result of Component.as_dict()). .. py:method:: add_component_from_store(from_store: StoreReadInterface, setup: str, name: str = 'all', platform: str = 'all', date: str | None = None, specname: str | None = None) -> None :abstractmethod: Add a component and all associated informatios to the db. The associated build id is also automatically added :param from_store: instance of an online store to query. :param setup: a setup name. :param name: a component name. :param platform: a platform name. :param date: a build date. :param specname: the spec name related to the component. .. py:method:: save(filename: pathlib.Path | None = None) -> None :abstractmethod: Save the local store database. This function can does nothing and is hightly related to the LocalStore implementation. :param filename: the file path to save the database. .. py:method:: bulk_update_from_store(from_store: StoreReadInterface, queries: list[dict[str, Any]]) -> list[dict[str, Any]] :abstractmethod: Perform a list of update queries (source and components) to Store. Each element of the queries list should conform to the specifications define by self.bulk_query. This function will populate the LocalStore depending of the queries. :param from_store: instance of an online store to query. :param queries: a list of queries :return: a list of answers