sqlalchemy-hawdb 0.22.0__py3-none-any.whl

sqlalchemy_hawdb/__init__.py

@@ -0,0 +1,5 @@
+"""SQLAlchemy integration for HawDB."""
+
+from sqlalchemy_hawdb.dialect import HawDBDialect
+
+__all__ = ["HawDBDialect"]

sqlalchemy_hawdb/dialect.py

@@ -0,0 +1,323 @@
+"""SQLAlchemy dialect for HawDB's embedded SQL interface."""
+
+from __future__ import annotations
+
+import importlib
+
+from sqlalchemy.engine import default
+from sqlalchemy.pool import NullPool, SingletonThreadPool
+from sqlalchemy.sql.compiler import GenericTypeCompiler, IdentifierPreparer
+
+
+class HawDBIdentifierPreparer(IdentifierPreparer):
+    """Quote identifiers using SQL-standard double quotes."""
+
+    reserved_words = IdentifierPreparer.reserved_words | {"match", "return", "graph"}
+
+
+class HawDBTypeCompiler(GenericTypeCompiler):
+    """Compile SQLAlchemy types to HawDB's supported PostgreSQL type subset."""
+
+    def visit_big_integer(self, type_, **kw):
+        return "BIGINT"
+
+    visit_integer = visit_big_integer
+    visit_small_integer = visit_big_integer
+
+    def visit_boolean(self, type_, **kw):
+        return "BOOLEAN"
+
+    def visit_double(self, type_, **kw):
+        return "DOUBLE PRECISION"
+
+    visit_float = visit_double
+    visit_real = visit_double
+    visit_numeric = visit_double
+
+    def visit_string(self, type_, **kw):
+        return "TEXT"
+
+    visit_text = visit_string
+    visit_unicode = visit_string
+    visit_unicode_text = visit_string
+
+    def visit_large_binary(self, type_, **kw):
+        return "BYTEA"
+
+    def visit_uuid(self, type_, **kw):
+        return "UUID"
+
+    def visit_date(self, type_, **kw):
+        return "TEXT"
+
+    visit_time = visit_date
+    visit_datetime = visit_date
+
+    def visit_enum(self, type_, **kw):
+        return "TEXT"
+
+
+class HawDBDialect(default.DefaultDialect):
+    name = "hawdb"
+    driver = "embedded"
+    supports_statement_cache = True
+    supports_native_boolean = True
+    supports_native_uuid = True
+    supports_sane_rowcount = False
+    supports_sane_multi_rowcount = False
+    supports_sequences = False
+    supports_identity_columns = False
+    supports_default_values = False
+    supports_empty_insert = False
+    supports_alter = False
+    supports_comments = False
+    postfetch_lastrowid = False
+    default_paramstyle = "numeric_dollar"
+    preparer = HawDBIdentifierPreparer
+    type_compiler_cls = HawDBTypeCompiler
+
+    @classmethod
+    def import_dbapi(cls):
+        try:
+            return importlib.import_module("hawdb.dbapi")
+        except ImportError as error:
+            raise ImportError(
+                "HawDB's Python binding is required; install it with "
+                "python -m pip install 'hawdb>=0.22.0,<0.23.0'"
+            ) from error
+
+    def create_connect_args(self, url):
+        if url.username or url.password or url.host or url.port:
+            raise ValueError(
+                "Invalid HawDB URL: provide a local database path without "
+                "credentials or a network host"
+            )
+        query = dict(url.query)
+        read_only = query.pop("read_only", "false").lower() in {"1", "true", "yes"}
+        if query:
+            options = ", ".join(sorted(query))
+            raise ValueError(f"unsupported HawDB URL option(s): {options}")
+        path = url.database
+        if path in (None, ":memory:"):
+            path = None
+        return (
+            [path],
+            {"read_only": read_only, "autocommit": False},
+        )
+
+    def do_begin(self, dbapi_connection):
+        # HawDB's PEP 249 connection begins on its first statement.
+        return None
+
+    def do_rollback(self, dbapi_connection):
+        dbapi_connection.rollback()
+
+    def do_commit(self, dbapi_connection):
+        dbapi_connection.commit()
+
+    @classmethod
+    def get_pool_class(cls, url):
+        # File handles own their path and cannot be shared across threads.
+        # In-memory URLs need a per-thread handle to persist across checkouts.
+        if url.database in (None, ":memory:"):
+            return SingletonThreadPool
+        return NullPool
+
+    def get_server_version_info(self, connection):
+        import hawdb
+
+        return tuple(int(part) for part in hawdb.__version__.split(".")[:3])
+
+    def get_default_schema_name(self, connection):
+        return "public"
+
+    def get_schema_names(self, connection, **kw):
+        return ["public"]
+
+    def has_table(self, connection, table_name, schema=None, **kw):
+        if schema not in (None, "public"):
+            return False
+        result = connection.exec_driver_sql(
+            "SELECT table_name FROM information_schema.tables "
+            "WHERE table_schema = 'public' AND table_name = $1",
+            (table_name,),
+        )
+        return result.first() is not None
+
+    def get_table_names(self, connection, schema=None, **kw):
+        if schema not in (None, "public"):
+            return []
+        result = connection.exec_driver_sql(
+            "SELECT table_name FROM information_schema.tables "
+            "WHERE table_schema = 'public' AND table_type = 'BASE TABLE' "
+            "ORDER BY table_name"
+        )
+        return [row[0] for row in result]
+
+    def get_view_names(self, connection, schema=None, **kw):
+        if schema not in (None, "public"):
+            return []
+        result = connection.exec_driver_sql(
+            "SELECT table_name FROM information_schema.tables "
+            "WHERE table_schema = 'public' AND table_type = 'MATERIALIZED VIEW' "
+            "ORDER BY table_name"
+        )
+        return [row[0] for row in result]
+
+    def get_columns(self, connection, table_name, schema=None, **kw):
+        if schema not in (None, "public"):
+            return []
+        result = connection.exec_driver_sql(
+            "SELECT column_name, data_type, is_nullable, column_default "
+            "FROM information_schema.columns "
+            "WHERE table_schema = 'public' AND table_name = $1 "
+            "ORDER BY ordinal_position",
+            (table_name,),
+        )
+        return [
+            {
+                "name": row[0],
+                "type": self._type_from_name(row[1]),
+                "nullable": row[2] == "YES",
+                "default": row[3],
+                "autoincrement": False,
+                "comment": None,
+            }
+            for row in result
+        ]
+
+    def get_pk_constraint(self, connection, table_name, schema=None, **kw):
+        if schema not in (None, "public"):
+            return {"name": None, "constrained_columns": []}
+        result = connection.exec_driver_sql(
+            "SELECT indexname, indexdef FROM pg_catalog.pg_indexes "
+            "WHERE schemaname = 'public' AND tablename = $1 ORDER BY indexname",
+            (table_name,),
+        )
+        primary_key_name = f"{table_name}_pkey"
+        for row in result:
+            if row[0] == primary_key_name:
+                return {
+                    "name": row[0],
+                    "constrained_columns": self._index_columns(row[1]),
+                }
+        return {"name": None, "constrained_columns": []}
+
+    def get_indexes(self, connection, table_name, schema=None, **kw):
+        if schema not in (None, "public"):
+            return []
+        result = connection.exec_driver_sql(
+            "SELECT indexname, indexdef FROM pg_catalog.pg_indexes "
+            "WHERE schemaname = 'public' AND tablename = $1 ORDER BY indexname",
+            (table_name,),
+        )
+        primary_key_name = f"{table_name}_pkey"
+        return [
+            {
+                "name": row[0],
+                "column_names": self._index_columns(row[1]),
+                "unique": row[1].upper().startswith("CREATE UNIQUE INDEX"),
+                "dialect_options": {},
+            }
+            for row in result
+            if row[0] != primary_key_name
+        ]
+
+    def get_unique_constraints(self, connection, table_name, schema=None, **kw):
+        if schema not in (None, "public"):
+            return []
+        result = connection.exec_driver_sql(
+            "SELECT indexname, indexdef FROM pg_catalog.pg_indexes "
+            "WHERE schemaname = 'public' AND tablename = $1 ORDER BY indexname",
+            (table_name,),
+        )
+        primary_key_name = f"{table_name}_pkey"
+        return [
+            {
+                "name": row[0],
+                "column_names": self._index_columns(row[1]),
+                "duplicates_index": row[0],
+            }
+            for row in result
+            if row[0] != primary_key_name
+            and row[1].upper().startswith("CREATE UNIQUE INDEX")
+        ]
+
+    @staticmethod
+    def _index_columns(definition: str) -> list[str]:
+        """Parse the simple parenthesized column list emitted by pg_indexes."""
+        opening = closing = -1
+        quoted = False
+        depth = 0
+        index = 0
+        while index < len(definition):
+            char = definition[index]
+            if char == '"':
+                if (
+                    quoted
+                    and index + 1 < len(definition)
+                    and definition[index + 1] == '"'
+                ):
+                    index += 1
+                else:
+                    quoted = not quoted
+            elif not quoted and char == "(":
+                if depth == 0:
+                    opening = index
+                depth += 1
+            elif not quoted and char == ")" and depth:
+                depth -= 1
+                if depth == 0:
+                    closing = index
+            index += 1
+        if opening < 0 or closing <= opening:
+            return []
+        columns = definition[opening + 1 : closing]
+        result = []
+        current = []
+        quoted = False
+        index = 0
+        while index < len(columns):
+            char = columns[index]
+            if char == '"':
+                if quoted and index + 1 < len(columns) and columns[index + 1] == '"':
+                    current.append('"')
+                    index += 1
+                else:
+                    quoted = not quoted
+            elif char == "," and not quoted:
+                result.append("".join(current).strip())
+                current = []
+            else:
+                current.append(char)
+            index += 1
+        if current:
+            result.append("".join(current).strip())
+        return result
+
+    @staticmethod
+    def _type_from_name(name: str):
+        from sqlalchemy import types
+
+        normalized = name.lower()
+        if normalized in {"smallint", "integer", "bigint"}:
+            return types.Integer()
+        if normalized in {"real", "double precision", "numeric", "decimal"}:
+            return types.Float()
+        if normalized in {"boolean", "bool"}:
+            return types.Boolean()
+        if normalized in {
+            "date",
+            "time",
+            "timestamp",
+            "timestamp without time zone",
+            "timestamp with time zone",
+        }:
+            return types.Text()
+        if normalized in {"uuid"}:
+            return types.Uuid()
+        if normalized in {"bytea", "binary", "varbinary"}:
+            return types.LargeBinary()
+        if normalized in {"text", "character varying", "varchar", "character", "char"}:
+            return types.Text()
+        return types.NullType()

