python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/connections/redis/connection.py

@@ -23,6 +23,7 @@ from redis import asyncio as aioredis
 
 from corekit.config import get_settings
 from corekit.connections import Connectable
+from corekit.exceptions import InternalCoreException, Retryability
 
 __all__ = ["RedisConnection", "RedisNotConnectedError"]
 
@@ -31,11 +32,14 @@ logger = logging.getLogger(__name__)
 DEFAULT_URL = "redis://localhost:6379/0"
 
 
-class RedisNotConnectedError(RuntimeError):
+class RedisNotConnectedError(InternalCoreException):
     """
     Raised when a client is used before its connection is opened.
     """
 
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
+
 
 def _encode(value: Any) -> str:
     """
@@ -65,14 +69,15 @@ class RedisConnection(Connectable):
     """
     A Connectable wrapper over a Redis client.
 
-    The sync client is shared per URL for the life of the process, because a
+    The sync client is shared per URL for the life of its holders, because a
     Redis client is a connection pool and building one per caller defeats it.
-    ``_disconnect`` is therefore a no-op: one caller finishing must not close a
-    pool others are still using. Async clients are per-instance, since they are
-    bound to a running event loop.
+    Each ``connect`` takes a hold; ``disconnect`` releases it and closes the
+    pool only when no holder remains. Async clients are per-instance, since they
+    are bound to a running event loop.
     """
 
     _shared_clients: dict[str, Any] = {}
+    _shared_refs: dict[str, int] = {}
 
     def __init__(self, url: str | None = None, safe: bool = False, **kwargs: Any) -> None:
         """
@@ -83,6 +88,7 @@ class RedisConnection(Connectable):
         self._url = url or get_settings().redis.url or DEFAULT_URL
         self._safe = safe
         self._async_client: Any = None
+        self._holds_shared = False
 
     @property
     def url(self) -> str:
@@ -93,7 +99,7 @@ class RedisConnection(Connectable):
 
     @property
     def is_connected(self) -> bool:
-        return RedisConnection._shared_clients.get(self._url) is not None
+        return self._holds_shared
 
     @property
     def is_async_connected(self) -> bool:
@@ -102,8 +108,10 @@ class RedisConnection(Connectable):
     @property
     def client(self) -> Any:
         """
-        The sync client, raising if the connection was never opened.
+        The sync client, raising if this instance has not connected.
         """
+        if not self._holds_shared:
+            raise RedisNotConnectedError("RedisConnection is not connected. Call connect() or use a with block.")
         existing = RedisConnection._shared_clients.get(self._url)
         if existing is None:
             raise RedisNotConnectedError("RedisConnection is not connected. Call connect() or use a with block.")
@@ -135,11 +143,29 @@ class RedisConnection(Connectable):
         if RedisConnection._shared_clients.get(self._url) is None:
             self.info(f"Creating shared Redis client for {self._url}")
             RedisConnection._shared_clients[self._url] = self._build(is_async=False)
+            RedisConnection._shared_refs[self._url] = 0
+        if not self._holds_shared:
+            RedisConnection._shared_refs[self._url] = RedisConnection._shared_refs.get(self._url, 0) + 1
+            self._holds_shared = True
 
     def _disconnect(self) -> None:
         """
-        Deliberately a no-op: the sync client is a process-wide pool.
+        Release this instance's hold on the shared pool; close it when last.
         """
+        if not self._holds_shared:
+            return
+        self._holds_shared = False
+        refs = RedisConnection._shared_refs.get(self._url, 1) - 1
+        if refs <= 0:
+            client = RedisConnection._shared_clients.pop(self._url, None)
+            RedisConnection._shared_refs.pop(self._url, None)
+            if client is not None:
+                try:
+                    client.close()
+                except Exception as exc:
+                    self.debug(f"Error closing Redis client for {self._url}: {exc}")
+        else:
+            RedisConnection._shared_refs[self._url] = refs
 
     async def _async_connect(self) -> None:
         self._async_client = self._build(is_async=True)
@@ -166,6 +192,7 @@ class RedisConnection(Connectable):
             except Exception as exc:
                 logger.debug("Error closing Redis client for %s: %s", url, exc)
             del cls._shared_clients[url]
+        cls._shared_refs.clear()
 
     # ------------------------------------------------------------------
     # Sync API
@@ -175,9 +202,11 @@ class RedisConnection(Connectable):
         return _decode(self.client.get(key))
 
     def set(self, key: str, value: Any, **kwargs: Any) -> None:
