adbcbridge 0.1.0__py3-none-win_amd64.whl

adbcbridge/__init__.py

@@ -0,0 +1,157 @@
+# Copyright 2026 the adbcbridge authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""adbcbridge: use any ODBC data source as an ADBC (Arrow) database.
+
+    import adbcbridge
+
+    with adbcbridge.connect(uri="Driver=SQLite3;Database=my.db;") as conn:
+        with conn.cursor() as cur:
+            cur.execute("SELECT * FROM t")
+            table = cur.fetch_arrow_table()
+
+This package is a thin convenience layer: it finds the adbcbridge shared
+library (:func:`driver_path`) and hands it to ``adbc_driver_manager``.  The
+object it returns is a plain ``adbc_driver_manager.dbapi.Connection``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from . import _preload
+from ._locate import (
+    DriverNotFoundError,
+    OdbcDriver,
+    driver_path,
+    odbc_driver_library,
+    odbc_drivers,
+    odbcinst_ini,
+)
+from ._preload import preload_odbc_driver
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from adbc_driver_manager import dbapi as _dbapi
+
+__all__ = [
+    "DriverNotFoundError",
+    "OdbcDriver",
+    "__version__",
+    "connect",
+    "driver_path",
+    "odbc_driver_library",
+    "odbc_drivers",
+    "odbcinst_ini",
+    "preload_odbc_driver",
+]
+
+__version__ = "0.1.0"
+
+# Local alias: the `driver_path` parameter of connect() shadows the function.
+_find_driver = driver_path
+
+
+def _dbapi_module():
+    """Import ``adbc_driver_manager.dbapi`` -- and, with it, pyarrow.
+
+    Deferred rather than done at import time so that ``import adbcbridge`` does
+    not pull pyarrow into the process: an ODBC driver that needs static
+    thread-local storage can then still be loaded first (see ``_preload``).
+    """
+    from adbc_driver_manager import dbapi
+
+    return dbapi
+
+
+#: Prefix for this driver's own options, e.g. ``adbc.odbc.batch_size``.
+OPTION_PREFIX = "adbc.odbc."
+
+# Options the driver takes verbatim (they are ADBC-standard names, not ours).
+_PLAIN_OPTIONS = frozenset({"uri", "dsn", "username", "password"})
+
+
+def _option_key(name: str) -> str:
+    """``batch_size`` -> ``adbc.odbc.batch_size``; dotted names pass through."""
+    if "." in name or name in _PLAIN_OPTIONS:
+        return name
+    return OPTION_PREFIX + name
+
+
+def _option_value(value: Any) -> str:
+    if isinstance(value, bool):  # the driver parses "true"/"false"
+        return "true" if value else "false"
+    return str(value)
+
+
+def connect(
+    uri: Optional[str] = None,
+    dsn: Optional[str] = None,
+    username: Optional[str] = None,
+    password: Optional[str] = None,
+    driver_path: Optional[str] = None,  # noqa: A002 - matches the documented API
+    *,
+    autocommit: bool = False,
+    conn_kwargs: Optional[Dict[str, str]] = None,
+    **options: Any,
+) -> _dbapi.Connection:
+    """Connect to an ODBC data source and return a DBAPI 2.0 connection.
+
+    :param uri: full ODBC connection string, e.g.
+        ``"Driver=/usr/lib/x86_64-linux-gnu/odbc/libsqlite3odbc.so;Database=my.db;"``.
+    :param dsn: DSN name from ``odbc.ini`` (used instead of, or alongside, *uri*).
+    :param username: sent as ``UID=``.
+    :param password: sent as ``PWD=``.
+    :param driver_path: path to ``libadbc_driver_odbc.so``; defaults to
+        :func:`driver_path`.  An ADBC driver manifest name such as ``"odbc"``
+        also works, since the value is passed straight to the driver manager.
+    :param autocommit: passed to the driver manager (default: transactional).
+    :param conn_kwargs: extra connection-level ADBC options.
+    :param options: further database options.  A bare name is prefixed with
+        ``adbc.odbc.`` (``batch_size=4096`` sets ``adbc.odbc.batch_size``);
+        a dotted name is used as given.  ``bool`` becomes ``"true"``/``"false"``.
+
+    The return value is an ``adbc_driver_manager.dbapi.Connection``, so
+    everything ADBC's DBAPI layer offers (``cursor()``, ``fetch_arrow_table()``,
+    ``adbc_ingest()``, ``adbc_get_objects()``, ...) is available.
+    """
+    if uri is None and dsn is None:
+        raise ValueError("connect() needs at least one of uri= or dsn=")
+
+    db_kwargs: Dict[str, str] = {}
+    if uri is not None:
+        db_kwargs["uri"] = uri
+    if dsn is not None:
+        db_kwargs["dsn"] = dsn
+    if username is not None:
+        db_kwargs["username"] = username
+    if password is not None:
+        db_kwargs["password"] = password
+    for key, value in options.items():
+        if value is None:
+            continue
+        db_kwargs[_option_key(key)] = _option_value(value)
+
+    driver = driver_path if driver_path is not None else _find_driver()
+    if _preload.preload_enabled():
+        # Before pyarrow comes in below.  Best effort: a driver that will not
+        # load here still gets its real failure reported by the connection.
+        preload_odbc_driver(uri=uri, dsn=dsn)
+    return _dbapi_module().connect(
+        driver=driver,
+        db_kwargs=db_kwargs,
+        conn_kwargs=dict(conn_kwargs or {}),
+        autocommit=autocommit,
+    )