sqlalchemy_hawdb-0.22.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-hawdb
+Version: 0.22.0
+Summary: SQLAlchemy dialect for the embedded HawDB database
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: hawdb<0.23.0,>=0.22.0
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Requires-Dist: ruff<1,>=0.14; extra == "test"
+
+# SQLAlchemy HawDB
+
+`sqlalchemy-hawdb` provides a SQLAlchemy 2.x dialect for the embedded HawDB
+database. It uses HawDB's own PEP 249 driver and does not add a wire protocol or
+duplicate its DBAPI implementation.
+
+## Requirements
+
+- Python 3.11 or newer
+- HawDB Python binding 0.22.x (CI tests 0.22.0)
+- SQLAlchemy 2.x
+
+Install the dialect and its HawDB dependency from PyPI:
+
+```sh
+python -m pip install sqlalchemy-hawdb
+```
+
+To install this checkout instead:
+
+```sh
+python -m pip install /path/to/sqlalchemy_hawdb
+```
+
+## Connect
+
+Use an absolute database directory path with four slashes:
+
+```python
+from sqlalchemy import Column, Integer, MetaData, String, Table, create_engine
+
+engine = create_engine("hawdb:////var/lib/my-app/knowledge")
+metadata = MetaData()
+records = Table(
+    "records",
+    metadata,
+    Column("id", Integer, primary_key=True, autoincrement=False),
+    Column("body", String(500), nullable=False),
+)
+
+metadata.create_all(engine)
+with engine.begin() as connection:
+    connection.execute(records.insert(), {"id": 1, "body": "Hello HawDB"})
+```
+
+HawDB creates the database directory itself; its parent directory must already
+exist.
+
+Use `hawdb:///:memory:` for an in-memory database. Like SQLAlchemy's SQLite
+dialect, the in-memory engine keeps one database per thread. Add
+`?read_only=true` to open an existing database read-only.
+
+HawDB connections are thread-affine and hold their database path until closed.
+For file databases the dialect uses SQLAlchemy's `NullPool`: each SQLAlchemy
+connection closes its HawDB handle when returned. Do not keep multiple
+connections to the same database path open at once or pass a SQLAlchemy
+connection between threads. In-memory connections are kept per thread and must
+also be used serially within that thread.
+
+## Supported behavior
+
+- SQLAlchemy Core and ORM statements using HawDB's relational SQL subset
+- Positional `$1`, `$2`, ... binding through HawDB's native DBAPI driver
+- Explicit SQLAlchemy transactions mapped to HawDB commit and rollback
+- Table, column, primary key, unique constraint, and index reflection from
+  HawDB's `information_schema` and `pg_catalog` views
+- The default `public` schema
+- HawDB-native scalar DDL types: integer types map to `BIGINT`, floating and
+  numeric types to `DOUBLE PRECISION`, strings to `TEXT`, and binary values to
+  `BYTEA`; SQLAlchemy string lengths and numeric precision are not enforced by
+  HawDB
+
+HawDB does not report affected row counts, so DBAPI `rowcount` is `-1` for
+statements without a result set. Date and time types compile to `TEXT`; their
+values are encoded and decoded by SQLAlchemy's standard processors.
+Auto-generated identity columns, sequences, schema alteration, savepoints, and
+concurrent connections to one database path are not supported by this initial
+dialect.
+
+## Development
+
+Install the project, the HawDB dependency, and the test tools:
+
+```sh
+python -m pip install -e '.[test]'
+python -m pytest
+```
+
+GitHub Actions builds the source distribution and wheel, checks their metadata,
+and tests the installed wheel against `hawdb==0.22.0` from PyPI on Python
+3.11-3.13 for every push and pull request. Missing HawDB wheels fail CI rather
+than skipping integration tests or falling back to a source build.
+
+## Publishing
+
+`.github/workflows/pypi.yaml` publishes the tested source distribution and wheel
+when a GitHub Release is published. The release tag must match the version in
+`pyproject.toml`, for example `v0.22.0`. A manual workflow dispatch runs the same
+build and tests without uploading to PyPI.
+
+Configure a PyPI Trusted Publisher for the `sqlalchemy-hawdb` project with:
+
+- Owner: `nowledge-co`
+- Repository: `sqlalchemy-hawdb`
+- Workflow: `pypi.yaml`
+- Environment: `pypi`
+
+For the first release, configure a pending publisher in your PyPI account.
+The publish job uses GitHub's `pypi` environment and OIDC; no PyPI API token
+secret is required.