+        self.require_writable()
         self.client.set(key, _encode(value), **kwargs)
 
     def delete(self, *keys: str) -> None:
+        self.require_writable()
         self.client.delete(*keys)
 
     def ping(self) -> bool:
@@ -187,15 +216,18 @@ class RedisConnection(Connectable):
         return bool(self.client.exists(key))
 
     def expire(self, key: str, seconds: int) -> None:
+        self.require_writable()
         self.client.expire(key, seconds)
 
     def ttl(self, key: str) -> int:
         return self.client.ttl(key)
 
     def incr(self, key: str, amount: int = 1) -> int:
+        self.require_writable()
         return self.client.incr(key, amount)
 
     def decr(self, key: str, amount: int = 1) -> int:
+        self.require_writable()
         return self.client.decr(key, amount)
 
     def keys(self, pattern: str = "*") -> list[Any]:
@@ -205,13 +237,19 @@ class RedisConnection(Connectable):
         return _decode(self.client.hget(key, field))
 
     def hset(self, key: str, field: str, value: Any) -> None:
+        self.require_writable()
         self.client.hset(key, field, _encode(value))
 
     def hdel(self, key: str, *fields: str) -> None:
+        self.require_writable()
         self.client.hdel(key, *fields)
 
     def publish(self, channel: str, message: Any) -> int:
-        return self.client.publish(channel, _encode(message))
+        self.require_writable()
+        # Pre-serialized pub/sub payloads (JSON strings, bytes) pass through;
+        # structured values are encoded the same way as cache writes.
+        payload = message if isinstance(message, (str, bytes, bytearray)) else _encode(message)
+        return self.client.publish(channel, payload)
 
     def pubsub(self) -> Any:
         return self.client.pubsub()
@@ -224,16 +262,21 @@ class RedisConnection(Connectable):
         return _decode(await self.async_client.get(key))
 
     async def aset(self, key: str, value: Any, **kwargs: Any) -> None:
+        self.require_writable()
         await self.async_client.set(key, _encode(value), **kwargs)
 
     async def asetex(self, key: str, seconds: int, value: Any) -> None:
+        self.require_writable()
         await self.async_client.setex(key, seconds, _encode(value))
 
     async def adelete(self, *keys: str) -> None:
+        self.require_writable()
         await self.async_client.delete(*keys)
 
     async def akeys(self, pattern: str = "*") -> list[Any]:
         return await self.async_client.keys(pattern)
 
     async def apublish(self, channel: str, message: Any) -> int:
-        return await self.async_client.publish(channel, _encode(message))
+        self.require_writable()
+        payload = message if isinstance(message, (str, bytes, bytearray)) else _encode(message)
+        return await self.async_client.publish(channel, payload)

corekit/connections/sql/__init__.py

@@ -1,10 +1,39 @@
 """
-SQL building blocks: a Connectable session, a query builder and a base table.
+SQL building blocks: a Connectable session, statement primitives and a base table.
 """
 
 from corekit.connections.sql.connection import PaginatedResult, SQLConnection
-from corekit.connections.sql.fields import JSONBField, PydanticJSON
+from corekit.connections.sql.fields import JSONBField, JsonModelField, PydanticJSON
+from corekit.connections.sql.operations import (
+    Conditional,
+    DdlOperation,
+    Delete,
+    DmlOperation,
+    DqlOperation,
+    Insert,
+    Operation,
+    Select,
+    Update,
+)
 from corekit.connections.sql.query import Query
-from corekit.connections.sql.table import NamedTable
+from corekit.connections.sql.table import NamedTable, TableExportItem
 
-__all__ = ["JSONBField", "NamedTable", "PaginatedResult", "PydanticJSON", "Query", "SQLConnection"]
+__all__ = [
+    "Conditional",
+    "DdlOperation",
+    "Delete",
+    "DmlOperation",
+    "DqlOperation",
+    "Insert",
+    "JsonModelField",
+    "JSONBField",
+    "NamedTable",
+    "Operation",
+    "PaginatedResult",
+    "PydanticJSON",
+    "Query",
+    "Select",
+    "SQLConnection",
+    "TableExportItem",
+    "Update",
+]

corekit/connections/sql/connection.py

@@ -24,6 +24,7 @@ from sqlmodel import Session, SQLModel, create_engine, select
 
 from corekit.config import get_settings
 from corekit.connections import Connectable
+from corekit.connections.sql.operations import DqlOperation, Operation, Select
 from corekit.connections.sql.query import Query
 from corekit.connections.sql.table import NamedTable
 
