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

clarity_api_sdk_python-0.2.10.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: clarity-api-sdk-python
+Version: 0.2.10
+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.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: brotli
+Requires-Dist: h2
+Requires-Dist: httpx_auth>=0.23.1
+Requires-Dist: httpx-retries>=0.4.5
+Requires-Dist: structlog
+Provides-Extra: brotli
+Requires-Dist: httpx[brotli]>=0.28.1; extra == "brotli"
+Provides-Extra: http2
+Requires-Dist: httpx[http2]>=0.28.1; extra == "http2"
+
+# Clarity API SDK for Python
+
+[![PyPI - Downloads](https://badge.fury.io/py/clarity-api-sdk-python.svg)](https://pypi.org/project/clarity-api-sdk-python/)
+[![Downloads](https://pepy.tech/badge/clarity-api-sdk-python)](ttps://test.pypi.org/project/clarity-api-sdk-python/)
+![python](https://img.shields.io/badge/python-3.11%2B-blue)
+
+A Python SDK for connecting to the CTI API server, with structured logging included.
+
+## Installation
+
+```bash
+pip install clarity-api-sdk-python
+```
+
+## Logging
+
+Logging support is built with [structlog](https://pypi.org/project/structlog/).
+
+Set the root logger by setting the environment variable `LOG_LEVEL`. Otherwise, the default root logging is set to `INFO`.
+
+```python
+"""Example"""
+
+import logging
+
+from cti.logger import initialize_logger, get_logger, ExternalLoggerConfig
+
+initialize_logger(
+    external_logger_configurations=[
+        ExternalLoggerConfig(name="urllib3"),
+        ExternalLoggerConfig(name="httpcore"),
+        ExternalLoggerConfig(name="httpx"),
+        ExternalLoggerConfig(name="httpx_auth"),
+        ExternalLoggerConfig(name="httpx_retries"),
+    ],
+    handlers=[logging.FileHandler("app.log")]
+)
+
+logger_a = get_logger("logger_a")
+logger_b = get_logger("logger_b", "WARNING")
+
+# root_logger = logging.getLogger()
+# root_logger.setLevel("DEBUG")
+
+logger_a.info("This is info message from logger_a")
+logger_a.critical("This is critical message from logger_a")
+
+# Dynamically change the log level of logger_a to WARNING
+print("\nChanging logger_a level to WARNING...\n")
+logging.getLogger("logger_a").setLevel(logging.WARNING)
+
+logger_a.info("This info message from logger_a should NOT be visible.")
+logger_a.warning("This is a new warning message from logger_a.")
+
+logger_b.info("This info message from logger_b should NOT be visible.")
+logger_b.warning("This is warning message from logger_b")
+```

clarity_api_sdk_python-0.2.10.dist-info/RECORD

@@ -0,0 +1,11 @@
+cti/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cti/main.py,sha256=EBTB9p_PONeC4rRqm8tknn58A5synrO4-SrFMIrATFQ,1034
+cti/api/__init__.py,sha256=HClrIT0WmCaPPRsejmXBOSS7R-OclE4g7qDgxQS_5hI,55
+cti/api/async_client.py,sha256=T-Rfcr70uYPzFCNanZloUQoJwuNCGFtDPf7HaTyycw8,4694
+cti/api/client.py,sha256=hhfxCpH8ymbArJFAhShPLhnvxf8clY-H8sMbfzIneos,4451
+cti/logger/__init__.py,sha256=o44tO0O_lUvpIN6w0B9-t61L5MKHmD14elaiIm6B6DA,102
+cti/logger/logger.py,sha256=9If0ckorKvJD807b41lR7fZJzT1JpGbu_hmsV1vC1YY,10777
+clarity_api_sdk_python-0.2.10.dist-info/METADATA,sha256=I253M2NSv7bPZ9wVHEfMSs1KtoluEZTLmk4FTmpanVk,2682
+clarity_api_sdk_python-0.2.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+clarity_api_sdk_python-0.2.10.dist-info/top_level.txt,sha256=q0eCD9KnKXWf_VImQ7xYkyYD7cvcG-4X-vm36HhdT_M,4
+clarity_api_sdk_python-0.2.10.dist-info/RECORD,,

clarity_api_sdk_python-0.2.10.dist-info/top_level.txt

@@ -0,0 +1 @@
+cti

cti/api/async_client.py

@@ -0,0 +1,127 @@
+"""Async client for clarity API"""
+
+import os
+import uuid
+
+from httpx import AsyncClient, HTTPStatusError, RequestError, Response, URL
+from httpx_auth import OAuth2ClientCredentials, OAuth2, TokenMemoryCache
+from httpx_retries import Retry, RetryTransport
+
+from cti.logger import get_logger
+
+logger = get_logger(__name__)
+OAuth2.token_cache = TokenMemoryCache()
+
+
+class ClarityApiAsyncClient(AsyncClient):
+    """Async 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.
+
+    The authorization token is cached and shared between each client instance to minimize
+    calls to the https://auth.sonarwiz.io/ keycloak server.
+    """
+
+    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"},
+        )
+
+    async def request(self, method: str, url: URL | str, **kwargs) -> Response:
+        """Make an async request to the Clarity API and handle exceptions. Using
+        this allows requests to be made concurrently and can provide significantly
+        improved performance. Use this to make multiple concurrent requests.
+
+        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 = await super().request(method, url, **kwargs)
+            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

{api → cti/api}/client.py

@@ -7,7 +7,7 @@ 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
+from cti.logger import get_logger
 
 logger = get_logger(__name__)
 OAuth2.token_cache = TokenMemoryCache()

{logger → cti/logger}/logger.py

@@ -3,6 +3,7 @@
 from collections import OrderedDict
 from dataclasses import dataclass
 import logging
+import os
 import socket
 import sys
 import urllib.error
@@ -32,16 +33,25 @@ class ExternalLoggerConfig:
         self.propagate = propagate
 
 
-def get_logger(name: str) -> logging.Logger:
+def get_logger(
+    name: str, level: int | str | None = None
+) -> structlog.stdlib.BoundLogger:
     """Creates a structlog logger with the specified name.
 
     Args:
         name (str): The logger name.
+        level (int | str | None, optional): The logging level for this logger.
+            If None, the root logger's level is used. Defaults to None.
 
     Returns:
-        logging.Logger: The structlog logger.
+        structlog.stdlib.BoundLogger: The structlog logger.
     """
-    return structlog.get_logger(name)
+    logger = structlog.get_logger(name)
+    if level:
+        # To set the level, we need to get the actual standard library logger instance.
+        stdlib_logger = logging.getLogger(name)
+        stdlib_logger.setLevel(level)
+    return logger
 
 
 def _flatten_extra_processor(_, __, event_dict):
@@ -166,8 +176,9 @@ def _secret_redaction_processor(_, __, event_dict):
 
 
 def initialize_logger(
-    initial_context: dict | None,
-    external_logger_configurations: list[ExternalLoggerConfig] | None,
+    initial_context: dict | None = None,
+    external_logger_configurations: list[ExternalLoggerConfig] | None = None,
+    handlers: list[logging.Handler] | None = None,
 ) -> None:
     """Configures logging for the application using structlog.
 
@@ -194,15 +205,24 @@ def initialize_logger(
             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
+        handlers (list[logging.Handler], optional): A list of handlers to send log records to.
     """
     # 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,
-    )
+    formatter = logging.Formatter("%(message)s")
+
+    # Create a handler for stdout
+    stdout_handler = logging.StreamHandler(sys.stdout)
+    stdout_handler.setFormatter(formatter)
+
+    # Get the root logger and add handlers
+    root_logger = logging.getLogger()
+    root_logger.addHandler(stdout_handler)
+    for handler in handlers or []:
+        handler.setFormatter(formatter)
+        root_logger.addHandler(handler)
+    root_logger.setLevel(_level())
 
     # configure external loggers
     if external_logger_configurations:
@@ -260,15 +280,13 @@ def initialize_logger(
         structlog.contextvars.bind_contextvars(**static_context)
 
 
-def _level():
+def _level() -> str:
     """Get the log level for the logger.
 
-    Set optional environment variable.
-
-        - MANUAL only logs ERROR
-        - PRODUCTION - turns off debug
+    The log level is determined by the `LOG_LEVEL` environment variable.
+    If the environment variable is not set, it defaults to "ERROR".
 
     Returns:
-        str: log level
+        str: The log level as a string (e.g., "DEBUG", "INFO", "ERROR").
     """
-    return "DEBUG"
+    return os.getenv("LOG_LEVEL", "INFO").upper()

cti/main.py

@@ -0,0 +1,33 @@
+"""Example"""
+
+import logging
+
+from cti.logger import initialize_logger, get_logger, ExternalLoggerConfig
+
+initialize_logger(
+    external_logger_configurations=[
+        ExternalLoggerConfig(name="urllib3"),
+        ExternalLoggerConfig(name="httpcore"),
+        ExternalLoggerConfig(name="httpx"),
+        ExternalLoggerConfig(name="httpx_auth"),
+        ExternalLoggerConfig(name="httpx_retries"),
+    ]
+)
+
+logger_a = get_logger("logger_a")
+logger_b = get_logger("logger_b", "WARNING")
+
+# root_logger = logging.getLogger()
+# root_logger.setLevel("DEBUG")
+
+logger_a.info("This is info message from logger_a")
+logger_a.critical("This is critical message from logger_a")
+
+# Dynamically change the log level of logger_a to WARNING
+print("\nChanging logger_a level to WARNING...\n")
+logging.getLogger("logger_a").setLevel(logging.WARNING)
+
+logger_a.info("This info message from logger_a should NOT be visible.")
+logger_a.warning("This is a new warning message from logger_a.")
+
+logger_b.warning("This is warning message from logger_b")

clarity_api_sdk_python-0.1.2.dist-info/METADATA

@@ -1,26 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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/top_level.txt

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