1.4. catalog
¶
This module provides functionality for processing and working with data published on the available add ons for the application.
1.4.1. Overview¶
The classes within this module are primarily for organizing the large amount of data describing published add ons. This information is broken down into the various objects in a hierarchy where the parent contain zero or more children objects. In this sense the hierarchy is a tree data structure where the nodes are different data types such as catalogs, repositories, collections etc.
The hierarchy of these objects is as follows in order of parent to children:
1.4.2. Data¶
1.4.3. Functions¶
-
sign_item_files
(local_path, signing_key, repo_path=None)[source]¶ This utility function is used to create a
CollectionItemFile
iterator from the specified source to be included in either a catalog file or one of it’s included files.Warning
This function contains a black list of file extensions which will be skipped. This is to avoid signing files originating from the development process such as
.pyc
and.ui~
.Parameters:
1.4.4. Classes¶
-
class
Catalog
(data, keys=None)[source]¶ Bases:
object
An object representing a set of
Repositories
containing add on data for the application. This information can then be loaded from an arbitrary source.-
__init__
(data, keys=None)[source]¶ Parameters: - data (dict) – The formatted catalog data.
- keys (
SecurityKeys
) – The keys to use for verifying remote data.
-
classmethod
from_url
(url, keys=None, encoding='utf-8')[source]¶ Initialize a new
Catalog
object from a resource at the specified URL. The resulting data is validated against a schema file withvalidate_json_schema()
before being passed to__init__()
.Parameters: - url (str) – The URL to the catalog data to load.
- keys (
SecurityKeys
) – The keys to use for verifying remote data. - encoding (str) – The encoding of the catalog data.
Returns: The new catalog instance.
Return type:
-
maintainers
[source]¶ A tuple containing the maintainers of the catalog and repositories. These are also the key identities that should be present for verifying the remote data.
-
repositories
[source]¶ A dict of the
Repository
objects included in this catalog keyed by their id.
-
security_keys
[source]¶ The
SecurityKeys
used for verifying remote data.
-
to_dict
()[source]¶ Dump the instance to a dictionary suitable for being reloaded with
__init__()
.Returns: The instance represented as a dictionary. Return type: dict
-
-
class
CatalogManager
(catalog_url=None)[source]¶ Bases:
object
Base manager for handling multiple
Catalog
instances.
-
class
Collection
(repo, type, items)[source]¶ Bases:
collections.abc.Mapping
An object representing a set of
CollectionItemFile
instances, each of which represent a piece of of add on data that are all of the same type (seeCOLLECTION_TYPES
). A collection is also a logical domain where the items contained within it must each have a unique identity in the form of its name attribute.-
__init__
(repo, type, items)[source]¶ Parameters: - repo (
Repository
) – The repository this collection is associated with. - type (str) – The collection type of these items.
- items (dict) – The items that are members of this collection, keyed by their name.
- repo (
-
classmethod
from_dict
(value, repo)[source]¶ Load the collection item file from the specified dict object.
Parameters: value (dict) – The dictionary to load the data from. Returns:
-
get_file
(*args, **kwargs)[source]¶ A simple convenience method which forwards to the associated
Repository
’sget_file()
method.
-
get_item
(*args, **kwargs)[source]¶ A simple convenience method which forwards to the associated
Repository
’sget_item()
method.
-
get_item_files
(*args, **kwargs)[source]¶ A simple convenience method which forwards to the associated
Repository
’sget_item_files()
method.
-
to_dict
()[source]¶ Dump the instance to a dictionary suitable for being reloaded with
from_dict()
.Returns: The instance represented as a dictionary. Return type: dict
-
-
class
CollectionItemFile
(path_destination, path_source, signature=None, signed_by=None)[source]¶ An object representing a single remote file and the necessary data to validate it’s integrity. In order to validate the data integrity both the
signature
andsigned_by
attributes must be available. These attributes must either both be present or absent, i.e. one can not be set without the other.-
__init__
(path_destination, path_source, signature=None, signed_by=None)[source]¶ Initialize self. See help(type(self)) for accurate signature.
-
classmethod
from_dict
(value)[source]¶ Load the collection item file from the specified dict object.
Parameters: value (dict) – The dictionary to load the data from. Returns:
-
signed_by
[source]¶ The identity of the
SigningKey
which generated thesignature
-
to_dict
()[source]¶ Dump the instance to a dictionary suitable for being reloaded with
from_dict()
.Returns: The instance represented as a dictionary. Return type: dict
-
-
class
Repository
(data, keys=None)[source]¶ Bases:
object
An object representing a single logical source of add on data.
-
__init__
(data, keys=None)[source]¶ Parameters: - data (dict) – The formatted repository data.
- keys (
SecurityKeys
) – The keys to use for verifying remote data.
-
get_file
(item_file, encoding=None)[source]¶ Download and return the file data from the repository. If no encoding is specified, the data is return as bytes, otherwise it is decoded to a string using the specified encoding. The file’s contents are verified using the signature that must be specified by the item_file information.
Parameters: - item_file (
CollectionItemFile
) – The information for the file to download. - encoding (str) – An optional encoding of the remote data.
Returns: The files contents.
Return type: - item_file (
-
get_item
(collection_type, name)[source]¶ Get the item by it’s name from the specified collection type. If the repository does not provide the named item, None is returned.
Parameters: Returns: The item if the repository provides it, otherwise None.
-
get_item_files
(collection_type, name, destination)[source]¶ Download all of the file references from the named item.
Parameters:
-
security_keys
[source]¶ The
SecurityKeys
used for verifying remote data.
-
to_dict
()[source]¶ Dump the instance to a dictionary suitable for being reloaded with
__init__()
.Returns: The instance represented as a dictionary. Return type: dict
-