canonicalwebteam.store-api 4.11.0__tar.gz → 4.11.2__tar.gz

{canonicalwebteam_store_api-4.11.0 → canonicalwebteam_store_api-4.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: canonicalwebteam.store-api
-Version: 4.11.0
+Version: 4.11.2
 Summary: 
 License: LGPL-3.0
 Author: Canonical Web Team

{canonicalwebteam_store_api-4.11.0 → canonicalwebteam_store_api-4.11.2}/canonicalwebteam/store_api/publisher.py

@@ -81,7 +81,7 @@ class Publisher:
             )
 
             return {
-                "Authorization": f"Macaroon root={root}, discharge={bound}"
+                "Authorization": f"macaroon root={root}, discharge={bound}"
             }
         # With Candid the header is Macaroons
         elif "macaroons" in session:
@@ -95,8 +95,12 @@ class Publisher:
         return headers.get("WWW-Authenticate") == ("Macaroon needs_refresh=1")
 
     def get_account(self, session):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/account.html#get--dev-api-account
+        Endpoint: [GET] https://dashboard.snapcraft.io/dev/api/account
+        """
         headers = self._get_authorization_header(session)
-
         response = self.session.get(
             url=self.get_endpoint_url("account"), headers=headers
         )
@@ -104,11 +108,21 @@ class Publisher:
         return self.process_response(response)
 
     def get_account_snaps(self, session):
+        """
+        Returns the snaps associated with a user account
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/account.html#get--dev-api-account
+        Endpoint: [GET] https://dashboard.snapcraft.io/dev/api/account
+        """
         return self.get_account(session).get("snaps", {}).get("16", {})
 
     def get_agreement(self, session):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#release-a-snap-build-to-a-channel
+        Endpoint: [GET] https://dashboard.snapcraft.io/dev/api/agreement
+        """
         headers = self._get_authorization_header(session)
-
         agreement_response = self.session.get(
             url=self.get_endpoint_url("agreement/"), headers=headers
         )
@@ -119,6 +133,11 @@ class Publisher:
         return agreement_response.json()
 
     def post_agreement(self, session, agreed):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#release-a-snap-build-to-a-channel
