craft_store package

Subpackages

Submodules

Module contents

Interact with Canonical services such as Charmhub and the Snap Store.

class craft_store.Auth(application_name, host, environment_auth=None, ephemeral=False)[source]

Bases: object

Auth wraps around the keyring to store credentials.

The application_name and host are used as key/values in the keyring to set, get and delete credentials.

If environment_auth is set on initialization of this class, then a MemoryKeyring is setup in lieu of the system one.

Credentials are base64 encoded into the keyring and decoded on retrieval.

Variables
  • application_name – name of the application using this library.

  • host – specific host for the store used.

Parameters
  • application_name (str) –

  • host (str) –

  • environment_auth (Optional[str]) –

  • ephemeral (bool) –

static decode_credentials(encoded_credentials)[source]

Decode base64 encoded credentials.

Raises

errors.CredentialsNotParseable – when the credentials are incorrectly encoded.

Parameters

encoded_credentials (str) –

Return type

str

del_credentials()[source]

Delete credentials from the keyring.

Return type

None

static encode_credentials(credentials)[source]

Encode credentials to base64.

Parameters

credentials (str) –

Return type

str

ensure_no_credentials()[source]

Check that no credentials exist.

Raises

errors.CredentialsAvailable – if credentials have already been set.

Return type

None

get_credentials()[source]

Retrieve credentials from the keyring.

Return type

str

set_credentials(credentials, force=False)[source]

Store credentials in the keyring.

Parameters
  • credentials (str) – token to store.

  • force (bool) – overwrite existing credentials.

Return type

None

class craft_store.BaseClient(*, base_url, storage_base_url, endpoints, application_name, user_agent, environment_auth=None, ephemeral=False)[source]

Bases: object

Encapsulates API calls for the Snap Store or Charmhub.

Parameters
  • base_url (str) – the base url of the API endpoint.

  • storage_base_url (str) – the base url for storage.

  • endpoints (Endpoints) – endpoints.CHARMHUB or endpoints.SNAP_STORE.

  • application_name (str) – the name application using this class, used for the keyring.

  • user_agent (str) – User-Agent header to use for HTTP(s) requests.

  • environment_auth (Optional[str]) – environment variable to use for credentials.

  • ephemeral (bool) – keep everything in memory.

Raises

errors.NoKeyringError – if there is no usable keyring.

get_list_releases(*, name)[source]

Query the list_releases endpoint and return the result.

Parameters

name (str) –

Return type

MarshableModel

login(*, permissions, description, ttl, packages=None, channels=None, **kwargs)[source]

Obtain credentials to perform authenticated requests.

Credentials are stored on the system’s keyring, handled by craft_store.auth.Auth.

The list of permissions to select from can be referred to on craft_store.attenuations.

The login process requires 3 steps:

This last macaroon is stored into the system’s keyring to perform authenticated requests.

Parameters
  • permissions (Sequence[str]) – Set of permissions to grant the login.

  • description (str) – Client description to refer to from the Store.

  • ttl (int) – time to live for the credential, in other words, how long until it expires, expressed in seconds.

  • packages (Optional[Sequence[Package]]) – Sequence of packages to limit the credentials to.

  • channels (Optional[Sequence[str]]) – Sequence of channel names to limit the credentials to.

Raises

errors.CredentialsAlreadyAvailable – if credentials already exist.

Return type

str

logout()[source]

Clear credentials.

Raises

errors.CredentialsUnavailable – if credentials cannot be found.

Return type

None

notify_revision(*, name, revision_request)[source]

Post to the revisions endpoint to notify the store about an upload.

This request usually takes place after a successful upload.

Parameters
Return type

RevisionsResponseModel

release(*, name, release_request)[source]

Request a release of name.

Parameters
  • name (str) – name to release.

  • release_request (Sequence[ReleaseRequestModel]) – sequence of items to release.

Return type

None

request(method, url, params=None, headers=None, **kwargs)[source]

Perform an authenticated request if auth_headers are True.

Parameters
  • method (str) – HTTP method used for the request.

  • url (str) – URL to request with method.

  • params (Optional[Dict[str, str]]) – Query parameters to be sent along with the request.

  • headers (Optional[Dict[str, str]]) – Headers to be sent along with the request.

