zabel-elements 1.47.2__tar.gz → 1.50.0__tar.gz

{zabel_elements-1.47.2/zabel_elements.egg-info → zabel_elements-1.50.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: zabel-elements
-Version: 1.47.2
-Summary: TThe Zabel default clients and images
+Version: 1.50.0
+Summary: The Zabel default clients and images
 Author-email: Martin Lafaix <martin.lafaix@external.engie.com>
 License-Expression: EPL-2.0
 Project-URL: Homepage, https://github.com/engie-group/zabel-elements

{zabel_elements-1.47.2 → zabel_elements-1.50.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zabel-elements"
-version = "1.47.2"
-description = "TThe Zabel default clients and images"
+version = "1.50.0"
+description = "The Zabel default clients and images"
 readme = "README.md"
 license = "EPL-2.0"
 authors = [

{zabel_elements-1.47.2 → zabel_elements-1.50.0}/zabel/elements/clients/base/atlassian.py

@@ -11,7 +11,7 @@ pagination if appropriate, but does not process the results or compose
 API requests.
 """
 
-from typing import Any, Iterable, Mapping
+from typing import Any, Iterable, Mapping, Optional
 
 import random
 import time
@@ -87,11 +87,12 @@ class Atlassian:
     ```python
     from zabel.elements.clients import Atlassian
 
-    url = 'https://api.atlassian.com/admin/v1/'
+    url = 'https://api.atlassian.com'
     token = '...'
     atlassian = Atlassian(url, bearer_auth=token)
     atlassian.list_organization_users('your-organization-id')
     ```
+
     """
 
     def __init__(
@@ -121,21 +122,28 @@ class Atlassian:
 
         `url` is the top-level API endpoint.  For example:
 
-            'https://api.atlassian.com/admin/v1/'
+            'https://api.atlassian.com'
         """
         ensure_nonemptystring('url')
         ensure_noneornonemptystring('bearer_auth')
         ensure_noneorinstance('basic_auth', tuple)
-        if not url.endswith('/v1/'):
-            raise ValueError(f'url must end with /v1/: {url}')
 
         if basic_auth is None and bearer_auth is None:
             raise ValueError(
                 'Provide at least one of bearer_auth or basic_auth'
             )
 
-        self.url = url
-        self.base_url = url.removesuffix('/v1/')
+        # Normalize url: strip legacy /admin/v1 or /admin suffix so
+        # both old inputs (e.g. 'https://api.atlassian.com/admin/v1/')
+        # and new inputs (e.g. 'https://api.atlassian.com') work.
+        normalized = url.rstrip('/')
+        for suffix in ('/admin/v1', '/admin'):
+            if normalized.endswith(suffix):
+                normalized = normalized[: -len(suffix)]
+                break
+        self.url = normalized
+        self.admin_url = join_url(self.url, 'admin')
+        self.v1_url = join_url(self.url, 'admin/v1')
         self.basic_auth = basic_auth
         self.bearer_auth = bearer_auth
 
@@ -183,21 +191,21 @@ class Atlassian:
         A list of _users_.  Each user is a dictionary with the
         following entries:
 
-        - `account_id`: a string
-        - `account_type`: a string
-        - `account_status`: a string
-        - `name`: a string
-        - `picture`: a string
-        - `email`: a string
-        - `access_billable`: a boolean
-        - `last_active`: a string
-        - `product_access`: a list of dictionaries
-        - `links`: a dictionary (with `self`)
+        - account_id: a string
+        - account_type: a string
+        - account_status: a string
+        - name: a string
+        - picture: a string
+        - email: a string
+        - access_billable: a boolean
+        - last_active: a string
+        - product_access: a list of dictionaries
+        - links: a dictionary (with self)
         """
         ensure_nonemptystring('org_id')
 
         session = self._get_session()
-        api_url = join_url(self.url, f'orgs/{org_id}/users')
+        api_url = join_url(self.v1_url, f'orgs/{org_id}/users')
 
         collected: list[dict[str, Any]] = []
         while True:
@@ -235,7 +243,7 @@ class Atlassian:
         # Returned value
 
         A list of _directories_.  Each directory is a dictionary with
-        entries such as `id`, `name`, `type`, `managementAccess`.
+        entries such as id, name, type, managementAccess.
         """
         ensure_nonemptystring('org_id')
 
@@ -255,8 +263,8 @@ class Atlassian:
         # Returned value
 
         A list of _groups_.  Each group is a dictionary with entries
-        such as `id`, `name`, `description`, `directoryId`,
-        `managementAccess`, `externalSynced`.
+        such as id, name, description, directoryId,
+        managementAccess, externalSynced.
         """
         ensure_nonemptystring('org_id')
         ensure_nonemptystring('directory_id')
@@ -287,11 +295,11 @@ class Atlassian:
         A list of _role assignments_.  Each role assignment is a
         dictionary with:
 
-        - `resourceId`: a string (e.g., `ari:cloud:confluence::site/<id>`)
-        - `resourceOwner`: a string (`jira`, `confluence`, `cmdb`, ...)
-        - `roles`: a list of strings (`atlassian/user`, `atlassian/admin`,
-          `atlassian/guest`)
-        - `defaultRole`: a string
+        - resourceId: a string (e.g., ari:cloud:confluence::site/<id>)
+        - resourceOwner: a string (jira, confluence, cmdb, ...)
+        - roles: a list of strings (atlassian/user, atlassian/admin,
+          atlassian/guest)
+        - defaultRole: a string
         """
         ensure_nonemptystring('org_id')
         ensure_nonemptystring('directory_id')
@@ -311,11 +319,11 @@ class Atlassian:
     ) -> list[dict[str, Any]]:
         """List users in a directory of an organization.
 
-        Returns full user info including the org-level `status` field
-        (`active` / `suspended` / `deactivated` / `not_invited` /
-        `for_deletion`), which is the source of truth for billing.
-        Note the difference with `accountStatus` returned by site-level
-        APIs: the latter can report `active` for users actually
+        Returns full user info including the org-level status field
+        (active / suspended / deactivated / not_invited /
+        for_deletion), which is the source of truth for billing.
+        Note the difference with accountStatus returned by site-level
+        APIs: the latter can report active for users actually
         suspended at the org level.
 
         # Required parameters
@@ -333,14 +341,14 @@ class Atlassian:
         A list of _users_.  Each user is a dictionary with entries
         such as:
 
-        - `accountId`: a string
-        - `accountType`: a string (`atlassian`, `app`, `customer`)
-        - `status`: a string (`active`, `suspended`, `deactivated`)
-        - `accountStatus`: a string (often `active` even when status is
-          suspended -- prefer `status` for billing decisions)
-        - `membershipStatus`: a string (per-directory membership)
-        - `name`, `nickname`, `email`, `claimStatus`, `addedToOrg`,
-          `deactivatedOn`, ...
+        - accountId: a string
+        - accountType: a string (atlassian, app, customer)
+        - status: a string (active, suspended, deactivated)
+        - accountStatus: a string (often active even when status is
+          suspended -- prefer status for billing decisions)
+        - membershipStatus: a string (per-directory membership)
+        - name, nickname, email, claimStatus, addedToOrg,
+          deactivatedOn, ...
 
         # Usage
 
@@ -354,7 +362,8 @@ class Atlassian:
         users = atlassian.list_directory_users(org_id, directory_id, params)
         ```
 
-        For billing, combining `roleIds` + `resourceIds` returns the
+
+        For billing, combining roleIds + resourceIds returns the
         exact billable user set for a given (site, product) couple --
         matching admin UI counts.
         """
@@ -375,20 +384,20 @@ class Atlassian:
 
         # Required parameters
 
-        - site_url: a non-empty string (of the form `https://...`)
+        - site_url: a non-empty string (of the form https://...)
 
         # Returned value
 
         A list of _users_.  Each user is a dictionary with the
         following entries:
 
-        - `accountId`: a string
-        - `accountType`: a string
-        - `emailAddress`: a string
-        - `avatarUrls`: a dictionary
-        - `displayName`: a string
-        - `active`: a boolean
-        - `locale`: a string
+        - accountId: a string
+        - accountType: a string
+        - emailAddress: a string
+        - avatarUrls: a dictionary
+        - displayName: a string
+        - active: a boolean
+        - locale: a string
         """
         ensure_nonemptystring('site_url')
 
@@ -452,8 +461,8 @@ class Atlassian:
         """List Jira application roles on a site.
 
         Each role describes one Jira product available on the site
-        (e.g. `jira-software`, `jira-servicedesk`, `jira-core`,
-        `jira-product-discovery`) and exposes the groups whose members
+        (e.g. jira-software, jira-servicedesk, jira-core,
+        jira-product-discovery) and exposes the groups whose members
         are granted access to that product.
 
         # Required parameters
@@ -465,14 +474,14 @@ class Atlassian:
         A list of _roles_.  Each role is a dictionary with entries
         such as:
 
-        - `key`: a string (the product key)
-        - `name`: a string
-        - `groups`: a list of strings (group names)
-        - `groupDetails`: a list of dictionaries (with `name`, `groupId`)
-        - `defaultGroups`: a list of strings
-        - `numberOfSeats`: an integer
-        - `userCount`: an integer
-        - `hasUnlimitedSeats`: a boolean
+        - key: a string (the product key)
+        - name: a string
+        - groups: a list of strings (group names)
+        - groupDetails: a list of dictionaries (with name, groupId)
+        - defaultGroups: a list of strings
+        - numberOfSeats: an integer
+        - userCount: an integer
+        - hasUnlimitedSeats: a boolean
         """
         ensure_nonemptystring('site_url')
 
@@ -492,7 +501,7 @@ class Atlassian:
         """List members of a group on a Jira site.
 
         Works for any group on the site, including the groups that
-        gate Confluence access (e.g. `confluence-users`).
+        gate Confluence access (e.g. confluence-users).
 
         # Required parameters
 
@@ -507,11 +516,11 @@ class Atlassian:
 
         A list of _users_.  Each user is a dictionary with entries:
 
-        - `accountId`: a string
-        - `accountType`: a string
-        - `displayName`: a string
-        - `active`: a boolean
-        - `emailAddress`: a string (omitted when the caller does not
+        - accountId: a string
+        - accountType: a string
+        - displayName: a string
+        - active: a boolean
+        - emailAddress: a string (omitted when the caller does not
           have the relevant privacy permission)
         """
         ensure_nonemptystring('site_url')
@@ -538,9 +547,181 @@ class Atlassian:
 
         return collected
 
+    ####################################################################
+    # Jira Rules
+    #
+    # list_rules
+    # get_rule
+    # enable_rule
+    # disable_rule
+
+    @api_call
+    @require_basic_auth
+    def list_rules(
+        self,
+        product: str,
+        site_id: str,
+    ) -> list[dict[str, Any]]:
+        """List rules for a Jira product on a site.
+        # Required parameters
+
+        - product: a non-empty string (e.g. jira, confluence)
+        - site_id: a non-empty string (the site ID, not the URL)
+
+        # Returned value
+        A list of _rules_.  Each rule is a dictionary with entries such as:
+        - uuid: a string
+        - name: a string
+        - state: a string (ENABLED, DISABLED)
+        - description: a string
+        - authorAccountId: a string
+        - actorAccountId: a string
+        - created: a float (Unix timestamp)
+        - updated: a float (Unix timestamp)
+        - labels: a list of strings
+        - ruleScopeARIs: a list of strings
+        """
+        ensure_nonemptystring('product')
+        ensure_nonemptystring('site_id')
+
+        session = self._get_session()
+        next_cursor = ''
+        api = join_url(
+            self.url,
+            f'automation/public/{product}/{site_id}/rest/v1/rule/summary',
+        )
+        collected: list[dict[str, Any]] = []
+        while True:
+            url = api if not next_cursor else join_url(api, next_cursor)
+            response = session.get(url)
+            data = response.json()
+            values = data.get('data', [])
+            collected.extend(values)
+            links = data.get('links', {})
+            next_link = links.get('next')
+            if not values or not next_link:
+                break
+            next_cursor = next_link
+        return collected
+
+    @api_call
+    @require_basic_auth
+    def get_rule(
+        self,
+        product: str,
+        site_id: str,
+        rule_id: str,
+    ) -> dict[str, Any]:
+        """Get a rule for a Jira product on a site.
+        # Required parameters
+
+        - product: a non-empty string (e.g. jira, confluence)
+        - site_id: a non-empty string (the site ID, not the URL)
+        - rule_id: a non-empty string
+
+        # Returned value
+
+        A dictionary with two top-level keys:
+
+        - rule: a dictionary with entries such as:
+          - uuid: a string
+          - name: a string
+          - state: a string (ENABLED or DISABLED)
+          - description: a string or None
+          - canOtherRuleTrigger: a boolean
+          - notifyOnError: a string (e.g. FIRSTERROR)
+          - authorAccountId: a string
+          - actor: a dictionary with keys type and actor (account ID)
+          - trigger: a dictionary describing the trigger component
+          - components: a list of dictionaries (conditions and actions)
+          - ruleScopeARIs: a list of strings (project ARIs)
+          - labels: a list of strings
+          - writeAccessType: a string (e.g. UNRESTRICTED)
+          - collaborators: a list
+          - created: a float (Unix timestamp)
+          - updated: a float (Unix timestamp)
+
+        - connections: a list of _connections_. Each connection is a
+         dictionary with entries such as:
+          - id: a string
+          - accountId: a string
+          - connectionTargetKey: a string
+          - targetConfigJson: a string
+          - authType: a string
+          - createdAt: a float (Unix timestamp)
+          - updatedAt: a float (Unix timestamp)
+          - container: a dictionary
+        """
+        ensure_nonemptystring('product')
+        ensure_nonemptystring('site_id')
+        ensure_nonemptystring('rule_id')
+
+        session = self._get_session()
+        api = join_url(
+            self.url,
+            f'automation/public/{product}/{site_id}/rest/v1/rule/{rule_id}',
+        )
+        response = session.get(api)
+        return response.json()
+
+    @api_call
+    @require_basic_auth
+    def enable_rule(
+        self,
+        product: str,
+        site_id: str,
+        rule_id: str,
+    ):
+        """Enable a rule for a Jira product on a site.
+        # Required parameters
+
+        - product: a non-empty string (e.g. jira, confluence)
+        - site_id: a non-empty string (the site ID, not the URL)
+        - rule_id: a non-empty string
+        """
+        ensure_nonemptystring('product')
+        ensure_nonemptystring('site_id')
+        ensure_nonemptystring('rule_id')
+
+        self._set_rule_state(product, site_id, rule_id, 'ENABLED')
+
+    @api_call
+    @require_basic_auth
+    def disable_rule(
+        self,
+        product: str,
+        site_id: str,
+        rule_id: str,
+    ):
+        """Disable a rule for a Jira product on a site.
+
+        # Required parameters
+
+        - product: a non-empty string (e.g. jira, confluence)
+        - site_id: a non-empty string (the site ID, not the URL)
+        - rule_id: a non-empty string
+        """
+        ensure_nonemptystring('product')
+        ensure_nonemptystring('site_id')
+        ensure_nonemptystring('rule_id')
+
+        self._set_rule_state(product, site_id, rule_id, 'DISABLED')
+
     ####################################################################
     # atlassian private helpers
 
+    def _set_rule_state(
+        self,
+        product: str,
+        site_id: str,
+        rule_id: str,
+        state: str,
+    ) -> None:
+        self._put(
+            f'automation/public/{product}/{site_id}/rest/v1/rule/{rule_id}/state',
+            json={'value': state},
+        )
+
     def _get(
         self,
         api: str,
@@ -551,6 +732,16 @@ class Atlassian:
         api_url = join_url(self.url, api)
         return session.get(api_url, params=params)
 
+    def _put(
+        self, api: str, json: Optional[Mapping[str, Any]] = None
+    ) -> requests.Response:
+        session = self._get_session()
+        api_url = join_url(self.url, api)
+        return session.put(
+            api_url,
+            json=json,
+        )
+
     def _collect_v2(
         self,
         api: str,
@@ -558,13 +749,13 @@ class Atlassian:
     ) -> list[dict[str, Any]]:
         """Return admin/v2 GET api call results, collected.
 
-        First page sends `params` (server-side filters); subsequent
+        First page sends params (server-side filters); subsequent
         pages send the cursor alone -- it encodes the filters, and
         mixing them again causes inconsistent results on some
-        endpoints (e.g. directory `users/`).  Retries on HTTP 429.
+        endpoints (e.g. directory users/).  Retries on HTTP 429.
         """
         session = self._get_session()
-        api_url = join_url(join_url(self.base_url, '/v2'), api)
+        api_url = join_url(join_url(self.admin_url, '/v2'), api)
 
         _params: dict[str, Any] = {
             'limit': _V2_PAGE_SIZE,

{zabel_elements-1.47.2 → zabel_elements-1.50.0}/zabel/elements/clients/base/confluence.py

@@ -249,6 +249,77 @@ class Confluence:
 
         return self._collect_data('content/search', params=params)
 
+    @api_call
+    def audit(
+        self,
+        group: str,
+        actions: Optional[str] = None,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        limit: int = 100,
+        scan_limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """Return all audit log events matching a group filter.
+
+        # Required parameters
+
+        - group: a non-empty string
+
+        # Optional parameters
+
+        - actions: a string or None (None by default)
+        - from_date: a string or None (None by default)
+        - to_date: a string or None (None by default)
+        - limit: an integer (`100` by default)
+        - scan_limit: an integer or None (None by default)
+
+        # Returned value
+
+        A possibly empty list of audit log event dictionaries.
+
+        Handles pagination (i.e., it returns all matching events, not
+        only the first n events).
+
+        # Raised exceptions
+
+        If the request fails, an _ApiError_ is raised.
+        """
+        ensure_nonemptystring('group')
+        ensure_noneorinstance('actions', str)
+        ensure_noneorinstance('from_date', str)
+        ensure_noneorinstance('to_date', str)
+        ensure_instance('limit', int)
+        ensure_noneorinstance('scan_limit', int)
+
+        params: Dict[str, Any] = {
+            'search': group,
+            'limit': limit,
+        }
+        add_if_specified(params, 'actions', actions)
+        add_if_specified(params, 'scanLimit', scan_limit)
+        add_if_specified(params, 'from', from_date)
+        add_if_specified(params, 'to', to_date)
+
+        all_events: List[Dict[str, Any]] = []
+        while True:
+            response = self.session().get(
+                join_url(self.url, '/rest/auditing/1.0/events'),
+                params=params,
+            )
+            if response.status_code // 100 != 2:
+                raise ApiError(response.text)
+            data = response.json()
+            entities = data.get('entities', [])
+            all_events.extend(entities)
+            paging = data.get('pagingInfo', {})
+            if paging.get('lastPage', True) or not entities:
+                break
+            cursor = paging.get('nextPageCursor')
+            if not cursor:
+                break
+            params['pageCursor'] = cursor
+        return all_events
+
     ####################################################################
     # Confluence groups&users
     #
@@ -957,6 +1028,8 @@ class Confluence:
     # list_space_permissionsets*
     # create_space
     # delete_space
+    # archive_space
+    # restore_space
     # add_space_label*
     # remove_space_permission*
     # add_space_permissions*
@@ -1262,6 +1335,40 @@ class Confluence:
         response = self._delete(f'/space/{space_key}')
         return response
 
+    @api_call
+    def archive_space(self, space_key: str) -> bool:
+        """Archive a space.
+
+        # Required parameters
+
+        - space_key: a non-empty string
+
+        # Returned value
+
+        A boolean, True if successful
+        """
+        ensure_nonemptystring('space_key')
+
+        response = self._put(f'/space/{space_key}/archive')
+        return response.status_code == 204
+
+    @api_call
+    def restore_space(self, space_key: str) -> bool:
+        """Restore a space.
+
+        # Required parameters
+
+        - space_key: a non-empty string
+
+        # Returned value
+
+        A boolean, True if successful
+        """
+        ensure_nonemptystring('space_key')
+
+        response = self._put(f'/space/{space_key}/restore')
+        return response.status_code == 204
+
     @api_call
     def add_space_label(self, space_key: str, label: str) -> bool:
         """Add label to space.

{zabel_elements-1.47.2 → zabel_elements-1.50.0}/zabel/elements/clients/base/github.py

@@ -4582,12 +4582,10 @@ class GitHub:
 
             remaining = response.headers.get('X-RateLimit-Remaining')
             retry_after = response.headers.get('Retry-After')
-            reset = response.headers.get('X-RateLimit-Reset')
             if (
                 response.status_code == 403
                 and remaining != '0'
                 and retry_after is None
-                and reset is None
             ):
                 return response