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

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 ")

clearskies_cortex/defaults/default_cortex_url.py

@@ -2,6 +2,44 @@ import clearskies
 
 
 class DefaultCortexUrl(clearskies.di.AdditionalConfigAutoImport):
+    """
+    Default URL provider for Cortex API.
+
+    This class provides automatic configuration for the Cortex API base URL using
+    the clearskies dependency injection system. It is auto-imported when the clearskies_cortex
+    package is used, making URL configuration seamless.
+
+    The URL can be configured via the `CORTEX_URL` environment variable. If not set,
+    it defaults to the standard Cortex API endpoint: `https://api.getcortexapp.com/api/v1/`
+
+    ```python
+    import clearskies
+    from clearskies_cortex.models import CortexTeam
+
+    # The URL is automatically configured via environment variable
+    # export CORTEX_URL=https://custom-cortex-instance.example.com/api/v1/
+
+    # Or use the default Cortex API URL by not setting the variable
+
+    # Then use models normally - URL is handled automatically
+    teams = CortexTeam()
+    for team in teams:
+        print(team.get_name())
+    ```
+    """
+
     def provide_cortex_url(self, environment: clearskies.Environment) -> str:
+        """
+        Provide the Cortex API base URL.
+
+        Checks for `CORTEX_URL` environment variable, falling back to the default
+        Cortex API URL if not set.
+
+        Args:
+            environment: The clearskies Environment instance for accessing env variables.
+
+        Returns:
+            The Cortex API base URL string.
+        """
         cortex_url = environment.get("CORTEX_URL", True)
         return cortex_url if cortex_url else "https://api.getcortexapp.com/api/v1/"

clearskies_cortex/models/cortex_catalog_entity.py

