clear-skies 2.0.27__py3-none-any.whl

clearskies/cursors/cursor.py

@@ -0,0 +1,161 @@
+from abc import ABC
+from types import ModuleType
+from typing import Protocol
+
+import clearskies.configs
+from clearskies import configurable, decorators, loggable
+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, loggable.Loggable):
+    """
+    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 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:
+            self.logger.debug(f"Executing SQL: {sql} with parameters: {parameters}")
+            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

@@ -0,0 +1,15 @@
+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__ = [
+    "AdditionalConfig",
+    "AdditionalConfigAutoImport",
+    "Di",
+    "Injectable",
+    "InjectableProperties",
+    "inject",
+]

clearskies/di/additional_config.py

@@ -0,0 +1,130 @@
+from typing import Any
+
+
+class AdditionalConfig:
+    """
+    This class allows you to add additional names to the Di container.
+
+    The idea here is that you extend the AdditonalConfig class and attach as many
+    `provide_*` methods to the class as you want.  This allows the developer to declare a number of
+    dependencies and easily attach them to the Di container in one go - helpful for modules that
+    come with a variety of things that they want to make available to developers.
+
+    When an AdditionalConfig instance is attached to the Di container, the container (in essence) finds all the
+    `provide_*` methods in the class and registers the corresponding name in the Di container - e.g. if you have
+    a method called `provide_widget` then when a class or function requests an argument named `widget`
+    from the Di container, the container will call the `provide_widget` method on your instance and pass along
+    the return value to the thing that requested a `widget`. The `provide_*` methods can declare their own
+    dependencies, including ones declared in the same `AdditionalConfig` class (they just can't be circular, of course).
+
+    As always, keep in mind the priority of dependency injection names (see the `clearskies.di.Di` class for full
+    details).  If two `AdditionalConfig` objects declare a `provide_*` method with the same name, then the Di
+    system will call the method for the `AdditionalConfig` object that was added last.
+
+    By default the Di system caches all values.  If you have a dependency that shouldn't be cached, you can
+    extend the `can_cache` method and have it return True/False depending on the name and context.
+
+    Example:
+    ```python
+    from clearskies.di import Di, AdditionalConfig
+
+
+    class MyAdditionalConfig(AdditionalConfig):
+        def provide_inner_dependency(self):
+            return 5
+
+        def provide_important_thing(self, inner_dependency):
+            return inner_dependency * 10
+
+
+    class AnotherAdditionalConfig(AdditionalConfig):
+        def provide_inner_dependency(self):
+            return 10
+
+
+    di = Di(additional_configs=[MyAdditionalConfig(), AnotherAdditionalConfig()])
+    # Equivalent:
+    # di = Di()
+    # di.add_addtional_configs([MyAdditionalConfig(), AnotherAdditionalConfig()])
+
+
+    def my_function(important_thing):
+        print(important_thing)  # prints 100
+    ```
+    """
+
+    def can_cache(self, name: str, di, context: str) -> bool:
+        """
+        Cache control.
+
+        The Di container caches values by default, but this method allows you to override that.
+        After fetching an object from the AdditionalConfig class, the Di container will call this method to
+        determine whether or not to cache  it.  `name` will be the name of the Di value that was built, and
+        context will be the name of the class that the value was built for.  You then return True/False.
+
+        Note that this controls whether or not to cache the returned value, not whether or not to check the
+        cache for a value.  The importance is that, once there is a value in the cache, that will be reused
+        for all future requests for that name.  Example:
+
+        ```python
+        from clearskies.di import Di, AdditionalConfig
+        import secrets
+
+
+        class MyAdditionalConfig(AdditionalConfig):
+            def provide_random_number_not_cached(self):
+                return secrets.randbelow(100)
+
+            def provide_random_number_cached(self):
+                return secrets.randbelow(100)
+
+            def can_cache(self, name, context=None):
+                return name == "random_number_not_cached"
+
+
+        di = Di(additional_configs=MyAdditionalConfig())
+
+
+        def my_function(random_number_cached, random_number_not_cached):
+            print(random_number_cached)
+            print(random_number_not_cached)
+
+
+        di.call_function(my_function)
+        di.call_function(my_function)
+        di.call_function(my_function)
+        di.call_function(my_function)
+
+        # This prints something like:
+        # 58
+        # 12
+        # 58
+        # 14
+        # 58
+        # 41
+        ```
+        """
+        return True
+
+    def can_build(self, name):
+        return hasattr(self, f"provide_{name}")
+
+    def build(self, name, di, context=None):
+        if not hasattr(self, f"provide_{name}"):
+            raise KeyError(
+                f"AdditionalConfig class '{self.__class__.__name__}' cannot build requested dependency, '{name}'"
+            )
+
+        return di.call_function(getattr(self, f"provide_{name}"))
+
+    def can_build_class(self, class_to_check: type) -> bool:
+        """Return True/False to denote if this AdditionalConfig class can provide a given class."""
+        return False
+
+    def build_class(self, class_to_provide: type, argument_name: str, di, context: str = "") -> Any:
+        """Return the desired instance of a given class."""
+        pass
+
+    def can_cache_class(self, class_to_build: type, di, context: str) -> bool:
+        """Control whether or not the Di container caches the instance after building a class."""
+        return False