craft_store package

Subpackages

craft_store.models package
- Submodules
- Module contents

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.
errors.KeyringUnlockError – if the keyring cannot be unlocked.

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

list_registered_names(*, include_collaborations=False)[source]

List the registered names available to the logged in account.

Parameters: include_collaborations (bool) – if True, includes names the user is a collaborator on but does not own.
Return type: List[RegisteredNameModel]

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:

request an initial macaroon on endpoints.Endpoints.tokens.
discharge that macaroon using Candid
send the discharge macaroon to endpoints.Endpoints.tokens_exchange to obtain final authorization of the macaroon

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

name (str) –
revision_request (RevisionsRequestModel) –

Return type

RevisionsResponseModel

register_name(name, *, entity_type=None, private=False, team=None)[source]

Register a name on the store.

Parameters

name (str) – the name to register.
entity_type (Optional[Literal[‘charm’, ‘bundle’, ‘snap’]]) – The type of package to register (e.g. charm or snap)
private (bool) – Whether this entity is private or not.
team (Optional[str]) – An optional team ID to register the name with.

Return type

str

Returns

the ID of the registered name.

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

errors.StoreServerError – for error responses.
errors.NetworkError – for lower level network issues.
errors.CredentialsUnavailable – if credentials cannot be found.

Return type

Response

Returns

Response from the request.

unregister_name(name)[source]

Unregister a name with no published packages.

Parameters: name (str) – The name to unregister.
Return type: str
Returns: the ID of the deleted name.

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

errors.StoreServerError – for error responses.
errors.NetworkError – for lower level network issues.

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

errors.StoreServerError – for error responses.
errors.NetworkError – for lower level network issues.
errors.CredentialsUnavailable – if credentials cannot be found.

Return type

Response

Returns

Response from the request.