lica-sqa 0.1.0__py3-none-any.whl

lica_sqa/__init__.py

@@ -0,0 +1,30 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# standard library
+# ----------------
+import logging
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lica-sqa")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+
+from .ports import Database
+from .metadata import Model, metadata
+from .view import view
+
+def sqa_logging(debug: bool) -> None:
+    if debug:
+        logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)
+        # This is needed, otherwise aiosqlite msgs will jump in
+        logging.getLogger("aiosqlite").setLevel(logging.INFO)
+    else:
+        logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+
+__all__ = ["sqa_logging","Database", "Model", "metadata", "view"]

lica_sqa/adapters/asyncio/decouple.py

@@ -0,0 +1,55 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# standard library
+# ----------------
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+# ---------------------
+# Third party libraries
+# ---------------------
+import decouple
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+# -----------------
+# Local dependecies
+# -----------------
+from ...ports.asyncio import AsyncDatabase
+
+
+class AsyncDcplDatabase(AsyncDatabase):
+    """main entry point instatinates this class"""
+
+    def __init__(self, env_var: str = "DATABASE_URL") -> None:
+        self._env_var = env_var
+
+    def init(self) -> None:
+        url: str = decouple.config(self._env_var)
+        self._engine = create_async_engine(
+            url,
+            pool_pre_ping=True,
+            connect_args={"check_same_thread": False},
+        )
+        self._session_factory = async_sessionmaker(
+            self._engine, autoflush=False, expire_on_commit=False
+        )
+
+    @asynccontextmanager
+    async def session(self) -> AsyncGenerator[AsyncSession]:
+        async with self._session_factory() as _session:
+            yield _session
+
+    @property
+    def engine(self) -> AsyncEngine:
+        return self._engine
+
+
+__all__ = ["DcplDatabase", "AsyncDcplDatabase"]

lica_sqa/adapters/decouple.py

@@ -0,0 +1,46 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# standard library
+# ----------------
+from collections.abc import Generator
+from contextlib import contextmanager
+
+import decouple  # pyright: ignore[reportMissingImports]
+from sqlalchemy import create_engine
+from sqlalchemy.engine.base import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+# ---------------
+# Own dependecies
+# ---------------
+from ..ports import Database
+
+class DcplDatabase(Database):
+    """main entry point instatinates this class"""
+
+    def __init__(self, env_var: str = "DATABASE_URL") -> None:
+        self._env_var = env_var
+
+    def init(self) -> None:
+        url: str = decouple.config(self._env_var)
+        self._engine = create_engine(
+            url,
+            pool_pre_ping=True,
+            connect_args={"check_same_thread": False},
+        )
+        self._session_factory = sessionmaker(self._engine, autoflush=False, expire_on_commit=False)
+
+    @contextmanager
+    def session(self) -> Generator[Session]:
+        with self._session_factory() as _session:
+            yield _session
+
+    @property
+    def engine(self) -> Engine:
+        return self._engine
+
+__all__ = ["DcplDatabase"]

lica_sqa/metadata/__init__.py

@@ -0,0 +1,30 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ---------------------
+# Third party libraries
+# ---------------------
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+metadata = MetaData(
+    # For the different artifacts (indexes, constraints, etc.)
+    naming_convention={
+        "ix": "ix_%(column_0_label)s",
+        "uq": "uq_%(table_name)s_%(column_0_name)s",
+        "ck": "ck_%(table_name)s_%(constraint_name)s",
+        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+        "pk": "pk_%(table_name)s",
+    }
+)
+
+
+class Model(DeclarativeBase):
+    """The Base class all of our models must derive"""
+
+    metadata = metadata
+
+
+__all__ = ["metadata", "Model"]

lica_sqa/metadata/asyncio.py

@@ -0,0 +1,28 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ---------------------
+# Third party libraries
+# ---------------------
+from sqlalchemy import MetaData
+from sqlalchemy.ext.asyncio import AsyncAttrs
+from sqlalchemy.orm import DeclarativeBase
+
+metadata = MetaData(
+    # For the different artifacts (indexes, constraints, etc.)
+    naming_convention={
+        "ix": "ix_%(column_0_label)s",
+        "uq": "uq_%(table_name)s_%(column_0_name)s",
+        "ck": "ck_%(table_name)s_%(constraint_name)s",
+        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+        "pk": "pk_%(table_name)s",
+    }
+)
+
+
+class AsyncModel(AsyncAttrs, DeclarativeBase):
+    """The Base class all of our async models must derive for lazy model loading"""
+
+    metadata = metadata

