deev 0.0.1__py3-none-any.whl

deev/_ImmutableMixin.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: © 2025 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import Any
+
+
+class _ImmutableMixin:
+    """Mixin that adds a ``freeze`` operation."""
+    __frozen__: bool = False
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if getattr(self, '__frozen__', False):
+            raise AttributeError(f'Cannot modify frozen instance: {name}')
+        # Call ``super()`` so the next class in the MRO (e.g. BaseModel) can run
+        super().__setattr__(name, value)
+
+    def __delattr__(self, name: str) -> None:
+        if getattr(self, '__frozen__', False):
+            raise AttributeError(f'Cannot delete attribute from frozen instance: {name}')
+        super().__delattr__(name)
+
+    def __freeze__(self) -> Any:
+        """Mark the instance as immutable."""
+        object.__setattr__(self, '__frozen__', True)
+        return self
+
+
+__all__ = ['_ImmutableMixin']

deev/_MigrationData.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .entities import entity, field
+
+
+@entity(table_name='_migrationdata')
+class _MigrationData:
+    """Internal entity representation of ``_migrationdata`` tables used by ``deev``."""
+    id: int = field(
+        autoincrement=True,
+        primary_key=True
+    )
+    migration: str = field(
+        max=260,
+        sqltype='VARCVHAR(260)'
+    )
+
+
+__all__ = ['_MigrationData']

deev/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .common.ConnectionString import ConnectionString
+from .common.DbError import DbError
+from .entities import (
+    entity,
+    field
+)
+from .utils import connect
+from . import common, entities, mysql, translation, utils, validation
+
+
+__version__ = '0.0.1'
+__commit__ = 'cb1b8ad'
+__all__ = [
+    '__version__', '__commit__',
+    'ConnectionString',
+    'DbError',
+    'common',
+    'connect',
+    'db_migrate',
+    'entities',
+    'entity',
+    'field',
+    'mysql',
+    'translation',
+    'utils',
+    'validation'
+]

deev/common/ConnectionString.py

@@ -0,0 +1,108 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ConnectionString:
+    """
+    A type-safe "Connection String" representation that can parse/build constituent parts.
+    """
+
+    __server: Optional[str]
+    __database: Optional[str]
+    __user: Optional[str]
+    __password: Optional[str]
+    __provider: Optional[str]
+
+    def __init__(
+        self,
+        connection_str: Optional[str] = None
+    ):
+        self.__server = None
+        self.__database = None
+        self.__user = None
+        self.__password = None
+        self.__provider = None
+        if connection_str is not None:
+            self.parse(connection_str)
+
+    def __str__(self) -> str:
+        parts = []
+        if self.server is not None:
+            parts.append(f'Server={self.server}')
+        if self.database is not None:
+            parts.append(f'Database={self.database}')
+        if self.user is not None:
+            parts.append(f'UID={self.user}')
+        if self.password is not None:
+            parts.append(f'PWD={self.password}')
+        if self.provider is not None:
+            parts.append(f'Provider={self.provider}')
+        return ';'.join(parts)
+
+    @property
+    def server(self) -> Optional[str]:
+        return self.__server
+
+    @server.setter
+    def server(self, value: Optional[str]):
+        self.__server = value
+
+    @property
+    def database(self) -> Optional[str]:
+        return self.__database
+
+    @database.setter
+    def database(self, value: Optional[str]):
+        self.__database = value
+
+    @property
+    def user(self) -> Optional[str]:
+        return self.__user
+
+    @user.setter
+    def user(self, value: Optional[str]):
+        self.__user = value
+
+    @property
+    def password(self) -> Optional[str]:
+        return self.__password
+
+    @password.setter
+    def password(self, value: Optional[str]):
+        self.__password = value
+
+    @property
+    def provider(self) -> Optional[str]:
+        return self.__provider
+
+    @provider.setter
+    def provider(self, value: Optional[str]):
+        self.__provider = value
+
+    def parse(self, connectionstring: Optional[str]) -> ConnectionString:
+        parts = (
+            []
+            if connectionstring is None
+            else connectionstring.split(';')
+        )
+        for part in parts:
+            key, value = part.split('=')
+            match key.lower():
+                case 'server':
+                    self.server = value
+                case 'database':
+                    self.database = value
+                case 'uid' | 'user' | 'user id' | 'username':
+                    self.user = value
+                case 'pwd' | 'password' | 'pass':
+                    self.password = value
+                case 'provider':
+                    self.provider = value
+        return self
+
+
+__all__ = ['ConnectionString']

