clarity-api-sdk-python 0.1.2__py3-none-any.whl

api/__init__.py

@@ -0,0 +1,3 @@
+"""API client"""
+
+from .client import ClarityApiClient

api/client.py

@@ -0,0 +1,124 @@
+"""client for clarity API"""
+
+import os
+import uuid
+
+from httpx import Client, HTTPStatusError, RequestError, Response, URL
+from httpx_auth import OAuth2ClientCredentials, OAuth2, TokenMemoryCache
+from httpx_retries import Retry, RetryTransport
+
+from logger import get_logger
+
+logger = get_logger(__name__)
+OAuth2.token_cache = TokenMemoryCache()
+
+
+class ClarityApiClient(Client):
+    """Client for Clarity API configured with OAuth2 authentication, retry mechanism
+    and other defaults to connect to the clarity server.
+
+    Reuse this client instance for multiple requests for faster performance.
+    """
+
+    def __init__(self):
+
+        # credentials for Clarity API
+        cti_credentials = OAuth2ClientCredentials(
+            token_url=(
+                f'{os.environ.get("KEYCLOAK_SERVER_URL", "missing KEYCLOAK_SERVER_URL")}/realms/'
+                f'{os.environ.get("KEYCLOAK_REALM", "missing KEYCLOAK_REALM")}'
+                "/protocol/openid-connect/token"
+            ),
+            client_id=os.environ.get(
+                "KEYCLOAK_CLIENT_ID", "missing KEYCLOAK_CLIENT_ID"
+            ),
+            client_secret=os.environ.get(
+                "KEYCLOAK_CLIENT_SECRET", "missing KEYCLOAK_CLIENT_SECRET"
+            ),
+        )
+
+        # retry mechanism for API requests
+        retry = Retry(total=12, backoff_factor=0.5)
+        transport = RetryTransport(retry=retry)
+
+        super().__init__(
+            base_url=os.environ.get("CLARITY_API_URL", "missing Clarity_API_URL"),
+            auth=cti_credentials,
+            timeout=60,
+            transport=transport,
+            http2=True,
+            headers={"Accept": "application/json"},
+        )
+
+    def request(self, method: str, url: URL | str, **kwargs) -> Response:
+        """Make a request to the Clarity API and handle exceptions.
+
+        The exceptions are caught and logged, and then re-raised.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE, etc.)
+            url: relative URL for the request, eg: "/api/v1/projects/12345"
+            kwargs: additional keyword arguments to be passed to the request
+
+        Returns:
+            httpx.Response: Response from the API
+
+        Raises:
+            RequestError: If there was an issue with the request
+            HTTPStatusError: If the response status code is not in the 2xx range
+            Exception: For any other uncaught exception
+        """
+        try:
+            request_id = str(uuid.uuid4())
+            if "headers" not in kwargs or kwargs["headers"] is None:
+                kwargs["headers"] = {}
+            # append x-request-id header to the kwargs "headers"
+            kwargs["headers"].update({"x-request-id": request_id})
+            logger.info(
+                "request",
+                extra={"url": url, "request_id": request_id},
+            )
+            # make the actual request and return the response
+            response = super().request(method, url, **kwargs)
+            # raise an exception if the response status is not in the 2xx range
+            response.raise_for_status()
+            logger.info(
+                "response",
+                extra={
+                    "request_id": request_id,
+                    "response": {"status_code": response.status_code},
+                },
+            )
+            return response
+        except HTTPStatusError as e:
+            logger.error(
+                "http",
+                extra={
+                    "request": {
+                        "method": e.request.method,
+                        "url": str(e.request.url),
+                        "headers": dict(e.request.headers),
+                    },
+                    "error": {
+                        "message": str(e.response.content),
+                        "status_code": e.response.status_code,
+                        "headers": dict(e.response.headers),
+                    },
+                },
+            )
+            raise e
+        except RequestError as e:
+            logger.error(
+                "request",
+                extra={
+                    "request": {
+                        "method": e.request.method,
+                        "url": str(e.request.url),
+                        "headers": dict(e.request.headers),
+                    },
+                    "error": {
+                        "message": str(e),
+                    },
+                },
+            )
+            raise e

clarity_api_sdk_python-0.1.2.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: clarity-api-sdk-python
+Version: 0.1.2
+Summary: A Python SDK to connect to the CTI Clarity API server.
+Author-email: "Chesapeake Technology Inc." <support@chesapeaketech.com>
+Project-URL: Homepage, https://github.com/chesapeake-tech/clarity-api-sdk-python
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx_auth>=0.23.1
+Requires-Dist: httpx-retries>=0.4.5
+Requires-Dist: httpx[brotli]>=0.28.1
+Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: structlog
+
+# Clarity API SDK for Python
+
+A Python SDK for connecting to the CTI API server, with structured logging included.
+
+## Installation
+
+```bash
+pip install clarity-api-sdk-python
+```