lica_sqa/ports/__init__.py

@@ -0,0 +1,20 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# standard library
+# ----------------
+from typing import ContextManager, Protocol
+
+# ---------------------
+# Third party libraries
+# ---------------------
+from sqlalchemy.orm import Session
+
+
+class Database(Protocol):
+    """application software use this interface as the dependency"""
+
+    def session(self) -> ContextManager[Session]: ...

lica_sqa/ports/asyncio.py

@@ -0,0 +1,20 @@
+# ----------------------------------------------------------------------
+# Copyright (c) 2026 Rafael Gonzalez.
+#
+# See the LICENSE file for details
+# ----------------------------------------------------------------------
+# ----------------
+# standard library
+# ----------------
+from typing import AsyncContextManager, Protocol
+
+# ---------------------
+# Third party libraries
+# ---------------------
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class AsyncDatabase(Protocol):
+    """application software use this interface as the dependency"""
+
+    def session(self) -> AsyncContextManager[AsyncSession]: ...

lica_sqa/view.py

@@ -0,0 +1,63 @@
+# --------------------------------------------------------------------
+# View recipe from https://github.com/sqlalchemy/sqlalchemy/wiki/Views
+# (updated for 2.0.38)
+# --------------------------------------------------------------------
+# ---------------------
+# Third party libraries
+# ---------------------
+import sqlalchemy
+from sqlalchemy.ext import compiler
+from sqlalchemy.schema import DDLElement
+
+
+class CreateView(DDLElement):
+    def __init__(self, name: str, selectable):
+        self.name = name
+        self.selectable = selectable
+
+
+class DropView(DDLElement):
+    def __init__(self, name: str):
+        self.name = name
+
+
+@compiler.compiles(CreateView)
+def _create_view(element, compiler, **kw):
+    return "CREATE VIEW %s AS %s" % (
+        element.name,
+        compiler.sql_compiler.process(element.selectable, literal_binds=True),
+    )
+
+
+@compiler.compiles(DropView)
+def _drop_view(element, compiler, **kw):
+    return "DROP VIEW %s" % (element.name)
+
+
+def view_exists(ddl, target, connection, **kw):
+    return ddl.name in sqlalchemy.inspect(connection).get_view_names()
+
+
+def view_doesnt_exist(ddl, target, connection, **kw):
+    return not view_exists(ddl, target, connection, **kw)
+
+
+def view(name, metadata, selectable):
+    t = sqlalchemy.table(
+        name,
+        *(
+            sqlalchemy.Column(c.name, c.type, primary_key=c.primary_key)
+            for c in selectable.selected_columns
+        ),
+    )
+    t.primary_key.update(c for c in t.c if c.primary_key)
+
+    sqlalchemy.event.listen(
+        metadata,
+        "after_create",
+        CreateView(name, selectable).execute_if(callable_=view_doesnt_exist),
+    )
+    sqlalchemy.event.listen(
+        metadata, "before_drop", DropView(name).execute_if(callable_=view_exists)
+    )
+    return t

