deltaforge-adbc 1.0.5__py3-none-win_amd64.whl

deltaforge_adbc/__init__.py

@@ -0,0 +1,205 @@
+"""DeltaForge ADBC driver: Arrow-native read and write for Delta tables.
+
+This package bundles the native DeltaForge ADBC driver and exposes a small,
+ergonomic surface over ``adbc_driver_manager`` so you can connect, run queries,
+and write a DataFrame straight into a Delta table without per-row marshalling.
+
+Quick start
+-----------
+    import deltaforge_adbc as df
+
+    conn = df.connect(
+        control_plane="https://control.example.com",
+        token="df_pat_...",                  # personal access token
+        compute="https://compute.example.com",
+    )
+
+    # Read into a pyarrow.Table (or .to_pandas() / .to_polars()).
+    table = df.read_table(conn, "SELECT * FROM sales.public.orders LIMIT 1000")
+
+    # Write a DataFrame (pandas, polars, or pyarrow) into a Delta table.
+    df.write_dataframe(conn, "sales.public.orders", my_dataframe, mode="append")
+
+    conn.close()
+
+The driver carries Arrow record batches end to end, so ``write_dataframe`` is
+the preferred bulk path for pandas / polars / pyarrow data.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+__all__ = [
+    "driver_path",
+    "connect",
+    "read_table",
+    "write_dataframe",
+    "DeltaForgeAdbcError",
+]
+
+
+class DeltaForgeAdbcError(RuntimeError):
+    """Raised for configuration problems before a request reaches the driver."""
+
+
+def driver_path() -> str:
+    """Absolute path to the bundled native ADBC driver shared library.
+
+    The wheel ships exactly one library, named per platform. Returns the path
+    so it can be handed to ``adbc_driver_manager`` as the ``driver`` option.
+    """
+    lib_dir = Path(__file__).resolve().parent / "lib"
+    candidates = [
+        "libdeltaforge_adbc.so",
+        "libdeltaforge_adbc.dylib",
+        "deltaforge_adbc.dll",
+    ]
+    for name in candidates:
+        p = lib_dir / name
+        if p.exists():
+            return str(p)
+    # Allow an explicit override (useful for local driver builds / debugging).
+    override = os.environ.get("DELTAFORGE_ADBC_PATH")
+    if override and Path(override).exists():
+        return override
+    raise DeltaForgeAdbcError(
+        f"no DeltaForge ADBC driver found in {lib_dir}. The installed wheel may "
+        f"not match this platform ({sys.platform}); reinstall with a matching "
+        f"wheel, or set DELTAFORGE_ADBC_PATH to a local driver build."
+    )
+
+
+def connect(
+    *,
+    control_plane: Optional[str] = None,
+    token: Optional[str] = None,
+    compute: Optional[str] = None,
+    **db_kwargs: Any,
+):
+    """Open a DB-API 2.0 connection to a DeltaForge compute node over ADBC.
+
+    Parameters
+    ----------
+    control_plane:
+        Control-plane URL. Defaults to ``$DELTAFORGE_CONTROL_PLANE_URL`` then
+        ``http://localhost:3000``.
+    token:
+        Session token or personal access token (``df_...`` / ``df_pat_...``).
+        Defaults to ``$DELTAFORGE_SESSION_TOKEN``.
+    compute:
+        Optional compute-node URL. Defaults to ``$DELTAFORGE_COMPUTE_URL`` when
+        set; otherwise the control plane selects a healthy node.
+    db_kwargs:
+        Extra ADBC database options passed through verbatim.
+    """
+    try:
+        import adbc_driver_manager.dbapi as dbapi
+    except ImportError as exc:  # pragma: no cover - dependency declared in pyproject
+        raise DeltaForgeAdbcError(
+            "adbc_driver_manager is required (pip install adbc-driver-manager)"
+        ) from exc
+
+    cp = control_plane or os.environ.get(
+        "DELTAFORGE_CONTROL_PLANE_URL", "http://localhost:3000"
+    )
+    tok = token or os.environ.get("DELTAFORGE_SESSION_TOKEN")
+    if not tok:
+        raise DeltaForgeAdbcError(
+            "no token: pass token=... or set DELTAFORGE_SESSION_TOKEN"
+        )
+    comp = compute or os.environ.get("DELTAFORGE_COMPUTE_URL")
+
+    kwargs = {
+        "driver": driver_path(),
+        "entrypoint": "AdbcDriverInit",
+        "uri": cp,
+        "adbc.deltaforge.session_token": tok,
+    }
+    if comp:
+        kwargs["adbc.deltaforge.compute_url"] = comp
+    kwargs.update(db_kwargs)
+    return dbapi.connect(db_kwargs=kwargs)
+
+
+def read_table(conn, sql: str):
+    """Execute ``sql`` and return the full result as a ``pyarrow.Table``.
+
+    Use ``.to_pandas()`` or ``polars.from_arrow(...)`` on the result for a
+    DataFrame.
+    """
+    with conn.cursor() as cur:
+        cur.execute(sql)
+        return cur.fetch_arrow_table()
+
+
+def _to_arrow(data):
+    """Coerce pandas / polars / pyarrow input into a pyarrow Table or batch."""
+    import pyarrow as pa
+
+    if isinstance(data, (pa.Table, pa.RecordBatch)):
+        return data
+    # polars
+    if data.__class__.__module__.startswith("polars"):
+        return data.to_arrow()
+    # pandas
+    if data.__class__.__module__.startswith("pandas"):
+        return pa.Table.from_pandas(data, preserve_index=False)
+    # Anything implementing the Arrow C stream / __arrow_c_stream__ protocol.
+    if hasattr(data, "__arrow_c_stream__") or hasattr(data, "__arrow_c_array__"):
+        return pa.table(data)
+    raise DeltaForgeAdbcError(
+        f"unsupported DataFrame type {type(data)!r}; pass pandas, polars, or "
+        f"pyarrow data"
+    )
+
+
+def write_dataframe(
+    conn,
+    table: str,
+    data,
+    *,
+    mode: str = "append",
+    idempotency_key: Optional[str] = None,
+) -> None:
+    """Write a DataFrame into a Delta table via Arrow bulk ingest.
+
+    Parameters
+    ----------
+    table:
+        Fully qualified target table (``zone.schema.table``). It must already
+        exist; this call does not create it.
+    data:
+        pandas / polars / pyarrow data. Converted to Arrow once, then streamed.
+    mode:
+        ``append`` (default), ``replace`` (overwrite), or ``upsert``.
+    idempotency_key:
+        Optional dedupe key. Re-sending the same batch with the same key is a
+        no-op rather than a duplicate insert.
+    """
+    arrow = _to_arrow(data)
+    valid = {"append", "replace", "upsert", "create", "create_append"}
+    if mode not in valid:
+        raise DeltaForgeAdbcError(f"mode must be one of {sorted(valid)}, got {mode!r}")
+
+    with conn.cursor() as cur:
+        if idempotency_key is None and mode in {"append", "replace", "create", "create_append"}:
+            cur.adbc_ingest(table, arrow, mode=mode)
+            return
+        # upsert and idempotent paths ride on the df.ingest.* statement options.
+        cur.adbc_statement.set_options(
+            **{
+                "adbc.ingest.target_table": table,
+                "df.ingest.mode": mode,
+                **(
+                    {"df.ingest.idempotency_key": idempotency_key}
+                    if idempotency_key
+                    else {}
+                ),
+            }
+        )
+        cur.adbc_statement.bind(arrow)
+        cur.adbc_statement.execute_update()

deltaforge_adbc/lib/.gitkeep

@@ -0,0 +1,3 @@
+# The native driver library (libdeltaforge_adbc.{so,dylib,dll}) is staged into
+# this directory by build_wheels.py at build time and is not committed to source
+# control. This placeholder keeps the directory present.

deltaforge_adbc-1.0.5.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: deltaforge-adbc
+Version: 1.0.5
+Summary: DeltaForge ADBC driver: Arrow-native read and write for Delta Lake and Apache Iceberg, carrying record batches end-to-end so BI tools skip row-by-row conversion
+Project-URL: Homepage, https://deltaforge.org
+Project-URL: Documentation, https://deltaforge.org/docs
+Project-URL: Issues, https://github.com/deltaforge-org/delta-forge-adbc/issues
+Author: DeltaForge
+License: LicenseRef-DeltaForge-Proprietary
+License-File: LICENSE
+Keywords: adbc,arrow,delta lake,deltaforge,lakehouse
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Requires-Dist: adbc-driver-manager>=1.0
+Requires-Dist: pyarrow>=14.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://deltaforge.org/assets/favicon/favicon-512.png" alt="DeltaForge" width="96" height="96">
+</p>
+
+<h1 align="center">deltaforge-adbc</h1>
+
+<p align="center"><strong>ADBC driver: Arrow-native read and write for Delta Lake and Apache Iceberg from Python</strong></p>
+
+<p align="center">
+  <a href="https://deltaforge.org">deltaforge.org</a> &middot;
+  <a href="https://deltaforge.org/pages/adbc.html">ADBC driver</a> &middot;
+  <a href="https://github.com/deltaforge-org/delta-forge-adbc/issues">Issues</a>
+</p>
+
+Arrow-native read and write for Delta tables from Python, via the DeltaForge
+ADBC driver. The driver carries Arrow record batches end to end, so it is the
+preferred connector for wide-column scans and for writing DataFrames straight
+into Delta tables.
+
+DeltaForge is commercial software with a free Community license. See
+[deltaforge.org/pricing](https://deltaforge.org/pricing).
+
+## Install
+
+```bash
+pip install deltaforge-adbc
+# optional DataFrame integrations:
+pip install "deltaforge-adbc[pandas]"   # or [polars]
+```
+
+The wheel bundles the native driver for your platform. No separate driver
+install or `unixODBC` setup is required.
+
+## Connect
+
+```python
+import deltaforge_adbc as df
+
+conn = df.connect(
+    control_plane="https://control.example.com",
+    token="df_pat_...",                    # personal access token
+    compute="https://compute.example.com", # optional; auto-selected if omitted
+)
+```
+
+Connection parameters also fall back to environment variables:
+`DELTAFORGE_CONTROL_PLANE_URL`, `DELTAFORGE_SESSION_TOKEN`,
+`DELTAFORGE_COMPUTE_URL`.
+
+## Read
+
+```python
+table = df.read_table(conn, "SELECT * FROM sales.public.orders LIMIT 1000")
+pdf   = table.to_pandas()        # pandas
+# import polars as pl; pl.from_arrow(table)   # polars
+```
+
+## Write a DataFrame
+
+```python
+import pandas as pd
+
+frame = pd.DataFrame({"id": [1, 2, 3], "region": ["us", "eu", "us"], "qty": [10, 20, 30]})
+
+# Append (default). Also: mode="replace" (overwrite), mode="upsert".
+df.write_dataframe(conn, "sales.public.orders", frame, mode="append")
+
+# Idempotent append: re-sending the same key is a no-op, not a duplicate.
+df.write_dataframe(conn, "sales.public.orders", frame, mode="append",
+                   idempotency_key="nightly-2026-05-31")
+```
+
+pandas, polars, and pyarrow inputs are all accepted; the target table must
+already exist.
+
+## Runnable examples
+
+See [`examples/`](examples/): `read.py` and `write_dataframe.py` are
+self-contained scripts driven by the environment variables above.

deltaforge_adbc-1.0.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+deltaforge_adbc/__init__.py,sha256=jTnPrEJbO2Wc3hLA0fZxl-FoDCq4oE7wZTJ4Vx9SNjQ,6816
+deltaforge_adbc/lib/.gitkeep,sha256=CxIOZrBkT4sfT0xZvSxBdQYfGSgqkRYE-1ozzC11_TQ,217
+deltaforge_adbc/lib/deltaforge_adbc.dll,sha256=sAHBGv9B-wCm_wQziX24FEk7Jl5XAD0tgzreOsqZs0s,1162904
+deltaforge_adbc-1.0.5.dist-info/METADATA,sha256=xRfnwuT924sQiGlmnd8g4RJZRPWLQaNbcn0_to-ACAk,3535
+deltaforge_adbc-1.0.5.dist-info/WHEEL,sha256=pp_iTzO0EBcCvlZZV2dJYp6L2tdDWBsn1ceo50wEt8Q,94
+deltaforge_adbc-1.0.5.dist-info/licenses/LICENSE,sha256=StCqCRJOqCkwuP7_gJA7lYqUANhupDcIbKav3ryrLjI,909
+deltaforge_adbc-1.0.5.dist-info/RECORD,,

deltaforge_adbc-1.0.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

deltaforge_adbc-1.0.5.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+DeltaForge Software License
+
+Copyright (c) 2025-2026 DeltaForge. All rights reserved.
+
+DeltaForge is commercial software. This package contains a compiled,
+redistributable client component (the DeltaForge ADBC driver). Use is
+governed by the DeltaForge license terms.
+
+  * A free Community license is available for individuals and single-node
+    use, and ships the full platform.
+  * Paid Standard, Professional, and Enterprise tiers add scale, included
+    capacity, and support.
+
+Tiers and details:   https://deltaforge.org/pricing
+Full license terms:  https://deltaforge.org/terms-of-service
+
+The DeltaForge source code is proprietary and is NOT licensed or distributed
+under this agreement. Only the compiled client component in this package is
+redistributable.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. SEE THE FULL LICENSE TERMS FOR THE GOVERNING CONDITIONS.