clear-skies-cortex 2.0.3__py3-none-any.whl → 2.0.4__py3-none-any.whl

{clear_skies_cortex-2.0.3.dist-info → clear_skies_cortex-2.0.4.dist-info}/METADATA

@@ -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.4.dist-info/RECORD

@@ -0,0 +1,28 @@
+clearskies_cortex/__init__.py,sha256=SwFkNfKLJgcq2qE6YJ_78_JfeoRGojlKuR_3DymZZSQ,142
+clearskies_cortex/dataclasses.py,sha256=UQP-Myo9SaGHOXMaNv85k0Z_Xvm_nmycpeLwkZqIvho,5289
+clearskies_cortex/backends/__init__.py,sha256=Ek74kpJLE7ERY-6yhH2KwFO25gm3Yjz51laUApnhgnU,179
+clearskies_cortex/backends/cortex_backend.py,sha256=Q2xzusGA_iXXxeSxd8v1iSxxlUWKtGuhwnywuMu_7Jk,8162
+clearskies_cortex/backends/cortex_team_relationship_backend.py,sha256=UiMZp0jcKvpx3tLbR8aMBS8-KIfECxJGiwM3fz8DmuM,7648
+clearskies_cortex/columns/__init__.py,sha256=BpoVCEVXRtKcsyRFnAYLtlwYtHBjciUbzuzaBxmfH00,87
+clearskies_cortex/columns/string_list.py,sha256=Ww9Bl1tuZlKhLbapYjjp_fy5RB4RQSquyh9tuC5PK4k,2104
+clearskies_cortex/defaults/__init__.py,sha256=tulZSvFgp4YUKj_bnArIevmlpC8z_AQKO0okYs4hCDo,216
+clearskies_cortex/defaults/default_cortex_auth.py,sha256=sWlWgXIoCXk0FkwK3Kz33TVohsaVpIOS9qj2Ef5_YN8,2135
+clearskies_cortex/defaults/default_cortex_url.py,sha256=sKBDQVPJWc4ozBquZ7fKryTbUOXYfrH6hUcQuUtMXEU,1576
+clearskies_cortex/models/__init__.py,sha256=zckJ4-KOjIcmtN7h7lXOESUu3d6JBsZZJq-s2MJ0NLQ,1145
+clearskies_cortex/models/cortex_catalog_entity.py,sha256=nWKApnvcr3pmSijEJgZ4cuZgG9ck6d8ey3AyVb8vfXQ,6632
+clearskies_cortex/models/cortex_catalog_entity_domain.py,sha256=AOa07Fq-SWc8zkg6g-fBi5x1GnGg42GhPM2GozrgC2c,2327
+clearskies_cortex/models/cortex_catalog_entity_group.py,sha256=D5Je_kX4dBW8jkhmZBca02mFYT3cqK1walleMXTlcdg,1295
+clearskies_cortex/models/cortex_catalog_entity_scorecard.py,sha256=XT08_865AzsiMGsybIhQPQ8jTR1HrCfAtRAME7MdDo0,2372
+clearskies_cortex/models/cortex_catalog_entity_service.py,sha256=OhX4nBRPpHxrA77B7HYNNKO265xBWxQN0x5pm2oHtKI,4003
+clearskies_cortex/models/cortex_catalog_entity_team.py,sha256=1Uk4ja9B5Pn-X2xxzs-R8LzfL20bsppRyeE2MRiDERw,2326
+clearskies_cortex/models/cortex_catalog_entity_types.py,sha256=kmpHEpL2ydUnyb_V2aY2rGdaOYTZqG0KcwSDLDA_X3Q,1611
+clearskies_cortex/models/cortex_entity_relationships.py,sha256=Zfv1DLf_vWsPELqPYaZcCMYh3K0qjIy8DpxNZfhMyHg,1815
+clearskies_cortex/models/cortex_model.py,sha256=U4hRboM49duUpDqvTfJ-pSFRHZzZyiGOM1aniq-iWK8,778
+clearskies_cortex/models/cortex_scorecard.py,sha256=aiM8_MkdMT_n-a6teG8y6zWSLmHuASW7IyXB-QKqU-Y,1712
+clearskies_cortex/models/cortex_team.py,sha256=UUS1KHufPqhO29h4eKIfeZzUz75KjwkqaW5ItmdAKS4,4356
+clearskies_cortex/models/cortex_team_category_tree.py,sha256=PRCIGeZrBoGiH1a7Q8ZsYYzSfj4cZF9tIRcBWEKAX60,1898
+clearskies_cortex/models/cortex_team_department.py,sha256=_0Go97ZFr_GCd_ol0iBw7Px5F_gE94WtAWFGnzQ9y-M,1582
+clear_skies_cortex-2.0.4.dist-info/METADATA,sha256=rhPhCyHqZqZ7yks_PDAaZX1aJ-MBL0kaG_oYh-NS_Bo,2117
+clear_skies_cortex-2.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clear_skies_cortex-2.0.4.dist-info/licenses/LICENSE,sha256=MkEX8JF8kZxdyBpTTcB0YTd-xZpWnHvbRlw-pQh8u58,1069
+clear_skies_cortex-2.0.4.dist-info/RECORD,,