lica_sqa-0.1.0.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: lica-sqa
+Version: 0.1.0
+Summary: LICA utilities for SQLAlchemy
+Author: Rafael González
+Author-email: Rafael González <rafael08@ucm.es>
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: alembic>=1.20
+Requires-Dist: sqlalchemy[asyncio]>=2.0 ; extra == 'asyncio'
+Requires-Dist: python-decouple ; extra == 'decouple'
+Requires-Python: >=3.12
+Provides-Extra: asyncio
+Provides-Extra: decouple
+Description-Content-Type: text/markdown
+
+# lica-sqa
+
+## Introduction
+
+`lica-sqa` is a lightweight SQLAlchemy utility layer for day-to-day LICA Python applications. It defines minimal synchronous and asynchronous database interfaces, provides shared declarative-model metadata, and includes adapters that create SQLAlchemy engines and session factories from a configuration value.
+
+The package supports conventional SQLAlchemy ORM models, asynchronous models based on `AsyncAttrs`, consistent database-object naming conventions, and a small helper for creating and dropping SQL views. Application code depends only on the `Database` or `AsyncDatabase` protocol, while the concrete database behaviour is supplied by an adapter.
+
+## Installation
+
+Install `lica-sqa` directly from the `lica-ng` Git repository:
+
+```bash
+pip install lica-sqa
+```
+
+or add it to your `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "lica-sqa",
+]
+```
+
+The included adapters require SQLAlchemy and `python-decouple`:
+
+```toml
+[project]
+dependencies = [
+    "lica-sqa",
+    "sqlalchemy",
+    "python-decouple",
+]
+```
+
+For asynchronous applications using SQLite, add an async driver such as `aiosqlite`:
+
+```toml
+[project]
+dependencies = [
+    "lica-sqa",
+    "sqlalchemy",
+    "python-decouple",
+    "aiosqlite",
+]
+```
+
+## Interfaces
+
+`lica-sqa` defines its database contracts using `typing.Protocol`. Adapters do not need to inherit from these protocols explicitly; they only need to provide the required methods.
+
+### Synchronous database
+
+```python
+from contextlib import AbstractContextManager
+from typing import Protocol
+
+from sqlalchemy.orm import Session
+
+
+class Database(Protocol):
+    """Application software uses this interface as the dependency."""
+
+    def session(self) -> AbstractContextManager[Session]: ...
+```
+
+### Asynchronous database
+
+```python
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class AsyncDatabase(Protocol):
+    """Application software uses this interface as the dependency."""
+
+    def session(self) -> AbstractAsyncContextManager[AsyncSession]: ...
+```
+
+## Adapters
+
+| Adapter | Module | Extra | Description |
+|---|---|---|---|
+| `DcplDatabase` | `lica_sqa.adapters.decouple` | `sqlalchemy`, `python-decouple` | Creates a synchronous SQLAlchemy engine and session factory from a `python-decouple` configuration value. |
+| `AsyncDcplDatabase` | `lica_sqa.adapters.asyncio.decouple` | `sqlalchemy`, `python-decouple` | Creates an asynchronous SQLAlchemy engine and session factory from a `python-decouple` configuration value. |
+
+Both adapters accept the name of the environment variable or configuration key containing the database URL:
+
+```python
+DcplDatabase(env_var: str = "DATABASE_URL") -> None
+AsyncDcplDatabase(env_var: str = "DATABASE_URL") -> None
+```
+
+Call `init()` before using the adapter. It reads the database URL, creates the engine with `pool_pre_ping=True`, and creates a session factory with `autoflush=False` and `expire_on_commit=False`.
+
+The expected configuration value is a standard SQLAlchemy database URL, for example:
+
+```bash
+DATABASE_URL=sqlite:///app.db
+```
+
+For an asynchronous SQLite database:
+
+```bash
+DATABASE_URL=sqlite+aiosqlite:///app.db
+```
+
+### Session usage
+
+The `session()` method returns a context manager that yields a SQLAlchemy session and closes it automatically on exit.
+
+```python
+with database.session() as session:
+    session.add(obj)
+    session.commit()
+```
+
+For asynchronous adapters:
+
+```python
+async with database.session() as session:
+    session.add(obj)
+    await session.commit()
+```
+
+## Models and metadata
+
+`lica-sqa` provides shared SQLAlchemy `MetaData` objects with a consistent naming convention for indexes, unique constraints, check constraints, foreign keys, and primary keys.
+
+### Synchronous models
+
+Derive application models from `Model`:
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lica_sqa import Model
+
+
+class User(Model):
+    __tablename__ = "user"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+```
+
+### Asynchronous models
+
+Derive asynchronous application models from `AsyncModel`:
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+
+from lica_sqa.metadata.asyncio import AsyncModel
+
+
+class User(AsyncModel):
+    __tablename__ = "user"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str]
+```
+
+`AsyncModel` combines SQLAlchemy’s `AsyncAttrs` and `DeclarativeBase`, enabling lazy attribute loading in asynchronous applications.
+
+## SQL views
+
+The `view()` helper creates a SQLAlchemy table-like object associated with a SQL view. It registers `CREATE VIEW` and `DROP VIEW` events on the supplied `MetaData`, creating the view only if it does not already exist and dropping it only if it exists.
+
+```python
+from sqlalchemy import select
+
+from lica_sqa import metadata, view
+from myapp.models import User
+
+user_view = view(
+    "user_names",
+    metadata,
+    select(User.id, User.name),
+)
+```
+
+The helper is based on the SQLAlchemy views recipe and has been updated for SQLAlchemy 2.0.
+
+## Logging
+
+Use `sqa_logging()` to configure the verbosity of SQLAlchemy engine logging:
+
+```python
+from lica_sqa import sqa_logging
+
+sqa_logging(debug=True)
+```
+
+When `debug=True`, the `sqlalchemy.engine` and `aiosqlite` loggers are set to `INFO`. Otherwise, `sqlalchemy.engine` is set to `WARNING`.
+
+## Usage example, with lica-cli package
+
+```python
+import sys
+from argparse import ArgumentParser, Namespace
+
+from lica_cli import parse_args, run_cli
+from lica_sqa import Database
+from lica_sqa.adapters.decouple import DcplDatabase
+
+from myapp.models import User
+from myprog import __version__
+
+DESCRIPTION = "My program short description"
+
+
+def add_args(parser: ArgumentParser) -> None:
+    """Add extra CLI arguments here"""
+    pass
+
+
+def cli_main(args: Namespace, database: Database) -> None:
+    with database.session() as session:
+        session.add(User(name="Alice"))
+        session.commit()
+
+
+def main():
+    args = parse_args(add_args, __name__, __version__, DESCRIPTION)
+
+    database: Database = DcplDatabase()
+    database.init()
+
+    return_code = run_cli(cli_main, args, __name__, __version__, database=database)
+    sys.exit(return_code)
+
+
+if __name__ == "__main__":
+    main()
+```

