craft_store.base_client module

Craft Store BaseClient.

class craft_store.base_client.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.

  • 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.


errors.NoKeyringError – if there is no usable keyring.

get_list_releases(*, name)[source]

Query the list_releases endpoint and return the result.


name (str) –

Return type


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.

  • 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.


errors.CredentialsAlreadyAvailable – if credentials already exist.

Return type



Clear credentials.


errors.CredentialsUnavailable – if credentials cannot be found.

Return type


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.

Return type


release(*, name, release_request)[source]

Request a release of name.

  • name (str) – name to release.

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

Return type


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

Perform an authenticated request if auth_headers are True.

  • 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.

Return type



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
  • monitor_callback (Optional[Callable]) – a callback to monitor progress.

  • filepath (Path) –

Return type



Return whoami json data queyring endpoints.Endpoints.whoami.

Return type

Dict[str, Any]