Raises
Return type

Response

Returns

Response from the request.

upload_file(*, filepath, monitor_callback=None)[source]

Upload filepath to storage.

The monitor_callback is a method receiving one argument of type MultipartEncoder, the total length of the upload can be accessed from this encoder from the len attribute to setup a progress bar instance.

The callback is to return a function that receives a MultipartEncoderMonitor from which the .bytes_read attribute can be read to update progress.

The simplest implementation can look like:

def monitor_callback(encoder: requests_toolbelt.MultipartEncoder):

    # instantiate progress class with total bytes encoder.len

    def progress_printer(monitor: requests_toolbelt.MultipartEncoderMonitor):
       # Print progress using monitor.bytes_read

    return progress_printer
Parameters
  • monitor_callback (Optional[Callable]) – a callback to monitor progress.

  • filepath (Path) –

Return type

str

whoami()[source]

Return whoami json data queyring endpoints.Endpoints.whoami.

Return type

Dict[str, Any]

class craft_store.HTTPClient(*, user_agent)[source]

Bases: object

Generic HTTP Client to communicate with Canonical’s Developer Gateway.

This client has a requests like interface, it creates a requests.Session on initialization to handle retries over HTTP and HTTPS requests.

The default number of retries is set in REQUEST_TOTAL_RETRIES and can be overridden with the CRAFT_STORE_RETRIES environment variable.

The backoff factor has a default set in REQUEST_BACKOFF and can be overridden with the CRAFT_STORE_BACKOFF environment variable.

Retries are done for the following return codes: 500, 502, 503 and 504.

Variables

user_agent – User-Agent header to identify the client.

Parameters

user_agent (str) –

get(*args, **kwargs)[source]

Perform an HTTP GET request.

Return type

Response

post(*args, **kwargs)[source]

Perform an HTTP POST request.

Return type

Response

put(*args, **kwargs)[source]

Perform an HTTP PUT request.

Return type

Response

request(method, url, params=None, headers=None, **kwargs)[source]

Send a request to url.

user_agent is set as part of the headers for the request. All requests are logged through a debug logs, headers matching Authorization and Macaroons have their value replaced.

Parameters
  • method (str) – HTTP method used for the request.

  • url (str) – URL to request with method.

  • params (Optional[Dict[str, str]]) – Query parameters to be sent along with the request.

  • headers (Optional[Dict[str, str]]) – Headers to be sent along with the request.

Raises
Return type

Response

Returns

Response from the request.

class craft_store.StoreClient(*, base_url, storage_base_url, endpoints, application_name, user_agent, environment_auth=None, ephemeral=False)[source]

Bases: craft_store.base_client.BaseClient

Encapsulates API calls for the Snap Store or Charmhub.

Parameters
  • base_url (str) –

  • storage_base_url (str) –

  • endpoints (Endpoints) –

  • application_name (str) –

  • user_agent (str) –

  • environment_auth (Optional[str]) –

  • ephemeral (bool) –

TOKEN_TYPE: str = 'macaroon'
class craft_store.UbuntuOneStoreClient(*, base_url, storage_base_url, auth_url, endpoints, application_name, user_agent, environment_auth=None, ephemeral=False)[source]

Bases: craft_store.base_client.BaseClient

Encapsulates API calls for the Snap Store or Charmhub with Ubuntu One.

Parameters
  • base_url (str) –

  • storage_base_url (str) –

  • auth_url (str) –

  • endpoints (Endpoints) –

  • application_name (str) –

  • user_agent (str) –

  • environment_auth (Optional[str]) –

  • ephemeral (bool) –

TOKEN_TYPE: str = 'u1-macaroon'
request(method, url, params=None, headers=None, **kwargs)[source]

Perform an authenticated request if auth_headers are True.

Parameters
  • method (str) – HTTP method used for the request.

  • url (str) – URL to request with method.

  • params (Optional[Dict[str, str]]) – Query parameters to be sent along with the request.

  • headers (Optional[Dict[str, str]]) – Headers to be sent along with the request.

Raises
Return type

Response

Returns

Response from the request.