@@ -17,7 +17,34 @@ from clearskies_cortex.models import (
 
 
 class CortexCatalogEntity(Model):
-    """Model for entities."""
+    """
+    Model for Cortex catalog entities.
+
+    This model represents entities in the Cortex catalog, which can include services, domains,
+    teams, and other entity types. It provides access to entity metadata, ownership information,
+    hierarchy data, and associated scorecards.
+
+    The model connects to the Cortex catalog API endpoint and supports various search parameters
+    for filtering entities.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntity
+
+    # Fetch all entities
+    entities = CortexCatalogEntity()
+    for entity in entities:
+        print(f"Entity: {entity.name} ({entity.type})")
+
+    # Find a specific entity by tag
+    entity = entities.find("tag=my-service")
+    print(entity.description)
+
+    # Access parsed hierarchy data
+    hierarchy = entity.parse_hierarchy()
+    if hierarchy.parents:
+        print(f"Parent: {hierarchy.parents[0].tag}")
+    ```
+    """
 
     id_column_name: str = "tag"
 
@@ -28,42 +55,172 @@ class CortexCatalogEntity(Model):
         """Return the slug of the api endpoint for this model."""
         return "catalog"
 
+    """
+    The unique identifier for the entity.
+    """
     id = String()
+
+    """
+    The unique tag identifier for the entity (e.g., "my-service").
+
+    This is the primary identifier used to reference entities in the Cortex catalog.
+    """
     tag = String()
+
+    """
+    List of groups the entity belongs to.
+
+    Groups are key-value pairs formatted as "key:value" strings. Use `parse_groups()`
+    to convert to a dictionary.
+    """
     groups = StringList("groups")
+
+    """
+    JSON object containing owner information for the entity.
+
+    Contains team and user ownership data. Use `parse_owners()` to convert to a typed dataclass.
+    """
     owners = Json()
+
+    """
+    JSON object containing ownership configuration.
+    """
     ownership = Json()
+
+    """
+    JSON object containing version 2 owner information.
+    """
     owners_v2 = Json()
+
+    """
+    Human-readable description of the entity.
+    """
     description = String()
+
+    """
+    JSON object containing Git repository information.
+
+    Includes repository URLs, default branch, and other Git-related metadata.
+    """
     git = Json()
+
+    """
+    JSON object containing hierarchy information.
+
+    Contains parent and child relationships. Use `parse_hierarchy()` to convert to a typed dataclass.
+    """
     hierarchy = Json()
+
+    """
+    Timestamp of when the entity was last updated.
+    """
     last_updated = Datetime()
+
+    """
+    Whether the entity is archived.
+    """
     is_archived = Boolean()
+
+    """
+    JSON object containing external links associated with the entity.
+    """
     links = Json()
+
+    """
+    JSON object containing member information for team entities.
+    """
     members = Json()
+
+    """
+    JSON object containing custom metadata for the entity.
+    """
     metadata = Json()
+
+    """
+    JSON object containing Slack channel configurations.
+    """
     slack_channels = Json()
+
+    """
+    Human-readable name of the entity.
+    """
     name = String()
+
+    """
+    The type of entity (e.g., "service", "domain", "team").
+    """
     type = String()
+
+    """
+    Related scorecards for this entity.
+
+    HasMany relationship to CortexCatalogEntityScorecard.
+    """
     scorecards = HasMany(
         cortex_catalog_entity_scorecard.CortexCatalogEntityScorecard,
         foreign_column_name="entity_tag",
     )
+
+    """
+    Related groups for this entity.
+
+    HasMany relationship to CortexCatalogEntityGroup.
+    """
     group_models = HasMany(
         cortex_catalog_entity_group.CortexCatalogEntityGroup,
         foreign_column_name="entity_tag",
     )
 
     # search columns
+
+    """
+    Search parameter: Filter by hierarchy depth level.
+    """
     hierarchy_depth = String(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Filter by Git repository URLs.
+    """
     git_repositories = StringList(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Filter by entity types (e.g., "service", "domain").
+    """
     types = StringList(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Free-text search query.
+    """
     query = String(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Include archived entities in results.
+    """
     include_archived = Boolean(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Include metadata in response.
+    """
     include_metadata = Boolean(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Include links in response.
+    """
     include_links = Boolean(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Include owner information in response.
+    """
     include_owners = Boolean(is_searchable=True)
+
+    """
+    Search parameter: Include nested fields in response (e.g., "team:members").
+    """
     include_nested_fields = StringList(is_searchable=True, is_temporary=True)
+
+    """
+    Search parameter: Include hierarchy fields in response (e.g., "groups").
+    """
     include_hierarchy_fields = StringList(is_searchable=True, is_temporary=True)
 
     def parse_hierarchy(self) -> dataclasses.ServiceEntityHierarchy:

clearskies_cortex/models/cortex_catalog_entity_domain.py

@@ -7,7 +7,35 @@ from clearskies_cortex.models import cortex_catalog_entity
 
 
 class CortexCatalogEntityDomain(cortex_catalog_entity.CortexCatalogEntity):
-    """Model for domain entities."""
+    """
+    Model for Cortex domain entities.
+
+    This model extends CortexCatalogEntity to specifically handle domain-type entities
+    in the Cortex catalog. Domains represent logical groupings of services and can be
+    organized hierarchically.
+
+    The model automatically filters for domain entities and includes nested fields for
+    team members, owners, metadata, and hierarchy groups.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityDomain
+
+    # Fetch all domains
+    domains = CortexCatalogEntityDomain()
+    for domain in domains.get_final_query():
+        print(f"Domain: {domain.name}")
+
+    # Get the top-level domain for a given domain
+    domain = domains.find("tag=my-domain")
+    top_level = domain.get_top_level_domain()
+    print(f"Top-level domain: {top_level.name}")
+
+    # Get the immediate parent domain
+    parent = domain.get_parent()
+    if parent.exists():
+        print(f"Parent domain: {parent.name}")
+    ```
+    """
 
     def get_final_query(self) -> Query:
         return (

clearskies_cortex/models/cortex_catalog_entity_group.py

@@ -7,7 +7,25 @@ from clearskies_cortex.backends import CortexBackend
 
 
 class CortexCatalogEntityGroup(Model):
-    """Model for teams."""
+    """
+    Model for Cortex entity groups.
+
+    This model represents groups associated with a specific catalog entity in Cortex.
+    Groups are used to categorize and organize entities with key-value pairs.
+
+    The model connects to the Cortex API endpoint `catalog/{entity_tag}/groups` to fetch
+    group information for a specific entity.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityGroup
+
+    # Fetch groups for a specific entity
+    groups = CortexCatalogEntityGroup()
+    entity_groups = groups.where("entity_tag=my-service")
+    for group in entity_groups:
+        print(f"Group tag: {group.tag}")
+    ```
+    """
 
     id_column_name: str = "entity_tag"
 
@@ -18,5 +36,12 @@ class CortexCatalogEntityGroup(Model):
         """Return the slug of the api endpoint for this model."""
         return "catalog/{entity_tag}/groups"
 
+    """
+    The tag identifier of the parent entity this group belongs to.
+    """
     entity_tag = String()
+
+    """
+    JSON object containing the group tag information.
+    """
     tag = Json()

clearskies_cortex/models/cortex_catalog_entity_scorecard.py

@@ -8,7 +8,27 @@ from clearskies_cortex.backends import CortexBackend
 
 
 class CortexCatalogEntityScorecard(Model):
-    """Model for teams."""
+    """
+    Model for Cortex entity scorecards.
+
+    This model represents scorecard data associated with a specific catalog entity in Cortex.
+    Scorecards track compliance, quality, and other metrics for entities based on defined rules.
+
+    The model connects to the Cortex API endpoint `catalog/:entity_tag/scorecards` to fetch
+    scorecard scores and ladder level information for a specific entity.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityScorecard
+
+    # Fetch scorecards for a specific entity
+    scorecards = CortexCatalogEntityScorecard()
+    entity_scorecards = scorecards.where("entity_tag=my-service")
+    for scorecard in entity_scorecards:
+        print(f"Scorecard: {scorecard.score_card_name}")
+        print(f"Score: {scorecard.score}/{scorecard.total_possible_score}")
+        print(f"Percentage: {scorecard.score_percentage}%")
+    ```
+    """
 
     id_column_name: str = "scorecard_id"
 
@@ -19,12 +39,41 @@ class CortexCatalogEntityScorecard(Model):
         """Return the slug of the api endpoint for this model."""
         return "catalog/:entity_tag/scorecards"
 
+    """
+    The unique identifier for the scorecard.
+    """
     scorecard_id = Integer()
+
+    """
+    The tag identifier of the entity this scorecard belongs to.
+    """
     entity_tag = String()
+
+    """
+    JSON object containing ladder level information.
+
+    Ladder levels define maturity stages for the scorecard (e.g., Bronze, Silver, Gold).
+    """
     ladder_levels = Json()
+
+    """
+    The current score achieved by the entity for this scorecard.
+    """
     score = Integer()
+
+    """
+    The score as a percentage of the total possible score.
+    """
     score_percentage = Float()
+
+    """
+    The human-readable name of the scorecard.
+    """
     score_card_name = String()
+
+    """
+    The maximum possible score for this scorecard.
+    """
     total_possible_score = Integer()
 
     def get_score_card_tag_name(self) -> str:

clearskies_cortex/models/cortex_catalog_entity_service.py

@@ -16,7 +16,41 @@ from clearskies_cortex.models import (
 
 
 class CortexCatalogEntityService(cortex_catalog_entity.CortexCatalogEntity):
-    """Model for domain entities."""
+    """
+    Model for Cortex service entities.
+
+    This model extends CortexCatalogEntity to specifically handle service-type entities
+    in the Cortex catalog. Services represent individual applications, microservices, or
+    other software components tracked in Cortex.
+
+    The model automatically filters for service entities and includes nested fields for
+    team members, owners, metadata, and hierarchy groups. It also provides methods to
+    navigate team and domain relationships.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityService
+
+    # Fetch all services
+    services = CortexCatalogEntityService()
+    for service in services.get_final_query():
+        print(f"Service: {service.name}")
+
+    # Get the owning team for a service
+    service = services.find("tag=my-service")
+    team = service.get_team()
+    if team.exists():
+        print(f"Owned by team: {team.get_name()}")
+
+    # Get the top-level team in the hierarchy
+    top_team = service.get_top_level_team()
+    print(f"Top-level team: {top_team.get_name()}")
+
+    # Get the parent domain for a service
+    parent_domain = service.get_parent_domain()
+    if parent_domain.exists():
+        print(f"Parent domain: {parent_domain.name}")
+    ```
+    """
 
     backend = CortexBackend()
 

clearskies_cortex/models/cortex_catalog_entity_team.py

@@ -7,7 +7,36 @@ from clearskies_cortex.models import cortex_catalog_entity
 
 
 class CortexCatalogEntityTeam(cortex_catalog_entity.CortexCatalogEntity):
-    """Model for team entities."""
+    """
+    Model for Cortex team entities.
+
+    This model extends CortexCatalogEntity to specifically handle team-type entities
+    in the Cortex catalog. Teams represent organizational units that own and manage
+    services and other entities.
+
+    The model automatically filters for team entities and includes nested fields for
+    team members, owners, metadata, and hierarchy groups. It provides methods to
+    navigate the team hierarchy.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityTeam
+
+    # Fetch all team entities
+    teams = CortexCatalogEntityTeam()
+    for team in teams.get_final_query():
+        print(f"Team: {team.name}")
+
+    # Get the top-level team in the hierarchy
+    team = teams.find("tag=my-team")
+    top_team = team.get_top_level_team()
+    print(f"Top-level team: {top_team.name}")
+
+    # Get the immediate parent team
+    parent = team.get_parent()
+    if parent.exists():
+        print(f"Parent team: {parent.name}")
+    ```
+    """
 
     def get_final_query(self) -> Query:
         return (

clearskies_cortex/models/cortex_catalog_entity_types.py

@@ -7,7 +7,25 @@ from clearskies_cortex.backends import CortexBackend
 
 
 class CortexCatalogEntityType(Model):
-    """Model for entities."""
+    """
+    Model for Cortex entity type definitions.
+
+    This model represents the available entity types in the Cortex catalog. Entity types
+    define the schema and structure for different kinds of entities (e.g., service, domain, team).
+
+    The model connects to the Cortex API endpoint `catalog/definitions` to fetch
+    entity type definitions.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityType
+
+    # Fetch all entity type definitions
+    entity_types = CortexCatalogEntityType()
+    for entity_type in entity_types:
+        print(f"Type: {entity_type.name}")
+        print(f"Description: {entity_type.description}")
+    ```
+    """
 
     id_column_name: str = "type"
 
@@ -18,8 +36,27 @@ class CortexCatalogEntityType(Model):
         """Return the slug of the api endpoint for this model."""
         return "catalog/definitions"
 
+    """
+    The human-readable name of the entity type.
+    """
     name = String()
+
+    """
+    A description of what this entity type represents.
+    """
     description = String()
+
+    """
+    JSON object containing the schema definition for this entity type.
+    """
     schema = Json()
+
+    """
+    The source of the entity type definition (e.g., "builtin", "custom").
+    """
     source = String()
+
+    """
+    The unique type identifier (e.g., "service", "domain", "team").
+    """
     type = String()

clearskies_cortex/models/cortex_entity_relationships.py

@@ -7,7 +7,27 @@ from clearskies_cortex.backends import CortexBackend
 
 
 class CortexCatalogEntityRelationship(Model):
-    """Model for entities."""
+    """
+    Model for Cortex entity relationships.
+
+    This model represents relationships between entities in the Cortex catalog.
+    Relationships define connections between entities such as dependencies,
+    ownership, or custom relationship types.
+
+    The model connects to the Cortex API endpoint
+    `catalog/:tag/relationships/:relationship_type_tag/destinations` to fetch
+    relationship destination entities.
+
+    ```python
+    from clearskies_cortex.models import CortexCatalogEntityRelationship
+
+    # Fetch relationship destinations for an entity
+    relationships = CortexCatalogEntityRelationship()
+    destinations = relationships.where("tag=my-service").where("relationship_type_tag=depends-on")
+    for dest in destinations:
+        print(f"Depends on: {dest.name} ({dest.type})")
+    ```
+    """
 
     id_column_name: str = "tag"
 
@@ -18,8 +38,27 @@ class CortexCatalogEntityRelationship(Model):
         """Return the slug of the api endpoint for this model."""
         return "catalog/:tag/relationships/:relationship_type_tag/destinations"
 
+    """
+    The unique identifier for the relationship destination entity.
+    """
     id = String()
+
+    """
+    The tag identifier of the relationship destination entity.
+    """
     tag = String()
+
+    """
+    A description of the relationship destination entity.
+    """
     description = String()
+
+    """
+    The human-readable name of the relationship destination entity.
+    """
     name = String()
+
+    """
+    The type of the relationship destination entity (e.g., "service", "domain").
+    """
     type = String()

clearskies_cortex/models/cortex_model.py

@@ -4,6 +4,29 @@ from clearskies_cortex.backends import CortexBackend
 
 
 class CortexModel(Model):
-    """Base model for cortex."""
+    """
+    Base model for Cortex API integration.
+
+    This is the foundational model class for all Cortex-related models. It pre-configures
+    the CortexBackend for API communication with the Cortex platform.
+
+    Extend this class to create models that interact with the Cortex API:
+
+    ```python
+    from clearskies_cortex.models import CortexModel
+    from clearskies.columns import String, Json
+
+
+    class MyCustomCortexModel(CortexModel):
+        id_column_name = "my_id"
+
+        my_id = String()
+        data = Json()
+
+        @classmethod
+        def destination_name(cls):
+            return "my-endpoint"
+    ```
+    """
 
     backend = CortexBackend()