deev 0.0.1__tar.gz

deev-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+© 2023 Shaun Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deev-0.0.1/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: deev
+Version: 0.0.1
+Summary: ..an entity framework for Python.
+Author-email: Shaun Wilson <mrshaunwilson@msn.com>
+License-Expression: MIT
+Keywords: DB,database,entity framework,mapper
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hanaro>=1.0.0
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: punit>=1.4.5; extra == "dev"
+Requires-Dist: py-conventional-semver>=1.0.5; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
+Dynamic: license-file
+
+
+[![deev on PyPI](https://img.shields.io/pypi/v/deev.svg)](https://pypi.org/project/deev/) [![deev on readthedocs](https://readthedocs.org/projects/deev/badge/?version=latest)](https://deev.readthedocs.io)
+
+**deev** (דיב) is an entity framework for Python.
+
+This README is only a high-level introduction to **deev**. For more detailed documentation, please view the official docs at [https://deev.readthedocs.io](https://deev.readthedocs.io).
+
+
+## Features
+
+* Entity-based; perform CRUD operations using Python objects instead of hand-crafting SQL.
+* Validation; Entities validate before they get persisted to a database, also validate entities on-demand.
+* Transaction Contexts; enter and exit transaction scopes with language-level context management, avoid mismanaged transaction states.
+* DB Migrations; use Python code to apply (and undo) schema changes, data translation, etc using `db-migrate` CLI tool for use from CI/CD pipelines.
+* PEP 249 compatible abstractions; no need to refactor code just to switch DBMS.
+* Syntax normalization; parameterize SQL using `%?` instead of provider-specific syntaxes.
+* Raw SQL Access; execute raw SQL as-needed, including provider/DBMS-specific functions (primarily intended for advanced `db-migrate` cases.)
+
+
+## Installation
+
+You can install `deev` from [PyPI](https://pypi.org/project/deev/) through usual means, such as `pip`:
+
+```bash
+    pip install deev
+```
+
+
+## Usage
+
+Let's have a look at the two popular use cases: using Python objects for CRUD operations, and using the `db-migrate` CLI tool to manage DB schema.
+
+### Entity CRUD
+
+```python
+    # imports
+    from deev import entity, field
+
+    # define a simple entity with an auto-increment PK, an int value column, and a list[str] column
+    @entity
+    class SimpleEntity:
+        id: int = field(autoincrement=True, primary_key=True)
+        column1: int
+        column2: list[str]
+
+    # create a database using familiar connection-string syntax
+    from deev.utils import create_database
+
+    connection_str = 'Server=./test_data/;Database=sqlite3/test.db;Provider=sqlite3'
+    create_database(connection_str)
+
+    # connect to your database, create a table for storage, and perform some CRUD operations
+    from deev import connect
+    from deev.sqlite import SqliteTableAdapter
+    with connect(connection_str) as db:
+        table = SqliteTableAdapter[SimpleEntity](db)
+        table.create_table()
+        # CREATE
+        entity_key = table.create(SimpleEntity(
+            column1=1,
+            column2=[3, 2, 1]
+        ))
+        # READ
+        entity = table.read(**entity_key)
+        assert entity.id is not None
+        assert entity.column1 == 1
+        assert entity.column2[0] == 3
+        assert entity.column2[1] == 2
+        assert entity.column2[2] == 1
+        # UPDATE
+        entity.column2[1] = 4
+        table.update(entity)
+        # DELETE
+        table.delete(**entity_key)
+
+        # alternatives: upsert + query
+        entity_key = table.upsert(SimpleEntity(
+            column1=2,
+            column2=[5]
+        ))
+        entity_key = table.upsert(SimpleEntity(
+            column1=2,
+            column2=[6]
+        ))
+        results = table.query(
+            where='column1 = %?',
+            orderby='column1 DESC',
+            limit=2,   
+            params=(2,)
+        )
+        count = 0
+        for result in results:
+            assert result.column2[0] in (5, 6)
+            count += 1
+        assert count == 2
+        # query kwargs are optional, for example this creates a generator for all table records:
+        results = table.query()
+```
+
+### CLI `db-migrate` Tool
+
+The `db-migrate` tool can be used to apply a migration script or undo a previously applied migration script.
+
+Basic syntax:
+
+```bash
+$ db-migrate -h
+usage: db-migrate [-h] [--verbose] <COMMAND> ...
+
+Utility for applying, undoing, or generating migrations.
+
+positional arguments:
+  <COMMAND>   Action to perform.
+    apply     Apply migrations.
+    undo      Undo migrations.
+
+options:
+  -h, --help  show this help message and exit
+  --verbose   Enable verbose logging.
+
+$ db-migrate apply -h
+usage: db-migrate apply [-h] [--stop-at name] path connectionstring
+
+positional arguments:
+  path              Directory containing migration scripts.
+  connectionstring  Database connection string.
+
+options:
+  -h, --help        show this help message and exit
+  --stop-at name    Stop processing at the named migration.
+```
+
+A migration script is a Python file which defines two functions `apply(...)` and `undo(...)`, each receiving a `DbTransactionContext` you can use to modify the database transactionally.  As an example let's assume we modified `SimpleEntity` with an additional attribute `column3` of type `datetime`:
+
+```python
+    @entity
+    class SimpleEntity:
+        id: int = field(autoincrement=True, primary_key=True)
+        column1: int
+        column2: list[str]
+        column3: Optional[datetime]] = field(nullable=True)
+```
+
+Since we already have a table for this entity, we want to modify the schema to support the new attribute:
+
+```python
+# 000_test01.py
+from deev.common import DbTransactionContext
+
+
+def apply(transaction: DbTransactionContext) -> None:
+    # alter the existing entity table
+    transaction.execute_nonquery('ALTER TABLE SimpleEntity ADD COLUMN column3 DATETIME')
+    transaction.commit()
+
+
+def undo(transaction: DbTransactionContext) -> None:
+    # undo the alteration applied by `apply(...)` above
+    transaction.execute_nonquery('ALTER TABLE SimpleEntity DROP COLUMN column3')
+    transaction.commit()
+```
+
+Finally, we can apply the change to our existing database:
+
+```bash
+# apply schema change
+db-migrate apply ./test_data/migrations 'Server=./test_data/;Database=sqlite3/test.db;Provider=sqlite3'
+```
+```
+..apply migration "000_test01"
+Migrations applied 1, skipped 0, available 1.
+```
+
+We can also undo the change after it has been applied:
+
+```bash
+# undo schema change
+db-migrate apply ./test_data/migrations 'Server=./test_data/;Database=sqlite3/test.db;Provider=sqlite3'
+```
+```
+..apply migration "000_test01"
+Migrations undone 1, skipped 0, available 1.
+```
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/deev/issues/new/choose).

deev-0.0.1/README.md

@@ -0,0 +1,187 @@
+
+[![deev on PyPI](https://img.shields.io/pypi/v/deev.svg)](https://pypi.org/project/deev/) [![deev on readthedocs](https://readthedocs.org/projects/deev/badge/?version=latest)](https://deev.readthedocs.io)
+
+**deev** (דיב) is an entity framework for Python.
+
+This README is only a high-level introduction to **deev**. For more detailed documentation, please view the official docs at [https://deev.readthedocs.io](https://deev.readthedocs.io).
+
+
+## Features
+
+* Entity-based; perform CRUD operations using Python objects instead of hand-crafting SQL.
+* Validation; Entities validate before they get persisted to a database, also validate entities on-demand.
+* Transaction Contexts; enter and exit transaction scopes with language-level context management, avoid mismanaged transaction states.
+* DB Migrations; use Python code to apply (and undo) schema changes, data translation, etc using `db-migrate` CLI tool for use from CI/CD pipelines.
+* PEP 249 compatible abstractions; no need to refactor code just to switch DBMS.
+* Syntax normalization; parameterize SQL using `%?` instead of provider-specific syntaxes.
+* Raw SQL Access; execute raw SQL as-needed, including provider/DBMS-specific functions (primarily intended for advanced `db-migrate` cases.)
+
+
+## Installation
+
+You can install `deev` from [PyPI](https://pypi.org/project/deev/) through usual means, such as `pip`:
+
+```bash
+    pip install deev
+```
+
+
+## Usage
+
+Let's have a look at the two popular use cases: using Python objects for CRUD operations, and using the `db-migrate` CLI tool to manage DB schema.
+
+### Entity CRUD
+
+```python
+    # imports
+    from deev import entity, field
+
+    # define a simple entity with an auto-increment PK, an int value column, and a list[str] column
+    @entity
+    class SimpleEntity:
+        id: int = field(autoincrement=True, primary_key=True)
+        column1: int
+        column2: list[str]
+
+    # create a database using familiar connection-string syntax
+    from deev.utils import create_database
+
+    connection_str = 'Server=./test_data/;Database=sqlite3/test.db;Provider=sqlite3'
+    create_database(connection_str)
+
+    # connect to your database, create a table for storage, and perform some CRUD operations
+    from deev import connect
+    from deev.sqlite import SqliteTableAdapter
+    with connect(connection_str) as db:
+        table = SqliteTableAdapter[SimpleEntity](db)
+        table.create_table()
+        # CREATE
+        entity_key = table.create(SimpleEntity(
+            column1=1,
+            column2=[3, 2, 1]
+        ))
+        # READ
+        entity = table.read(**entity_key)
+        assert entity.id is not None
+        assert entity.column1 == 1
+        assert entity.column2[0] == 3
+        assert entity.column2[1] == 2
+        assert entity.column2[2] == 1
+        # UPDATE
+        entity.column2[1] = 4
+        table.update(entity)
+        # DELETE
+        table.delete(**entity_key)
+
+        # alternatives: upsert + query
+        entity_key = table.upsert(SimpleEntity(
+            column1=2,
+            column2=[5]
+        ))
+        entity_key = table.upsert(SimpleEntity(
+            column1=2,
+            column2=[6]
+        ))
+        results = table.query(
+            where='column1 = %?',
+            orderby='column1 DESC',
+            limit=2,   
+            params=(2,)
+        )
+        count = 0
+        for result in results:
+            assert result.column2[0] in (5, 6)
+            count += 1
+        assert count == 2
+        # query kwargs are optional, for example this creates a generator for all table records:
+        results = table.query()
+```
+
+### CLI `db-migrate` Tool
+
+The `db-migrate` tool can be used to apply a migration script or undo a previously applied migration script.
+
+Basic syntax:
+
+```bash
+$ db-migrate -h
+usage: db-migrate [-h] [--verbose] <COMMAND> ...
+
+Utility for applying, undoing, or generating migrations.
+
+positional arguments:
+  <COMMAND>   Action to perform.
+    apply     Apply migrations.
+    undo      Undo migrations.
+
+options:
+  -h, --help  show this help message and exit
+  --verbose   Enable verbose logging.
+
+$ db-migrate apply -h
+usage: db-migrate apply [-h] [--stop-at name] path connectionstring
+
+positional arguments:
+  path              Directory containing migration scripts.
+  connectionstring  Database connection string.
+
+options:
+  -h, --help        show this help message and exit
+  --stop-at name    Stop processing at the named migration.
+```
+
+A migration script is a Python file which defines two functions `apply(...)` and `undo(...)`, each receiving a `DbTransactionContext` you can use to modify the database transactionally.  As an example let's assume we modified `SimpleEntity` with an additional attribute `column3` of type `datetime`:
+
+```python
+    @entity
+    class SimpleEntity:
+        id: int = field(autoincrement=True, primary_key=True)
+        column1: int
+        column2: list[str]
+        column3: Optional[datetime]] = field(nullable=True)
+```
+
+Since we already have a table for this entity, we want to modify the schema to support the new attribute:
+
+```python
+# 000_test01.py
+from deev.common import DbTransactionContext
+
+
+def apply(transaction: DbTransactionContext) -> None:
+    # alter the existing entity table
+    transaction.execute_nonquery('ALTER TABLE SimpleEntity ADD COLUMN column3 DATETIME')
+    transaction.commit()
+
+
+def undo(transaction: DbTransactionContext) -> None:
+    # undo the alteration applied by `apply(...)` above
+    transaction.execute_nonquery('ALTER TABLE SimpleEntity DROP COLUMN column3')
+    transaction.commit()
+```
+
+Finally, we can apply the change to our existing database:
+
+```bash
+# apply schema change
+db-migrate apply ./test_data/migrations 'Server=./test_data/;Database=sqlite3/test.db;Provider=sqlite3'
+```
+```
+..apply migration "000_test01"
+Migrations applied 1, skipped 0, available 1.
+```
+
+We can also undo the change after it has been applied:
+
+```bash
+# undo schema change
+db-migrate apply ./test_data/migrations 'Server=./test_data/;Database=sqlite3/test.db;Provider=sqlite3'
+```
+```
+..apply migration "000_test01"
+Migrations undone 1, skipped 0, available 1.
+```
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/deev/issues/new/choose).

deev-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "deev"
+version = "0.0.1"
+description = "..an entity framework for Python."
+keywords = ["DB", "database", "entity framework", "mapper"]
+authors = [
+    { name="Shaun Wilson", email="mrshaunwilson@msn.com" }
+]
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python"
+]
+requires-python = ">=3.11"
+dependencies = [
+    "hanaro (>=1.0.0)"
+]
+
+[project.optional-dependencies]
+dev = [
+    "coverage",
+    "mypy",
+    "punit (>=1.4.5)",
+    "py-conventional-semver (>=1.0.5)",
+    "twine"
+]
+mysql = [
+    "mysql-connector-python"
+]
+
+[project.scripts]
+db-migrate = "deev.db_migrate:main"
+
+[tool.setuptools.package-data]
+"deev" = ["py.typed"]

deev-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deev-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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']