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

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:
@@ -88,3 +245,162 @@ class CortexCatalogEntity(Model):
     def parse_owners(self) -> dataclasses.EntityTeamOwner:
         """Parse the owners column into a dictionary."""
         return from_dict(dataclasses.EntityTeamOwner, data=self.owners)
+
+    def get_group_tags(self) -> list[str]:
+        """Get groups as simple tags.
+
+        Returns groups that don't have a key:value format.
+
+        Returns:
+            List of group names that are simple tags without key:value format.
+
+        Example:
+            >>> entity.groups = ["my-tag", "team:platform", "production"]
+            >>> entity.get_group_tags()
+            ["my-tag", "production"]
+        """
+        tags: list[str] = []
+        if self.groups:
+            for group in self.groups:
+                if ":" not in group:
+                    tags.append(group)
+        return tags
+
+    def get_group_value(self, key: str) -> str | None:
+        """Get the value for a specific group key.
+
+        Groups can be formatted as "key:value" pairs. This method extracts
+        the value for a given key.
+
+        Args:
+            key: The group key to look up.
+
+        Returns:
+            The value associated with the key, or None if not found.
+
+        Example:
+            >>> entity.groups = ["team:platform", "env:production"]
+            >>> entity.get_group_value("team")
+            "platform"
+        """
+        if self.groups:
+            for group in self.groups:
+                if group.startswith(f"{key}:"):
+                    return group.split(":", 1)[1]
+        return None
+
+    def get_git_repository_url(self) -> str | None:
+        """Get the Git repository URL.
+
+        Returns:
+            The repository URL, or None if not configured.
+
+        Example:
+            >>> entity.git = {"repository": "https://github.com/org/repo"}
+            >>> entity.get_git_repository_url()
+            "https://github.com/org/repo"
+        """
+        if not self.git:
+            return None
+        return self.git.get("repository") or self.git.get("repositoryUrl")
+
+    def get_git_provider(self) -> str | None:
+        """Get the Git provider name.
+
+        Returns:
+            The provider name (e.g., "github", "gitlab", "bitbucket", "azure-devops"),
+            or None if not configured.
+
+        Example:
+            >>> entity.git = {"provider": "github", "repository": "..."}
+            >>> entity.get_git_provider()
+            "github"
+        """
+        if not self.git:
+            return None
+        return self.git.get("provider")
+
+    def get_git_project_id(self) -> str | None:
+        """Extract the project/repository identifier from the Git configuration.
+
+        Cortex supports multiple SCM providers (GitHub, GitLab, Bitbucket, Azure DevOps).
+        This method extracts the project identifier in a provider-agnostic way.
+
+        For GitLab, this returns the numeric project ID if available in the URL.
+        For GitHub/Bitbucket, this returns the "owner/repo" format.
+        For Azure DevOps, this returns the project/repo path.
+
+        Returns:
+            The project identifier as a string, or None if not found.
+
+        Example:
+            >>> entity.git = {"repository": "https://github.com/org/repo"}
+            >>> entity.get_git_project_id()
+            "org/repo"
+
+            >>> entity.git = {"repository": "https://gitlab.com/projects/12345"}
+            >>> entity.get_git_project_id()
+            "12345"
+        """
+        if not self.git:
+            return None
+
+        repo_url = self.git.get("repository") or self.git.get("repositoryUrl") or ""
+
+        # GitLab numeric project ID format: https://gitlab.com/projects/12345
+        if "/projects/" in repo_url:
+            try:
+                project_id = repo_url.split("/projects/")[1].split("/")[0]
+                return project_id
+            except IndexError:
+                pass
+
+        # Standard URL format: https://provider.com/owner/repo or https://provider.com/owner/repo.git
+        # Works for GitHub, GitLab (path format), Bitbucket
+        for prefix in ["github.com/", "gitlab.com/", "bitbucket.org/"]:
+            if prefix in repo_url:
+                try:
+                    path = repo_url.split(prefix)[1]
+                    # Remove .git suffix if present
+                    if path.endswith(".git"):
+                        path = path[:-4]
+                    # Remove trailing slashes
+                    path = path.rstrip("/")
+                    # Return owner/repo format
+                    parts = path.split("/")
+                    if len(parts) >= 2:
+                        return f"{parts[0]}/{parts[1]}"
+                except IndexError:
+                    pass
+
+        # Azure DevOps format: https://dev.azure.com/org/project/_git/repo
+        if "dev.azure.com/" in repo_url:
+            try:
+                path = repo_url.split("dev.azure.com/")[1]
+                parts = path.split("/")
+                if len(parts) >= 4 and parts[2] == "_git":
+                    return f"{parts[0]}/{parts[1]}/{parts[3]}"
+            except IndexError:
+                pass
+
+        return None
+
+    @property
+    def is_cloud_resource(self) -> bool:
+        """Check if entity represents a cloud resource.
+
+        Cortex supports pulling in resources from AWS, Azure, and Google Cloud.
+        This property checks if the entity type indicates a cloud resource.
+
+        Returns:
+            True if the entity type indicates a cloud resource.
+
+        Example:
+            >>> entity.type = "AWS::Lambda::Function"
+            >>> entity.is_cloud_resource
+            True
+        """
+        if not self.type:
+            return False
+        cloud_prefixes = ("AWS::", "Azure::", "Google::")
+        return self.type.startswith(cloud_prefixes)

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