clear-skies 1.22.10__py3-none-any.whl → 2.0.23__py3-none-any.whl

clearskies/contexts/wsgi_ref.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import datetime
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Callable
+from wsgiref.simple_server import make_server
+
+from clearskies.contexts.context import Context
+from clearskies.input_outputs import Wsgi as WsgiInputOutput
+
+if TYPE_CHECKING:
+    from clearskies.di import AdditionalConfig
+    from clearskies.endpoint import Endpoint
+    from clearskies.endpoint_group import EndpointGroup
+
+
+class WsgiRef(Context):
+    """
+    Use a built in WSGI server (for development purposes only).
+
+    This context will launch a built-in HTTP server for you, so you can run applications locally
+    without having to install extra dependencies.  Note that this server is not intended for production
+    usage, so this is best used for simple tests/demonstration purposes.  Unlike the WSGI context, where
+    you define the application handler and invoke the context from inside of it (passing along the
+    environment and start_response variables), in this case you simply directly invoke the context to
+    launch the server.  The default port is 8080:
+
+    ```
+    #!/usr/bin/env python
+    import clearskies
+
+
+    def hello_world(name):
+        return f"Hello {name}!"
+
+
+    wsgi = clearskies.contexts.WsgiRef(
+        clearskies.endpoints.Callable(
+            hello_world,
+            url="/hello/:name",
+        )
+    )
+    wsgi()
+    ```
+
+    And to invoke it:
+
+    ```
+    curl 'http://localhost:8080/hello/Friend'
+    ```
+    """
+
+    port: int = 8080
+
+    def __init__(
+        self,
+        application: Callable | Endpoint | EndpointGroup,
+        port: int = 8080,
+        classes: type | list[type] = [],
+        modules: ModuleType | list[ModuleType] = [],
+        bindings: dict[str, Any] = {},
+        additional_configs: AdditionalConfig | list[AdditionalConfig] = [],
+        class_overrides: dict[type, type] = {},
+        overrides: dict[str, type] = {},
+        now: datetime.datetime | None = None,
+        utcnow: datetime.datetime | None = None,
+    ):
+        super().__init__(
+            application,
+            classes=classes,
+            modules=modules,
+            bindings=bindings,
+            additional_configs=additional_configs,
+            class_overrides=class_overrides,
+            overrides=overrides,
+            now=now,
+            utcnow=utcnow,
+        )
+        self.port = port
+
+    def __call__(self):  # type: ignore
+        with make_server("", self.port, self.handler) as httpd:
+            print(f"Starting WSGI server on port {self.port}.  This is NOT intended for production usage.")
+            httpd.serve_forever()
+
+    def handler(self, environment, start_response):
+        return self.execute_application(WsgiInputOutput(environment, start_response))

clearskies/cursors/__init__.py

@@ -0,0 +1,7 @@
+from clearskies.cursors.cursor import Cursor
+from clearskies.cursors.mysql import Mysql
+from clearskies.cursors.postgresql import Postgresql
+from clearskies.cursors.sqlite import Sqlite
+from clearskies.cursors import from_environment
+
+__all__ = ["Cursor", "Mysql", "Postgresql", "Sqlite", "from_environment"]

clearskies/cursors/cursor.py