+        Endpoint: [POST] https://dashboard.snapcraft.io/dev/api/agreement
+        """
         headers = self._get_authorization_header(session)
 
         json = {"latest_tos_accepted": agreed}
@@ -129,6 +148,11 @@ class Publisher:
         return self.process_response(agreement_response)
 
     def post_username(self, session, username):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/account.html#get--dev-api-account
+        Endpoint: [PATCH] https://dashboard.snapcraft.io/dev/api/account
+        """
         headers = self._get_authorization_header(session)
         json = {"short_namespace": username}
         username_response = self.session.patch(
@@ -141,6 +165,11 @@ class Publisher:
             return self.process_response(username_response)
 
     def get_publisher_metrics(self, session, json):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#fetch-metrics-for-snaps
+        Endpoint: [POST] https://dashboard.snapcraft.io/dev/api/snaps/metrics
+        """
         headers = self._get_authorization_header(session)
         headers["Content-Type"] = "application/json"
 
@@ -160,6 +189,11 @@ class Publisher:
         is_private=False,
         store=None,
     ):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#register-a-snap-name
+        Endpoint: [POST] https://dashboard.snapcraft.io/dev/api/register-name/
+        """
         json = {"snap_name": snap_name}
 
         if registrant_comment:
@@ -180,6 +214,12 @@ class Publisher:
         return self.process_response(response)
 
     def post_register_name_dispute(self, session, snap_name, claim_comment):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#register-a-snap-name-dispute
+        Endpoint: [POST]
+            https://dashboard.snapcraft.io/dev/api/register-name-dispute
+        """
         json = {"snap_name": snap_name, "comment": claim_comment}
 
         response = self.session.post(
@@ -191,6 +231,12 @@ class Publisher:
         return self.process_response(response)
 
     def get_snap_info(self, snap_name, session):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#obtaining-information-about-a-snap
+        Endpoint: [GET]
+            https://dashboard.snapcraft.io/dev/api/snaps/info/{snap_name}
+        """
         response = self.session.get(
             url=self.get_endpoint_url(f"snaps/info/{snap_name}"),
             headers=self._get_authorization_header(session),
@@ -199,6 +245,11 @@ class Publisher:
         return self.process_response(response)
 
     def get_package_upload_macaroon(self, session, snap_name, channels):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/macaroon.html#request-a-macaroon
+        Endpoint: [POST] https://dashboard.snapcraft.io/dev/api/acl/
+        """
         json = {
             "packages": [{"name": snap_name, "series": "16"}],
             "permissions": ["package_upload"],
@@ -214,11 +265,22 @@ class Publisher:
         return self.process_response(response)
 
     def get_snap_id(self, snap_name, session):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#obtaining-information-about-a-snap
+        Endpoint: https://dashboard.snapcraft.io/dev/api/snaps/info/{snap_name}
+        """
         snap_info = self.get_snap_info(snap_name, session)
 
         return snap_info["snap_id"]
 
     def snap_metadata(self, snap_id, session, json=None):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#managing-snap-metadata
+        Endpoint: [PUT]
+            https://dashboard.snapcraft.io/dev/api/snaps/{snap_id}/metadata
+        """
         method = "PUT" if json is not None else None
 
         metadata_response = self.session.request(
@@ -232,6 +294,12 @@ class Publisher:
         return self.process_response(metadata_response)
 
     def snap_screenshots(self, snap_id, session, data=None, files=None):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#managing-snap-metadata
+        Endpoint: [GET, PUT]
+            https://dashboard.snapcraft.io/dev/api/snaps/{snap_id}/binary-metadata
+        """
         method = "GET"
         files_array = None
         headers = self._get_authorization_header(session)
@@ -264,6 +332,12 @@ class Publisher:
         return self.process_response(screenshot_response)
 
     def get_snap_revision(self, session, snap_id, revision_id):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/macaroon.html#request-a-macaroon
+        Endpoint: [GET]
+            https://dashboard.snapcraft.io/api/v2/snaps/{snap_id}/revisions/{revision_id}
+        """
         response = self.session.get(
             url=self.get_endpoint_url(
                 f"snaps/{snap_id}/revisions/{revision_id}", 2
@@ -274,6 +348,12 @@ class Publisher:
         return self.process_response(response)
 
     def snap_revision_history(self, session, snap_id):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#list-all-revisions-of-a-snap
+        Endpoint: [GET]
+            https://dashboard.snapcraft.io/dev/api/snaps/{snap_id}/history
+        """
         response = self.session.get(
             url=self.get_endpoint_url(f"snaps/{snap_id}/history"),
             headers=self._get_authorization_header(session),
@@ -282,6 +362,12 @@ class Publisher:
         return self.process_response(response)
 
     def snap_release_history(self, session, snap_name, page=1):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/snaps.html#snap-releases
+        Endpoint: [GET]
+            https://dashboard.snapcraft.io/api/v2/snaps/{snap_name}/releases
+        """
         response = self.session.get(
             url=self.get_endpoint_url(f"snaps/{snap_name}/releases", 2),
             params={"page": page},
@@ -291,6 +377,12 @@ class Publisher:
         return self.process_response(response)
 
     def snap_channel_map(self, session, snap_name):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/snaps.html#snap-channel-map
+        Endpoint: [GET]
+            https://dashboard.snapcraft.io/api/v2/snaps/{snap_name}/channel-map
+        """
         response = self.session.get(
             url=self.get_endpoint_url(f"snaps/{snap_name}/channel-map", 2),
             headers=self._get_authorization_header(session),
@@ -299,6 +391,11 @@ class Publisher:
         return self.process_response(response)
 
     def post_snap_release(self, session, snap_name, json):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#release-a-snap-build-to-a-channel
+        Endpoint: [POST] https://dashboard.snapcraft.io/dev/api/snap-release
+        """
         response = self.session.post(
             url=self.get_endpoint_url("snap-release/"),
             headers=self._get_authorization_header(session),
@@ -308,6 +405,12 @@ class Publisher:
         return self.process_response(response)
 
     def post_close_channel(self, session, snap_id, json):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/snap.html#close-a-channel-for-a-snap-package
+        Endpoint: [POST]
+            https://dashboard.snapcraft.io/dev/api/snaps/{snap_id}/close
+        """
         response = self.session.post(
             url=self.get_endpoint_url(f"snaps/{snap_id}/close"),
             headers=self._get_authorization_header(session),

{canonicalwebteam_store_api-4.11.0 → canonicalwebteam_store_api-4.11.2}/canonicalwebteam/store_api/store.py

@@ -66,6 +66,10 @@ class Store:
         arch="wide",
         api_version=1,
     ):
+        """
+        Documentation: https://api.snapcraft.io/docs/search.html#snap_search
+        Endpoint:  https://api.snapcraft.io/api/v1/snaps/search
+        """
         url = self.get_endpoint_url("search", api_version)
         headers = self.config[api_version].get("headers")
 
@@ -113,6 +117,10 @@ class Store:
         )
 
     def get_all_items(self, size, api_version=1):
+        """
+        Documentation: https://api.snapcraft.io/docs/search.html#snap_search
+        Endpoint:  https://api.snapcraft.io/api/v1/snaps/search
+        """
         url = self.get_endpoint_url("search", api_version)
 
         return self.process_response(
@@ -124,6 +132,10 @@ class Store:
         )
 
     def get_category_items(self, category, size=10, page=1, api_version=1):
+        """
+        Documentation: https://api.snapcraft.io/docs/search.html#snap_search
+        Endpoint:  https://api.snapcraft.io/api/v1/snaps/search
+        """
         return self.search(
             search="",
             category=category,
@@ -133,6 +145,10 @@ class Store:
         )
 
     def get_featured_items(self, size=10, page=1, api_version=1):
+        """
+        Documentation: https://api.snapcraft.io/docs/search.html#snap_search
+        Endpoint:  https://api.snapcraft.io/api/v1/snaps/search
+        """
         return self.search(
             search="",
             category="featured",
@@ -142,6 +158,10 @@ class Store:
         )
 
     def get_publisher_items(self, publisher, size=500, page=1, api_version=1):
+        """
+        Documentation: https://api.snapcraft.io/docs/search.html#snap_search
+        Endpoint:  https://api.snapcraft.io/api/v1/snaps/search
+        """
         return self.search(
             search="publisher:" + publisher,
             size=size,
@@ -150,8 +170,12 @@ class Store:
         )
 
     def get_item_details(self, name, channel=None, fields=[], api_version=2):
+        """
+        Documentation: https://api.snapcraft.io/docs/info.html
+        Endpoint: [GET]
+            https://api.snapcraft.io/api/v2/{name_space}/info/{package_name}
+        """
         url = self.get_endpoint_url("info/" + name, api_version)
-
         params = {"fields": ",".join(fields)}
 
         if channel:
@@ -166,6 +190,10 @@ class Store:
         )
 
     def get_public_metrics(self, json, api_version=1):
+        """
+        Documentation: https://api.snapcraft.io/docs/metrics.html
+        Endpoint: https://api.snapcraft.io/api/v1/snaps/metrics
+        """
         url = self.get_endpoint_url("metrics")
 
         headers = self.config[api_version].get("headers", {})
@@ -176,8 +204,11 @@ class Store:
         )
 
     def get_categories(self, api_version=2, type="shared"):
+        """
+        Documentation: https://api.snapcraft.io/docs/categories.html
+        Endpoint: https://api.snapcraft.io/api/v2/{name_space}/categories
+        """
         url = self.get_endpoint_url("categories", api_version)
-
         return self.process_response(
             self.session.get(
                 url,
@@ -187,6 +218,12 @@ class Store:
         )
 
     def get_resource_revisions(self, name, resource_name, api_version=2):
+        """
+        Documentation:
+            https://api.snapcraft.io/docs/charms.html#list_resource_revisions
+        Endpoint:
+            https://api.snapcraft.io/api/v2/charms/resources/{package_name}/{resource_name}/revisions
+        """
         url = self.get_endpoint_url(
             f"resources/{name}/{resource_name}/revisions", api_version
         )

{canonicalwebteam_store_api-4.11.0 → canonicalwebteam_store_api-4.11.2}/canonicalwebteam/store_api/stores/charmstore.py

@@ -67,11 +67,16 @@ class CharmPublisher(Publisher):
         self.session.headers.update({"Bakery-Protocol-Version": "2"})
 
     def _get_authorization_header(self, publisher_auth):
+        """
+        Return the formatted Authorization header for the publisher API.
+        """
         return {"Authorization": f"Macaroon {publisher_auth}"}
 
     def get_macaroon(self):
         """
         Return a bakery v2 macaroon from the publisher API to be discharged
+        Documentation: https://api.charmhub.io/docs/default.html#get_macaroon
+        Endpoint URL: [GET] https://api.charmhub.io/v1/tokens
         """
         response = self.session.get(url=self.get_endpoint_url("tokens"))
 
@@ -80,6 +85,8 @@ class CharmPublisher(Publisher):
     def issue_macaroon(self, permissions, description=None, ttl=None):
         """
         Return a bakery v2 macaroon from the publisher API to be discharged
+        Documentation: https://api.charmhub.io/docs/default.html#issue_macaroon
+        Endpoint URL: [POST] https://api.charmhub.io/v1/tokens
         """
         data = {"permissions": permissions}
 
@@ -99,6 +106,9 @@ class CharmPublisher(Publisher):
     def exchange_macaroons(self, issued_macaroon):
         """
         Return an exchanged snapstore-only authentication macaroon.
+        Documentation:
+            https://api.charmhub.io/docs/default.html#exchange_macaroons
+        Endpoint URL: [POST] https://api.charmhub.io/v1/tokens/exchange
         """
 
         response = self.session.post(
@@ -112,6 +122,8 @@ class CharmPublisher(Publisher):
     def macaroon_info(self, publisher_auth):
         """
         Return information about the authenticated macaroon token.
+        Documentation: https://api.charmhub.io/docs/default.html#macaroon_info
+        Endpoint URL: [GET] https://api.charmhub.io/v1/tokens/whoami
         """
         response = self.session.get(
             url=self.get_endpoint_url("tokens/whoami"),
@@ -121,6 +133,11 @@ class CharmPublisher(Publisher):
         return self.process_response(response)
 
     def whoami(self, publisher_auth):
+        """
+        Return information about the authenticated macaroon token.
+        Documentation: 'DEPRECATED'
+        Endpoint URL: [GET] https://api.charmhub.io/v1/whoami
+        """
         response = self.session.get(
             url=self.get_endpoint_url("whoami"),
             headers=self._get_authorization_header(publisher_auth),
@@ -137,6 +154,8 @@ class CharmPublisher(Publisher):
     ):
         """
         Return publisher packages
+        Documentation: https://api.charmhub.io/docs/default.html
+        Endpoint URL: [GET] https://api.charmhub.io/v1/charm
 
         Args:
             publisher_auth: Serialized macaroon to consume the API.
@@ -174,6 +193,11 @@ class CharmPublisher(Publisher):
     def get_package_metadata(self, publisher_auth, package_type, name):
         """
         Get general metadata for a package.
+        Documentation:
+            https://api.charmhub.io/docs/default.html#package_metadata
+        Endpoint URL: [GET] https://api.charmhub.io/v1/charm/<name>
+        namespace: charm for both charms and bundles
+        name: Package name
 
         Args:
             publisher_auth: Serialized macaroon to consume the API.
@@ -201,6 +225,12 @@ class CharmPublisher(Publisher):
     ):
         """
         Update general metadata for a package.
+        Documentation:
+            https://api.charmhub.io/docs/default.html#update_package_metadata
+        Endpoint URL: [PATCH]
+            https://api.charmhub.io/v1/charm/<name>
+        namespace: charm for both charms and bundles
+        name: Package name
 
         Args:
             publisher_auth: Serialized macaroon to consume the API.
@@ -229,6 +259,8 @@ class CharmPublisher(Publisher):
     def register_package_name(self, publisher_auth, data):
         """
         Register a package name.
+        Documentation: https://api.charmhub.io/docs/default.html#register_name
+        Endpoint URL: [POST] https://api.charmhub.io/v1/charm
 
         Args:
             publisher_auth: Serialized macaroon to consume the API.
@@ -249,6 +281,9 @@ class CharmPublisher(Publisher):
     def unregister_package_name(self, publisher_auth, name):
         """
         Unregister a package name.
+        Documentation:
+            https://api.charmhub.io/docs/default.html#unregister_package
+        Endpoint URL: [DELETE] https://api.charmhub.io/v1/charm/<name>
 
         Args:
             publisher_auth: Serialized macaroon to consume the API.
@@ -265,6 +300,12 @@ class CharmPublisher(Publisher):
         return response
 
     def get_charm_libraries(self, charm_name):
+        """
+        Get libraries for a charm.
+        Documentation:
+            https://api.charmhub.io/docs/libraries.html#fetch_libraries
+        Endpoint URL: [POST] https://api.charmhub.io/v1/charm/libraries/bulk
+        """
         response = self.session.post(
             url=self.get_endpoint_url("charm/libraries/bulk"),
             json=[{"charm-name": charm_name}],
@@ -273,6 +314,18 @@ class CharmPublisher(Publisher):
         return self.process_response(response)
 
     def get_charm_library(self, charm_name, library_id, api_version=None):
+        """
+        Get library metadata and content
+        Documentation:
+            https://api.charmhub.io/docs/libraries.html#fetch_library
+        Endpoint URL: [GET]
+        https://api.charmhub.io/v1/charm/libraries/<charm_name>/<library_id>
+
+        Args:
+            charm_name: Name of the charm
+            library_id: ID of the library
+            api_version: API version to use
+        """
         params = {}
 
         if api_version is not None:
@@ -290,6 +343,14 @@ class CharmPublisher(Publisher):
     def get_collaborators(self, publisher_auth, name):
         """
         Get collaborators (accepted invites) for the given package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#get_collaborators
+        Endpoint URL: [GET]
+            https://api.charmhub.io/v1/charm/<name>/collaborators
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package
         """
         response = self.session.get(
             url=self.get_endpoint_url(f"charm/{name}/collaborators"),
@@ -300,6 +361,14 @@ class CharmPublisher(Publisher):
     def get_pending_invites(self, publisher_auth, name):
         """
         Get pending collaborator invites for the given package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#get_pending_invites
+        Endpoint URL: [GET]
+            https://api.charmhub.io/v1/charm/<name>/collaborators/invites
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package
         """
         response = self.session.get(
             url=self.get_endpoint_url(f"charm/{name}/collaborators/invites"),
@@ -310,6 +379,15 @@ class CharmPublisher(Publisher):
     def invite_collaborators(self, publisher_auth, name, emails):
         """
         Invite one or more collaborators for a package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#invite_collaborators
+        Endpoint URL: [POST]
+            https://api.charmhub.io/v1/charm/<name>/collaborators/invites
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package
+            emails: List of emails to invite
         """
         payload = {"invites": []}
 
@@ -326,6 +404,15 @@ class CharmPublisher(Publisher):
     def revoke_invites(self, publisher_auth, name, emails):
         """
         Revoke invites to the specified emails for the package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#revoke_invites
+        Endpoint URL: [POST]
+            https://api.charmhub.io/v1/charm/<name>/collaborators/invites/revoke
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package
+            emails: List of emails to revoke
         """
         payload = {"invites": []}
 
@@ -344,6 +431,15 @@ class CharmPublisher(Publisher):
     def accept_invite(self, publisher_auth, name, token):
         """
         Accept a collaborator invite.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#accept_invite
+        Endpoint URL: [POST]
+            https://api.charmhub.io/v1/charm/<name>/collaborators/invites/accept
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package
+            token: Invite token
         """
         response = self.session.post(
             url=self.get_endpoint_url(
@@ -357,6 +453,15 @@ class CharmPublisher(Publisher):
     def reject_invite(self, publisher_auth, name, token):
         """
         Reject a collaborator invite.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#reject_invite
+        Endpoint URL: [POST]
+            https://api.charmhub.io/v1/charm/<name>/collaborators/invites/reject
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package
+            token: Invite token
         """
         response = self.session.post(
             url=self.get_endpoint_url(
@@ -370,6 +475,14 @@ class CharmPublisher(Publisher):
     def create_track(self, publisher_auth, charm_name, track_name):
         """
         Create a track for a charm base on the charm's guardrail pattern.
+        Documentation: https://api.charmhub.io/docs/default.html#create_tracks
+        Endpoint URL: [POST]
+            https://api.charmhub.io/v1/charm/<charm_name>/tracks
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            charm_name: Name of the charm
+            track_name: Name of the track
         """
         response = self.session.post(
             url=self.get_endpoint_url(f"charm/{charm_name}/tracks"),

{canonicalwebteam_store_api-4.11.0 → canonicalwebteam_store_api-4.11.2}/canonicalwebteam/store_api/stores/snapstore.py

@@ -69,6 +69,10 @@ class SnapStore(Store):
         featured="false",
         fields=[],
     ):
+        """
+        Documentation: https://api.snapcraft.io/docs/search.html#snaps_find
+        Endpoint: [GET] https://api.snapcraft.io/v2/snaps/find
+        """
         url = self.get_endpoint_url("find", 2)
         headers = self.config[2].get("headers")
         params = {
@@ -96,6 +100,9 @@ class SnapPublisher(Publisher):
     def get_macaroon(self, permissions):
         """
         Return a bakery v2 macaroon from the publisher API to be discharged
+        Documemntation:
+            https://dashboard.snapcraft.io/docs/reference/v1/macaroon.html
+        Endpoint: [POST] https://dashboard.snapcraft.iodev/api/acl
         """
         response = self.session.post(
             url=self.get_endpoint_url("tokens", 2),
@@ -105,6 +112,12 @@ class SnapPublisher(Publisher):
         return self.process_response(response)["macaroon"]
 
     def whoami(self, session):
+        """
+        Get the authenticated user details.
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/tokens.html#api-tokens-whoami
+        Endpoint: [GET] https://dashboard.snapcraft.io/api/v2/tokens/whoami
+        """
         response = self.session.get(
             url=self.get_endpoint_url("tokens/whoami", 2),
             headers=self._get_authorization_header(session),
@@ -121,6 +134,9 @@ class SnapPublisher(Publisher):
     def exchange_dashboard_macaroons(self, session):
         """
         Exchange dashboard.snapcraft.io SSO discharged macaroons
+        Documentation:
+            https://api.charmhub.io/docs/default.html#exchange_dashboard_macaroons
+        Endpoint: [POST] https://api.charmhub.io/v1/tokens/dashboard/exchange
         """
         response = self.session.post(
             url=self.get_publisherwg_endpoint_url("tokens/dashboard/exchange"),
@@ -133,6 +149,10 @@ class SnapPublisher(Publisher):
     def get_collaborators(self, session, name):
         """
         Get collaborators (accepted invites) for the given package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#get_collaborators
+        Endpoint: [GET]
+            https://api.charmhub.io/v1/snap/{snap_name}/collaborators
         """
         response = self.session.get(
             url=self.get_publisherwg_endpoint_url(
@@ -145,6 +165,10 @@ class SnapPublisher(Publisher):
     def get_pending_invites(self, session, name):
         """
         Get pending collaborator invites for the given package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#get_pending_invites
+        Endpoint: [GET]
+            https://api.charmhub.io/v1/snap/{snap_name}/collaborators/invites
         """
         response = self.session.get(
             url=self.get_publisherwg_endpoint_url(
@@ -157,6 +181,10 @@ class SnapPublisher(Publisher):
     def invite_collaborators(self, session, name, emails):
         """
         Invite one or more collaborators for a package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#invite_collaborators
+        Endpoint: [POST]
+            https://api.charmhub.io/v1/snap/{snap_name}/collaborators/invites
         """
         payload = {"invites": []}
 
@@ -175,6 +203,10 @@ class SnapPublisher(Publisher):
     def revoke_invites(self, session, name, emails):
         """
         Revoke invites to the specified emails for the package.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#revoke_invites
+        Endpoint: [POST]
+            https://api.charmhub.io/v1/snap/{snap_name}/collaborators/invites/revoke
         """
         payload = {"invites": []}
 
@@ -193,6 +225,10 @@ class SnapPublisher(Publisher):
     def accept_invite(self, session, name, token):
         """
         Accept a collaborator invite.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#accept_invite
+        Endpoint: [POST]
+            https://api.charmhub.io/v1/snap/{snap_name}/collaborators/invites/accept
         """
         response = self.session.post(
             url=self.get_publisherwg_endpoint_url(
@@ -206,6 +242,10 @@ class SnapPublisher(Publisher):
     def reject_invite(self, session, name, token):
         """
         Reject a collaborator invite.
+        Documentation:
+            https://api.charmhub.io/docs/collaborator.html#reject_invite
+        Endpoint: [POST]
+            https://api.charmhub.io/v1/snap/{snap_name}/collaborators/invites/reject
         """
         response = self.session.post(
             url=self.get_publisherwg_endpoint_url(
@@ -219,6 +259,8 @@ class SnapPublisher(Publisher):
     def create_track(self, session, snap_name, track_name):
         """
         Create a track for a snap base on the snap's guardrail pattern.
+        Documentation: https://api.charmhub.io/docs/default.html#create_tracks
+        Endpoint: [POST]  https://api.charmhub.io/v1/snap/{snap_name}/tracks
         """
         response = self.session.post(
             url=self.get_publisherwg_endpoint_url(f"snap/{snap_name}/tracks"),
@@ -227,6 +269,26 @@ class SnapPublisher(Publisher):
         )
         return response
 
+    def unregister_package_name(self, publisher_auth, snap_name):
+        """
+        Unregister a package name.
+        Documentation: https://api.charmhub.io/docs/default.html#register_name
+        Endpoint: [DELETE] https://api.charmhub.io/v1/snap/{snap_name}
+
+        Args:
+            publisher_auth: Serialized macaroon to consume the API.
+            name: Name of the package to unregister
+        Returns:
+            The package name ID if successful
+            Otherwise, returns an error list
+        """
+        url = self.get_publisherwg_endpoint_url(f"snap/{snap_name}")
+        response = self.session.delete(
+            url=url,
+            headers=self._get_authorization_header(publisher_auth),
+        )
+        return response
+
 
 class SnapStoreAdmin(SnapPublisher):
     def get_endpoint_url(self, endpoint, api_version=2):
@@ -234,6 +296,9 @@ class SnapStoreAdmin(SnapPublisher):
 
     def get_stores(self, session, roles=["admin", "review", "view", "access"]):
         """Return a list a stores with the given roles
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v1/account.html#get--dev-api-account
+        Endpoint: [GET] https://dashboard.snapcraft.io/dev/api/account
 
         :return: A list of stores
         """
@@ -255,6 +320,10 @@ class SnapStoreAdmin(SnapPublisher):
 
     def get_store(self, session, store_id):
         """Return a store where the user is an admin
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#list-the-details-of-a-brand-store
+        Endpoint:  [GET]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}
 
         :return: Store details
         """
@@ -269,6 +338,12 @@ class SnapStoreAdmin(SnapPublisher):
     def get_store_snaps(
         self, session, store_id, query=None, allowed_for_inclusion=None
     ):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#get
+        Endpoint: [GET]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}/snaps
+        """
         headers = self._get_authorization_header(session)
         params = {}
 
@@ -287,6 +362,11 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response).get("snaps", [])
 
     def get_store_members(self, session, store_id):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#list-the-details-of-a-brand-store
+        Endpoint: [GET] https://dashboard.snapcraft.io/api/v2/stores/{store_id}
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.get(
@@ -297,6 +377,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response).get("users", [])
 
     def update_store_members(self, session, store_id, members):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#add-remove-or-edit-users-roles
+        Endpoint: [POST]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}/users
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.post(
@@ -308,6 +394,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def invite_store_members(self, session, store_id, members):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#manage-store-invitations
+        Endpoint: [POST]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}/invites
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.post(
@@ -319,6 +411,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def change_store_settings(self, session, store_id, settings):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#change-store-settings
+        Endpoint: [PUT]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}/settings
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.put(
@@ -330,6 +428,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def update_store_snaps(self, session, store_id, snaps):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#post
+        Endpoint: [POST]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}/snaps
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.post(
@@ -341,6 +445,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def update_store_invites(self, session, store_id, invites):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#manage-store-invitations
+        Endpoint: [PUT]
+            https://dashboard.snapcraft.io/api/v2/stores/{store_id}/invites
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.put(
@@ -352,6 +462,11 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def get_store_invites(self, session, store_id):
+        """
+        Documentation:
+            https://dashboard.snapcraft.io/docs/reference/v2/en/stores.html#list-the-details-of-a-brand-store
+        Endpoint: [GET] https://dashboard.snapcraft.io/api/v2/stores/{store_id}
+        """
         headers = self._get_authorization_header(session)
 
         response = self.session.get(
@@ -363,6 +478,11 @@ class SnapStoreAdmin(SnapPublisher):
 
     # MODEL SERVICE ADMIN
     def get_store_models(self, session, store_id):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#read_models
+        Endpoint: [GET] https://api.charmhub.io/v1/brand/{store_id}/model
+        """
         response = self.session.get(
             url=self.get_publisherwg_endpoint_url(f"brand/{store_id}/model"),
             headers=self._get_publisherwg_authorization_header(session),
@@ -371,6 +491,11 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def create_store_model(self, session, store_id, name, api_key=None):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#create_model
+        Endpoint: [POST] https://api.charmhub.io/v1/brand/{store_id}/model
+        """
         if api_key:
             payload = {"name": name, "api-key": api_key, "series": "16"}
         else:
@@ -384,6 +509,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def update_store_model(self, session, store_id, model_name, api_key):
+        """
+        Doucumentation:
+            https://api.charmhub.io/docs/model-service-admin.html#update_model
+        Endpoint: [PATCH]
+            https://api.charmhub.io/v1/brand/{store_id}/model/{model_name}
+        """
         response = self.session.patch(
             url=self.get_publisherwg_endpoint_url(
                 f"brand/{store_id}/model/{model_name}"
@@ -395,6 +526,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def get_store_model_policies(self, session, store_id, model_name):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#read_serial_policies
+        Endpoint: [GET]
+            https://api.charmhub.io/v1/brand/{store_id}/model/<model_name>/serial_policy
+        """
         response = self.session.get(
             url=self.get_publisherwg_endpoint_url(
                 f"brand/{store_id}/model/{model_name}/serial_policy"
@@ -407,6 +544,12 @@ class SnapStoreAdmin(SnapPublisher):
     def create_store_model_policy(
         self, session, store_id, model_name, signing_key
     ):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#create_serial_policy
+        Endpoint: [POST]
+            https://api.charmhub.io/v1/brand/{store_id}/model/{model_name}/serial_policy
+        """
         response = self.session.post(
             url=self.get_publisherwg_endpoint_url(
                 f"brand/{store_id}/model/{model_name}/serial_policy"
@@ -420,6 +563,12 @@ class SnapStoreAdmin(SnapPublisher):
     def delete_store_model_policy(
         self, session, store_id, model_name, revision
     ):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#delete_serial_policy
+        Endpoint: [DELETE]
+            https://api.charmhub.io/v1/brand/{store_id}/model/{model_name}/serial_policy/{serial_policy_revision}
+        """
         response = self.session.delete(
             url=self.get_publisherwg_endpoint_url(
                 f"brand/{store_id}/model/{model_name}/serial_policy/{revision}"
@@ -430,6 +579,11 @@ class SnapStoreAdmin(SnapPublisher):
         return response
 
     def get_store_signing_keys(self, session, store_id):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#read_signing_keys
+        Endpoint: [GET] https://api.charmhub.io/v1/brand/{store_id}/signing_key
+        """
         headers = self._get_publisherwg_authorization_header(session)
         url = self.get_publisherwg_endpoint_url(
             f"brand/{store_id}/signing_key"
@@ -441,6 +595,12 @@ class SnapStoreAdmin(SnapPublisher):
         return self.process_response(response)
 
     def create_store_signing_key(self, session, store_id, name):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#create_signing_key
+        Endpoint: [POST]
+            https://api.charmhub.io/v1/brand/{store_id}/signing_key
+        """
         headers = self._get_publisherwg_authorization_header(session)
         url = self.get_publisherwg_endpoint_url(
             f"brand/{store_id}/signing_key"
@@ -455,6 +615,12 @@ class SnapStoreAdmin(SnapPublisher):
     def delete_store_signing_key(
         self, session, store_id, signing_key_sha3_384
     ):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#delete_signing_key
+        Endpoint: [DELETE]
+            https://api.charmhub.io/v1/brand/{store_id}/signing_key/<signing_key_sha3_384}
+        """
         headers = self._get_publisherwg_authorization_header(session)
         url = self.get_publisherwg_endpoint_url(
             f"brand/{store_id}/signing_key/{signing_key_sha3_384}"
@@ -467,6 +633,11 @@ class SnapStoreAdmin(SnapPublisher):
         return response
 
     def get_brand(self, session, store_id):
+        """
+        Documentation:
+            https://api.charmhub.io/docs/model-service-admin.html#read_brand
+        Endpoint: [GET] https://api.charmhub.io/v1/brand/{store_id}
+        """
         headers = self._get_publisherwg_authorization_header(session)
         url = self.get_publisherwg_endpoint_url(f"brand/{store_id}")
         response = self.session.get(
@@ -478,6 +649,11 @@ class SnapStoreAdmin(SnapPublisher):
 
     # FEATURED SNAPS AUTOMATION
     def delete_featured_snaps(self, session, snaps):
+        """
+        Documentation: (link to spec)
+            https://docs.google.com/document/d/1UAybxuZyErh3ayqb4nzL3T4BbvMtnmKKEPu-ixcCj_8
+        Endpoint: [DELETE] https://api.charmhub.io/v1/snap/featured
+        """
         headers = self._get_publisherwg_authorization_header(session)
         url = self.get_publisherwg_endpoint_url("snap/featured")
         response = self.session.delete(
@@ -488,6 +664,11 @@ class SnapStoreAdmin(SnapPublisher):
         return response
 
     def update_featured_snaps(self, session, snaps):
+        """
+        Documentation: (link to spec)
+            https://docs.google.com/document/d/1UAybxuZyErh3ayqb4nzL3T4BbvMtnmKKEPu-ixcCj_8
+        Endpoint: [PUT] https://api.charmhub.io/v1/snap/featured
+        """
         headers = self._get_publisherwg_authorization_header(session)
         url = self.get_publisherwg_endpoint_url("snap/featured")
         response = self.session.put(
@@ -497,15 +678,20 @@ class SnapStoreAdmin(SnapPublisher):
         )
         return response
 
-    def get_featured_snaps(self, session, api_version=1):
-        url = "https://api.staging.snapcraft.io/api/v1/snaps/search"
+    def get_featured_snaps(self, session, api_version=1, fields="snap_id"):
+        """
+        Documentation: (link to spec)
+            https://docs.google.com/document/d/1UAybxuZyErh3ayqb4nzL3T4BbvMtnmKKEPu-ixcCj_8/edit
+        Endpoint: https://api.snapcraft.io/api/v1/snaps/search
+        """
+        url = f"{SNAPSTORE_API_URL}api/v1/snaps/search"
         headers = self.config[api_version].get("headers")
 
         params = {
             "scope": "wide",
             "arch": "wide",
             "confinement": "strict,classic,devmode",
-            "fields": "snap_id",
+            "fields": fields,
             "section": "featured",
         }
 

{canonicalwebteam_store_api-4.11.0 → canonicalwebteam_store_api-4.11.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = 'canonicalwebteam.store-api'
-version = '4.11.0'
+version = '4.11.2'
 description = ''
 authors = ['Canonical Web Team <webteam@canonical.com>']
 license = 'LGPL-3.0'