clearskies_cortex/backends/cortex_backend.py

@@ -2,29 +2,113 @@ from typing import Any
 
 import clearskies
 import requests
-from clearskies import Column, configs
+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
-from clearskies.query.result import CountQueryResult
 
 
 class CortexBackend(clearskies.backends.ApiBackend):
-    """Backend for Cortex.io."""
+    """
+    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 = True
+    can_count = False
 
     @parameters_to_properties
     def __init__(
@@ -40,22 +124,29 @@ class CortexBackend(clearskies.backends.ApiBackend):
     ):
         self.finalize_and_validate_configuration()
 
-    def count(self, query: Query) -> CountQueryResult:
-        """Return count of records matching query."""
-        self.check_query(query)
-        (url, method, body, headers) = self.build_records_request(query)
-        response = self.execute_request(url, method, json=body, headers=headers)
-        response.raise_for_status()
-        data = response.json()
-        if "total" in data:
-            return CountQueryResult(count=data["total"])
-        data = self.map_records_response(data, query)
-        return CountQueryResult(count=len(data))
-
     def map_records_response(
         self, response_data: Any, query: Query, query_data: dict[str, Any] | None = None
     ) -> list[dict[str, Any]]:
-        """Map api response to model fields."""
+        """
+        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"]
@@ -68,34 +159,78 @@ class CortexBackend(clearskies.backends.ApiBackend):
                 return super().map_records_response(response_data[first_item], query, query_data)
         return super().map_records_response(response_data, query, query_data)
 
-    def set_next_page_data_from_response(
+    def get_next_page_data_from_response(
         self,
-        next_page_data: dict[str, Any],
         query: Query,
         response: "requests.Response",  # type: ignore
-    ) -> None:
+    ) -> dict[str, Any]:
         """
-        Update the next_page_data dictionary with the appropriate data needed to fetch the next page of records.
+        Extract pagination data from the Cortex API response.
 
-        This method has a very important job, which is to inform clearskies about how to make another API call to fetch the next
-        page of records.  The way this happens is by updating the `next_page_data` dictionary in place with whatever pagination
-        information is necessary.  Note that this relies on next_page_data being passed by reference, hence the need to update
-        it in place.  That means that you can do this:
+        The Cortex API includes pagination information in the response body:
 
-        ```python
-        next_page_data["some_key"] = "some_value"
-        ```
-
-        but if you do this:
+        - `page`: The current page number
+        - `totalPages`: The total number of pages available
+        - `total`: The total number of records
 
-        ```python
-        next_page_data = {"some_key": "some_value"}
-        ```
+        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.
 
-        Then things simply won't work.
+        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)
         """
-        if isinstance(response.json(), dict):
-            page = response.json().get("page", None)
-            total_pages = response.json().get("totalPages", None)
-            if page is not None and total_pages is not None and page < total_pages:
+        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)

clearskies_cortex/columns/string_list.py

@@ -4,20 +4,64 @@ from clearskies.columns import String
 
 
 class StringList(String):
-    """Column type for comma delimited 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]:
-        """Return comma delimited string to list."""
+        """
+        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]:
         """
-        Make any changes needed to save the data to the backend.
+        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.
 
-        This typically means formatting changes - converting DateTime objects to database
-        date strings, etc...
+        Returns:
+            Dictionary with the column value converted to a comma-delimited string.
         """
         if self.name not in data:
             return data

clearskies_cortex/dataclasses.py

@@ -4,70 +4,240 @@ from typing import Any
 
 @dataclass
 class ServiceEntityHierarchy:
-    """Dataclass for parent in service hierarchy."""
+    """
+    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 for parent in hierarchy."""
+    """
+    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 for child in hierarchy."""
+    """
+    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 for Team Category Tree."""
+    """
+    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 for team in Catalog Entity."""
+    """
+    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 for individual in Catalog Entity."""
+    """
+    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 for team owners in Catalog Entity."""
+    """
+    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]

clearskies_cortex/defaults/default_cortex_auth.py

@@ -2,7 +2,53 @@ 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 ")