clear-skies-cortex 2.0.3__tar.gz → 2.0.4__tar.gz

{clear_skies_cortex-2.0.3 → clear_skies_cortex-2.0.4}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v0.0.45
+_commit: v0.0.46
 _src_path: gh:clearskies-py/clearskies-module-template
 author_email: tom.nijboer@cimpress.com
 author_name: Tom Nijboer

{clear_skies_cortex-2.0.3 → clear_skies_cortex-2.0.4}/.github/workflows/docs.yaml

@@ -33,6 +33,8 @@ jobs:
           enable-cache: true
       - name: Publish
         run: |
+            uv sync --all-groups --all-extras
+            uv add clear-skies-doc-builder --group doc
             cd docs/python
             uv run build.py
             sudo apt update

{clear_skies_cortex-2.0.3 → clear_skies_cortex-2.0.4}/CHANGELOG.md

@@ -5,9 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.4] - 2026-01-28
+
+### Changed
+- Update to v0.0.46
+- Document all the files
+
+### Fixed
+- Set the count data correctly
+
 ## [2.0.3] - 2026-01-27
 
 ### Changed
+- Bump version to v2.0.3 by @github-actions[bot]
 - Udpate to QueryResult
 - Update to latest copier version
 
@@ -41,6 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * @tnijboer made their first contribution in [#1](https://github.com/clearskies-py/cortex/pull/1)
 * @cmancone made their first contribution
 * @ made their first contribution
+[2.0.4]: https://github.com/clearskies-py/cortex/compare/v2.0.3..v2.0.4
 [2.0.3]: https://github.com/clearskies-py/cortex/compare/v2.0.2..v2.0.3
 [2.0.2]: https://github.com/clearskies-py/cortex/compare/v2.0.1..v2.0.2
 

clear_skies_cortex-2.0.4/LATEST_CHANGELOG.md

@@ -0,0 +1,9 @@
+## [2.0.4] - 2026-01-28
+
+### Changed
+- Update to v0.0.46
+- Document all the files
+
+### Fixed
+- Set the count data correctly
+

{clear_skies_cortex-2.0.3 → clear_skies_cortex-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clear-skies-cortex
-Version: 2.0.3
+Version: 2.0.4
 Summary: Cortex module for Clearskies
 Project-URL: Docs, https://https://clearskies.info/modules/clear-skies-cortex
 Project-URL: Repository, https://github.com/clearskies-py/cortex

{clear_skies_cortex-2.0.3 → clear_skies_cortex-2.0.4}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "clear-skies-cortex"
 description = "Cortex module for Clearskies"
-version = "2.0.3"
+version = "2.0.4"
 license = "MIT"
 readme = "./README.md"
 authors = [{name = "Tom Nijboer", email = "tom.nijboer@cimpress.com"}]
@@ -65,3 +65,6 @@ dev = [
     "pytest-cov>=6.2.1",
     "ruff>=0.12.10",
 ]
+doc = [
+    "clear-skies-doc-builder>=2.0.11",
+]

clear_skies_cortex-2.0.4/src/clearskies_cortex/backends/cortex_backend.py

@@ -0,0 +1,236 @@
+from typing import Any
+
+import clearskies
+import requests
+from clearskies import configs
+from clearskies.authentication import Authentication
+from clearskies.decorators import parameters_to_properties
+from clearskies.di import inject
+from clearskies.query import Query
+
+
+class CortexBackend(clearskies.backends.ApiBackend):
+    """
+    Backend for interacting with the Cortex.io API.
+
+    This backend extends the ApiBackend to provide seamless integration with the Cortex.io platform.
+    It handles the specific pagination and response format used by Cortex APIs, where pagination
+    information (`page`, `totalPages`, `total`) is returned in the response body rather than headers.
+
+    ## Usage
+
+    The CortexBackend is typically used with models that represent Cortex entities:
+
+    ```python
+    import clearskies
+    from clearskies_cortex.backends import CortexBackend
+
+
+    class CortexService(clearskies.Model):
+        backend = CortexBackend()
+
+        @classmethod
+        def destination_name(cls) -> str:
+            return "catalog/services"
+
+        tag = clearskies.columns.String()
+        name = clearskies.columns.String()
+        description = clearskies.columns.String()
+    ```
+
+    ## Authentication
+
+    By default, the backend uses the `cortex_auth` binding for authentication, which should be
+    configured in your application's dependency injection container. You can also provide a custom
+    authentication instance:
+
+    ```python
+    backend = CortexBackend(
+        authentication=clearskies.authentication.SecretBearer(
+            environment_key="CORTEX_API_KEY",
+        )
+    )
+    ```
+
+    ## Pagination
+
+    The Cortex API uses page-based pagination with the following response format:
+
+    ```json
+    {
+        "entities": [...],
+        "page": 1,
+        "totalPages": 5,
+        "total": 100
+    }
+    ```
+
+    The backend automatically handles extracting pagination data and provides the next page
+    information to clearskies for seamless iteration through results.
+    """
+
+    """
+    The base URL for the Cortex API.
+    """
+    base_url = configs.String(default="https://api.getcortexapp.com/api/v1/")
+
+    """
+    The authentication instance to use for API requests.
+
+    By default, this uses the `cortex_auth` binding from the dependency injection container.
+    """
+    authentication = inject.ByName("cortex_auth")  # type: ignore[assignment]
+
+    """
+    The requests instance for making HTTP calls.
+    """
+    requests = inject.Requests()
+
+    """
+    The casing style used by the Cortex API (camelCase by default).
+    """
+    api_casing = configs.Select(["snake_case", "camelCase", "TitleCase"], default="camelCase")
+
+    _auth_headers: dict[str, str] = {}
+
+    """
+    A mapping from API response keys to model column names.
+    """
+    api_to_model_map = configs.AnyDict(default={})
+
+    """
+    The name of the pagination parameter used in requests.
+    """
+    pagination_parameter_name = configs.String(default="page")
+
+    """
+    The name of the limit parameter used in requests.
+    """
+    limit_parameter_name = configs.String(default="pageSize")
+
+    can_count = False
+
+    @parameters_to_properties
+    def __init__(
+        self,
+        base_url: str | None = "https://api.getcortexapp.com/api/v1/",
+        authentication: Authentication | None = None,
+        model_casing: str = "snake_case",
+        api_casing: str = "camelCase",
+        api_to_model_map: dict[str, str | list[str]] = {},
+        pagination_parameter_name: str = "page",
+        pagination_parameter_type: str = "int",
+        limit_parameter_name: str = "pageSize",
+    ):
+        self.finalize_and_validate_configuration()
+
+    def map_records_response(
+        self, response_data: Any, query: Query, query_data: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        """
+        Map the Cortex API response to model fields.
+
+        The Cortex API returns responses in a specific format where the actual records are nested
+        within a dictionary alongside pagination metadata. This method extracts the records and
+        removes the pagination fields before passing to the parent implementation.
+
+        Example Cortex API response:
+
+        ```json
+        {
+            "entities": [{"tag": "service-1", "name": "My Service"}, ...],
+            "page": 1,
+            "totalPages": 5,
+            "total": 100
+        }
+        ```
+
+        This method will extract the `entities` list and pass it to the parent for further processing.
+        """
+        if isinstance(response_data, dict):
+            if "page" in response_data:
+                del response_data["page"]
+                del response_data["totalPages"]
+                del response_data["total"]
+            first_item = next(iter(response_data))
+            if isinstance(response_data[first_item], list) and all(
+                isinstance(item, dict) for item in response_data[first_item]
+            ):
+                return super().map_records_response(response_data[first_item], query, query_data)
+        return super().map_records_response(response_data, query, query_data)
+
+    def get_next_page_data_from_response(
+        self,
+        query: Query,
+        response: "requests.Response",  # type: ignore
+    ) -> dict[str, Any]:
+        """
+        Extract pagination data from the Cortex API response.
+
+        The Cortex API includes pagination information in the response body:
+
+        - `page`: The current page number
+        - `totalPages`: The total number of pages available
+        - `total`: The total number of records
+
+        This method checks if there are more pages available and returns the next page number
+        if so. It also extracts total count information for use in RecordsQueryResult.
+        The returned dictionary is used by clearskies to fetch subsequent pages and
+        populate count metadata.
+
+        Returns:
+            A dictionary containing:
+            - The next page number if more pages exist
+            - total_count: The total number of records (if available)
+            - total_pages: The total number of pages (if available)
+        """
+        next_page_data: dict[str, Any] = {}
+
+        response_data = response.json() if response.content else {}
+
+        if isinstance(response_data, dict):
+            # Extract count information from response body
+            count_info = self.extract_count_from_response(None, response_data)
+            if count_info:
+                total_count, total_pages = count_info
+                if total_count is not None:
+                    next_page_data["total_count"] = total_count
+                if total_pages is not None:
+                    next_page_data["total_pages"] = total_pages
+
+            # Check if there are more pages
+            page = response_data.get("page", None)
+            total_pages_from_response = response_data.get("totalPages", None)
+            if page is not None and total_pages_from_response is not None and page < total_pages_from_response:
+                next_page_data[self.pagination_parameter_name] = page + 1
+
+        return next_page_data
+
+    def extract_count_from_response(
+        self,
+        response_headers: dict[str, str] | None = None,
+        response_data: Any = None,
+    ) -> tuple[int | None, int | None]:
+        """
+        Extract count information from the Cortex API response body.
+
+        Unlike many APIs that return count information in headers, the Cortex API includes
+        this data in the response body:
+
+        - `total`: The total number of records matching the query
+        - `totalPages`: The total number of pages available
+
+        This method extracts these values and returns them as a tuple for use in
+        `RecordsQueryResult`.
+
+        Returns:
+            A tuple of (total_count, total_pages) where either value may be None
+            if not present in the response.
+        """
+        if not isinstance(response_data, dict):
+            return (None, None)
+
+        total_count = response_data.get("total", None)
+        total_pages = response_data.get("totalPages", None)
+
+        return (total_count, total_pages)

clear_skies_cortex-2.0.4/src/clearskies_cortex/columns/string_list.py

@@ -0,0 +1,69 @@
+from typing import Any
+
+from clearskies.columns import String
+
+
+class StringList(String):
+    """
+    Column type for comma-delimited string lists.
+
+    This column type extends the String column to handle values that are stored as
+    comma-delimited strings but should be represented as Python lists. It automatically
+    converts between the two formats when reading from and writing to the backend.
+
+    Use this column type when the API returns or expects comma-separated values that
+    you want to work with as lists in your application code.
+
+    ```python
+    from clearskies import Model
+    from clearskies_cortex.columns import StringList
+
+
+    class MyModel(Model):
+        # Define a column that stores ["tag1", "tag2"] as "tag1,tag2"
+        tags = StringList()
+
+
+    # When reading from the backend:
+    # API returns: {"tags": "tag1,tag2,tag3"}
+    # Model provides: model.tags = ["tag1", "tag2", "tag3"]
+
+    # When writing to the backend:
+    # Model has: model.tags = ["tag1", "tag2", "tag3"]
+    # API receives: {"tags": "tag1,tag2,tag3"}
+    ```
+    """
+
+    def from_backend(self, value: str | list[str]) -> list[str]:
+        """
+        Convert backend value to a Python list.
+
+        Handles both string (comma-delimited) and list inputs for flexibility.
+
+        Args:
+            value: Either a comma-delimited string or a list of strings.
+
+        Returns:
+            A list of strings.
+        """
+        if isinstance(value, list):
+            return value
+        return value.split(",")
+
+    def to_backend(self, data: dict[str, Any]) -> dict[str, Any]:
+        """
+        Convert Python list to comma-delimited string for backend storage.
+
+        Transforms the list value back into a comma-separated string format
+        expected by the backend API.
+
+        Args:
+            data: Dictionary containing the column data.
+
+        Returns:
+            Dictionary with the column value converted to a comma-delimited string.
+        """
+        if self.name not in data:
+            return data
+
+        return {**data, self.name: str(",".join(data[self.name]))}

clear_skies_cortex-2.0.4/src/clearskies_cortex/dataclasses.py

@@ -0,0 +1,243 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ServiceEntityHierarchy:
+    """
+    Dataclass representing the hierarchy structure of a service entity.
+
+    This dataclass is used to parse the hierarchy JSON data from Cortex catalog entities.
+    It contains both parent and child relationships for navigating the entity hierarchy.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntity
+
+    entity = CortexCatalogEntity().find("tag=my-service")
+    hierarchy = entity.parse_hierarchy()
+
+    # Access parents
+    for parent in hierarchy.parents:
+        print(f"Parent: {parent.name} ({parent.type})")
+
+    # Access children
+    for child in hierarchy.children:
+        print(f"Child: {child.name} ({child.type})")
+    ```
+    """
+
+    """
+    List of parent entities in the hierarchy (from immediate parent to root).
+    """
+    parents: list["ServiceEntityHierarchyParent"]
+
+    """
+    List of child entities in the hierarchy.
+    """
+    children: list["ServiceEntityHierarchyChild"]
+
+
+@dataclass
+class ServiceEntityHierarchyParent:
+    """
+    Dataclass representing a parent entity in the hierarchy.
+
+    Contains information about a parent entity including its tag, type, name,
+    and recursively its own parents for traversing up the hierarchy tree.
+    """
+
+    """
+    The unique tag identifier of the parent entity.
+    """
+    tag: str
+
+    """
+    The type of the parent entity (e.g., "domain", "team").
+    """
+    type: str
+
+    """
+    The human-readable name of the parent entity.
+    """
+    name: str
+
+    """
+    Optional description of the parent entity.
+    """
+    description: str | None
+
+    """
+    Optional definition data for the parent entity.
+    """
+    definition: None | dict[str, Any]
+
+    """
+    List of grandparent entities (recursive parent structure).
+    """
+    parents: list["ServiceEntityHierarchyParent"]
+
+    """
+    Optional list of groups the parent entity belongs to.
+    """
+    groups: list[str] | None
+
+
+@dataclass
+class ServiceEntityHierarchyChild:
+    """
+    Dataclass representing a child entity in the hierarchy.
+
+    Contains information about a child entity including its tag, type, name,
+    and recursively its own children for traversing down the hierarchy tree.
+    """
+
+    """
+    The unique tag identifier of the child entity.
+    """
+    tag: str
+
+    """
+    The type of the child entity (e.g., "service", "domain").
+    """
+    type: str
+
+    """
+    The human-readable name of the child entity.
+    """
+    name: str
+
+    """
+    Optional description of the child entity.
+    """
+    description: str | None
+
+    """
+    Optional definition data for the child entity.
+    """
+    definition: None | dict[str, Any]
+
+    """
+    List of grandchild entities (recursive child structure).
+    """
+    children: list["ServiceEntityHierarchyChild"]
+
+    """
+    Optional list of groups the child entity belongs to.
+    """
+    groups: list[str] | None
+
+
+@dataclass
+class TeamCategory:
+    """
+    Dataclass representing a team category in the category tree.
+
+    Used for organizing teams into hierarchical categories with parent-child relationships.
+    """
+
+    """
+    The name of the category.
+    """
+    name: str
+
+    """
+    The depth level in the category hierarchy (0 for root).
+    """
+    level: int
+
+    """
+    The name of the parent category.
+    """
+    parent_name: str
+
+
+@dataclass
+class EntityTeam:
+    """
+    Dataclass representing a team associated with a catalog entity.
+
+    Contains team information including ownership inheritance and provider details.
+    """
+
+    """
+    Optional description of the team.
+    """
+    description: str | None
+
+    """
+    The inheritance type for ownership (e.g., "direct", "inherited").
+    """
+    inheritance: str
+
+    """
+    Whether the team is archived.
+    """
+    isArchived: bool  # noqa: N815
+
+    """
+    The human-readable name of the team.
+    """
+    name: str
+
+    """
+    The provider of the team data (e.g., "cortex", "external").
+    """
+    provider: str
+
+    """
+    The unique tag identifier of the team.
+    """
+    tag: str
+
+
+@dataclass
+class EntityIndividual:
+    """
+    Dataclass representing an individual owner of a catalog entity.
+
+    Contains information about individual (non-team) owners.
+    """
+
+    """
+    Optional description of the individual.
+    """
+    description: str | None
+
+    """
+    The email address of the individual.
+    """
+    email: str
+
+
+@dataclass
+class EntityTeamOwner:
+    """
+    Dataclass representing the ownership information for a catalog entity.
+
+    Contains both team and individual owners. Used by `CortexCatalogEntity.parse_owners()`.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntity
+
+    entity = CortexCatalogEntity().find("tag=my-service")
+    owners = entity.parse_owners()
+
+    # Access team owners
+    for team in owners.teams:
+        print(f"Team owner: {team.name} ({team.tag})")
+
+    # Access individual owners
+    for individual in owners.individuals:
+        print(f"Individual owner: {individual.email}")
+    ```
+    """
+
+    """
+    List of teams that own the entity.
+    """
+    teams: list[EntityTeam]
+
+    """
+    List of individuals that own the entity.
+    """
+    individuals: list[EntityIndividual]

clear_skies_cortex-2.0.4/src/clearskies_cortex/defaults/default_cortex_auth.py

@@ -0,0 +1,55 @@
+import clearskies
+
+
+class DefaultCortexAuth(clearskies.di.AdditionalConfigAutoImport):
+    """
+    Default authentication provider for Cortex API.
+
+    This class provides automatic configuration for Cortex API authentication using
+    the clearskies dependency injection system. It is auto-imported when the clearskies_cortex
+    package is used, making authentication configuration seamless.
+
+    The authentication can be configured in two ways:
+
+    1. **Secret Path (recommended for production)**: Set the `CORTEX_AUTH_SECRET_PATH` environment
+       variable to point to a secret manager path containing the API key.
+
+    2. **Direct Environment Key**: Set the `CORTEX_AUTH_KEY` environment variable directly
+       with the Cortex API key.
+
+    ```python
+    import clearskies
+    from clearskies_cortex.models import CortexTeam
+
+    # The authentication is automatically configured via environment variables
+    # Option 1: Using secret path
+    # export CORTEX_AUTH_SECRET_PATH=/path/to/secret
+
+    # Option 2: Using direct key
+    # export CORTEX_AUTH_KEY=your-api-key
+
+    # Then use models normally - auth is handled automatically
+    teams = CortexTeam()
+    for team in teams:
+        print(team.get_name())
+    ```
+    """
+
+    def provide_cortex_auth(self, environment: clearskies.Environment):
+        """
+        Provide the Cortex authentication configuration.
+
+        Checks for `CORTEX_AUTH_SECRET_PATH` first, falling back to `CORTEX_AUTH_KEY`
+        if not set. Returns a SecretBearer authentication instance configured for
+        the Cortex API.
+
+        Args:
+            environment: The clearskies Environment instance for accessing env variables.
+
+        Returns:
+            A SecretBearer authentication instance configured for Cortex API.
+        """
+        if environment.get("CORTEX_AUTH_SECRET_PATH", True):
+            secret_key = environment.get("CORTEX_AUTH_SECRET_PATH")
+            return clearskies.authentication.SecretBearer(secret_key=secret_key, header_prefix="Bearer ")
+        return clearskies.authentication.SecretBearer(environment_key="CORTEX_AUTH_KEY", header_prefix="Bearer ")