deev/common/DbConnection.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Literal, Optional, Protocol, runtime_checkable
+
+from .DbCursor import DbCursor
+
+
+@runtime_checkable
+class DbConnection(Protocol):
+    """DB-API 2.0 Connection proto."""
+
+    def cursor(self, *args: Any, **kwargs: Any) -> DbCursor:
+        ...
+
+    def commit(self) -> None:
+        ...
+
+    def rollback(self) -> None:
+        ...
+
+    def close(self) -> None:
+        ...
+
+    def __enter__(self) -> DbConnection:
+        ...
+
+    def __exit__(self, exc_type: Optional[type[BaseException]], exc: Optional[BaseException], tb: Optional[TracebackType], /) -> Literal[False]:
+        ...
+
+    @classmethod
+    def __subclasshook__(cls, subclass: type) -> bool | None:   # type: ignore[override]
+        # if db api providers can't be bothered to follow the
+        # spec anyone else can't be bothered to enforce it.
+        required = {
+            name
+            for name in dir(cls)
+            if not name.startswith('_')
+        }
+        for name in required:
+            if name not in subclass.__dict__:
+                return False  # pragma: no cover
+        return True
+
+
+__all__ = ['DbConnection']

deev/common/DbContext.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import TypeAlias
+
+from .DbConnection import DbConnection
+from .DbTransactionContext import DbTransactionContext
+
+DbContext: TypeAlias = DbConnection | DbTransactionContext
+
+
+__all__ = ['DbContext']

deev/common/DbCursor.py

@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Iterable,
+    Optional,
+    Sequence,
+    Protocol,
+    runtime_checkable
+)
+
+from .DbParams import DbParams
+
+
+@runtime_checkable
+class DbCursor(Protocol):
+    """DB-API 2.0 Cursor proto."""
+
+    @property
+    def description(self) -> Sequence[tuple[Any, ...]]:
+        ...
+    
+    @property
+    def rowcount(self) -> int:
+        ...
+
+    def execute(self, operation: str, params: Optional[DbParams] = ...) -> None:
+        ...
+
+    def executemany(self, operation: str, seq_of_params: Sequence[DbParams]) -> None:
+        ...
+
+    def fetchone(self) -> tuple[Any, ...] | None:
+        ...
+
+    def fetchmany(self, size: int = ...) -> list[tuple[Any, ...]]:
+        ...
+
+    def fetchall(self) -> list[tuple[Any, ...]]:
+        ...
+
+    def close(self) -> None:
+        ...
+
+    def __iter__(self) -> Iterable[tuple[Any, ...]]:
+        ...
+
+    @classmethod
+    def __subclasshook__(cls, subclass: type) -> bool | None:   # type: ignore[override]
+        # if db api providers can't be bothered to follow the
+        # spec anyone else can't be bothered to enforce it.
+        required = {
+            name
+            for name in dir(cls)
+            if not name.startswith('_')
+        }
+        for name in required:
+            if name not in subclass.__dict__:
+                return False  # pragma: no cover
+        return True
+
+
+__all__ = ['DbCursor']

deev/common/DbError.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import final
+
+
+@final
+class DbError(Exception):
+    """Exception raised when a DB operation fails."""
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(reason)
+
+    def __repr__(self) -> str:
+        return (f'{self.__class__.__name__}(reason={self.reason!r})')
+
+    def __str__(self) -> str:
+        return self.__repr__()

deev/common/DbMigrator.py