sqlalchemy_hawdb-0.22.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sqlalchemy_hawdb/__init__.py,sha256=9zJu4JP1VSSpilWq0NlddfVQLpXG7bEHHeILcbgffjM,119
+sqlalchemy_hawdb/dialect.py,sha256=uYb_OYDxmyYif51vUmXP1hQVzgrzl0-Db6a07kfb_0U,10996
+sqlalchemy_hawdb-0.22.0.dist-info/METADATA,sha256=WMUsSECpUEskBw7YDxsPQqLFsJp3F2imHhXhzIVVfCs,4647
+sqlalchemy_hawdb-0.22.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sqlalchemy_hawdb-0.22.0.dist-info/entry_points.txt,sha256=O6N7Zc7UOCf5nMrTDrAZBCwGI04yEvxSV4LKVUBsa6c,68
+sqlalchemy_hawdb-0.22.0.dist-info/top_level.txt,sha256=DSRzcmNpZj4SJkt_sDro6bAc0WOYZTIU2JW3jprKViU,17
+sqlalchemy_hawdb-0.22.0.dist-info/RECORD,,

sqlalchemy_hawdb-0.22.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sqlalchemy_hawdb-0.22.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.dialects]
+hawdb = sqlalchemy_hawdb.dialect:HawDBDialect

sqlalchemy_hawdb-0.22.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sqlalchemy_hawdb