adbc-driver-spanner 0.5.0__py3-none-win_amd64.whl

adbc_driver_spanner/__init__.py

@@ -0,0 +1,116 @@
+"""ADBC driver for Google Cloud Spanner.
+
+This package bundles the prebuilt Spanner ADBC driver shared library and exposes
+a thin Python wrapper around it. The heavy lifting lives in the Rust cdylib; this
+module just locates the bundled library and hands it to ``adbc_driver_manager``,
+which loads it over the ADBC C ABI.
+
+For a DBAPI 2.0 (PEP 249) connection with pandas/polars/Arrow helpers, use
+:func:`adbc_driver_spanner.dbapi.connect` instead of the low-level
+:func:`connect` here.
+"""
+
+import functools
+import pathlib
+import typing
+
+import adbc_driver_manager
+
+from ._version import __version__
+
+__all__ = ["connect", "option_kwargs", "ENTRYPOINT", "__version__"]
+
+#: C entrypoint exported by the shared library (see src/ffi.rs).
+ENTRYPOINT = "AdbcSpannerInit"
+
+
+def option_kwargs(
+    database: typing.Optional[str] = None,
+    *,
+    endpoint: typing.Optional[str] = None,
+    emulator: bool = False,
+    keyfile: typing.Optional[str] = None,
+    keyfile_json: typing.Optional[str] = None,
+    db_kwargs: typing.Optional[typing.Mapping[str, str]] = None,
+) -> typing.Dict[str, str]:
+    """Translate the friendly connection kwargs into ``adbc.spanner.*`` options.
+
+    Shared by :func:`connect` and :func:`adbc_driver_spanner.dbapi.connect` so the
+    two entry points map parameters identically. ``db_kwargs`` is an escape hatch
+    for raw option keys and is merged last.
+    """
+    options: typing.Dict[str, str] = {}
+    # Friendly kwargs -> the driver's option keys (see src/lib.rs).
+    if database is not None:
+        options["adbc.spanner.database"] = database
+    if endpoint is not None:
+        options["adbc.spanner.endpoint"] = endpoint
+    if emulator:
+        options["adbc.spanner.emulator"] = "true"
+    if keyfile is not None:
+        options["adbc.spanner.keyfile"] = keyfile
+    if keyfile_json is not None:
+        options["adbc.spanner.keyfile_json"] = keyfile_json
+    if db_kwargs:
+        options.update(db_kwargs)
+    return options
+
+
+def connect(
+    database: typing.Optional[str] = None,
+    *,
+    endpoint: typing.Optional[str] = None,
+    emulator: bool = False,
+    keyfile: typing.Optional[str] = None,
+    keyfile_json: typing.Optional[str] = None,
+    db_kwargs: typing.Optional[typing.Mapping[str, str]] = None,
+) -> adbc_driver_manager.AdbcDatabase:
+    """Create a low-level ADBC database handle for Spanner.
+
+    Parameters
+    ----------
+    database:
+        Fully-qualified database path,
+        ``projects/<p>/instances/<i>/databases/<d>``.
+    endpoint:
+        Override the Spanner gRPC endpoint (e.g. an emulator ``host:port``).
+    emulator:
+        Use anonymous credentials and talk to the emulator. When
+        ``SPANNER_EMULATOR_HOST`` is set the driver detects the emulator on its
+        own, so this is only needed to force it explicitly.
+    keyfile / keyfile_json:
+        Service-account credentials, as a path or inline JSON. Omit both to use
+        Application Default Credentials.
+    db_kwargs:
+        Escape hatch for raw ``adbc.spanner.*`` option keys, merged last.
+
+    For a DBAPI 2.0 connection, prefer :func:`adbc_driver_spanner.dbapi.connect`.
+    """
+    options = option_kwargs(
+        database,
+        endpoint=endpoint,
+        emulator=emulator,
+        keyfile=keyfile,
+        keyfile_json=keyfile_json,
+        db_kwargs=db_kwargs,
+    )
+    # ** unpacking accepts the dotted, non-identifier option keys; they land in
+    # AdbcDatabase's **kwargs and are forwarded as ADBC options.
+    return adbc_driver_manager.AdbcDatabase(
+        driver=_driver_path(), entrypoint=ENTRYPOINT, **options
+    )
+
+
+@functools.cache
+def _driver_path() -> str:
+    """Absolute path to the shared library bundled in this wheel."""
+    here = pathlib.Path(__file__).resolve().parent
+    for name in ("libadbc_spanner.so", "libadbc_spanner.dylib", "adbc_spanner.dll"):
+        candidate = here / name
+        if candidate.is_file():
+            return str(candidate)
+    raise RuntimeError(
+        "adbc_driver_spanner: no bundled Spanner driver library found next to "
+        f"{here}. This usually means a source/sdist install without a matching "
+        "platform wheel; install a prebuilt wheel for your platform instead."
+    )