@@ -0,0 +1,132 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import glob
+import importlib
+import importlib.util
+import logging
+import os
+from pathlib import Path
+from types import ModuleType
+from typing import Optional
+
+from .._MigrationData import _MigrationData
+from .ConnectionString import ConnectionString
+from .DbError import DbError
+from .DbTableAdapter import DbTableAdapter
+
+
+class DbMigrator:
+    """
+    Performs database changes for a set of migration scripts.
+
+    Migration scripts can be scanned from a path, or an explicit set of script paths may be provided.
+    """
+
+    __connectionstring: ConnectionString
+    __logger: logging.Logger
+
+    def __init__(self, connectionstring: ConnectionString):
+        self.__logger = logging.getLogger(__name__)
+        self.__connectionstring = connectionstring
+
+    def __get_or_create_migrations_table(self) -> DbTableAdapter:
+        from ..utils import get_table_adapter
+        table_adapter = get_table_adapter(_MigrationData, self.__connectionstring)
+        table_adapter.create_table()
+        return table_adapter
+
+    def __load_migration(self, path: str) -> ModuleType:
+        """Load a Python file as a module given its absolute file path."""
+        module_name = os.path.splitext(os.path.basename(path))[0]
+        spec = importlib.util.spec_from_file_location(module_name, path)
+        if spec is None or spec.loader is None:  # pragma: no cover
+            raise ImportError(f'Cannot create spec for {path}')
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)  # type: ignore[arg-type]
+        return module
+
+    def apply(self, migrations_path: Path | str, stop_at: Optional[str] = None) -> None:
+        from ..utils import create_database, get_transaction_context
+        create_database(self.__connectionstring)
+        if isinstance(migrations_path, str):
+            migrations_path = Path(migrations_path)
+        if not os.path.exists(migrations_path):
+            self.__logger.warn(f'Migrations path does not exist: {migrations_path}')
+            return
+        available_migrations = sorted(glob.glob(os.path.join(migrations_path, '*.py')))
+        if len(available_migrations) == 0:
+            self.__logger.warn(f'Migrations path does not contain migrations: {migrations_path}')
+            return
+        migrations_table = self.__get_or_create_migrations_table()
+        applied_migrations = dict[str, int]({
+            e.migration: e.id
+            for e in migrations_table.query(orderby='migration')
+        })
+        skipped_migration_count = 0
+        applied_migration_count = 0
+        for migration_filepath in available_migrations:
+            migration_name = os.path.splitext(os.path.basename(migration_filepath))[0]
+            if migration_name not in applied_migrations:
+                self.__logger.info(f'..apply migration "{migration_name}"')
+                migration_module = self.__load_migration(migration_filepath)
+                migration_func = getattr(migration_module, 'apply', None)
+                if migration_func is not None:
+                    with get_transaction_context(self.__connectionstring) as db_transaction:
+                        migration_func(db_transaction)
+                    migrations_table.create(_MigrationData(migration=migration_name))  # type: ignore[call-arg]
+                    migrations_table.commit()
+                    applied_migration_count += 1
+                else:
+                    raise DbError(f'Invalid migration "{migration_name}", missing `apply(...)` call.')
+            else:
+                self.__logger.info(f'..skipped migration "{migration_name}" (already applied.)')
+                skipped_migration_count += 1
+            if stop_at is not None and migration_name == stop_at:
+                self.__logger.info(f'..stopping at "{migration_name}", as instructed.')
+                break
+        self.__logger.info(f'Migrations applied {applied_migration_count}, skipped {skipped_migration_count}, available {len(available_migrations)}.')
+
+    def undo(self, migrations_path: Path | str, stop_at: Optional[str] = None) -> None:
+        from ..utils import create_database, get_transaction_context
+        create_database(self.__connectionstring)
+        if isinstance(migrations_path, str):
+            migrations_path = Path(migrations_path)
+        if not os.path.exists(migrations_path):
+            self.__logger.warn(f'Migrations path does not exist: {migrations_path}')
+            return
+        available_migrations = sorted(glob.glob(os.path.join(migrations_path, '*.py')), reverse=True)
+        if len(available_migrations) == 0:
+            self.__logger.warn(f'Migrations path does not contain migrations: {migrations_path}')
+            return
+        migrations_table = self.__get_or_create_migrations_table()
+        applied_migrations = dict[str, int]({
+            e.migration: e.id
+            for e in migrations_table.query(orderby='migration DESC')
+        })
+        skipped_migration_count = 0
+        applied_migration_count = 0
+        for migration_filepath in available_migrations:
+            migration_name = os.path.splitext(os.path.basename(migration_filepath))[0]
+            if migration_name in applied_migrations:
+                self.__logger.info(f'..undo migration "{migration_name}"')
+                migration_module = self.__load_migration(migration_filepath)
+                migration_func = getattr(migration_module, 'undo', None)
+                if migration_func is not None:
+                    with get_transaction_context(self.__connectionstring) as db_transaction:
+                        migration_func(db_transaction)
+                    migrations_table.delete(id=applied_migrations.get(migration_name, 0))
+                    migrations_table.commit()
+                    applied_migration_count += 1
+                else:
+                    raise DbError(f'Invalid migration "{migration_name}", missing `undo(...)` call.')
+            else:
+                self.__logger.info(f'..skipped migration "{migration_name}" (not applied.)')
+                skipped_migration_count += 1
+            if stop_at is not None and migration_name == stop_at:
+                self.__logger.info(f'..stopping at "{migration_name}", as instructed.')
+                break
+        self.__logger.info(f'Migrations undone {applied_migration_count}, skipped {skipped_migration_count}, available {len(available_migrations)}.')
+
+
+__all__ = ['DbMigrator']

deev/common/DbParams.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import Any, TypeAlias
+
+DbParams: TypeAlias = tuple[Any, ...] | list[Any] | dict[str, Any]
+
+
+__all__ = ['DbParams']

deev/common/DbTableAdapter.py