clarity_api_sdk_python-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+api/__init__.py,sha256=HClrIT0WmCaPPRsejmXBOSS7R-OclE4g7qDgxQS_5hI,55
+api/client.py,sha256=ACXwN8MYWcj-1LNk2TJXD015ePNX0OQWC7qbJnc35Dc,4447
+logger/__init__.py,sha256=o44tO0O_lUvpIN6w0B9-t61L5MKHmD14elaiIm6B6DA,102
+logger/logger.py,sha256=p6VVXp8tcnaIM2hVMOWACS-Bs1kPCbS4dD9pBSQJ0a0,9720
+clarity_api_sdk_python-0.1.2.dist-info/METADATA,sha256=gH9wBa9rkKmW8KQiBVTlsRZjldPbYEFwKe82WygTtIw,842
+clarity_api_sdk_python-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+clarity_api_sdk_python-0.1.2.dist-info/top_level.txt,sha256=pfn0Jb5h-xZeUmY1lAn7svgMuIf_2siz75uRuyChn5s,11
+clarity_api_sdk_python-0.1.2.dist-info/RECORD,,

clarity_api_sdk_python-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clarity_api_sdk_python-0.1.2.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+api
+logger

logger/__init__.py

@@ -0,0 +1,3 @@
+"""import modules"""
+
+from .logger import get_logger, initialize_logger, ExternalLoggerConfig  # noqa

logger/logger.py

