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

{clear_skies_cortex-2.0.2 → 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.35
+_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.2 → clear_skies_cortex-2.0.4}/.github/workflows/create-version.yaml

@@ -79,7 +79,7 @@ jobs:
       # STEP 2: Commit all file changes together
       - name: Commit All Changes
         run: |
-          git add pyproject.toml CHANGELOG.md
+          git add pyproject.toml CHANGELOG.md uv.lock
           git commit -m "chore(release): bump version to ${{ steps.bump.outputs.tag }}"
 
       # STEP 3: Create the tag for the final commit

{clear_skies_cortex-2.0.2 → 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.2 → clear_skies_cortex-2.0.4}/.github/workflows/run-tests.yml

@@ -67,7 +67,7 @@ jobs:
       python-version: ${{ matrix.python-version }}
       run-mypy: ${{ needs.changes.outputs.tests == 'true' }}
       run-pytest: ${{ needs.changes.outputs.tests == 'true' }}
-      run-black: ${{ needs.changes.outputs.tests == 'true' }}
+      run-ruff-format: ${{ needs.changes.outputs.tests == 'true' }}
       run-ruff-check: ${{ needs.changes.outputs.tests == 'true' }}
     secrets: inherit
     strategy:
@@ -76,6 +76,7 @@ jobs:
           - '3.11'
           - '3.12'
           - '3.13'
+          - '3.14'
       fail-fast: false
 
   status:

{clear_skies_cortex-2.0.2 → clear_skies_cortex-2.0.4}/.github/workflows/tests-matrix.yaml

@@ -14,7 +14,7 @@ on:
       run-pytest:
         required: true
         type: boolean
-      run-black:
+      run-ruff-format:
         required: true
         type: boolean
       run-ruff-check:
@@ -66,27 +66,14 @@ jobs:
       - run: uv run pytest -v
       - run: git diff --exit-code --stat HEAD
 
-  black:
-    name: black
+  ruff-format:
+    name: ruff-format
     runs-on: ${{ inputs.runner }}
-    if: inputs.run-black
+    if: inputs.run-ruff-format
     steps:
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-
-      - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v6
-        with:
-          python-version: ${{ inputs.python-version }}
-          enable-cache: true
-      - name: Install dependencies
-        run: uv sync --locked --all-extras --dev
-      - uses: psf/black@stable
+      - uses: astral-sh/ruff-action@v3
         with:
-          options: "--check --verbose"
-          src: "./src"
+          args: "format --diff"
 
   ruff-check:
     name: ruff-check

{clear_skies_cortex-2.0.2 → clear_skies_cortex-2.0.4}/.pre-commit-config.yaml

@@ -38,12 +38,6 @@ repos:
     hooks:
       - id: uv-lock
 
-  - repo: https://github.com/psf/black
-    rev: 25.1.0
-    hooks:
-      - id: black
-        files: \.py$
-
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.12.1
     hooks:
@@ -55,7 +49,7 @@ repos:
     rev: v1.16.1
     hooks:
       - id: mypy
-        additional_dependencies: [types-requests, clear-skies]
+        additional_dependencies: [types-requests]
         files: \.py$
 
   - repo: https://github.com/adrienverge/yamllint

clear_skies_cortex-2.0.4/.vscode/settings.json

@@ -0,0 +1,21 @@
+{
+    "python.testing.pytestArgs": ["tests"],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "ruff.interpreter": ["${workspaceFolder}/.venv/bin/python"],
+    "ruff.path": ["${workspaceFolder}/.venv/bin/ruff"],
+    "ruff.configuration": "${workspaceFolder}/ruff.toml",
+    "ruff.nativeServer": "on",
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff"
+    },
+    "mypy-type-checker.args": [
+        "--config-file=${workspaceFolder}/pyproject.toml"
+    ]
+}

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

@@ -5,12 +5,29 @@ 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
+
 ## [2.0.2] - 2026-01-06
 
 ### Added
 - Add teams
 
 ### Changed
+- Bump version to v2.0.2 by @github-actions[bot]
 - Make it all work with the api
 
 ### Fixed
@@ -34,6 +51,8 @@ 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
 
 <!-- generated by git-cliff -->

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.2 → clear_skies_cortex-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clear-skies-cortex
-Version: 2.0.2
+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
@@ -14,7 +14,7 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Requires-Python: <4.0,>=3.11
-Requires-Dist: clear-skies<3.0.0,>=2.0.0
+Requires-Dist: clear-skies<3.0.0,>=2.0.37
 Requires-Dist: dacite>=1.9.2
 Provides-Extra: dev
 Requires-Dist: types-requests>=2.32.4; extra == 'dev'

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