@@ -203,12 +204,14 @@ class SQLConnection(Connectable):
         """
         Create any tables present in SQLModel metadata but missing from the database.
         """
+        self.require_writable()
         SQLModel.metadata.create_all(_get_engine(self._connection_url))
 
     def exec_ddl(self, sql: str) -> None:
         """
         Run a raw DDL statement. Intended for migrations, not application code.
         """
+        self.require_writable()
         self._start_session()
         self.session.exec(text(sql))
         self.session.commit()
@@ -221,6 +224,7 @@ class SQLConnection(Connectable):
         """
         Insert new rows.
         """
+        self.require_writable()
         self._start_session()
         self.session.add_all(items)
         self.session.commit()
@@ -229,6 +233,7 @@ class SQLConnection(Connectable):
         """
         Insert or update rows. Slower than insert, but tolerates existing ids.
         """
+        self.require_writable()
         self._start_session()
         for item in items:
             self.session.merge(item)
@@ -238,6 +243,7 @@ class SQLConnection(Connectable):
         """
         Delete a row by id.
         """
+        self.require_writable()
         item = self.fetch_one_by_id(table, identifier)
         if item is None:
             return
@@ -295,8 +301,12 @@ class SQLConnection(Connectable):
     def fetch_one_by_condition(self, table: type[NamedTable], key: Any, value: Any) -> NamedTable | None:
         """
         The first row where a column equals a value.
+
+        ``key`` may be a column attribute (``Person.city``) or a column name
+        string resolved against ``table``.
         """
-        return self.first(select(table).where(key == value))
+        column = getattr(table, key) if isinstance(key, str) else key
+        return self.first(select(table).where(column == value))
 
     def exists(self, table: type[NamedTable], identifier: str) -> bool:
         """
@@ -320,6 +330,36 @@ class SQLConnection(Connectable):
         """
         return list(self._exec(query.build()))
 
+    def delete_many_by_query(self, query: Query) -> None:
+        """
+        Delete every row matching a Query.
+        """
+        self.require_writable()
+        self._start_session()
+        for item in self.fetch_many_by_query(query):
+            self.session.delete(item)
+        self.session.commit()
+
+    def execute(self, operation: Operation) -> Any:
+        """
+        Run an operation, committing if it writes.
+
+        A read returns its rows; a write returns the result, whose
+        ``rowcount`` reports how many rows it touched.
+        """
+        if operation.writes:
+            self.require_writable()
+        result = self._exec(operation.build())
+        if operation.writes:
+            self.session.commit()
+        return result
+
+    def fetch(self, operation: DqlOperation) -> list[NamedTable]:
+        """
+        Every row an operation selects.
+        """
+        return list(self.execute(operation))
+
     def fetch_one_by_query(self, query: Query) -> NamedTable | None:
         """
         The first row matching a Query.
@@ -333,10 +373,23 @@ class SQLConnection(Connectable):
         self._start_session()
         return self.session.exec(select(func.count()).select_from(table)).one()
 
-    def paginate(self, table: type[NamedTable], offset: int = 0, limit: int = 50) -> PaginatedResult:
+    def paginate(
+        self,
+        table: type[NamedTable],
+        offset: int = 0,
+        limit: int = 50,
+        *,
+        order_by: Any = None,
+        desc: bool = False,
+    ) -> PaginatedResult:
         """
         A page of rows, together with the total row count.
+
+        Pages are ordered: pass ``order_by`` for a column, or omit it to order
+        by ``table.id`` so offsets are stable.
         """
         total = self.count(table)
-        rows = list(self._exec(select(table).offset(offset).limit(limit)))
+        query = Select(table=table).offset(offset).limit(limit)
+        query.order_by(order_by if order_by is not None else table.id, desc=desc)
+        rows = self.fetch(query)
         return PaginatedResult(rows=rows, total=total)

corekit/connections/sql/fields/__init__.py

@@ -2,6 +2,6 @@
 Custom SQL column types.
 """
 
-from corekit.connections.sql.fields.jsonb import JSONBField, PydanticJSON
+from corekit.connections.sql.fields.jsonb import JSONBField, JsonModelField, PydanticJSON
 
-__all__ = ["JSONBField", "PydanticJSON"]
+__all__ = ["JsonModelField", "JSONBField", "PydanticJSON"]

corekit/connections/sql/fields/jsonb.py

