sqlalchemy-hawdb 0.22.0__tar.gz

sqlalchemy_hawdb-0.22.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlalchemy-hawdb"
+version = "0.22.0"
+description = "SQLAlchemy dialect for the embedded HawDB database"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+dependencies = ["SQLAlchemy>=2.0,<3.0", "hawdb>=0.22.0,<0.23.0"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.entry-points."sqlalchemy.dialects"]
+hawdb = "sqlalchemy_hawdb.dialect:HawDBDialect"
+
+[project.optional-dependencies]
+test = ["pytest>=8,<9", "ruff>=0.14,<1"]
+
+[tool.setuptools.packages.find]
+include = ["sqlalchemy_hawdb*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

sqlalchemy_hawdb-0.22.0/setup.cfg

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

sqlalchemy_hawdb-0.22.0/sqlalchemy_hawdb/__init__.py

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

sqlalchemy_hawdb-0.22.0/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/sqlalchemy_hawdb.egg-info/PKG-INFO

@@ -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/sqlalchemy_hawdb.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+sqlalchemy_hawdb/__init__.py
+sqlalchemy_hawdb/dialect.py
+sqlalchemy_hawdb.egg-info/PKG-INFO
+sqlalchemy_hawdb.egg-info/SOURCES.txt
+sqlalchemy_hawdb.egg-info/dependency_links.txt
+sqlalchemy_hawdb.egg-info/entry_points.txt
+sqlalchemy_hawdb.egg-info/requires.txt
+sqlalchemy_hawdb.egg-info/top_level.txt
+tests/test_dialect.py
+tests/test_sqlalchemy_integration.py

sqlalchemy_hawdb-0.22.0/sqlalchemy_hawdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sqlalchemy_hawdb-0.22.0/sqlalchemy_hawdb.egg-info/entry_points.txt

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

sqlalchemy_hawdb-0.22.0/sqlalchemy_hawdb.egg-info/requires.txt

@@ -0,0 +1,6 @@
+SQLAlchemy<3.0,>=2.0
+hawdb<0.23.0,>=0.22.0
+
+[test]
+pytest<9,>=8
+ruff<1,>=0.14

sqlalchemy_hawdb-0.22.0/sqlalchemy_hawdb.egg-info/top_level.txt

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

sqlalchemy_hawdb-0.22.0/tests/test_dialect.py

@@ -0,0 +1,89 @@
+from sqlalchemy import (
+    BigInteger,
+    Boolean,
+    Column,
+    LargeBinary,
+    MetaData,
+    Numeric,
+    String,
+    Table,
+    column,
+    select,
+    table,
+)
+from sqlalchemy.engine import make_url
+from sqlalchemy.pool import NullPool, SingletonThreadPool
+from sqlalchemy.schema import CreateTable
+
+from sqlalchemy_hawdb.dialect import HawDBDialect
+
+
+def test_dialect_compiles_positional_dollar_parameters():
+    statement = (
+        select(column("id")).select_from(table("widgets")).where(column("id") == 7)
+    )
+    compiled = statement.compile(dialect=HawDBDialect())
+
+    assert "$1" in str(compiled)
+    assert compiled.positiontup == ["id_1"]
+    assert compiled.params == {"id_1": 7}
+
+
+def test_type_compiler_uses_hawdb_scalar_types():
+    statement = CreateTable(
+        Table(
+            "values_table",
+            MetaData(),
+            Column("id", BigInteger, primary_key=True),
+            Column("enabled", Boolean),
+            Column("amount", Numeric(12, 3)),
+            Column("label", String(40)),
+            Column("payload", LargeBinary),
+        )
+    ).compile(dialect=HawDBDialect())
+
+    sql = str(statement)
+    assert "id BIGINT" in sql
+    assert "enabled BOOLEAN" in sql
+    assert "amount DOUBLE PRECISION" in sql
+    assert "label TEXT" in sql
+    assert "payload BYTEA" in sql
+
+
+def test_url_uses_path_and_read_only_option():
+    dialect = HawDBDialect()
+    args, kwargs = dialect.create_connect_args(
+        make_url("hawdb:////tmp/example.hawdb?read_only=true")
+    )
+
+    assert args == ["/tmp/example.hawdb"]
+    assert kwargs == {"read_only": True, "autocommit": False}
+
+
+def test_memory_url_opens_an_ephemeral_database():
+    args, kwargs = HawDBDialect().create_connect_args(make_url("hawdb:///:memory:"))
+
+    assert args == [None]
+    assert kwargs == {"read_only": False, "autocommit": False}
+
+
+def test_memory_databases_are_pooled_per_thread_but_file_handles_are_not_pooled():
+    memory_url = make_url("hawdb:///:memory:")
+    file_url = make_url("hawdb:////tmp/example.hawdb")
+
+    assert HawDBDialect.get_pool_class(memory_url) is SingletonThreadPool
+    assert HawDBDialect.get_pool_class(file_url) is NullPool
+
+
+def test_dialect_uses_hawdb_native_dbapi():
+    dbapi = HawDBDialect.import_dbapi()
+
+    assert dbapi.paramstyle == "numeric_dollar"
+    assert dbapi.threadsafety == 1
+    assert callable(dbapi.connect)
+
+
+def test_primary_key_index_parser_handles_quoted_commas_and_escaped_quotes():
+    definition = 'CREATE INDEX x ON public.t USING btree ("a,b", "a""b", "p(q)")'
+
+    assert HawDBDialect._index_columns(definition) == ["a,b", 'a"b', "p(q)"]

sqlalchemy_hawdb-0.22.0/tests/test_sqlalchemy_integration.py

@@ -0,0 +1,123 @@
+from sqlalchemy import (
+    Column,
+    Integer,
+    MetaData,
+    String,
+    Table,
+    UniqueConstraint,
+    create_engine,
+    inspect,
+    select,
+)
+from sqlalchemy.engine import URL
+from sqlalchemy.orm import Session, declarative_base
+
+
+def make_engine(path):
+    return create_engine(URL.create("hawdb", database=str(path)))
+
+
+def test_core_create_insert_select_and_reflection(tmp_path):
+    engine = make_engine(tmp_path / "core.hawdb")
+    metadata = MetaData()
+    widgets = Table(
+        "widgets",
+        metadata,
+        Column("id", Integer, primary_key=True, autoincrement=False),
+        Column("name", String(80), nullable=False),
+        UniqueConstraint("name"),
+    )
+    try:
+        metadata.create_all(engine)
+        with engine.begin() as connection:
+            connection.execute(
+                widgets.insert(),
+                [{"id": 1, "name": "first"}, {"id": 2, "name": "second"}],
+            )
+        with engine.connect() as connection:
+            rows = connection.execute(
+                select(widgets.c.id, widgets.c.name).order_by(widgets.c.id)
+            ).all()
+            reordered = connection.execute(
+                select(widgets.c.name, widgets.c.id).order_by(widgets.c.id)
+            )
+            assert list(reordered.keys()) == ["name", "id"]
+            assert reordered.all() == [("first", 1), ("second", 2)]
+
+            empty = connection.execute(
+                select(widgets.c.name, widgets.c.id).where(widgets.c.id < 0)
+            )
+            assert list(empty.keys()) == ["name", "id"]
+            assert empty.all() == []
+        assert rows == [(1, "first"), (2, "second")]
+
+        inspector = inspect(engine)
+        assert "widgets" in inspector.get_table_names()
+        assert [column["name"] for column in inspector.get_columns("widgets")] == [
+            "id",
+            "name",
+        ]
+        assert inspector.get_pk_constraint("widgets")["constrained_columns"] == ["id"]
+        assert [
+            constraint["column_names"]
+            for constraint in inspector.get_unique_constraints("widgets")
+        ] == [["name"]]
+    finally:
+        engine.dispose()
+
+
+def test_transaction_rollback(tmp_path):
+    engine = make_engine(tmp_path / "rollback.hawdb")
+    try:
+        with engine.begin() as connection:
+            connection.exec_driver_sql(
+                "CREATE TABLE events (id BIGINT PRIMARY KEY, name TEXT)"
+            )
+        try:
+            with engine.begin() as connection:
+                connection.exec_driver_sql(
+                    "INSERT INTO events (id, name) VALUES ($1, $2)",
+                    (1, "rolled back"),
+                )
+                raise RuntimeError("force rollback")
+        except RuntimeError:
+            pass
+
+        with engine.connect() as connection:
+            assert connection.exec_driver_sql("SELECT id FROM events").all() == []
+    finally:
+        engine.dispose()
+
+
+def test_orm_session_round_trip(tmp_path):
+    engine = make_engine(tmp_path / "orm.hawdb")
+    base = declarative_base()
+
+    class Entry(base):
+        __tablename__ = "entries"
+
+        id = Column(Integer, primary_key=True, autoincrement=False)
+        value = Column(String(80), nullable=False)
+
+    try:
+        base.metadata.create_all(engine)
+        with Session(engine) as session:
+            session.add(Entry(id=1, value="orm"))
+            session.commit()
+            assert session.scalars(select(Entry.value)).all() == ["orm"]
+    finally:
+        engine.dispose()
+
+
+def test_in_memory_database_survives_connection_checkin():
+    engine = create_engine("hawdb:///:memory:")
+    try:
+        with engine.begin() as connection:
+            connection.exec_driver_sql("CREATE TABLE scratch (id BIGINT PRIMARY KEY)")
+            connection.exec_driver_sql("INSERT INTO scratch (id) VALUES ($1)", (9,))
+        with engine.connect() as connection:
+            assert (
+                connection.exec_driver_sql("SELECT id FROM scratch").scalar_one() == 9
+            )
+    finally:
+        engine.dispose()