@@ -1,13 +1,13 @@
 [project]
 name = "clear-skies-cortex"
 description = "Cortex module for Clearskies"
-version = "2.0.2"
+version = "2.0.4"
 license = "MIT"
 readme = "./README.md"
 authors = [{name = "Tom Nijboer", email = "tom.nijboer@cimpress.com"}]
 requires-python = ">=3.11,<4.0"
 dependencies = [
-    "clear-skies>=2.0.0,<3.0.0",
+    "clear-skies>=2.0.37,<3.0.0",
     "dacite>=1.9.2",
 ]
 classifiers = [
@@ -44,19 +44,6 @@ exclude = [
     "tests/**"
 ]
 
-[tool.black]
-line-length = 120
-skip-magic-trailing-comma = false
-preview = false
-
-[tool.mypy]
-python_version = "3.11"
-
-exclude = [
-    ".*_test\\.py$",
-    "docs/.*"
-]
-
 [tool.pytest.ini_options]
 minversion = "6.0"
 addopts = "-ra -q"
@@ -72,10 +59,12 @@ pythonpath = [
 [dependency-groups]
 dev = [
     "akeyless>=5.0.8",
-    "black>=25.1.0",
     "mypy>=1.18.2",
     "pre-commit>=4.3.0",
     "pytest>=8.4.1",
     "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.2 → clear_skies_cortex-2.0.4}/src/clearskies_cortex/backends/cortex_team_relationship_backend.py

@@ -9,6 +9,7 @@ from clearskies.backends.memory_backend import MemoryBackend, MemoryTable
 from clearskies.columns import String, Uuid
 from clearskies.di import inject
 from clearskies.query import Condition, Query
+from clearskies.query.result import RecordsQueryResult
 
 from clearskies_cortex.backends import cortex_backend as rest_backend
 
@@ -34,7 +35,7 @@ class CortexTeamRelationshipBackend(MemoryBackend, Configurable):
         # or we need to let the di system build the CortexBackend.  This change does both:
         self.cortex_backend = cortex_backend
 
-    def records(self, query: Query, next_page_data: dict[str, str | int] | None = None) -> list[dict[str, Any]]:
+    def records(self, query: Query) -> RecordsQueryResult:
         """Accept either a model or a model class and creates a "table" for it."""
         table_name = query.model_class.destination_name()
         if table_name not in self._tables:
@@ -45,7 +46,7 @@ class CortexTeamRelationshipBackend(MemoryBackend, Configurable):
             # we don't need since we built the data ourselves.  In short, it will be a lot slower, so I cheat.
             self._tables[table_name]._rows = records  # type: ignore[assignment]
             self._tables[table_name]._id_index = id_index  # type: ignore[assignment]
-        return super().records(query, next_page_data)
+        return super().records(query)
 
     def _fetch_and_map_relationship_data(self, table_name: str) -> tuple[list[dict[str, str | int]], dict[str, int]]:
         class RelationshipModel(Model):
@@ -75,11 +76,14 @@ class CortexTeamRelationshipBackend(MemoryBackend, Configurable):
         root_categories: dict[str, str] = {}
         known_children: dict[str, str] = {}
         relationships: dict[str, set[str]] = {}
-        for relationship in self._get_cortex_backend().records(
-            Query(
-                model_class=RelationshipModel,
-            ),
-            {},
+        for relationship in (
+            self._get_cortex_backend()
+            .records(
+                Query(
+                    model_class=RelationshipModel,
+                ),
+            )
+            .records
         ):
             child_category = relationship["child_team_tag"]
             parent_category = relationship["parent_team_tag"]
@@ -153,12 +157,15 @@ class CortexTeamRelationshipBackend(MemoryBackend, Configurable):
         from clearskies_cortex.models.cortex_team import CortexTeam
 
         teams: dict[str, dict[str, Any]] = {}
-        for team in self._get_cortex_backend().records(
-            Query(
-                model_class=CortexTeam,
-                conditions=[Condition("include_teams_without_members=true")],
-            ),
-            {},
+        for team in (
+            self._get_cortex_backend()
+            .records(
+                Query(
+                    model_class=CortexTeam,
+                    conditions=[Condition("include_teams_without_members=true")],
+                ),
+            )
+            .records
         ):
             teams[team["team_tag"]] = team
         self._cached_teams = teams

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]))}