adbc_driver_spanner/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.0"

adbc_driver_spanner/dbapi.py

@@ -0,0 +1,58 @@
+"""DBAPI 2.0 (PEP 249) interface for the Spanner ADBC driver.
+
+This is the layer most users want: it returns a standard DBAPI connection with
+cursors, plus the ADBC Arrow extensions (``fetch_arrow_table``, ``fetch_df``,
+``adbc_ingest``) that pandas / polars / DuckDB consume directly.
+
+    import adbc_driver_spanner.dbapi as spanner
+    with spanner.connect(database="projects/p/instances/i/databases/d") as conn:
+        df = conn.cursor().execute("SELECT * FROM Singers").fetch_df()
+
+Note: DBAPI is autocommit-off by default, which puts this driver into its
+buffer-and-commit manual-transaction mode — call ``conn.commit()`` to apply DML.
+Pass ``autocommit=True`` to keep the driver's default single-statement mode.
+"""
+
+import typing
+
+import adbc_driver_manager.dbapi
+
+from . import ENTRYPOINT, _driver_path, option_kwargs
+
+__all__ = ["connect"]
+
+
+def connect(
+    database: typing.Optional[str] = None,
+    *,
+    endpoint: typing.Optional[str] = None,
+    emulator: bool = False,
+    keyfile: typing.Optional[str] = None,
+    keyfile_json: typing.Optional[str] = None,
+    db_kwargs: typing.Optional[typing.Mapping[str, str]] = None,
+    conn_kwargs: typing.Optional[typing.Mapping[str, str]] = None,
+    autocommit: bool = False,
+) -> adbc_driver_manager.dbapi.Connection:
+    """Open a DBAPI 2.0 connection to a Spanner database.
+
+    Accepts the same connection parameters as
+    :func:`adbc_driver_spanner.connect`; ``conn_kwargs`` sets raw
+    ``adbc.connection.*`` options and ``autocommit`` toggles PEP 249 autocommit.
+    """
+    options = option_kwargs(
+        database,
+        endpoint=endpoint,
+        emulator=emulator,
+        keyfile=keyfile,
+        keyfile_json=keyfile_json,
+        db_kwargs=db_kwargs,
+    )
+    # The driver manager builds and owns the database/connection handles here and
+    # tears them down if the connection fails, so no manual cleanup is needed.
+    return adbc_driver_manager.dbapi.connect(
+        driver=_driver_path(),
+        entrypoint=ENTRYPOINT,
+        db_kwargs=options,
+        conn_kwargs=conn_kwargs,
+        autocommit=autocommit,
+    )