@@ -1,18 +1,21 @@
 """
 Columns that store a Pydantic model as JSON.
 
-``JSONBField`` round-trips a model through a JSON column, so a table can hold
-structured data without a separate table and without hand-written encoding at
-every call site::
+``JsonModelField`` round-trips a model through a JSON column, so a table can
+hold structured data without a separate table and without hand-written encoding
+at every call site::
 
     class Profile(BaseModel):
         theme: str = "dark"
 
     class User(NamedTable, table=True):
         id: str = Field(primary_key=True)
-        profile: Profile = JSONBField(Profile)
+        profile: Profile = JsonModelField(Profile)
 
 Reading ``user.profile`` gives a ``Profile``, not a dict.
+
+The SQLAlchemy ``impl`` is ``JSON``, not PostgreSQL ``JSONB``. The historical
+``JSONBField`` name is kept as an alias.
 """
 
 from typing import Any
@@ -22,7 +25,7 @@ from sqlalchemy import Column
 from sqlalchemy.types import JSON, TypeDecorator
 from sqlmodel import Field
 
-__all__ = ["JSONBField", "PydanticJSON"]
+__all__ = ["JsonModelField", "JSONBField", "PydanticJSON"]
 
 
 class PydanticJSON(TypeDecorator):
@@ -60,8 +63,12 @@ class PydanticJSON(TypeDecorator):
         return self.pydantic_model(**value)
 
 
-def JSONBField(pydantic_model: type[BaseModel], **kwargs: Any) -> Any:  # noqa: N802 - reads as a field constructor
+def JsonModelField(pydantic_model: type[BaseModel], **kwargs: Any) -> Any:  # noqa: N802 - reads as a field constructor
     """
     Declare a column holding ``pydantic_model`` as JSON.
     """
     return Field(sa_column=Column(PydanticJSON(pydantic_model)), **kwargs)
+
+
+#: Historical name. The column type is SQLAlchemy ``JSON``, not PostgreSQL JSONB.
+JSONBField = JsonModelField

corekit/connections/sql/migration/__init__.py

@@ -8,7 +8,7 @@ Define a migration by subclassing ``Migration`` and listing its operations::
         name = "user_is_active"
         description = "Adds the is_active flag to users."
 
-        def operations(self) -> list[Operation]:
+        def operations(self) -> list[MigrationOperation]:
             return [AddColumn(table="user", column="is_active", dtype="BOOLEAN", default="true")]
 
 Collect them from a package and run them::
@@ -24,13 +24,15 @@ from corekit.connections.sql.migration.base import Migration
 from corekit.connections.sql.migration.operations import (
     AddColumn,
     AlterColumnType,
+    ColumnSpec,
     CreateIndex,
-    DataOperation,
+    CreateTable,
+    DataMigrationOperation,
     DropColumn,
     DropColumnDefault,
     DropIndex,
     DropTable,
-    Operation,
+    MigrationOperation,
     RenameColumn,
     RenameTable,
     SetColumnDefault,
@@ -41,8 +43,10 @@ from corekit.connections.sql.migration.table import SchemaMigration
 __all__ = [
     "AddColumn",
     "AlterColumnType",
+    "ColumnSpec",
     "CreateIndex",
-    "DataOperation",
+    "CreateTable",
+    "DataMigrationOperation",
     "DropColumn",
     "DropColumnDefault",
     "DropIndex",
@@ -50,7 +54,7 @@ __all__ = [
     "Migration",
     "MigrationChecksumError",
     "MigrationRegistry",
-    "Operation",
+    "MigrationOperation",
     "RenameColumn",
     "RenameTable",
     "SchemaMigration",

corekit/connections/sql/migration/base.py

@@ -5,7 +5,7 @@ A Migration is defined by:
   - version:     unique positive integer, determines execution order
   - name:        short human-readable label (used in logs and the DB table)
   - description: longer explanation of what and why
-  - operations:  ordered list of Operation instances to execute
+  - operations:  ordered list of MigrationOperation instances to execute
 
 The checksum is computed at class definition time from the canonical
 representations of all operations. It is stored in the schema_migration
@@ -17,7 +17,7 @@ and will cause a hard crash.
 import hashlib
 from abc import ABC, abstractmethod
 
-from corekit.connections.sql.migration.operations import Operation
+from corekit.connections.sql.migration.operations import MigrationOperation
 
 
 class Migration(ABC):
@@ -26,7 +26,7 @@ class Migration(ABC):
     description: str
 
     @abstractmethod
-    def operations(self) -> list[Operation]:
+    def operations(self) -> list[MigrationOperation]:
         raise NotImplementedError
 
     @property