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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zabel-elements
-Version: 1.47.0
+Version: 1.47.2
 Summary: TThe Zabel default clients and images
 Author-email: Martin Lafaix <martin.lafaix@external.engie.com>
 License-Expression: EPL-2.0
@@ -18,7 +18,7 @@ Requires-Dist: python-gitlab>=8.0; extra == "gitlab"
 Provides-Extra: jira
 Requires-Dist: Jira>=3.0; extra == "jira"
 Provides-Extra: kubernetes
-Requires-Dist: kubernetes>=35.0; extra == "kubernetes"
+Requires-Dist: kubernetes<36,>=35.0; extra == "kubernetes"
 Provides-Extra: okta
 Requires-Dist: okta<=2.9.10,>=2.9; extra == "okta"
 Provides-Extra: pynacl

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zabel-elements"
-version = "1.47.0"
+version = "1.47.2"
 description = "TThe Zabel default clients and images"
 readme = "README.md"
 license = "EPL-2.0"
@@ -30,7 +30,7 @@ dependencies = [
     "Jira>=3.0",
 ]
 "kubernetes" = [
-    "kubernetes>=35.0",
+    "kubernetes>=35.0,<36",
 ]
 "okta" = [
     "okta>=2.9,<=2.9.10",

zabel_elements-1.47.2/zabel/elements/clients/base/atlassian.py

@@ -0,0 +1,600 @@
+"""Atlassian.
+
+A base class wrapping Atlassian cloud APIs.
+
+This module depends on the public **requests** library.  It also depends
+on three **zabel-commons** modules, #::zabel.commons.exceptions,
+#::zabel.commons.sessions, and #::zabel.commons.utils.
+
+A base class wrapper only implements 'simple' API requests.  It handles
+pagination if appropriate, but does not process the results or compose
+API requests.
+"""
+
+from typing import Any, Iterable, Mapping
+
+import random
+import time
+
+from contextvars import ContextVar
+from functools import wraps
+
+import requests
+
+from zabel.commons.exceptions import ApiError
+from zabel.commons.sessions import prepare_session
+from zabel.commons.utils import (
+    api_call,
+    ensure_nonemptystring,
+    ensure_noneorinstance,
+    ensure_noneornonemptystring,
+    join_url,
+    BearerAuth,
+)
+
+########################################################################
+########################################################################
+
+# Atlassian Cloud low-level API
+
+_V2_PAGE_SIZE = 100
+_V2_MAX_RETRIES = 5
+
+# Thread-safe context variable to force basic auth for specific endpoints
+_force_basic_auth: ContextVar[bool] = ContextVar(
+    'force_basic_auth', default=False
+)
+
+
+def require_basic_auth(func):
+    """Decorator to force basic auth for site-level API endpoints.
+
+    Some Atlassian site APIs (e.g. rest/api/3/user/search) require basic
+    auth instead of bearer auth.  Uses ContextVar for thread-safety.
+    """
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        prev = _force_basic_auth.set(True)
+        try:
+            return func(self, *args, **kwargs)
+        finally:
+            _force_basic_auth.reset(prev)
+
+    return wrapper
+
+
+class Atlassian:
+    """Atlassian Low-Level Wrapper.
+
+    ## Reference URLs
+
+    - <https://developer.atlassian.com/cloud/admin>
+    - <https://developer.atlassian.com/cloud/admin/rest-apis/>
+
+    Some methods target the underlying product (Confluence Cloud,
+    Jira Cloud, ...)
+
+    - <https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro>
+    - <https://developer.atlassian.com/cloud/confluence/rest/v2/intro>
+
+    ## Implemented features
+
+    - users
+
+    ## Examples
+
+    ```python
+    from zabel.elements.clients import Atlassian
+
+    url = 'https://api.atlassian.com/admin/v1/'
+    token = '...'
+    atlassian = Atlassian(url, bearer_auth=token)
+    atlassian.list_organization_users('your-organization-id')
+    ```
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        basic_auth: tuple[str, str] | None = None,
+        bearer_auth: str | None = None,
+    ) -> None:
+        """Create an Atlassian instance object.
+
+        You can specify `basic_auth`, `bearer_auth`, or both.
+
+        When both are provided, `bearer_auth` is used as the default
+        session (for admin APIs) and `basic_auth` is available for
+        site-level endpoints via the `@require_basic_auth` decorator.
+
+        # Required parameters
+
+        At least one of `basic_auth` or `bearer_auth` must be provided.
+
+        - url: a non-empty string
+        - basic_auth: a tuple of (user, token)
+        - bearer_auth: a string
+
+        # Usage
+
+        `url` is the top-level API endpoint.  For example:
+
+            'https://api.atlassian.com/admin/v1/'
+        """
+        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/')
+        self.basic_auth = basic_auth
+        self.bearer_auth = bearer_auth
+
+        if bearer_auth:
+            self.session = prepare_session(BearerAuth(bearer_auth))
+            if basic_auth:
+                self._basic_session = prepare_session(basic_auth)
+            else:
+                self._basic_session = self.session
+        else:
+            self._basic_session = self.session = prepare_session(basic_auth)
+
+    def __str__(self) -> str:
+        return f'{self.__class__.__name__}: {self.url}'
+
+    def __repr__(self) -> str:
+        rep = []
+        if self.basic_auth:
+            rep.append('basic_auth={self.basic_auth[0]!r}')
+        if self.bearer_auth:
+            rep.append('bearer_auth=***{self.bearer_auth[-6:]!r}')
+        return f'<{self.__class__.__name__}: {self.url!r}, {', '.join(rep)}>'
+
+    def _get_session(self) -> requests.Session:
+        """Return the appropriate session based on current auth context."""
+        if _force_basic_auth.get():
+            return self._basic_session()
+        return self.session()
+
+    ####################################################################
+    # atlassian users
+    #
+    # list_organization_users
+
+    @api_call
+    def list_organization_users(self, org_id: str) -> list[dict[str, Any]]:
+        """List organization users.
+
+        # Required parameters
+
+        - org_id: a string
+
+        # Returned value
+
+        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`)
+        """
+        ensure_nonemptystring('org_id')
+
+        session = self._get_session()
+        api_url = join_url(self.url, f'orgs/{org_id}/users')
+
+        collected: list[dict[str, Any]] = []
+        while True:
+            response = session.get(api_url).json()
+            collected.extend(response['data'])
+            links = response['links']
+
+            if 'next' in links:
+                api_url = links['next']
+            else:
+                break
+
+        return collected
+
+    ####################################################################
+    # atlassian organization directories / groups / role assignments / users
+    #
+    # list_organization_directories
+    # list_directory_groups
+    # list_directory_users
+    # list_group_roleassignments
+
+    @api_call
+    def list_organization_directories(
+        self, org_id: str
+    ) -> list[dict[str, Any]]:
+        """List directories in an organization.
+
+        Each directory typically maps to one Atlassian Cloud site.
+
+        # Required parameters
+
+        - org_id: a non-empty string
+
+        # Returned value
+
+        A list of _directories_.  Each directory is a dictionary with
+        entries such as `id`, `name`, `type`, `managementAccess`.
+        """
+        ensure_nonemptystring('org_id')
+
+        return self._collect_v2(f'orgs/{org_id}/directories')
+
+    @api_call
+    def list_directory_groups(
+        self, org_id: str, directory_id: str
+    ) -> list[dict[str, Any]]:
+        """List groups in a directory of an organization.
+
+        # Required parameters
+
+        - org_id: a non-empty string
+        - directory_id: a non-empty string
+
+        # Returned value
+
+        A list of _groups_.  Each group is a dictionary with entries
+        such as `id`, `name`, `description`, `directoryId`,
+        `managementAccess`, `externalSynced`.
+        """
+        ensure_nonemptystring('org_id')
+        ensure_nonemptystring('directory_id')
+
+        return self._collect_v2(
+            f'orgs/{org_id}/directories/{directory_id}/groups'
+        )
+
+    @api_call
+    def list_group_roleassignments(
+        self, org_id: str, directory_id: str, group_id: str
+    ) -> list[dict[str, Any]]:
+        """List role assignments for a group.
+
+        Reveals which product (jira, confluence, cmdb, avp...) and role
+        (atlassian/user, atlassian/admin, atlassian/guest) the group
+        grants on which resource (site).  This is the mapping that
+        Atlassian's v1 API doesn't expose (CONFCLOUD-74996 workaround).
+
+        # Required parameters
+
+        - org_id: a non-empty string
+        - directory_id: a non-empty string
+        - group_id: a non-empty string
+
+        # Returned value
+
+        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
+        """
+        ensure_nonemptystring('org_id')
+        ensure_nonemptystring('directory_id')
+        ensure_nonemptystring('group_id')
+
+        return self._collect_v2(
+            f'orgs/{org_id}/directories/{directory_id}'
+            f'/groups/{group_id}/role-assignments'
+        )
+
+    @api_call
+    def list_directory_users(
+        self,
+        org_id: str,
+        directory_id: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> 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
+        suspended at the org level.
+
+        # Required parameters
+
+        - org_id: a non-empty string
+        - directory_id: a non-empty string
+
+        # Optional parameters
+
+        - params: a dictionary of query parameters passed verbatim as
+          server-side filters or None (None by default)
+
+        # Returned value
+
+        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`, ...
+
+        # Usage
+
+        ```python
+        params = {
+          'status': ['active'],
+          'claimStatus': 'unmanaged',
+          'roleIds': ['atlassian/user', 'atlassian/admin'],
+          'resourceIds': ['ari:cloud:confluence::site/<siteId>'],
+        }
+        users = atlassian.list_directory_users(org_id, directory_id, params)
+        ```
+
+        For billing, combining `roleIds` + `resourceIds` returns the
+        exact billable user set for a given (site, product) couple --
+        matching admin UI counts.
+        """
+        ensure_nonemptystring('org_id')
+        ensure_nonemptystring('directory_id')
+
+        return self._collect_v2(
+            f'orgs/{org_id}/directories/{directory_id}/users', params=params
+        )
+
+    ####################################################################
+    # atlassian sites
+
+    @api_call
+    @require_basic_auth
+    def list_site_users(self, site_url: str) -> list[dict[str, Any]]:
+        """List site users.
+
+        # Required parameters
+
+        - 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
+        """
+        ensure_nonemptystring('site_url')
+
+        session = self._get_session()
+        api_url = join_url(site_url, 'rest/api/3/users/search')
+
+        params = {'maxResults': 1000}
+
+        start = 0
+        collected: list[Any] = []
+        while True:
+            params['startAt'] = start
+            response = session.get(api_url, params=params).json()
+            if not response:
+                break
+            if not isinstance(response, list):
+                raise ApiError(
+                    f'list_site_users({site_url}): unexpected response {response!r}'
+                )
+
+            collected.extend(response)
+
+            start += len(response)
+
+        return collected
+
+    @api_call
+    @require_basic_auth
+    def search_site_user(
+        self, site_url: str, query: str
+    ) -> list[dict[str, Any]]:
+        """Search for site user details.
+
+        Uses basic auth as required by the Atlassian site REST API.
+
+        # Required parameters
+
+        - site_url: a non-empty string
+        - query: a non-empty string
+
+        # Returned value
+
+        A possibly empty list of _users_.  See #list_site_users() for
+        details on its structure.
+        """
+        ensure_nonemptystring('site_url')
+        ensure_nonemptystring('query')
+
+        session = self._get_session()
+        api_url = join_url(site_url, 'rest/api/3/user/search')
+
+        params = {'query': query}
+
+        return session.get(api_url, params=params)  # type: ignore
+
+    @api_call
+    @require_basic_auth
+    def list_site_application_roles(
+        self, site_url: str
+    ) -> list[dict[str, Any]]:
+        """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
+        are granted access to that product.
+
+        # Required parameters
+
+        - site_url: a non-empty string
+
+        # Returned value
+
+        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
+        """
+        ensure_nonemptystring('site_url')
+
+        session = self._get_session()
+        api_url = join_url(site_url, 'rest/api/3/applicationrole')
+
+        return session.get(api_url).json()  # type: ignore
+
+    @api_call
+    @require_basic_auth
+    def list_site_group_members(
+        self,
+        site_url: str,
+        group_name: str,
+        include_inactive: bool = False,
+    ) -> list[dict[str, Any]]:
+        """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`).
+
+        # Required parameters
+
+        - site_url: a non-empty string
+        - group_name: a non-empty string
+
+        # Optional parameters
+
+        - include_inactive: a boolean (default False)
+
+        # Returned value
+
+        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
+          have the relevant privacy permission)
+        """
+        ensure_nonemptystring('site_url')
+        ensure_nonemptystring('group_name')
+
+        session = self._get_session()
+        api_url = join_url(site_url, 'rest/api/3/group/member')
+
+        params: dict[str, Any] = {
+            'groupname': group_name,
+            'includeInactiveUsers': 'true' if include_inactive else 'false',
+            'maxResults': 50,
+            'startAt': 0,
+        }
+
+        collected: list[dict[str, Any]] = []
+        while True:
+            page = session.get(api_url, params=params).json()
+            values = page.get('values', [])
+            collected.extend(values)
+            if not values or page.get('isLast', False):
+                break
+            params['startAt'] += len(values)
+
+        return collected
+
+    ####################################################################
+    # atlassian private helpers
+
+    def _get(
+        self,
+        api: str,
+        params: Mapping[str, str | Iterable[str] | int | bool] | None = None,
+    ) -> requests.Response:
+        """Return atlassian api call results, as Response."""
+        session = self._get_session()
+        api_url = join_url(self.url, api)
+        return session.get(api_url, params=params)
+
+    def _collect_v2(
+        self,
+        api: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Return admin/v2 GET api call results, collected.
+
+        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.
+        """
+        session = self._get_session()
+        api_url = join_url(join_url(self.base_url, '/v2'), api)
+
+        _params: dict[str, Any] = {
+            'limit': _V2_PAGE_SIZE,
+            **(params or {}),
+        }
+
+        collected: list[dict[str, Any]] = []
+        while True:
+            for attempt in range(_V2_MAX_RETRIES + 1):
+                response = session.get(api_url, params=_params)
+                if response.status_code != 429:
+                    break
+                if attempt == _V2_MAX_RETRIES:
+                    raise ApiError(
+                        f'{api}: rate-limited after {_V2_MAX_RETRIES + 1} attempts'
+                    )
+                try:
+                    retry_after = int(response.headers.get('Retry-After', 0))
+                except (TypeError, ValueError):
+                    retry_after = 0
+                wait = max(retry_after, 10 * (attempt + 1))
+                time.sleep(wait + random.uniform(0, 5))
+
+            if response.status_code // 100 != 2:
+                raise ApiError(response.text)
+            workload = response.json()
+            collected += workload.get('data', [])
+            cursor = (workload.get('links') or {}).get('next')
+            if not cursor:
+                break
+            _params = {'cursor': cursor}
+
+        return collected