adbc_driver_spanner-0.5.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: adbc-driver-spanner
+Version: 0.5.0
+Summary: ADBC (Arrow Database Connectivity) driver for Google Cloud Spanner
+Author-email: Fredrik Fornwall <fredrik@fornwall.net>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/fornwall/adbc-spanner
+Project-URL: Repository, https://github.com/fornwall/adbc-spanner
+Keywords: adbc,arrow,spanner,database,gcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: adbc-driver-manager
+Provides-Extra: dbapi
+Requires-Dist: pyarrow>=8; extra == "dbapi"
+
+# adbc-driver-spanner
+
+A Python [ADBC](https://arrow.apache.org/adbc/) driver for **Google Cloud Spanner**.
+
+It bundles the prebuilt native driver (a Rust cdylib) and exposes it through
+[`adbc_driver_manager`](https://pypi.org/project/adbc-driver-manager/), so you
+get a standard DBAPI 2.0 connection whose results come back as Apache Arrow —
+ready for pandas, polars, DuckDB, or PyArrow with no per-row conversion.
+
+## Install
+
+```sh
+pip install adbc-driver-spanner
+# for the DataFrame / Arrow helpers used below:
+pip install adbc-driver-spanner[dbapi] pandas
+```
+
+Prebuilt wheels are published for Linux (x86-64, aarch64), macOS (arm64,
+x86-64), and Windows (x86-64, arm64).
+
+## Quickstart
+
+```python
+import adbc_driver_spanner.dbapi as spanner
+
+with spanner.connect(
+    database="projects/my-project/instances/my-instance/databases/my-db",
+) as conn:
+    with conn.cursor() as cur:
+        cur.execute("SELECT SingerId, FirstName FROM Singers")
+        df = cur.fetch_df()          # -> pandas.DataFrame
+```
+
+## Connection options
+
+Options mirror the driver's `adbc.spanner.*` keys:
+
+| kwarg          | driver option               |
+| -------------- | --------------------------- |
+| `database=`    | `adbc.spanner.database`     |
+| `endpoint=`    | `adbc.spanner.endpoint`     |
+| `emulator=`    | `adbc.spanner.emulator`     |
+| `keyfile=`     | `adbc.spanner.keyfile`      |
+| `keyfile_json=`| `adbc.spanner.keyfile_json` |
+
+Credentials default to Application Default Credentials; pass `keyfile=` /
+`keyfile_json=` for a service account, or point at the emulator:
+
+```python
+# docs-test: skip
+spanner.connect(database="projects/p/instances/i/databases/d",
+                endpoint="localhost:9010", emulator=True)
+```
+
+## Cookbook
+
+Every snippet below is executed against the Spanner emulator in CI, so they stay
+correct. They assume a `Singers(SingerId INT64, FirstName STRING)` table.
+
+Two things to know:
+
+- **DBAPI is autocommit-off by default**, so **DML and ingest need a
+  `conn.commit()`** (or pass `autocommit=True`). Reads need neither.
+- The DataFrame / Arrow paths need the `[dbapi]` extra (pyarrow).
+
+**pyarrow — zero-copy Arrow:**
+
+```python
+import adbc_driver_spanner.dbapi as spanner
+
+with spanner.connect(
+    database="projects/my-project/instances/my-instance/databases/my-db",
+) as conn:
+    with conn.cursor() as cur:
+        cur.execute("SELECT SingerId, FirstName FROM Singers ORDER BY SingerId")
+        table = cur.fetch_arrow_table()      # -> pyarrow.Table
+```
+
+**polars — read straight from the connection:**
+
+```python
+import polars as pl
+import adbc_driver_spanner.dbapi as spanner
+
+with spanner.connect(
+    database="projects/my-project/instances/my-instance/databases/my-db",
+) as conn:
+    df = pl.read_database(
+        "SELECT SingerId, FirstName FROM Singers ORDER BY SingerId",
+        connection=conn,                     # an ADBC connection, not a URI
+    )
+```
+
+**DuckDB — query the fetched Arrow table in-process:**
+
+```python
+import duckdb
+import adbc_driver_spanner.dbapi as spanner
+
+with spanner.connect(
+    database="projects/my-project/instances/my-instance/databases/my-db",
+) as conn:
+    with conn.cursor() as cur:
+        cur.execute("SELECT SingerId, FirstName FROM Singers")
+        singers = cur.fetch_arrow_table()
+
+# `singers` is a pyarrow.Table; DuckDB queries it by variable name, no copy.
+top = duckdb.sql("SELECT COUNT(*) AS n, MIN(FirstName) AS first FROM singers").fetchone()
+```
+
+**Insert a DataFrame (bulk ingest):**
+
+```python
+import pandas as pd
+import pyarrow as pa
+import adbc_driver_spanner.dbapi as spanner
+
+frame = pd.DataFrame({"SingerId": [10, 11], "FirstName": ["Carol", "Dave"]})
+
+with spanner.connect(
+    database="projects/my-project/instances/my-instance/databases/my-db",
+    autocommit=True,                         # apply immediately; returns the row count
+) as conn:
+    with conn.cursor() as cur:
+        # The target table must already exist — only append mode is supported.
+        rows = cur.adbc_ingest("Singers", pa.Table.from_pandas(frame), mode="append")
+```
+
+## Partitioned reads and Data Boost
+
+A large scan can be split into independent partitions and read in parallel —
+optionally on Spanner's serverless [Data Boost] compute, so the work is isolated
+from your provisioned instance. This uses the ADBC partitioned-execution
+extension (`adbc_execute_partitions` / `adbc_read_partition`):
+
+```python
+import adbc_driver_spanner.dbapi as spanner
+
+with spanner.connect(
+    database="projects/my-project/instances/my-instance/databases/my-db",
+) as conn:
+    with conn.cursor() as cur:
+        # Optional statement options, set on the underlying ADBC statement:
+        cur.adbc_statement.set_options(**{
+            "adbc.spanner.data_boost_enabled": "true",  # run on Data Boost
+            "adbc.spanner.max_partitions": "8",          # cap the partition count
+        })
+        partitions, schema = cur.adbc_execute_partitions("SELECT SingerId FROM Singers")
+
+    # Each descriptor is opaque bytes; it can be shipped to another worker,
+    # process, or connection and read independently.
+    for token in partitions:
+        with conn.cursor() as cur:
+            cur.adbc_read_partition(token)
+            table = cur.fetch_arrow_table()
+            ...
+```
+
+The Data Boost choice is baked into each descriptor, so it is honoured wherever
+the partition is read. Only single-table scans are partitionable — queries with
+an `ORDER BY` or aggregation are not.
+
+[Data Boost]: https://cloud.google.com/spanner/docs/databoost/databoost-overview
+
+## How this package is built
+
+The wheel is **data-only**: it does not compile anything at install time and
+links nothing against Python. CI (`.github/workflows/libraries.yml`) builds the
+native library per platform, drops it into `adbc_driver_spanner/`, and packages
+a `py3-none-<platform>` wheel. See that workflow for the release wiring.

adbc_driver_spanner-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+adbc_driver_spanner/__init__.py,sha256=2zV0i1fbiJyGuuYAAKTG504WIGZJ-wKPT9xdEtMb4rk,4209
+adbc_driver_spanner/_version.py,sha256=LBK46heutvn3KmsCrKIYu8RQikbfnjZaj2xFrXaeCzQ,22
+adbc_driver_spanner/adbc_spanner.dll,sha256=XGFb7Vll8Vtf2-73GmKUp3uS6Zczik9yW59SVY6lQMs,18796032
+adbc_driver_spanner/dbapi.py,sha256=obq1KQu9EI727oWonG39VtEQ1sv6sNezGtReOVafvOA,2104
+adbc_driver_spanner/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adbc_driver_spanner-0.5.0.dist-info/METADATA,sha256=lZnZC_9gz__KRyJykOdXsSXmVg_NHhv28q-bIcuQIFA,6668
+adbc_driver_spanner-0.5.0.dist-info/WHEEL,sha256=hVx9elvUDfBjRmbl8JwIcXXikst35RZTZK9nspfI_28,98
+adbc_driver_spanner-0.5.0.dist-info/top_level.txt,sha256=OQpyk3MKXSGZElB1wpO5_JMeFvzz3zAHYza6ahRQmb4,20
+adbc_driver_spanner-0.5.0.dist-info/RECORD,,

adbc_driver_spanner-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

adbc_driver_spanner-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+adbc_driver_spanner