clear-skies 2.0.27__py3-none-any.whl

clearskies/backends/secrets_backend.py

@@ -0,0 +1,100 @@
+from typing import TYPE_CHECKING, Any, Callable
+
+from clearskies.autodoc.schema import Schema as AutoDocSchema
+from clearskies.backends.backend import Backend
+from clearskies.di import inject
+from clearskies.query import Condition, Query
+
+if TYPE_CHECKING:
+    from clearskies import Model
+
+
+class SecretsBackend(Backend):
+    """
+    Fetch and store data from a secret provider.
+
+    ## Installing Dependencies
+
+    Clearskies uses Akeyless by default to manage the secrets.
+    This is not installed by default, but is a named extra that you can install when needed via:
+
+    ```bash
+    pip install clear-skies[secrets]
+    ```
+    """
+
+    """The secrets instance."""
+    secrets = inject.Secrets()
+
+    can_count: bool = False
+
+    def __init__(self):
+        pass
+
+    def check_query(self, query: Query) -> None:
+        if not query.conditions:
+            raise KeyError(f"You must search by an id when using the secrets backend.")
+
+    def update(self, id: str, data: dict[str, Any], model: Model) -> dict[str, Any]:  # type: ignore[override]
+        """Update the record with the given id with the information from the data dictionary."""
+        folder_path = self._make_folder_path(model, id)
+        for key, value in data.items():
+            if key == model.id_column_name:
+                continue
+            self.secrets.update(f"{folder_path}{key}", value)
+
+        # and now query again to fetch the updated record.
+        return self.records(Query(model.__class__, conditions=[Condition(f"{model.id_column_name}={id}")]))[0]
+
+    def create(self, data: dict[str, Any], model: Model) -> dict[str, Any]:
+        if not model.id_column_name in data:
+            raise ValueError(
+                f"You must provide '{model.id_column_name}' when creating a record with the secrets backend"
+            )
+        return self.update(data[model.id_column_name], data, model)
+
+    def delete(self, id: str, model: Model) -> bool:  # type: ignore[override]
+        """
+        Delete the record with the given id.
+
+        Note that this isn't implemented yet, and always returns True.
+        """
+        return True
+
+    def records(self, query: Query, next_page_data: dict[str, str | int] | None = None) -> list[dict[str, Any]]:
+        """Return a list of records that match the given query configuration."""
+        self.check_query(query)
+        for condition in query.conditions:
+            if condition.operator != "=":
+                raise ValueError(
+                    f"I'm not very smart and only know how to search with the equals operator, but I received a condition of {condition.parsed}.  If you need to support this, you'll have to extend the ApiBackend and overwrite the build_records_request method."
+                )
+            if condition.column_name == query.model_class.id_column_name:
+                id = condition.values[0]
+                break
+        if id is None:
+            raise ValueError(f"You must search by '{query.model_class.id_column_name}' when using the secrets backend")
+
+        folder_path = self._make_folder_path(query.model_class, id)
+        data = {query.model_class.id_column_name: id}
+        for path in self.secrets.list_secrets(folder_path):
+            data[path[len(folder_path) :]] = self.secrets.get(path)
+        return [data]
+
+    def _make_folder_path(self, model, id):
+        return model.table_name().rstrip("/") + "/" + id.strip("/") + "/"
+
+    def validate_pagination_data(self, data: dict[str, Any], case_mapping: Callable[[str], str]) -> str:
+        return ""
+
+    def allowed_pagination_keys(self) -> list[str]:
+        return []
+
+    def documentation_pagination_next_page_response(self, case_mapping: Callable) -> list[Any]:
+        return []
+
+    def documentation_pagination_parameters(self, case_mapping: Callable) -> list[tuple[AutoDocSchema, str]]:
+        return []
+
+    def documentation_pagination_next_page_example(self, case_mapping: Callable) -> dict[str, Any]:
+        return {}

clearskies/clients/__init__.py

@@ -0,0 +1,5 @@
+from clearskies.clients.graphql_client import GraphqlClient
+
+__all__ = [
+    "GraphqlClient",
+]

clearskies/clients/graphql_client.py