@@ -0,0 +1,166 @@
+import logging
+from abc import ABC
+from types import ModuleType
+from typing import Protocol
+
+import clearskies.configs
+from clearskies import configurable, decorators
+from clearskies.di import InjectableProperties
+
+
+class DBAPICursor(Protocol):
+    """
+    A minimal protocol for a DB-API 2.0 cursor.
+
+    This uses structural subtyping. Any object (like a real cursor
+    or a mock) will match this type as long as it has the
+    required attributes, even if it doesn't explicitly inherit
+    from DBAPICursor.
+    """
+
+    def execute(self, sql: str, parameters: tuple | list):
+        """Execute a SQL statement with parameters."""
+        ...
+
+
+class Cursor(ABC, configurable.Configurable, InjectableProperties):
+    """
+    Abstract base class for database cursor implementations.
+
+    Provides a common interface for database operations across different
+    database backends. Handles connection management, query execution,
+    and SQL formatting with configurable escape characters and placeholders.
+
+    Attributes
+    ----------
+        database: Name of the database to connect to.
+        autocommit: Whether to automatically commit transactions.
+        port_forwarding: Optional port forwarding configuration.
+        connect_timeout: Connection timeout in seconds.
+        table_escape_character: Character used to escape table names.
+        column_escape_character: Character used to escape column names.
+        value_placeholder: Placeholder character for parameter binding.
+    """
+
+    database = clearskies.configs.String(default="example")
+    autocommit = clearskies.configs.Boolean(default=True)
+    port_forwarding = clearskies.configs.Any(default=None)
+    connect_timeout = clearskies.configs.Integer(default=2)
+
+    table_escape_character = "`"
+    column_escape_character = "`"
+    value_placeholder = "%s"
+    _cursor: DBAPICursor
+    _factory: ModuleType
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        database="example",
+        autocommit=True,
+        port_forwarding=None,
+        connect_timeout=2,
+    ):
+        pass
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Return the logger for this cursor."""
+        return logging.getLogger(self.__class__.__name__)
+
+    @property
+    def factory(self) -> ModuleType:
+        """Return the factory for the cursor."""
+        return self._factory
+
+    def build_connection_kwargs(self) -> dict:
+        """Return the connection kwargs for the cursor."""
+        return {
+            "database": self.database,
+            "autocommit": self.autocommit,
+            "connect_timeout": self.connect_timeout,
+        }
+
+    @property
+    def cursor(self) -> DBAPICursor:
+        """Get or create a database cursor instance."""
+        if not hasattr(self, "_cursor"):
+            try:
+                if self.port_forwarding:
+                    self.port_forwarding_context()
+            except KeyError:
+                pass
+
+            self._cursor = self.factory.connect(
+                **self.build_connection_kwargs(),
+            ).cursor()
+
+        return self._cursor
+
+    def __call__(self, *args: configurable.Any, **kwds: configurable.Any) -> configurable.Any:
+        return self.cursor
+
+    def __iter__(self):
+        """Allow direct iteration over the cursor config."""
+        return iter(self())
+
+    def __next__(self):
+        """Allow direct next() calls on the cursor config."""
+        return next(self())
+
+    def port_forwarding_context(self):
+        """Context manager for port forwarding (if applicable)."""
+        raise NotImplementedError("Port forwarding not implemented for this cursor.")
+
+    def column_equals_with_placeholder(self, column_name: str) -> str:
+        """
+        Generate SQL for a column equality check with placeholder.
+
+        Args:
+            column_name: Name of the column to check.
+
+        Returns
+        -------
+            SQL string in format: `column`=%s
+        """
+        return f"{self.column_escape_character}{column_name}{self.column_escape_character}={self.value_placeholder}"
+
+    def as_sql_with_placeholders(self, table: str, column: str, operator: str, number_values: int = 1) -> str | None:
+        """
+        Generate SQL condition with placeholders.
+
+        Args:
+            table: Table name.
+            column: Column name.
+            operator: SQL operator (e.g., '=', '>', '<').
+            number_values: Number of value placeholders needed.
+
+        Returns
+        -------
+            SQL string if number_values is 1, None otherwise.
+        """
+        if number_values == 1:
+            return f"{table}.{column} {operator} {self.value_placeholder}"
+        return None
+
+    def execute(self, sql: str, parameters: tuple | list = ()):
+        """
+        Execute a SQL statement with parameters.
+
+        Args:
+            sql: SQL statement to execute.
+            parameters: Parameters for the SQL statement.
+
+        Returns
+        -------
+            Result of cursor.execute().
+        """
+        try:
+            return self.cursor.execute(sql, parameters)
+        except Exception as e:
+            self.logger.exception(f"Error executing SQL: {sql} with parameters: {parameters}")
+            raise
+
+    @property
+    def lastrowid(self):
+        return getattr(self.cursor, "lastrowid", None)

clearskies/cursors/from_environment/__init__.py

@@ -0,0 +1,5 @@
+from clearskies.cursors.from_environment.mysql import MySql
+from clearskies.cursors.from_environment.postgresql import Postgresql
+from clearskies.cursors.from_environment.sqlite import Sqlite
+
+__all__ = ["MySql", "Postgresql", "Sqlite"]

clearskies/cursors/from_environment/mysql.py

@@ -0,0 +1,51 @@
+import clearskies.configs
+from clearskies import decorators
+from clearskies.cursors.mysql import Mysql as MysqlBase
+from clearskies.di import inject
+
+
+class MySql(MysqlBase):
+    hostname_environment_key = clearskies.configs.String(default="DATABASE_HOST")
+    username_environment_key = clearskies.configs.String(default="DATABASE_USERNAME")
+    password_environment_key = clearskies.configs.String(default="DATABASE_PASSWORD")
+    database_environment_key = clearskies.configs.String(default="DATABASE_NAME")
+
+    port_environment_key = clearskies.configs.String(default="DATABASE_PORT")
+    cert_path_environment_key = clearskies.configs.String(default="DATABASE_CERT_PATH")
+    autocommit_environment_key = clearskies.configs.String(default="DATABASE_AUTOCOMMIT")
+    connect_timeout_environment_key = clearskies.configs.String(default="DATABASE_CONNECT_TIMEOUT")
+
+    environment = inject.Environment()
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        hostname_environment_key="DATABASE_HOST",
+        username_environment_key="DATABASE_USERNAME",
+        password_environment_key="DATABASE_PASSWORD",
+        database_environment_key="DATABASE_NAME",
+        port_environment_key="DATABASE_PORT",
+        cert_path_environment_key="DATABASE_CERT_PATH",
+        autocommit_environment_key="DATABASE_AUTOCOMMIT",
+        connect_timeout_environment_key="DATABASE_CONNECT_TIMEOUT",
+        port_forwarding=None,
+    ):
+        pass
+
+    def build_connection_kwargs(self) -> dict:
+        connection_kwargs = {
+            "user": self.environment.get(self.username_environment_key),
+            "password": self.environment.get(self.password_environment_key),
+            "host": self.environment.get(self.hostname_environment_key),
+            "database": self.environment.get(self.database_environment_key),
+            "port": self.environment.get(self.port_environment_key, silent=True),
+            "ssl_ca": self.environment.get(self.cert_path_environment_key, silent=True),
+            "autocommit": self.environment.get(self.autocommit_environment_key, silent=True),
+            "connect_timeout": self.environment.get(self.connect_timeout_environment_key, silent=True),
+        }
+
+        for kwarg in ["autocommit", "connect_timeout", "port", "ssl_ca"]:
+            if not connection_kwargs[kwarg]:
+                del connection_kwargs[kwarg]
+
+        return {**super().build_connection_kwargs(), **connection_kwargs}

clearskies/cursors/from_environment/postgresql.py

@@ -0,0 +1,49 @@
+import clearskies.configs
+from clearskies import decorators
+from clearskies.cursors.postgresql import Postgresql as PostgresqlBase
+from clearskies.di import inject
+
+
+class Postgresql(PostgresqlBase):
+    hostname_environment_key = clearskies.configs.String(default="DATABASE_HOST")
+    username_environment_key = clearskies.configs.String(default="DATABASE_USERNAME")
+    password_environment_key = clearskies.configs.String(default="DATABASE_PASSWORD")
+    database_environment_key = clearskies.configs.String(default="DATABASE_NAME")
+
+    port_environment_key = clearskies.configs.String(default="DATABASE_PORT")
+    cert_path_environment_key = clearskies.configs.String(default="DATABASE_CERT_PATH")
+    autocommit_environment_key = clearskies.configs.String(default="DATABASE_AUTOCOMMIT")
+    connect_timeout_environment_key = clearskies.configs.String(default="DATABASE_CONNECT_TIMEOUT")
+
+    environment = inject.Environment()
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        hostname_environment_key="DATABASE_HOST",
+        username_environment_key="DATABASE_USERNAME",
+        password_environment_key="DATABASE_PASSWORD",
+        database_environment_key="DATABASE_NAME",
+        port_environment_key="DATABASE_PORT",
+        cert_path_environment_key="DATABASE_CERT_PATH",
+        autocommit_environment_key="DATABASE_AUTOCOMMIT",
+        port_forwarding=None,
+    ):
+        pass
+
+    def build_connection_kwargs(self) -> dict:
+        connection_kwargs = {
+            "user": self.environment.get(self.username_environment_key),
+            "password": self.environment.get(self.password_environment_key),
+            "host": self.environment.get(self.hostname_environment_key),
+            "database": self.environment.get(self.database_environment_key),
+            "port": self.environment.get(self.port_environment_key, silent=True),
+            "sslcert": self.environment.get(self.cert_path_environment_key, silent=True),
+            "connect_timeout": self.environment.get(self.connect_timeout_environment_key, silent=True),
+        }
+
+        for kwarg in ["autocommit", "connect_timeout", "port", "sslcert"]:
+            if not connection_kwargs[kwarg]:
+                del connection_kwargs[kwarg]
+
+        return {**super().build_connection_kwargs(), **connection_kwargs}

clearskies/cursors/from_environment/sqlite.py

@@ -0,0 +1,35 @@
+import clearskies.configs
+from clearskies import decorators
+from clearskies.cursors.sqlite import Sqlite as SqliteBase
+from clearskies.di import inject
+
+
+class Sqlite(SqliteBase):
+    database_environment_key = clearskies.configs.String(default="DATABASE_NAME")
+    autocommit_environment_key = clearskies.configs.String(default="DATABASE_AUTOCOMMIT")
+    connect_timeout_environment_key = clearskies.configs.String(default="DATABASE_CONNECT_TIMEOUT")
+
+    environment = inject.Environment()
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        database_environment_key="DATABASE_NAME",
+        autocommit_environment_key="DATABASE_AUTOCOMMIT",
+        connect_timeout_environment_key="DATABASE_CONNECT_TIMEOUT",
+    ):
+        pass
+
+    def build_connection_kwargs(self) -> dict:
+        connection_kwargs = {
+            "database": self.environment.get(self.database_environment_key),
+            "autocommit": self.environment.get(self.autocommit_environment_key, silent=True),
+            "connect_timeout": self.environment.get(self.connect_timeout_environment_key, silent=True),
+        }
+
+        for kwarg in ["autocommit", "connect_timeout"]:
+            if not connection_kwargs[kwarg]:
+                del connection_kwargs[kwarg]
+            del connection_kwargs["connect_timeout"]
+
+        return {**super().build_connection_kwargs(), **connection_kwargs}

clearskies/cursors/mysql.py

@@ -0,0 +1,61 @@
+from types import ModuleType
+
+import clearskies.configs
+from clearskies import decorators
+from clearskies.cursors.cursor import Cursor
+
+
+class Mysql(Cursor):
+    hostname = clearskies.configs.String(default="localhost")
+    username = clearskies.configs.String(default="root")
+    password = clearskies.configs.String(default="")
+    port = clearskies.configs.Integer(default=None)
+    default_port = clearskies.configs.Integer(default=3306)
+    cert_path = clearskies.configs.String(default=None)
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        hostname="localhost",
+        username="root",
+        password="",
+        database="example",
+        autocommit=True,
+        connect_timeout=2,
+        port=None,
+        cert_path=None,
+        port_forwarding=None,
+    ):
+        pass
+
+    @property
+    def factory(self) -> ModuleType:
+        """Return the factory for the cursor."""
+        if not hasattr(self, "_factory"):
+            try:
+                import pymysql
+
+                self._factory = pymysql
+            except ImportError:
+                raise ValueError(
+                    "The cursor requires pymysql to be installed.  This is an optional dependency of clearskies, so to include it do a `pip install 'clear-skies[mysql]'`"
+                )
+        return self._factory
+
+    def build_connection_kwargs(self) -> dict:
+        connection_kwargs = {
+            "user": self.username,
+            "password": self.password,
+            "host": self.hostname,
+            "port": self.port,
+            "ssl_ca": self.cert_path,
+            "autocommit": self.autocommit,
+            "cursorclass": self.factory.cursors.DictCursor,
+        }
+        if not connection_kwargs["ssl_ca"]:
+            del connection_kwargs["ssl_ca"]
+
+        if not connection_kwargs["port"]:
+            connection_kwargs["port"] = self.default_port
+
+        return {**super().build_connection_kwargs(), **connection_kwargs}

clearskies/cursors/postgresql.py

@@ -0,0 +1,61 @@
+from types import ModuleType
+
+import clearskies.configs
+from clearskies import decorators
+from clearskies.cursors.cursor import Cursor
+
+
+class Postgresql(Cursor):
+    hostname = clearskies.configs.String(default="localhost")
+    username = clearskies.configs.String(default="root")
+    password = clearskies.configs.String(default="")
+    port = clearskies.configs.Integer(default=None)
+    default_port = clearskies.configs.Integer(default=5432)
+    cert_path = clearskies.configs.String(default=None)
+
+    @decorators.parameters_to_properties
+    def __init__(
+        self,
+        hostname="localhost",
+        username="root",
+        password="",
+        database="example",
+        autocommit=True,
+        connect_timeout=2,
+        port=None,
+        cert_path=None,
+        port_forwarding=None,
+    ):
+        pass
+
+    @property
+    def factory(self) -> ModuleType:
+        """Return the factory for the cursor."""
+        if not hasattr(self, "_factory"):
+            try:
+                import psycopg
+
+                self._factory = psycopg
+            except ImportError:
+                raise ValueError(
+                    "The cursor requires psycopg to be installed.  This is an optional dependency of clearskies, so to include it do a `pip install 'clear-skies[pgsql]'`"
+                )
+        return self._factory
+
+    def build_connection_kwargs(self) -> dict:
+        connection_kwargs = {
+            "user": self.username,
+            "password": self.password,
+            "host": self.hostname,
+            "port": self.port,
+            "ssl_ca": self.cert_path,
+            "sslcert": self.cert_path,
+            "row_factory": self.factory.rows.dict_row,
+        }
+        if not connection_kwargs["sslcert"]:
+            del connection_kwargs["sslcert"]
+
+        if not connection_kwargs["port"]:
+            connection_kwargs["port"] = self.default_port
+
+        return {**super().build_connection_kwargs(), **connection_kwargs}

clearskies/cursors/sqlite.py

@@ -0,0 +1,62 @@
+from sqlite3 import Cursor as SQLiteCursor
+from types import ModuleType
+
+import clearskies.configs
+from clearskies.cursors.cursor import Cursor
+from clearskies.di import inject
+
+
+class Sqlite(Cursor):
+    database = clearskies.configs.String(default="example.db")
+    connect_timeout = clearskies.configs.Float(default=2.0)  # type: ignore[assignment]
+    value_placeholder = "?"
+    sys = inject.ByName("sys")
+
+    def __init__(
+        self,
+        database="example.db",
+        autocommit=True,
+        connect_timeout=2.0,
+    ):
+        self.autocommit = autocommit
+        self.database = database
+        self.connect_timeout = connect_timeout
+
+    @property
+    def factory(self) -> ModuleType:
+        """Return the factory for the cursor."""
+        if not hasattr(self, "_factory"):
+            try:
+                import sqlite3
+
+                self._factory = sqlite3
+            except ImportError as e:
+                raise ValueError(  # noqa: TRY003
+                    "The cursor requires sqlite3 to be available. sqlite3 is included with the standard library for Python, "
+                    f"so this error likely indicates a misconfigured Python installation. Error: {e}"
+                ) from e
+        return self._factory
+
+    @property
+    def cursor(self) -> SQLiteCursor:
+        """Get or create a database cursor instance."""
+        if not hasattr(self, "_cursor"):
+
+            def dict_factory(cursor, row):
+                fields = [column[0] for column in cursor.description]
+                return dict(zip(fields, row))
+
+            connection = self.factory.connect(
+                database=self.database,
+                timeout=2.0,
+            )
+            connection.row_factory = dict_factory
+            if self.autocommit:
+                connection.isolation_level = None  # Enable autocommit for sqlite3
+            else:
+                if self.sys.version_info > (3, 12):  # noqa: UP036
+                    connection.autocommit = False
+                else:
+                    connection.isolation_level = "DEFERRED"  # Disable autocommit
+            self._cursor = connection.cursor()
+        return self._cursor  # type: ignore[return-value]

clearskies/decorators.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import inspect
+
+import wrapt
+
+
+@wrapt.decorator
+def parameters_to_properties(wrapped, instance, args, kwargs):
+    if not instance:
+        raise ValueError(
+            "The parameters_to_properties decorator only works for methods in classes, not plain functions"
+        )
+
+    if args:
+        wrapped_args = inspect.getfullargspec(wrapped)
+        for key, value in zip(wrapped_args.args[1:], args):
+            # if it's a dictionary or a list then copy it to avoid linking data
+            if isinstance(value, dict):
+                value = {**value}
+            if isinstance(value, list):
+                value = [*value]
+            setattr(instance, key, value)
+
+    for key, value in kwargs.items():
+        # if it's a dictionary or a list then copy it to avoid linking data
+        if isinstance(value, dict):
+            value = {**value}
+        if isinstance(value, list):
+            value = [*value]
+        setattr(instance, key, value)
+
+    wrapped(*args, **kwargs)

clearskies/decorators.pyi

@@ -0,0 +1,10 @@
+# decorators.pyi
+from typing import Any, Callable, TypeVar
+
+# A TypeVar is used to say "whatever kind of function comes in,
+# the same kind of function goes out."
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+# This is the type signature for your decorator.
+# It tells Pylance that it preserves the signature of the function it wraps.
+def parameters_to_properties(wrapped: _F) -> _F: ...

clearskies/di/__init__.py

@@ -1,11 +1,15 @@
-from .additional_config_auto_import import AdditionalConfigAutoImport
-from .di import DI
-from .standard_dependencies import StandardDependencies
-from .additional_config import AdditionalConfig
+import clearskies.di.inject as inject
+from clearskies.di.additional_config import AdditionalConfig
+from clearskies.di.additional_config_auto_import import AdditionalConfigAutoImport
+from clearskies.di.di import Di
+from clearskies.di.injectable import Injectable
+from clearskies.di.injectable_properties import InjectableProperties
 
 __all__ = [
-    "AdditionalConfigAutoImport",
-    "DI",
-    "StandardDependencies",
     "AdditionalConfig",
+    "AdditionalConfigAutoImport",
+    "Di",
+    "Injectable",
+    "InjectableProperties",
+    "inject",
 ]