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:

• CatalogManager
• Catalog
• Repository
• Collection
• CollectionItemFile

1.4.2. Data

COLLECTION_TYPES

A tuple of the known collection type identity strings. Collection types are logical groupings of published data types. These type identifiers provide some context as to how the data is intended to be used and what parts of the application may be interested in using it.

1.4.3. Functions

sign_item_files(local_path, signing_key, repo_path=None)

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:

• local_path (str) – The real location of where the files exist on disk.
• signing_key – The key with which to sign the files for verification.
• repo_path (str) – The path of the repository as it exists on disk.

1.4.4. Classes

class Catalog(data, keys=None)

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)

Parameters:

• data (dict) – The formatted catalog data.
• keys (SecurityKeys) – The keys to use for verifying remote data.

created

The timestamp of when the remote data was generated.

classmethod from_url(url, keys=None, encoding='utf-8')

Initialize a new Catalog object from a resource at the specified URL. The resulting data is validated against a schema file with validate_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:

Catalog

id

The unique identifier of this catalog.

maintainers

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

A dict of the Repository objects included in this catalog keyed by their id.

security_keys

The SecurityKeys used for verifying remote data.

to_dict()

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)

Bases: object

Base manager for handling multiple Catalog instances.

__init__(catalog_url=None)

Initialize self. See help(type(self)) for accurate signature.

add_catalog(catalog)

Adds the specified catalog to the manager.

Parameters:catalog (Catalog) – Add the specified catalog to the manager. Returns:The catalog. Return type:Catalog

catalog_ids()

The key names of the catalogs in the manager.

Returns:The catalogs IDs in the manager instance. Return type:tuple

class Collection(repo, type, items)

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 (see COLLECTION_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)

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.

classmethod from_dict(value, repo)

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)

A simple convenience method which forwards to the associated Repository’s get_file() method.

get_item(*args, **kwargs)

A simple convenience method which forwards to the associated Repository’s get_item() method.

get_item_files(*args, **kwargs)

A simple convenience method which forwards to the associated Repository’s get_item_files() method.

to_dict()

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)

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 and signed_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)

Initialize self. See help(type(self)) for accurate signature.

classmethod from_dict(value)

Load the collection item file from the specified dict object.

Parameters:value (dict) – The dictionary to load the data from. Returns:

path_destination

The relative path of where this file should be placed.

path_source

The relative path of where this file should be retrieved from.

signature

The signature data used for integrity verification of the represented resource.

signed_by

The identity of the SigningKey which generated the signature

to_dict()

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)

Bases: object

An object representing a single logical source of add on data.

__init__(data, keys=None)

Parameters:

• data (dict) – The formatted repository data.
• keys (SecurityKeys) – The keys to use for verifying remote data.

collections

The dictionary of the different collection types included in this repository.

get_file(item_file, encoding=None)

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:

bytes, str

get_item(collection_type, name)

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:

• collection_type (str) – The type of collection the specified item is in.
• name (str) – The name of the item to retrieve.

Returns:

The item if the repository provides it, otherwise None.

get_item_files(collection_type, name, destination)

Download all of the file references from the named item.

Parameters:

• collection_type (str) – The type of collection the specified item is in.
• name (str) – The name of the item to retrieve.
• destination (str) – The path of where to save the downloaded files to.

homepage

The URL of the homepage for this repository if it was specified.

id

The unique identifier of this repository.

security_keys

The SecurityKeys used for verifying remote data.

title

The title string of this repository.

to_dict()

Dump the instance to a dictionary suitable for being reloaded with __init__().

Returns:The instance represented as a dictionary. Return type:dict

url_base

The base URL string of files included in this repository.