@@ -0,0 +1,182 @@
+from typing import TYPE_CHECKING, Any
+
+from clearskies import configs, configurable, decorators, loggable
+from clearskies.authentication import Authentication
+from clearskies.di import InjectableProperties, inject
+
+if TYPE_CHECKING:
+    from gql import Client
+
+
+class GraphqlClient(configurable.Configurable, loggable.Loggable, InjectableProperties):
+    """
+    A simple GraphQL client wrapper using gql library.
+
+    This client handles the connection to GraphQL APIs and provides methods to execute
+    queries and mutations. It supports authentication, custom headers, and configurable timeouts.
+
+    Example usage:
+    ```python
+    import clearskies
+
+    client = clearskies.clients.GraphqlClient(
+        endpoint="https://api.example.com/graphql",
+        authentication=clearskies.authentication.SecretBearer(
+            environment_key="API_TOKEN", header_prefix="Bearer "
+        ),
+        headers={"X-Custom-Header": "value"},
+        timeout=30,
+    )
+
+    # Execute a query
+    result = client.execute('''
+        query {
+            projects {
+                id
+                name
+            }
+        }
+    ''')
+    ```
+    """
+
+    """
+    The GraphQL API endpoint URL.
+
+    The full URL to your GraphQL API endpoint. Example:
+
+    ```python
+    client = clearskies.clients.GraphqlClient(
+        endpoint="https://api.example.com/graphql"
+    )
+    ```
+
+    Defaults to "http://localhost:4000/graphql" for local development.
+    """
+    endpoint = configs.String(default="http://localhost:4000/graphql")
+
+    """
+    Authentication mechanism for the GraphQL API.
+
+    An instance of a clearskies authentication class that provides credentials for the API.
+    The authentication object's headers() method will be called to add authorization headers
+    to requests. Example:
+
+    ```python
+    client = clearskies.clients.GraphqlClient(
+        endpoint="https://api.example.com/graphql",
+        authentication=clearskies.authentication.SecretBearer(
+            environment_key="GRAPHQL_TOKEN",
+            header_prefix="Bearer "
+        )
+    )
+    ```
+
+    Set to None for public APIs that don't require authentication.
+    """
+    authentication = configs.Authentication(default=None)
+
+    """
+    Additional HTTP headers to include in requests.
+
+    A dictionary of header names and values to send with every request. These headers
+    are merged with any headers provided by the authentication mechanism. Example:
+
+    ```python
+    client = clearskies.clients.GraphqlClient(
+        endpoint="https://api.example.com/graphql",
+        headers={
+            "X-API-Version": "v1",
+            "X-Client-Name": "my-app"
+        }
+    )
+    ```
+
+    Defaults to an empty dictionary.
+    """
+    headers = configs.AnyDict(default={})
+
+    """
+    Request timeout in seconds.
+
+    Maximum time to wait for a response from the GraphQL API before raising a timeout error.
+    Applies to both connection and read timeouts. Example:
+
+    ```python
+    client = clearskies.clients.GraphqlClient(
+        endpoint="https://api.example.com/graphql",
+        timeout=60  # Wait up to 60 seconds for responses
+    )
+    ```
+
+    Defaults to 10 seconds.
+    """
+    timeout = configs.Integer(default=10)
+
+    di = inject.Di()
+
+    _client: Any
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        endpoint="http://localhost:4000/graphql",
+        headers={},
+        authentication: Authentication | None = None,
+        timeout=10,
+    ):
+        self.finalize_and_validate_configuration()
+
+    @property
+    def client(self) -> "Client":
+        """
+        Get the underlying gql Client instance.
+
+        Lazily creates and caches a gql Client with the configured endpoint, authentication,
+        headers, and timeout. The client handles the HTTP transport layer for GraphQL requests.
+
+        This property is primarily used internally by the execute() method, but can be accessed
+        directly if you need lower-level control over GraphQL operations.
+
+        Returns:
+            Client: A gql Client instance configured with this GraphqlClient's settings.
+        """
+        from gql import Client
+        from gql.transport.requests import RequestsHTTPTransport
+
+        if hasattr(self, "_client"):
+            return self._client  # type: ignore
+
+        if self.authentication:
+            # Inject dependencies if the authentication object supports it
+            if hasattr(self.authentication, "injectable_properties"):
+                self.authentication.injectable_properties(self.di)  # type: ignore[attr-defined]
+        transport = RequestsHTTPTransport(
+            url=self.endpoint,
+            headers=self.headers,
+            auth=self.authentication,
+            timeout=self.timeout,
+        )
+        self._client = Client(transport=transport, fetch_schema_from_transport=False)
+        return self._client
+
+    def execute(self, query: str, variable_values: dict[str, Any] | None = None) -> dict[str, Any]:
+        """
+        Execute a GraphQL query or mutation.
+
+        Args:
+            query (str): The GraphQL query or mutation string.
+            variable_values (dict, optional): Variables for the query/mutation. Defaults to None
+        Returns:
+            dict: The response data from the GraphQL API.
+        """
+        from gql import gql
+
+        client = self.client
+        prepared_query = gql(query)
+        self.logger.debug(
+            f"Executing GraphQL query: {prepared_query} on endpoint: {self.endpoint} with variables: {variable_values}"
+        )
+        result = client.execute(prepared_query, variable_values=variable_values)
+        self.logger.debug(f"GraphQL response: {result}")
+        return result