sqlalchemy-seerdb 0.2.0__tar.gz

sqlalchemy_seerdb-0.2.0/LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Lemenkov <lemenkov@gmail.com>
+
+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.

sqlalchemy_seerdb-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-seerdb
+Version: 0.2.0
+Summary: SQLAlchemy dialect for the seerdb driver
+Author-email: Peter Lemenkov <lemenkov@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/seerdb/sqlalchemy-seerdb
+Project-URL: Source, https://github.com/seerdb/sqlalchemy-seerdb
+Keywords: sqlalchemy,dialect,database,dbapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSES/MIT.txt
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: seerdb>=2.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+<!--
+SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+SPDX-License-Identifier: MIT
+-->
+
+# sqlalchemy-seerdb
+
+A SQLAlchemy dialect for the [seerdb](https://github.com/seerdb/seerdb) driver.
+
+```python
+import sqlalchemy as sa
+
+engine = sa.create_engine('oracle+seerdb://user:password@host:1521/?service_name=XE')
+```
+
+## Why this exists
+
+The SQL is nothing new — this inherits SQLAlchemy's built-in compiler, DDL and
+reflection wholesale and supplies only what is specific to this DBAPI. What it
+adds is **reach**.
+
+seerdb speaks the wire protocol itself, in pure Python, with no vendor client
+libraries. The alternatives connect directly only to newer servers and fall back
+to loading vendor client libraries for anything older. So this dialect covers a
+range that otherwise needs a native client installed:
+
+| Server | This dialect | Direct connection elsewhere |
+|--------|--------------|-----------------------------|
+| 8i, 9i, 10g, 11g | yes | no, needs vendor client libraries |
+| 12.1 and later   | yes | yes |
+
+Verified against live servers: an 11g instance reports
+`server_version_info == (11, 2, 0, 2, 0)` and a current one reports
+`(23, 1, 162, 0, 0)`, both over the same dialect.
+
+If you are on a modern server and can install a native client, the dialects that
+ship with SQLAlchemy are the better-trodden path. This one is for the cases they
+do not reach.
+
+## Status
+
+Early. Connections, Core `select`, DDL, parameter binding and reflection all
+work against live servers — `has_table`, `get_columns`, `get_pk_constraint` and
+`autoload_with` round-trip.
+
+The current target is SQLAlchemy's dialect compliance suite. Progress is tracked
+under the [SQLAlchemy conformance](https://github.com/seerdb/sqlalchemy-seerdb/milestone/1)
+milestone.
+
+## Running the tests
+
+The suite is SQLAlchemy's dialect compliance suite, which upstream names as the
+target for third-party dialects. It is entirely live-database driven — there is
+no offline mode — so point it at a server:
+
+```bash
+pytest --dburi "oracle+seerdb://user:password@host:1521/?service_name=XE"
+```
+
+Run it from the repository root. `test.cfg` has to be found in the working
+directory: SQLAlchemy's plugin reads it with configparser and does not look at
+`pyproject.toml`.
+
+### One setup step, and it needs a DBA
+
+The suite expects a second namespace called `test_schema`, which on this backend
+is a **username**, and the test account must be able to create and drop tables
+inside it. Skipping this does not fail a handful of tests — every test in
+`ComponentReflectionTest` errors in setup, because they share a fixture that
+builds tables there.
+
+The test account cannot create it (`ORA-01031`), so run this as a DBA once:
+
+```sql
+CREATE USER test_schema IDENTIFIED BY test_schema;
+GRANT CREATE SESSION TO test_schema;
+ALTER USER test_schema QUOTA UNLIMITED ON USERS;
+
+-- so the test account can build and drop the fixtures inside that schema
+GRANT CREATE ANY TABLE, DROP ANY TABLE, SELECT ANY TABLE, INSERT ANY TABLE,
+      UPDATE ANY TABLE, DELETE ANY TABLE, CREATE ANY INDEX, DROP ANY INDEX,
+      CREATE ANY VIEW, DROP ANY VIEW, CREATE ANY SEQUENCE, DROP ANY SEQUENCE,
+      COMMENT ANY TABLE, ANALYZE ANY TO <your test user>;
+```
+
+Those `ANY` privileges are broad. They are fine on a throwaway test instance —
+CI creates the namespace in a container it discards — but narrow them before
+granting on anything long-lived.
+
+## Connect string
+
+Everything after `?` is passed through to `seerdb.connect`, with integers and
+booleans coerced:
+
+```
+oracle+seerdb://user:password@host:1521/?service_name=XE
+oracle+seerdb://user:password@host:1521/?sid=XE&timeout=5000
+```
+
+## Licence
+
+MIT. This repository is [REUSE](https://reuse.software/) compliant.

sqlalchemy_seerdb-0.2.0/README.md

@@ -0,0 +1,102 @@
+<!--
+SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+SPDX-License-Identifier: MIT
+-->
+
+# sqlalchemy-seerdb
+
+A SQLAlchemy dialect for the [seerdb](https://github.com/seerdb/seerdb) driver.
+
+```python
+import sqlalchemy as sa
+
+engine = sa.create_engine('oracle+seerdb://user:password@host:1521/?service_name=XE')
+```
+
+## Why this exists
+
+The SQL is nothing new — this inherits SQLAlchemy's built-in compiler, DDL and
+reflection wholesale and supplies only what is specific to this DBAPI. What it
+adds is **reach**.
+
+seerdb speaks the wire protocol itself, in pure Python, with no vendor client
+libraries. The alternatives connect directly only to newer servers and fall back
+to loading vendor client libraries for anything older. So this dialect covers a
+range that otherwise needs a native client installed:
+
+| Server | This dialect | Direct connection elsewhere |
+|--------|--------------|-----------------------------|
+| 8i, 9i, 10g, 11g | yes | no, needs vendor client libraries |
+| 12.1 and later   | yes | yes |
+
+Verified against live servers: an 11g instance reports
+`server_version_info == (11, 2, 0, 2, 0)` and a current one reports
+`(23, 1, 162, 0, 0)`, both over the same dialect.
+
+If you are on a modern server and can install a native client, the dialects that
+ship with SQLAlchemy are the better-trodden path. This one is for the cases they
+do not reach.
+
+## Status
+
+Early. Connections, Core `select`, DDL, parameter binding and reflection all
+work against live servers — `has_table`, `get_columns`, `get_pk_constraint` and
+`autoload_with` round-trip.
+
+The current target is SQLAlchemy's dialect compliance suite. Progress is tracked
+under the [SQLAlchemy conformance](https://github.com/seerdb/sqlalchemy-seerdb/milestone/1)
+milestone.
+
+## Running the tests
+
+The suite is SQLAlchemy's dialect compliance suite, which upstream names as the
+target for third-party dialects. It is entirely live-database driven — there is
+no offline mode — so point it at a server:
+
+```bash
+pytest --dburi "oracle+seerdb://user:password@host:1521/?service_name=XE"
+```
+
+Run it from the repository root. `test.cfg` has to be found in the working
+directory: SQLAlchemy's plugin reads it with configparser and does not look at
+`pyproject.toml`.
+
+### One setup step, and it needs a DBA
+
+The suite expects a second namespace called `test_schema`, which on this backend
+is a **username**, and the test account must be able to create and drop tables
+inside it. Skipping this does not fail a handful of tests — every test in
+`ComponentReflectionTest` errors in setup, because they share a fixture that
+builds tables there.
+
+The test account cannot create it (`ORA-01031`), so run this as a DBA once:
+
+```sql
+CREATE USER test_schema IDENTIFIED BY test_schema;
+GRANT CREATE SESSION TO test_schema;
+ALTER USER test_schema QUOTA UNLIMITED ON USERS;
+
+-- so the test account can build and drop the fixtures inside that schema
+GRANT CREATE ANY TABLE, DROP ANY TABLE, SELECT ANY TABLE, INSERT ANY TABLE,
+      UPDATE ANY TABLE, DELETE ANY TABLE, CREATE ANY INDEX, DROP ANY INDEX,
+      CREATE ANY VIEW, DROP ANY VIEW, CREATE ANY SEQUENCE, DROP ANY SEQUENCE,
+      COMMENT ANY TABLE, ANALYZE ANY TO <your test user>;
+```
+
+Those `ANY` privileges are broad. They are fine on a throwaway test instance —
+CI creates the namespace in a container it discards — but narrow them before
+granting on anything long-lived.
+
+## Connect string
+
+Everything after `?` is passed through to `seerdb.connect`, with integers and
+booleans coerced:
+
+```
+oracle+seerdb://user:password@host:1521/?service_name=XE
+oracle+seerdb://user:password@host:1521/?sid=XE&timeout=5000
+```
+
+## Licence
+
+MIT. This repository is [REUSE](https://reuse.software/) compliant.

sqlalchemy_seerdb-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlalchemy-seerdb"
+version = "0.2.0"
+description = "SQLAlchemy dialect for the seerdb driver"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSES/MIT.txt"]
+requires-python = ">=3.10"
+authors = [{ name = "Peter Lemenkov", email = "lemenkov@gmail.com" }]
+keywords = ["sqlalchemy", "dialect", "database", "dbapi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+]
+dependencies = ["SQLAlchemy>=2.0", "seerdb>=2.5.0"]
+
+[project.urls]
+Homepage = "https://github.com/seerdb/sqlalchemy-seerdb"
+Source = "https://github.com/seerdb/sqlalchemy-seerdb"
+
+# How SQLAlchemy finds the dialect: this is what makes the URL prefix
+# `oracle+seerdb://` resolve to the class below.
+[project.entry-points."sqlalchemy.dialects"]
+"oracle.seerdb" = "sqlalchemy_seerdb.seerdb:SeerdbDialect"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+include = ["sqlalchemy_seerdb*"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.pytest.ini_options]
+addopts = "--tb=short"
+testpaths = ["test"]
+python_files = ["test_*.py"]

sqlalchemy_seerdb-0.2.0/setup.cfg

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

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb/__init__.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+
+"""A SQLAlchemy dialect for the seerdb driver.
+
+Registered through the ``sqlalchemy.dialects`` entry point, so a URL of
+``oracle+seerdb://user:password@host:port/?service_name=…`` selects it.
+
+The SQL that goes over the wire is the same dialect SQLAlchemy already speaks,
+so this package inherits the built-in compiler, DDL and reflection wholesale and
+supplies only what is specific to this DBAPI. What it adds is *reach*: seerdb
+speaks the wire protocol itself, so the dialect works against server versions
+that the alternatives can only reach by loading vendor client libraries.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy_seerdb.seerdb import SeerdbDialect
+
+__all__ = ['SeerdbDialect', '__version__']
+
+__version__ = '0.2.0'

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb/provision.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+
+"""Provisioning hooks for SQLAlchemy's dialect compliance suite.
+
+The suite asks the dialect how to do a handful of things it cannot express in
+portable SQL — create a temporary table, reset a connection's default schema,
+and so on. Each hook is looked up by the URL's *backend* name, which is
+``oracle`` here, and a hook with no registration raises `NotImplementedError`
+before the test reaches the database. That is what made the whole
+`ComponentReflectionTest` class error out in setup.
+
+Only the hooks the suite actually asks for are registered. The ones SQLAlchemy
+bundles for this backend are written around a different driver's connection
+API and its own CI's throwaway-database model, neither of which applies: this
+suite runs against an existing account, so there is nothing to create or reap.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.testing.provision import (
+    set_default_schema_on_connection,
+    temp_table_keyword_args,
+)
+
+
+@temp_table_keyword_args.for_db('oracle')
+def _temp_table_keyword_args(cfg, eng):
+    """How this backend spells a temporary table.
+
+    Its temporary tables are *global*: the definition is permanent and shared,
+    only the rows are session-private. The suite wants rows to outlive the
+    transaction that inserted them, so the table has to preserve them on commit
+    rather than the default of deleting them.
+    """
+    return {
+        'prefixes': ['GLOBAL TEMPORARY'],
+        'oracle_on_commit': 'PRESERVE ROWS',
+    }
+
+
+@set_default_schema_on_connection.for_db('oracle')
+def _set_default_schema_on_connection(cfg, dbapi_connection, schema_name):
+    """Point a connection's unqualified name resolution at ``schema_name``."""
+    cursor = dbapi_connection.cursor()
+    cursor.execute(f'ALTER SESSION SET CURRENT_SCHEMA={schema_name}')
+    cursor.close()

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb/requirements.py

@@ -0,0 +1,257 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+
+"""Which parts of the compliance suite apply to this backend.
+
+The suite assumes a capable backend and asks here about anything a particular
+one may not do. Left at the defaults, features this backend simply does not have
+are counted as **failures** rather than **skips**, which buries the real work
+under noise.
+
+Every entry below was checked against a live server rather than assumed, and
+each says which it is: something the backend genuinely cannot do, or something
+it can do that the suite is conservative about by default. Entries for our own
+unfinished work do **not** belong here — a dialect gap is a bug to fix, and
+silencing it here would hide it.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.testing import exclusions
+from sqlalchemy.testing.requirements import SuiteRequirements
+
+
+class Requirements(SuiteRequirements):
+    # --- things the backend genuinely does not have -----------------------
+
+    @property
+    def time(self):
+        """No standalone time-of-day column type.
+
+        `CREATE TABLE t (c TIME)` is rejected outright with "invalid datatype".
+        A time of day is stored inside a date or timestamp instead, so the
+        suite's TIME round-trips cannot apply.
+        """
+        return exclusions.closed()
+
+    @property
+    def time_microseconds(self):
+        """Follows from there being no time type at all."""
+        return exclusions.closed()
+
+    @property
+    def datetime_microseconds(self):
+        """The plain date/time type has one-second resolution.
+
+        Verified: a value carrying microseconds comes back with them zeroed,
+        because that type has no sub-second component. The timestamp type does
+        keep them — see below — so this is a property of the type the suite
+        exercises here, not of the backend as a whole.
+        """
+        return exclusions.closed()
+
+    @property
+    def symbol_names_w_double_quote(self):
+        """A double quote cannot appear in an identifier at all.
+
+        Not a quoting bug on our side — the generated DDL is correct, doubling
+        the inner quote the way SQL says to. The server rejects it anyway:
+
+            CREATE TABLE "quote "" two" (...)
+            ORA-25716: The identifier contains a double quotation mark (")
+
+        A single quote in an identifier is fine, so this is specifically about
+        the double quote.
+        """
+        return exclusions.closed()
+
+    @property
+    def expressions_against_unbounded_text(self):
+        """An unbounded text column cannot appear in a WHERE clause.
+
+        Verified: comparing one is refused outright.
+
+            select 1 from t where clob_column = 'x'
+            ORA-22848: cannot use CLOB type as comparison key
+
+        Such a column has to be converted first, which is a different query
+        from the one the suite writes, so these comparisons cannot apply.
+        """
+        return exclusions.closed()
+
+    @property
+    def empty_strings_varchar(self):
+        """An empty string is not a value here — it is NULL.
+
+        Verified: inserting `''` into a VARCHAR2 and reading it back gives NULL,
+        and `v IS NULL` is true. This is the backend's own rule about the empty
+        string, not a driver or dialect choice, so a test that round-trips one
+        cannot apply.
+        """
+        return exclusions.closed()
+
+    @property
+    def empty_strings_text(self):
+        """The same rule, verified separately on an unbounded text column."""
+        return exclusions.closed()
+
+    @property
+    def unbounded_varchar(self):
+        """A bounded character column must say how long it is.
+
+            CREATE TABLE t (one VARCHAR2)
+            ORA-00906: missing left parenthesis
+
+        An unbounded *text* column is a different type and does work — see the
+        CLOB round trips, which pass — so this is specifically about declaring a
+        varchar with no length.
+        """
+        return exclusions.closed()
+
+    @property
+    def parens_in_union_contained_select_wo_limit_offset(self):
+        """A parenthesised branch of a UNION cannot carry its own ORDER BY.
+
+            (SELECT id FROM t ORDER BY id) UNION (SELECT id FROM t ORDER BY id)
+            ORA-00907: missing right parenthesis
+
+        SQLAlchemy's own requirement documents this as failing on this backend:
+        without a LIMIT or OFFSET nothing wraps the branch in a subquery, and
+        the bare form is a syntax error here.
+        """
+        return exclusions.closed()
+
+    @property
+    def parens_in_union_contained_select_w_limit_offset(self):
+        """The same with a row limit, which is refused just as firmly.
+
+        (SELECT ... ORDER BY id FETCH FIRST 1 ROWS ONLY) UNION (...)
+        ORA-00900: invalid SQL statement
+        """
+        return exclusions.closed()
+
+    # --- things it can do that the suite is conservative about ------------
+
+    @property
+    def temp_table_names(self):
+        """Temporary tables can be listed by name.
+
+        Off by default in the suite. This backend's temporary tables are
+        *global*: the definition is a permanent, ordinary catalog entry — only
+        the rows are session-private — so listing them is no different from
+        listing any other table. Verified: a `CREATE GLOBAL TEMPORARY TABLE`
+        appears in `user_tables` with `TEMPORARY = 'Y'`, and
+        `Inspector.get_temp_table_names()` returns it, while `get_table_names()`
+        correctly leaves it out.
+
+        Saying so matters beyond the one test that asks directly. Left closed,
+        the suite still *creates* its temporary table — that is governed by the
+        separate `temp_table_reflection`, which is on — but then expects
+        reflection not to mention it. Reflection here does mention it, correctly,
+        and the disagreement was the single largest source of failures in the
+        suite: 72 of them, across ten reflection tests that have nothing to do
+        with temporary tables as such.
+        """
+        return exclusions.open()
+
+    @property
+    def has_temp_table(self):
+        """A single temporary table can be checked by name.
+
+        Follows from the above and verified the same way:
+        `Inspector.has_table()` on a global temporary table returns True.
+        """
+        return exclusions.open()
+
+    @property
+    def views(self):
+        """Views exist, so the suite may build its own and expect to see them.
+
+        Off by default. Verified: a view created here is listed by
+        `Inspector.get_view_names()` and its text comes back from
+        `get_view_definition()`. Left closed, the fixture never creates the
+        suite's views and `test_get_view_names` compares an empty list against
+        the three names it expected to find.
+        """
+        return exclusions.open()
+
+    @property
+    def unique_constraints_reflect_as_index(self):
+        """A UNIQUE constraint is backed by an index this backend creates for it,
+        and reflection reports that index.
+
+        Verified: `UniqueConstraint('u', name='v_parent_u_uq')` reflects through
+        `get_indexes()` as `{'name': 'v_parent_u_uq', 'unique': True, ...}`.
+        The suite's expected index sets include such entries only when this is
+        declared, so left at the default every reflected unique constraint was
+        an unexplained extra — the single largest group of remaining failures.
+
+        A FOREIGN KEY, by contrast, gets no index here, so
+        `foreign_keys_reflect_as_index` stays at its closed default. Also
+        verified rather than assumed.
+        """
+        return exclusions.open()
+
+    @property
+    def reflect_indexes_with_ascdesc_as_expression(self):
+        """A DESC column in an index reflects as an expression, not a column.
+
+        Verified: `Index('ix', text('q DESC'))` comes back as
+        `column_names: [None], expressions: ['"Q"'],
+        column_sorting: {'"Q"': ('desc',)}`. That is the shape this requirement
+        describes, and the shape the suite expects once it is declared.
+        """
+        return exclusions.open()
+
+    @property
+    def reflect_table_options(self):
+        """Table options can be reflected.
+
+        Verified: `get_table_options()` returns a dict, e.g.
+        `{'oracle_tablespace': 'USERS'}`. Off by default the suite expects a
+        `NotImplementedError` instead, and fails on "Callable did not raise".
+        """
+        return exclusions.open()
+
+    @property
+    def reflects_pk_names(self):
+        """A primary-key constraint's name survives reflection.
+
+        Verified: an unnamed key reflects as its system name (`sys_c0012860`) and
+        an explicitly named one keeps that name. Off by default the suite treats
+        the name check as expected-to-fail, and reports an "Unexpected success"
+        when it passes.
+        """
+        return exclusions.open()
+
+    @property
+    def timestamp_microseconds(self):
+        """The timestamp type keeps sub-second precision.
+
+        Off by default in the suite. Verified: a value with 123456 microseconds
+        round-trips intact through a `TIMESTAMP(6)` column.
+        """
+        return exclusions.open()
+
+    # ----- what needs a 12c server -----
+
+    @staticmethod
+    def _has_identity_columns(config):
+        # The Oracle dialect renders an autoincrement column as an identity
+        # column, which the server has from 12c. Before that the column is a
+        # plain NUMBER, an INSERT that leaves it out fails with ORA-01400, and
+        # there is no other way to say "generate the key" short of a sequence
+        # plus trigger, which the suite does not model.
+        return config.db.dialect.server_version_info >= (12,)
+
+    @property
+    def autoincrement_insert(self):
+        return exclusions.only_if(
+            self._has_identity_columns, 'autoincrement needs identity columns (12c+)'
+        )
+
+    @property
+    def autoincrement_without_sequence(self):
+        return exclusions.only_if(
+            self._has_identity_columns, 'autoincrement needs identity columns (12c+)'
+        )

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb/seerdb.py

@@ -0,0 +1,377 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+
+r"""The seerdb dialect.
+
+Connect string::
+
+    oracle+seerdb://user:password@host:port/?service_name=ORCLPDB1
+    oracle+seerdb://user:password@host:port/?sid=XE
+
+Query-string arguments are passed to :func:`seerdb.connect` after the ones the
+URL already carries. Integers and booleans are coerced, so ``?timeout=5000`` and
+``?autocommit=true`` do the expected thing.
+
+This subclasses the *generic* dialect rather than one of the bundled
+DBAPI-specific ones: those carry type handlers written against a different
+driver's extension API, none of which applies here. What is left to supply is
+small, because the DBAPI is already conformant and its paramstyle already
+matches what the generic dialect emits.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import seerdb
+from sqlalchemy import types as sqltypes
+from sqlalchemy import util
+from sqlalchemy.dialects.oracle import base as _oracle_base
+from sqlalchemy.dialects.oracle.base import (
+    OracleCompiler,
+    OracleDialect,
+    OracleExecutionContext,
+)
+from sqlalchemy.dialects.oracle.types import _OracleDate
+from sqlalchemy.engine import cursor as _cursor
+from sqlalchemy.engine import interfaces
+
+if TYPE_CHECKING:
+    from sqlalchemy.engine.url import URL
+
+# Query-string arguments that are not strings on the driver's side.
+_INT_ARGS = frozenset({'port', 'timeout', 'sdu', 'field_version', 'purity', 'fetch'})
+_BOOL_ARGS = frozenset({'autocommit', 'ssl', 'prelim'})
+_TRUTHY = frozenset({'1', 'true', 'yes', 'on'})
+
+
+def _coerce(key: str, value: str) -> Any:
+    if key in _INT_ARGS:
+        return int(value)
+    if key in _BOOL_ARGS:
+        return value.strip().lower() in _TRUTHY
+    return value
+
+
+class _SeerdbDate(_OracleDate):
+    """A `Date` column read back as a `date`, not a `datetime`.
+
+    This backend has no date-only type: a DATE always carries a time of day, so
+    the driver reads one back as a `datetime` — correctly, since that is what
+    the column holds. A column the schema declares as `Date` is asking for the
+    date part, so it is taken here.
+
+    The generic dialect leaves this to the driver, because the ones it ships
+    with are configured to do the narrowing themselves.
+    """
+
+    def result_processor(self, dialect, coltype):
+        def process(value):
+            return value.date() if value is not None else None
+
+        return process
+
+
+class SeerdbExecutionContext(OracleExecutionContext):
+    """Turns this backend's RETURNING into the rows SQLAlchemy expects.
+
+    There is no result set for RETURNING here. The compiler already emits the
+    form the server wants — `RETURNING id INTO :ret_0` — and the values come
+    back on those binds afterwards, which is a shape SQLAlchemy has no idea
+    what to do with on its own: it asks the cursor for rows and finds none.
+
+    So the values are collected off the binds after execution and handed back
+    as a fully buffered result, which is what the caller was expecting all
+    along. `inserted_primary_key` rides on the same path.
+    """
+
+    out_parameters: dict | None = None
+
+    def _returning_var_type(self, index):
+        """The bind type for one returned column, from what the query says."""
+        columns = self.compiled._result_columns
+        if index < len(columns):
+            sqla_type = columns[index].type
+            try:
+                impl = sqla_type.dialect_impl(self.dialect)
+                dbapi_type = impl.get_dbapi_type(self.dialect.loaded_dbapi)
+            except (AttributeError, NotImplementedError):
+                dbapi_type = None
+            # Every numeric column maps to the same database type, so the
+            # receiver has to be bound with the Python type the query asked for
+            # or the value comes back as whichever one that database type
+            # decodes to. The driver honours the request (seerdb#688), so this
+            # is all it takes.
+            try:
+                if sqla_type.python_type is float:
+                    return float
+            except (AttributeError, NotImplementedError):
+                pass
+            if dbapi_type is not None:
+                return dbapi_type
+        # A returned column whose type does not map cleanly still has to be
+        # bound as something; a string accepts whatever comes back.
+        return str
+
+    def pre_exec(self):
+        super().pre_exec()
+        compiled = self.compiled
+        if not getattr(compiled, '_oracle_returning', False):
+            return
+        # Bind a receiver per returned column, in the order the compiler named
+        # them, and hand them to the driver in place of the plain values.
+        self.out_parameters = {}
+        names = [f'ret_{i}' for i in range(len(compiled._result_columns))]
+        for index, name in enumerate(names):
+            var = self.cursor.var(self._returning_var_type(index))
+            self.out_parameters[name] = var
+            if isinstance(self.parameters, list):
+                for parameter_set in self.parameters:
+                    parameter_set[name] = var
+            else:
+                self.parameters[name] = var
+
+    def get_out_parameter_values(self, names):
+        assert self.out_parameters is not None
+        return [self.out_parameters[name].getvalue() for name in names]
+
+    def fetchall_for_returning(self, cursor):
+        """The returned values, shaped as rows.
+
+        A receiver reports what it received as a list, one entry per row the
+        statement affected, so even a single-row statement arrives wrapped. An
+        array execute goes further and reports per iteration, which is read one
+        position at a time and concatenated: iterations come back in the order
+        the rows were submitted, which is the parameter order the caller can ask
+        to have the rows in.
+        """
+        if not self.out_parameters:
+            return []
+        iterations = len(self.parameters) if self.executemany else 1
+        columns = []
+        for index in range(len(self.compiled._result_columns)):
+            receiver = self.out_parameters[f'ret_{index}']
+            values: list = []
+            for iteration in range(iterations):
+                received = receiver.getvalue(iteration)
+                values += received if isinstance(received, list) else [received]
+            columns.append(values)
+        return list(zip(*columns)) if columns else []
+
+    def post_exec(self):
+        compiled = self.compiled
+        if compiled is not None and getattr(compiled, '_oracle_returning', False):
+            self.cursor_fetch_strategy = _cursor.FullyBufferedCursorFetchStrategy(
+                self.cursor,
+                [(entry.keyname, None) for entry in compiled._result_columns],
+                initial_buffer=self.fetchall_for_returning(self.cursor),
+            )
+        super().post_exec()
+
+
+class SeerdbCompiler(OracleCompiler):
+    """Renders bind names this server will actually accept.
+
+    The server is far pickier about bind names than SQL generally is. A name may
+    not start with a digit or an underscore, and a good many punctuation
+    characters are rejected outright with "invalid host/bind variable name" —
+    which is what a name like ``/slashes/`` or ``q?marks`` produces. Names like
+    those are not contrived: they come from column names, and a caller who names
+    a column that way gets a bind named after it.
+
+    Two mechanisms are needed, because neither covers the other:
+
+    * an escape map, used for the expanded parameters of an ``IN`` clause, where
+      quoting is not available; and
+    * quoting the name outright everywhere else, which also handles reserved
+      words and the illegal leading characters.
+    """
+
+    # The generic compiler escapes eight characters. These three more are
+    # rejected by this server and have to travel as an escape rather than a
+    # quoted name, because an expanded parameter cannot be quoted.
+    bindname_escape_characters = util.immutabledict(
+        {
+            '%': 'P',
+            '(': 'A',
+            ')': 'Z',
+            ':': 'C',
+            '.': 'C',
+            '[': 'C',
+            ']': 'C',
+            ' ': 'C',
+            '\\': 'C',
+            '/': 'C',
+            '?': 'C',
+        }
+    )
+
+    def bindparam_string(self, name, **kw):
+        """Rewrite a bind name into one the server accepts.
+
+        Escaping only, never quoting. The quoted form `:"name"` is what the
+        bundled dialects lean on, but this driver does not parse it — the
+        placeholder goes unrecognised and the value is reported as never
+        provided. Escaping covers the same ground and works everywhere,
+        including the expanded parameters of an `IN` clause, where quoting is
+        not available anyway.
+
+        The original name is recorded in `escaped_from` so the value still
+        binds to it.
+        """
+        if not kw.get('escaped_from'):
+            translated = name
+            if self._bind_translate_re.search(name):
+                translated = self._bind_translate_re.sub(
+                    lambda m: self._bind_translate_chars[m.group(0)], name
+                )
+            # Escaping the characters is not the whole job. A reserved word
+            # (`desc`) and an illegal leading character (a digit or an
+            # underscore) are both still rejected, and both are what quoting
+            # would normally have solved. A prefix does the same work: the name
+            # only has to be unique and legal.
+            if self.preparer._bindparam_requires_quotes(translated):
+                translated = 'D' + translated
+            if translated != name:
+                kw['escaped_from'] = name
+                name = translated
+        return super().bindparam_string(name, **kw)
+
+
+class SeerdbDialect(OracleDialect):
+    """SQLAlchemy dialect driving the seerdb DBAPI."""
+
+    name = 'oracle'
+    driver = 'seerdb'
+    statement_compiler = SeerdbCompiler
+    execution_ctx_cls = SeerdbExecutionContext
+
+    # RETURNING works through SeerdbExecutionContext above, which collects the
+    # values off the OUT binds the compiler emits and presents them as rows.
+    insert_returning = True
+    update_returning = True
+    delete_returning = True
+    # An array insert reports its returned values per iteration, in the order
+    # the rows were submitted, so the rows can be handed back in parameter order
+    # (seerdb#687).
+    insert_executemany_returning = True
+    insert_executemany_returning_sort_by_parameter_order = True
+
+    # Pass a bind's type to the driver rather than leaving it to be guessed from
+    # the value. A `None` carries no type, so without this the server infers CHAR
+    # and refuses to compare it to a DATE or a NUMBER column (ORA-00932). The
+    # driver takes the declaration through setinputsizes (seerdb#696) and sends
+    # the value as the declared type (seerdb#701); the hook below hands it over.
+    bind_typing = interfaces.BindTyping.SETINPUTSIZES
+
+    # The driver hands a NUMBER back as a Decimal, not a float. Saying so is
+    # what makes SQLAlchemy convert: a column declared Float asks for a float and
+    # gets one, and a Numeric column is left as the Decimal it already is. Left
+    # at the default, SQLAlchemy assumes the driver returns floats and installs
+    # no processor either way, so a Float column came back holding a Decimal.
+    supports_native_decimal = True
+
+    # As the base dialect's, plus the date narrowing above.
+    colspecs: ClassVar[dict] = {**_oracle_base.colspecs, sqltypes.Date: _SeerdbDate}
+
+    # No SQL is generated differently from the base dialect, so cached
+    # statements stay valid.
+    supports_statement_cache = True
+
+    def do_set_input_sizes(self, cursor, list_of_tuples, context):
+        """Declare the binds' types for the statement about to run.
+
+        SQLAlchemy hands over one `(name, dbapi_type, sqla_type)` per bind, in
+        order. Only the ones with a type to declare are passed on; a bind with
+        no `dbapi_type` is left for the driver to read off its value, which it
+        does perfectly well whenever the value can say.
+        """
+        declared = {}
+        for name, dbapi_type, sqla_type in list_of_tuples:
+            wanted = self._declared_bind_type(dbapi_type, sqla_type)
+            if wanted is not None:
+                declared[name] = wanted
+        if declared:
+            cursor.setinputsizes(**declared)
+
+    @staticmethod
+    def _declared_bind_type(dbapi_type, sqla_type):
+        """The driver type to declare for one bind, or None to leave it alone.
+
+        Mostly the DBAPI type SQLAlchemy names. The exception is a value with a
+        time of day: the generic mapping asks for the date type, which on this
+        backend is seven bytes and holds no fraction of a second, so declaring it
+        would round the value on its way in. The timestamp type is the lossless
+        one, and the server narrows it for a column that cannot hold the extra
+        precision, so it is the right thing to declare for the whole family.
+
+        A `Date` column keeps the date type: it has no time of day to lose, and
+        saying so is what makes an untyped NULL comparable to one.
+        """
+        if dbapi_type is None:
+            return None
+        # Through the affinity, not the type itself: a TypeDecorator wrapping a
+        # timestamp is still a timestamp, and testing the wrapper would miss it.
+        affinity = getattr(sqla_type, '_type_affinity', None)
+        if affinity is not None and issubclass(affinity, sqltypes.DateTime):
+            return seerdb.DB_TYPE_TIMESTAMP
+        return dbapi_type
+
+    @classmethod
+    def import_dbapi(cls) -> Any:
+        import seerdb
+
+        return seerdb
+
+    # Kept for SQLAlchemy 1.4 callers, which look for the old spelling.
+    @classmethod
+    def dbapi(cls) -> Any:
+        return cls.import_dbapi()
+
+    def create_connect_args(self, url: URL) -> tuple[list, dict]:
+        options: dict[str, Any] = {}
+        if url.host:
+            options['host'] = url.host
+        if url.port:
+            options['port'] = url.port
+        if url.username:
+            options['user'] = url.username
+        if url.password:
+            options['password'] = url.password
+        # A bare path is the service name, so both the modern URL form and the
+        # query-string form work.
+        if url.database:
+            options.setdefault('service_name', url.database)
+        # The driver commits every statement unless told otherwise, which would
+        # make SQLAlchemy's transactions, and its rollback, mean nothing. The
+        # DBAPI contract SQLAlchemy builds on is autocommit off, so that is the
+        # default here; ``?autocommit=true`` in the URL still turns it on.
+        options['autocommit'] = False
+        for key, value in url.query.items():
+            # A repeated key arrives as a tuple; the driver takes one value.
+            options[key] = _coerce(
+                key, value[-1] if isinstance(value, tuple) else value
+            )
+        return ([], options)
+
+    def _get_server_version_info(self, connection: Any) -> tuple[int, ...]:
+        # The driver already decodes the packed release the server sends at
+        # login, so there is no round trip to make here.
+        raw = getattr(connection.connection, 'version', None)
+        if not raw:
+            return ()
+        parts = []
+        for piece in str(raw).split('.'):
+            try:
+                parts.append(int(piece))
+            except ValueError:
+                break
+        return tuple(parts)
+
+    def is_disconnect(self, e: Exception, connection: Any, cursor: Any) -> bool:
+        if isinstance(e, self.loaded_dbapi.InterfaceError):
+            return True
+        return super().is_disconnect(e, connection, cursor)
+
+
+dialect = SeerdbDialect

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-seerdb
+Version: 0.2.0
+Summary: SQLAlchemy dialect for the seerdb driver
+Author-email: Peter Lemenkov <lemenkov@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/seerdb/sqlalchemy-seerdb
+Project-URL: Source, https://github.com/seerdb/sqlalchemy-seerdb
+Keywords: sqlalchemy,dialect,database,dbapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSES/MIT.txt
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: seerdb>=2.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+<!--
+SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+SPDX-License-Identifier: MIT
+-->
+
+# sqlalchemy-seerdb
+
+A SQLAlchemy dialect for the [seerdb](https://github.com/seerdb/seerdb) driver.
+
+```python
+import sqlalchemy as sa
+
+engine = sa.create_engine('oracle+seerdb://user:password@host:1521/?service_name=XE')
+```
+
+## Why this exists
+
+The SQL is nothing new — this inherits SQLAlchemy's built-in compiler, DDL and
+reflection wholesale and supplies only what is specific to this DBAPI. What it
+adds is **reach**.
+
+seerdb speaks the wire protocol itself, in pure Python, with no vendor client
+libraries. The alternatives connect directly only to newer servers and fall back
+to loading vendor client libraries for anything older. So this dialect covers a
+range that otherwise needs a native client installed:
+
+| Server | This dialect | Direct connection elsewhere |
+|--------|--------------|-----------------------------|
+| 8i, 9i, 10g, 11g | yes | no, needs vendor client libraries |
+| 12.1 and later   | yes | yes |
+
+Verified against live servers: an 11g instance reports
+`server_version_info == (11, 2, 0, 2, 0)` and a current one reports
+`(23, 1, 162, 0, 0)`, both over the same dialect.
+
+If you are on a modern server and can install a native client, the dialects that
+ship with SQLAlchemy are the better-trodden path. This one is for the cases they
+do not reach.
+
+## Status
+
+Early. Connections, Core `select`, DDL, parameter binding and reflection all
+work against live servers — `has_table`, `get_columns`, `get_pk_constraint` and
+`autoload_with` round-trip.
+
+The current target is SQLAlchemy's dialect compliance suite. Progress is tracked
+under the [SQLAlchemy conformance](https://github.com/seerdb/sqlalchemy-seerdb/milestone/1)
+milestone.
+
+## Running the tests
+
+The suite is SQLAlchemy's dialect compliance suite, which upstream names as the
+target for third-party dialects. It is entirely live-database driven — there is
+no offline mode — so point it at a server:
+
+```bash
+pytest --dburi "oracle+seerdb://user:password@host:1521/?service_name=XE"
+```
+
+Run it from the repository root. `test.cfg` has to be found in the working
+directory: SQLAlchemy's plugin reads it with configparser and does not look at
+`pyproject.toml`.
+
+### One setup step, and it needs a DBA
+
+The suite expects a second namespace called `test_schema`, which on this backend
+is a **username**, and the test account must be able to create and drop tables
+inside it. Skipping this does not fail a handful of tests — every test in
+`ComponentReflectionTest` errors in setup, because they share a fixture that
+builds tables there.
+
+The test account cannot create it (`ORA-01031`), so run this as a DBA once:
+
+```sql
+CREATE USER test_schema IDENTIFIED BY test_schema;
+GRANT CREATE SESSION TO test_schema;
+ALTER USER test_schema QUOTA UNLIMITED ON USERS;
+
+-- so the test account can build and drop the fixtures inside that schema
+GRANT CREATE ANY TABLE, DROP ANY TABLE, SELECT ANY TABLE, INSERT ANY TABLE,
+      UPDATE ANY TABLE, DELETE ANY TABLE, CREATE ANY INDEX, DROP ANY INDEX,
+      CREATE ANY VIEW, DROP ANY VIEW, CREATE ANY SEQUENCE, DROP ANY SEQUENCE,
+      COMMENT ANY TABLE, ANALYZE ANY TO <your test user>;
+```
+
+Those `ANY` privileges are broad. They are fine on a throwaway test instance —
+CI creates the namespace in a container it discards — but narrow them before
+granting on anything long-lived.
+
+## Connect string
+
+Everything after `?` is passed through to `seerdb.connect`, with integers and
+booleans coerced:
+
+```
+oracle+seerdb://user:password@host:1521/?service_name=XE
+oracle+seerdb://user:password@host:1521/?sid=XE&timeout=5000
+```
+
+## Licence
+
+MIT. This repository is [REUSE](https://reuse.software/) compliant.

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+LICENSES/MIT.txt
+sqlalchemy_seerdb/__init__.py
+sqlalchemy_seerdb/provision.py
+sqlalchemy_seerdb/requirements.py
+sqlalchemy_seerdb/seerdb.py
+sqlalchemy_seerdb.egg-info/PKG-INFO
+sqlalchemy_seerdb.egg-info/SOURCES.txt
+sqlalchemy_seerdb.egg-info/dependency_links.txt
+sqlalchemy_seerdb.egg-info/entry_points.txt
+sqlalchemy_seerdb.egg-info/requires.txt
+sqlalchemy_seerdb.egg-info/top_level.txt
+test/test_connect_args.py
+test/test_suite.py
+test/test_version.py

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.dialects]
+oracle.seerdb = sqlalchemy_seerdb.seerdb:SeerdbDialect

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb.egg-info/requires.txt

@@ -0,0 +1,5 @@
+SQLAlchemy>=2.0
+seerdb>=2.5.0
+
+[test]
+pytest>=7

sqlalchemy_seerdb-0.2.0/sqlalchemy_seerdb.egg-info/top_level.txt

@@ -0,0 +1 @@
+sqlalchemy_seerdb

sqlalchemy_seerdb-0.2.0/test/test_connect_args.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2025 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+"""The connect arguments the dialect derives from a URL."""
+
+import unittest
+
+from sqlalchemy.engine import make_url
+
+from sqlalchemy_seerdb.seerdb import SeerdbDialect
+
+
+def _options(url):
+    _args, options = SeerdbDialect().create_connect_args(make_url(url))
+    return options
+
+
+class TestAutocommit(unittest.TestCase):
+    """The driver commits every statement by default; SQLAlchemy must not.
+
+    With the driver's default a transaction's rollback undid nothing, which
+    the compliance suite noticed as rows surviving from one test into the
+    next.
+    """
+
+    def test_off_by_default(self):
+        options = _options('oracle+seerdb://u:p@h:1521/?service_name=s')
+        self.assertIs(options['autocommit'], False)
+
+    def test_the_url_can_turn_it_on(self):
+        options = _options('oracle+seerdb://u:p@h:1521/?service_name=s&autocommit=true')
+        self.assertIs(options['autocommit'], True)

sqlalchemy_seerdb-0.2.0/test/test_suite.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+
+"""Run SQLAlchemy's dialect compliance suite against this dialect."""
+
+from sqlalchemy.testing.suite import *

sqlalchemy_seerdb-0.2.0/test/test_version.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
+# SPDX-License-Identifier: MIT
+"""The version lives in two places and they must agree."""
+
+import re
+import unittest
+from pathlib import Path
+
+import sqlalchemy_seerdb
+
+
+class TestVersion(unittest.TestCase):
+    def test_module_and_package_metadata_agree(self):
+        pyproject = (
+            Path(__file__).resolve().parent.parent / 'pyproject.toml'
+        ).read_text()
+        declared = re.search(r'^version = "([^"]+)"', pyproject, re.MULTILINE).group(1)
+        self.assertEqual(sqlalchemy_seerdb.__version__, declared)