@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Generator,
+    Optional,
+    Protocol,
+    TypeVar,
+    runtime_checkable
+)
+
+from .DbParams import DbParams
+
+TEntity = TypeVar('TEntity')
+
+
+@runtime_checkable
+class DbTableAdapter(Protocol[TEntity]):
+
+    def create_table(self) -> None:
+        """Utility method for creating the target table."""
+        ...
+
+    def commit(self) -> None:
+        ...
+
+    def rollback(self) -> None:
+        ...
+
+    def create(self, entity: TEntity) -> dict[str, Any]:
+        """
+        Creates a new record in the specified table with the provided keyword arguments.
+
+        :param kwargs: A dictionary containing the column names and their corresponding values for the new record.
+        :type kwargs: dict[str, Any]
+        :return: The newly created record's ID if successful, otherwise None.
+        :rtype: Any
+        """
+        ...
+
+    def read(self, **kwargs: Any) -> TEntity | None:
+        """
+        Reads a record from the specified table with the primary key represented by `kwargs`.
+
+        :param kwargs: The primary key.
+        :type kwargs: dict[str, Any]
+        :return: A dictionary containing the column names and their corresponding values for the specified record, or None if no such record exists.
+        :rtype: dict[str, Any] | None
+        """
+        ...
+
+    def update(self, entity: TEntity) -> None:
+        ...
+
+    def delete(self, **kwargs: Any) -> None:
+        ...
+
+    def exists(self, **kwargs: Any) -> bool:
+        ...
+
+    def upsert(self, entity: TEntity) -> dict[str, Any]:
+        ...
+
+    def query(
+        self,
+        where: Optional[str] = ...,
+        params: Optional[DbParams] = ...,
+        orderby: Optional[str] = ...,
+        limit: Optional[int] = ...
+    ) -> Generator[TEntity, None, None]:
+        ...
+
+
+__all__ = ['DbTableAdapter']

deev/common/DbTransactionContext.py

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import (
+    Any,
+    Generator,
+    Optional,
+    Protocol,
+    runtime_checkable
+)
+
+from .DbConnection import DbConnection
+from .DbCursor import DbCursor
+from .DbParams import DbParams
+
+
+@runtime_checkable
+class DbTransactionContext(Protocol):
+
+    def __init__(self, connection: DbConnection) -> None:
+        ...
+
+    def __del__(self) -> None:
+        ...
+
+    def __enter__(self) -> DbTransactionContext:
+        ...
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]] = None,
+        exc_value: Optional[BaseException] = None,
+        traceback: Optional[TracebackType] = None
+    ) -> bool:
+        ...
+
+    @property
+    def connection(self) -> DbConnection:
+        ...
+
+    def cursor(self) -> DbCursor:
+        ...
+
+    def commit(self) -> None:
+        ...
+
+    def execute(self, sql: str, params: Optional[DbParams] = ...) -> DbCursor:
+        ...
+
+    def execute_script(self, sql: str) -> None:
+        ...
+
+    def execute_nonquery(self, sql: str, params: Optional[DbParams] = ...) -> None:
+        ...
+
+    def execute_reader(self, sql: str, params: Optional[DbParams] = ...) -> Generator[tuple[Any, ...], None, None]:
+        ...
+
+    def execute_scalar(self, sql: str, params: Optional[DbParams] = ...) -> Any:
+        ...
+
+    def rollback(self) -> None:
+        ...
+
+    @classmethod
+    def __subclasshook__(cls, subclass: type) -> bool | None:   # type: ignore[override]
+        # if db api providers can't be bothered to follow the
+        # spec anyone else can't be bothered to enforce it.
+        required = {
+            name
+            for name in dir(cls)
+            if not name.startswith('_')
+        }
+        for name in required:
+            if name not in subclass.__dict__:
+                return False  # pragma: no cover
+        return True
+
+
+__all__ = ['DbTransactionContext']

deev/common/DbTypeMapper.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DbTypeMapper(Protocol):
+
+    def get_sqltype(self, field_name: str) -> str:
+        """
+        Get the SQL type (string) needed to represent an entity field in the underlying table.
+
+        :param field_spec: The "Entity Field Spec".
+        :return: The SQL type string.
+        """
+        ...

deev/common/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: © 2023 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .ConnectionString import ConnectionString
+from .DbConnection import DbConnection
+from .DbCursor import DbCursor
+from .DbContext import DbContext
+from .DbError import DbError
+from .DbMigrator import DbMigrator
+from .DbParams import DbParams
+from .DbTableAdapter import DbTableAdapter
+from .DbTransactionContext import DbTransactionContext
+from .DbTypeMapper import DbTypeMapper
+
+
+__all__ = [
+    'ConnectionString',
+    'DbConnection',
+    'DbCursor',
+    'DbContext',
+    'DbError',
+    'DbMigrator',
+    'DbParams',
+    'DbTableAdapter',
+    'DbTransactionContext',
+    'DbTypeMapper'
+]