@@ -0,0 +1,274 @@
+"""Structured Logger configuration."""
+
+from collections import OrderedDict
+from dataclasses import dataclass
+import logging
+import socket
+import sys
+import urllib.error
+import urllib.request
+
+import structlog
+
+
+@dataclass
+class ExternalLoggerConfig:
+    """External logger configuration parameters."""
+
+    def __init__(
+        self, name: str, level: int = logging.CRITICAL, disabled=False, propagate=False
+    ):
+        """Construct an external logger configuration to configure external logging.
+
+        Args:
+            name: The name of the external logger
+            level: The level to set for the logger
+            disabled: Whether or not to disable logging
+            propagate: Whether or not to propagate the log messages to the parent logger
+        """
+        self.name = name
+        self.level = level
+        self.disabled = disabled
+        self.propagate = propagate
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Creates a structlog logger with the specified name.
+
+    Args:
+        name (str): The logger name.
+
+    Returns:
+        logging.Logger: The structlog logger.
+    """
+    return structlog.get_logger(name)
+
+
+def _flatten_extra_processor(_, __, event_dict):
+    """A structlog processor to flatten the 'extra' dictionary into the top level.
+
+    Args:
+        event_dict (structlog.typing.EventDict): The log event dictionary to be processed.
+
+    Returns:
+        structlog.typing.EventDict: The processed event dictionary with extra flattened.
+    """
+    if "extra" in event_dict:
+        extra_data = event_dict.pop("extra")
+        if isinstance(extra_data, dict):
+            # Merge extra data into the main event_dict
+            event_dict.update(extra_data)
+    return event_dict
+
+
+def _get_aws_metadata() -> dict:
+    """A structlog processor to add AWS instance metadata to the log entry.
+    This is an expensive call, so only call it when necessary.
+
+    This function attempts to retrieve the instance-id, instance-type, and
+    public-ipv4 from the AWS metadata service with a short timeout. If the
+    information cannot be retrieved, 'unknown' is used as a fallback value.
+
+    For more details, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html
+
+    Returns:
+        dict: A dictionary with AWS metadata.
+    """
+
+    def _get_metadata(key: str, timeout: int = 1) -> str:
+        """Helper to fetch a metadata key with a timeout."""
+        try:
+            # yes, a hard coded IPv4 is best practice
+            url = f"http://169.254.169.245/latest/meta-data/{key}"
+            with urllib.request.urlopen(url, timeout=timeout) as response:
+                return response.read().decode("utf-8")
+        except (urllib.error.URLError, socket.timeout):
+            return "unknown"
+
+    return {
+        "aws_instance_id": _get_metadata("instance-id"),
+        "aws_instance_type": _get_metadata("instance-type"),
+        "aws_public_ipv4": _get_metadata("public-ipv4"),
+    }
+
+
+def _order_event_dict(
+    _logger: structlog.typing.WrappedLogger,
+    _method_name: str,
+    event_dict: structlog.typing.EventDict,
+) -> structlog.typing.EventDict:
+    """A structlog processor to reorder the event dictionary.
+
+    This processor ensures that certain important keys ("timestamp", "job_id",
+    "level", "event") appear at the beginning of the log entry, making the
+    logs more readable and consistent. The specified keys are ordered first,
+    and any other keys in the event dictionary are appended afterwards in the
+    order they were originally.
+
+    Args:
+        event_dict (structlog.typing.EventDict): The log event dictionary to be reordered.
+
+    Returns:
+        collections.OrderedDict: The event dictionary with keys reordered.
+    """
+    key_order = ["timestamp", "jobId", "level", "event"]
+    # Use OrderedDict to preserve the order of the remaining keys.
+    ordered_event_dict = OrderedDict()
+    for key in key_order:
+        if key in event_dict:
+            ordered_event_dict[key] = event_dict.pop(key)
+
+    # Add the rest of the items, which will now be at the end.
+    ordered_event_dict.update(event_dict.items())
+
+    return ordered_event_dict
+
+
+def _secret_redaction_processor(_, __, event_dict):
+    """A structlog processor to redact sensitive information in log entries.
+
+    Args:
+        event_dict (structlog.typing.EventDict): The log event dictionary to be processed.
+
+    Returns:
+        structlog.typing.EventDict: The processed event dictionary.
+    """
+    sensitive_keys = ["password", "api_key", "token", "SecretString"]
+
+    def redact_dict(data):
+        """Recursively redact sensitive keys in nested dictionaries.
+
+        Args:
+            data (dict): The dictionary to redact sensitive keys.
+
+        Returns:
+            dict: The redacted dictionary.
+        """
+        if isinstance(data, dict):
+            for key, value in data.items():
+                if key in sensitive_keys:
+                    data[key] = "[REDACTED]"
+                elif isinstance(value, dict):
+                    redact_dict(value)
+        return data
+
+    # Redact top-level sensitive keys
+    for key in sensitive_keys:
+        if key in event_dict:
+            event_dict[key] = "[REDACTED]"
+
+    # Check for nested dictionaries and redact them
+    for key, value in event_dict.items():
+        if isinstance(value, dict):
+            redact_dict(value)
+
+    return event_dict
+
+
+def initialize_logger(
+    initial_context: dict | None,
+    external_logger_configurations: list[ExternalLoggerConfig] | None,
+) -> None:
+    """Configures logging for the application using structlog.
+
+    This function sets up `structlog` to produce structured JSON logs. It
+    configures a chain of processors to enrich log entries with contextual
+    information such as timestamps, host details, and log levels. The standard
+    Python `logging` module is configured to act as the sink, directing the
+    formatted JSON logs to standard output in JSONL format.
+
+    The processor chain includes:
+    - Merging context variables.
+    - Filtering by log level.
+    - Adding logger name and log level.
+    - `add_host_info`: Custom processor to add hostname and IP.
+    - `TimeStamper`: Adds an ISO formatted timestamp.
+    - `PositionalArgumentsFormatter`: Formats positional arguments into the message.
+    - Exception and stack info renderers.
+    - `UnicodeDecoder`: Decodes unicode characters.
+    - `order_event_dict`: Custom processor to ensure a consistent key order.
+    - `JSONRenderer`: Renders the final log entry as a JSON string.
+
+    Args:
+        initial_context (dict, optional): A dictionary of key-value pairs to
+            bind to the context at the start of the application. These values
+            will be included in every log message. Defaults to None.
+        external_logger_configurations (list[ExternalLoggerConfig], optional): A list of configuration
+    """
+    # Configure standard logging to be the sink for structlog.
+    # The format="%(message)s" is important because structlog will format the log record
+    # into a JSON string and pass it as the 'message'.
+    logging.basicConfig(
+        level=_level(),
+        format="%(message)s",
+        stream=sys.stdout,
+    )
+
+    # configure external loggers
+    if external_logger_configurations:
+        for config in external_logger_configurations:
+            logger = logging.getLogger(config.name)
+            logger.setLevel(config.level)
+            logger.disabled = config.disabled
+            logger.propagate = config.propagate
+
+    # Configure structlog to produce JSON logs.
+    structlog.configure(
+        processors=[
+            # Merge contextvars into the event dictionary.
+            structlog.contextvars.merge_contextvars,
+            # Filter logs by level.
+            structlog.stdlib.filter_by_level,
+            # Add logger name and log level to the event dict.
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            # Add a timestamp in ISO format.
+            structlog.processors.TimeStamper(fmt="iso"),
+            # Render positional arguments into the message.
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            # If the log record contains an exception, render it.
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            _flatten_extra_processor,
+            _secret_redaction_processor,
+            # Decode unicode characters.
+            structlog.processors.UnicodeDecoder(),
+            # partial sort of key values.
+            _order_event_dict,
+            # Render the final event dict as JSON.
+            structlog.processors.JSONRenderer(),
+        ],
+        # Use a standard library logger factory.
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        # Use a wrapper class to provide standard logging methods.
+        wrapper_class=structlog.stdlib.BoundLogger,
+        # Cache the logger on first use.
+        cache_logger_on_first_use=True,
+    )
+
+    # Gather static context information at startup.
+    static_context = {}
+    static_context.update(_get_aws_metadata())
+
+    # Merge with any context provided at startup.
+    if initial_context:
+        static_context.update(initial_context)
+
+    # Bind the initial context if it's provided.
+    # This context will be included in all logs.
+    if initial_context:
+        structlog.contextvars.bind_contextvars(**static_context)
+
+
+def _level():
+    """Get the log level for the logger.
+
+    Set optional environment variable.
+
+        - MANUAL only logs ERROR
+        - PRODUCTION - turns off debug
+
+    Returns:
+        str: log level
+    """
+    return "DEBUG"