adbcbridge/__main__.py

@@ -0,0 +1,24 @@
+# Copyright 2026 the adbcbridge authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""``python -m adbcbridge`` / the ``adbcbridge`` console script."""
+
+import sys
+
+from ._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

adbcbridge/_cli.py

@@ -0,0 +1,134 @@
+# Copyright 2026 the adbcbridge authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The ``adbcbridge`` command line tool."""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+from typing import List, Optional, Sequence
+
+from . import __version__, connect
+from ._locate import DriverNotFoundError, driver_path, odbc_drivers, odbcinst_ini
+
+
+def _cmd_query(args: argparse.Namespace) -> int:
+    params: Optional[List[str]] = args.param or None
+    with connect(uri=args.connection_string, driver_path=args.driver_path,
+                 autocommit=True) as conn:
+        with conn.cursor() as cur:
+            cur.execute(args.sql, parameters=params)
+            if not cur.description:  # DDL/DML: no result set
+                affected = cur.rowcount
+                # ODBC reports -1 when a statement has no meaningful row count.
+                print("OK" if affected is None or affected < 0
+                      else "rows affected: %d" % affected)
+                return 0
+            table = cur.fetch_arrow_table()
+    if args.limit is not None and table.num_rows > args.limit:
+        table = table.slice(0, args.limit)
+    if args.format == "csv":
+        import pyarrow.csv
+
+        pyarrow.csv.write_csv(table, sys.stdout.buffer)
+    elif args.format == "schema":
+        print(table.schema)
+    else:
+        print(table)
+        print("%d rows x %d columns" % (table.num_rows, table.num_columns))
+    return 0
+
+
+def _cmd_drivers(args: argparse.Namespace) -> int:
+    ini = odbcinst_ini()
+    drivers = odbc_drivers()
+    if not drivers:
+        where = str(ini) if ini else "odbcinst -j / odbcinst.ini"
+        print("no ODBC drivers registered (%s)" % where, file=sys.stderr)
+        return 1
+    print("# %s" % ini)
+    width = max(len(d.name) for d in drivers)
+    for driver in drivers:
+        note = ""
+        if driver.path and not pathlib.Path(driver.path).is_file():
+            note = "  (missing)"
+        print("%-*s  %s%s" % (width, driver.name, driver.path or "-", note))
+        if args.verbose and driver.description:
+            print("%-*s  %s" % (width, "", driver.description))
+    return 0
+
+
+def _cmd_driver_path(args: argparse.Namespace) -> int:
+    print(driver_path())
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="adbcbridge",
+        description="Query any ODBC data source through adbcbridge (ADBC/Arrow).",
+    )
+    parser.add_argument("--version", action="version", version="adbcbridge " + __version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    query = sub.add_parser(
+        "query",
+        help="run a SQL statement and print the resulting Arrow table",
+        description="Run a SQL statement against an ODBC connection string.",
+        epilog='example: adbcbridge query "Driver=SQLite3;Database=my.db;" '
+               '"SELECT * FROM t"',
+    )
+    query.add_argument("connection_string", help="ODBC connection string (Driver=...;)")
+    query.add_argument("sql", help="SQL to execute")
+    query.add_argument("-p", "--param", action="append", metavar="VALUE",
+                       help="value for a '?' parameter (repeat, in order); "
+                            "always sent as a string")
+    query.add_argument("--driver-path", metavar="PATH",
+                       help="path to libadbc_driver_odbc.so (default: auto-detect)")
+    query.add_argument("--limit", type=int, metavar="N", help="print at most N rows")
+    query.add_argument("--format", choices=("table", "csv", "schema"), default="table",
+                       help="output format (default: table)")
+    query.set_defaults(func=_cmd_query)
+
+    drivers = sub.add_parser(
+        "drivers",
+        help="list the ODBC drivers registered on this machine",
+        description="List the ODBC drivers from odbcinst -j / odbcinst.ini.",
+    )
+    drivers.add_argument("-v", "--verbose", action="store_true",
+                         help="also print each driver's description")
+    drivers.set_defaults(func=_cmd_drivers)
+
+    where = sub.add_parser(
+        "driver-path",
+        help="print the path of the adbcbridge shared library that would be used",
+    )
+    where.set_defaults(func=_cmd_driver_path)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except DriverNotFoundError as exc:
+        print("adbcbridge: %s" % exc, file=sys.stderr)
+        return 2
+    except Exception as exc:  # database errors: a traceback helps nobody here
+        print("adbcbridge: %s: %s" % (type(exc).__name__, exc), file=sys.stderr)
+        return 1