lica_sqa-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+lica_sqa/__init__.py,sha256=-kPUbsM1qgauX8Txm-XhwdroBlWlaHkptjC_1Si9DMQ,947
+lica_sqa/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lica_sqa/adapters/asyncio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lica_sqa/adapters/asyncio/decouple.py,sha256=Gx0CvBAQItMzomqZntX4T8ATtch3qS_Hm0QHKRTZ8Bk,1533
+lica_sqa/adapters/decouple.py,sha256=4ooytjzcL41jPI_kexMfCgV74AWxb5J3lCyKSFzwH8M,1379
+lica_sqa/metadata/__init__.py,sha256=041505Mtqw0MC5iZIOuzmTXQeWpbMJx_HU3s0uZgljI,890
+lica_sqa/metadata/asyncio.py,sha256=qXEDlNGkmv8_nD4awp6bX1TMUX2GV_toMFNWF98k0tY,948
+lica_sqa/ports/__init__.py,sha256=FAGUrwUnT4VeWsKwZLdF5zS30pmujeisdZ0u9rdZeCY,581
+lica_sqa/ports/asyncio.py,sha256=GlpU6SDPCpJkh1kq0S5iRuB5D0ihBNhVR20mgo6gHww,614
+lica_sqa/view.py,sha256=9OGV0LV2LhILJOY6szMBf5SKJieOzmRh5iJ166gH-Xg,1779
+lica_sqa-0.1.0.dist-info/licenses/LICENSE,sha256=AAxFY4JFsUgATHGcfHy_aFXU7KbvycCxGfszmPiUCjA,1066
+lica_sqa-0.1.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+lica_sqa-0.1.0.dist-info/METADATA,sha256=RPdNLUJn8DTtrNF7asMl6WEWESGVR86DJdhNZRyyLlY,7072
+lica_sqa-0.1.0.dist-info/RECORD,,

lica_sqa-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.1
+Root-Is-Purelib: true
+Tag: py3-none-any

lica_sqa-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guaix UCM
+
+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 this 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.