You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2022/12/13 17:21:40 UTC
[arrow-adbc] branch main updated: docs: reorganize docs to highlight drivers (#238)
This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new 88121b1 docs: reorganize docs to highlight drivers (#238)
88121b1 is described below
commit 88121b1d7a962eb3ebac6babca14df99727aa0b3
Author: David Li <li...@gmail.com>
AuthorDate: Tue Dec 13 12:21:35 2022 -0500
docs: reorganize docs to highlight drivers (#238)
---
docs/source/conf.py | 12 ++
docs/source/cpp/driver_manager.rst | 7 +-
docs/source/cpp/index.rst | 2 -
docs/source/cpp/install.rst | 123 ---------------------
.../driver/index.rst => driver/cpp/features.rst} | 38 +++++--
.../{cpp/driver => driver/cpp}/flight_sql.rst | 2 +-
docs/source/{cpp/driver => driver/cpp}/index.rst | 17 ++-
.../{cpp/driver => driver/cpp}/postgresql.rst | 46 +++++++-
docs/source/{cpp/driver => driver/cpp}/sqlite.rst | 54 ++++++++-
.../index.rst => driver/java/flight_sql.rst} | 23 ++--
docs/source/{cpp/driver => driver/java}/index.rst | 17 +--
.../{cpp/driver/index.rst => driver/java/jdbc.rst} | 22 ++--
docs/source/{python => go}/index.rst | 10 +-
docs/source/index.rst | 26 +++--
docs/source/nightly.rst | 6 +-
docs/source/python/api/adbc_driver_manager.rst | 6 +-
.../api/adbc_driver_postgresql.rst} | 26 +++--
.../api/adbc_driver_sqlite.rst} | 26 +++--
docs/source/python/api/index.rst | 4 +-
docs/source/python/driver_manager.rst | 66 +++++++++++
docs/source/python/index.rst | 3 +-
.../adbc_driver_manager/__init__.py | 2 +
22 files changed, 316 insertions(+), 222 deletions(-)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 806bf84..bce8f7e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -45,6 +45,18 @@ try:
except ImportError:
autodoc_mock_imports = ["adbc_driver_manager"]
+try:
+ import adbc_driver_postgresql
+ import adbc_driver_postgresql.dbapi # noqa: F401
+except ImportError:
+ autodoc_mock_imports = ["adbc_driver_postgresql"]
+
+try:
+ import adbc_driver_sqlite
+ import adbc_driver_sqlite.dbapi # noqa: F401
+except ImportError:
+ autodoc_mock_imports = ["adbc_driver_sqlite"]
+
autodoc_default_options = {
"show-inheritance": True,
}
diff --git a/docs/source/cpp/driver_manager.rst b/docs/source/cpp/driver_manager.rst
index a017f06..120e5dd 100644
--- a/docs/source/cpp/driver_manager.rst
+++ b/docs/source/cpp/driver_manager.rst
@@ -27,7 +27,7 @@ specific driver.
Installation
============
-See :doc:`./install`.
+TODO
Usage
=====
@@ -50,9 +50,10 @@ entrypoint (see :cpp:type:`AdbcDriverInitFunc`).
* On MacOS: loads libadbc_driver_sqlite.dylib
* On Windows: loads adbc_driver_sqlite.dll */
AdbcDatabaseSetOption(&database, "driver", "adbc_driver_sqlite", NULL);
- /* Set additional options for the specific driver */
+ /* Set additional options for the specific driver, if needed */
+ /* Initialize the database */
AdbcDatabaseInit(&database, NULL);
-
+ /* Create connections as usual */
API Reference
=============
diff --git a/docs/source/cpp/index.rst b/docs/source/cpp/index.rst
index 3c13d01..295d873 100644
--- a/docs/source/cpp/index.rst
+++ b/docs/source/cpp/index.rst
@@ -22,8 +22,6 @@ C and C++
.. toctree::
:maxdepth: 2
- install
- driver/index
driver_manager
concurrency
api/index
diff --git a/docs/source/cpp/install.rst b/docs/source/cpp/install.rst
deleted file mode 100644
index 32eb07e..0000000
--- a/docs/source/cpp/install.rst
+++ /dev/null
@@ -1,123 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
-.. or more contributor license agreements. See the NOTICE file
-.. distributed with this work for additional information
-.. regarding copyright ownership. The ASF licenses this file
-.. to you 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.
-
-============
-Installation
-============
-
-To build the libraries from source, see :doc:`../contributing`.
-
-.. _cpp-install-driver-manager:
-
-ADBC Driver Manager
-===================
-
-.. _cpp-install-flight-sql:
-
-.. tab-set::
-
- .. tab-item:: C++
- :sync: cpp
-
- .. note:: Under construction
-
- .. tab-item:: Python (pip)
- :sync: python
-
- .. note:: Under construction
-
- .. tab-item:: Python (conda-forge)
- :sync: python-conda-forge
-
- .. note:: Under construction
-
-Flight SQL Driver
-=================
-
-.. tab-set::
-
- .. tab-item:: C++
- :sync: cpp
-
- Link to the Arrow C++ libraries, in particlar the Flight SQL
- libraries. See :doc:`arrow:cpp/build_system`.
-
- .. tab-item:: Python (pip)
- :sync: python
-
- 1. Install PyArrow 11.0.0 or greater. See
- :doc:`arrow:python/install`.
- 2. :ref:`Install the Python ADBC Driver Manager
- <cpp-install-driver-manager>`.
- 3. Import ``pyarrow.flight_sql`` for a `DBAPI 2.0`_-compatible
- interface.
-
- .. tab-item:: Python (conda-forge)
- :sync: python-conda-forge
-
- 1. Install PyArrow 11.0.0 or greater. See
- :doc:`arrow:python/install`.
- 2. :ref:`Install the Python ADBC Driver Manager
- <cpp-install-driver-manager>`.
- 3. Import ``pyarrow.flight_sql`` for a `DBAPI 2.0`_-compatible
- interface.
-
-.. _cpp-install-libpq:
-
-PostgreSQL Driver
-=================
-
-.. tab-set::
-
- .. tab-item:: C++
- :sync: cpp
-
- .. note:: Under construction
-
- .. tab-item:: Python (pip)
- :sync: python
-
- .. note:: Under construction
-
- .. tab-item:: Python (conda-forge)
- :sync: python-conda-forge
-
- .. note:: Under construction
-
-.. _cpp-install-sqlite:
-
-SQLite Driver
-=============
-
-.. tab-set::
-
- .. tab-item:: C++
- :sync: cpp
-
- .. note:: Under construction
-
- .. tab-item:: Python (pip)
- :sync: python
-
- .. note:: Under construction
-
- .. tab-item:: Python (conda-forge)
- :sync: python-conda-forge
-
- .. note:: Under construction
-
-.. _DBAPI 2.0: https://peps.python.org/pep-0249/
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/driver/cpp/features.rst
similarity index 54%
copy from docs/source/cpp/driver/index.rst
copy to docs/source/driver/cpp/features.rst
index 8bbe521..51406fe 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/driver/cpp/features.rst
@@ -15,16 +15,34 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
+======================
+Feature Support Matrix
+======================
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+.. list-table:: ADBC Feature Support
+ :header-rows: 1
-.. toctree::
- :maxdepth: 1
+ * - Driver
+ - Bulk Ingestion
+ - Metadata
+ - Partitioned Result Sets
+ - Prepared Statements
+ - Transactions
- flight_sql
- postgresql
- sqlite
+ * - SQLite
+ - Yes
+ - Yes
+ - No
+ - Yes
+ - Yes
+
+Bulk Ingestion
+ Creating or appending to a database table from an Arrow table.
+
+Metadata
+ Functions like :cpp:func:`AdbcConnectionGetObjects` that get
+ metadata about the database catalog, etc.
+
+Partitioned Result Sets
+ Being able to read individual chunks of a (generally distributed)
+ result set (:cpp:func:`AdbcStatementExecutePartitions`).
diff --git a/docs/source/cpp/driver/flight_sql.rst b/docs/source/driver/cpp/flight_sql.rst
similarity index 98%
rename from docs/source/cpp/driver/flight_sql.rst
rename to docs/source/driver/cpp/flight_sql.rst
index 1aa5318..a67c617 100644
--- a/docs/source/cpp/driver/flight_sql.rst
+++ b/docs/source/driver/cpp/flight_sql.rst
@@ -26,7 +26,7 @@ Installation
============
The Flight SQL driver is shipped as part of the Arrow C++ libraries
-and PyArrow. See :ref:`Installation <cpp-install-flight-sql>`.
+and PyArrow.
Usage
=====
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/driver/cpp/index.rst
similarity index 74%
copy from docs/source/cpp/driver/index.rst
copy to docs/source/driver/cpp/index.rst
index 8bbe521..6a049a8 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/driver/cpp/index.rst
@@ -15,16 +15,21 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
-
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+============
+C/C++/Python
+============
.. toctree::
:maxdepth: 1
+ :caption: Drivers
flight_sql
postgresql
sqlite
+
+ features
+
+The ADBC project ships some drivers. Others may (eventually) be
+available from database vendors or third parties. The drivers here
+implement the C API standard and are directly usable in C/C++. They
+also provide Python bindings.
diff --git a/docs/source/cpp/driver/postgresql.rst b/docs/source/driver/cpp/postgresql.rst
similarity index 67%
rename from docs/source/cpp/driver/postgresql.rst
rename to docs/source/driver/cpp/postgresql.rst
index cc22ef7..1dd47af 100644
--- a/docs/source/cpp/driver/postgresql.rst
+++ b/docs/source/driver/cpp/postgresql.rst
@@ -29,11 +29,17 @@ overall approach.
.. _libpq: https://www.postgresql.org/docs/current/libpq.html
.. _pgeon: https://github.com/0x0L/pgeon
+Status
+======
+
+The PostgreSQL driver is experimental. Performance/optimization and
+support for complex types and different ADBC features is still
+ongoing.
+
Installation
============
-The PostgreSQL driver is shipped as a standalone library. See
-:ref:`Installation <cpp-install-libpq>`.
+The PostgreSQL driver is shipped as a standalone library.
Usage
=====
@@ -68,3 +74,39 @@ the :cpp:class:`AdbcDatabase`. This should be a `connection URI
uri = "postgresql://localhost:5433"
with adbc_driver_postgresql.dbapi.connect(uri) as conn:
pass
+
+Supported Features
+==================
+
+Bulk Ingestion
+--------------
+
+Bulk ingestion is supported. The mapping from Arrow types to
+PostgreSQL types is the same as below.
+
+Partitioned Result Sets
+-----------------------
+
+Partitioned result sets are not supported.
+
+Performance
+-----------
+
+The driver makes use of COPY and the binary format to speed up result
+set reading. Formal benchmarking is forthcoming.
+
+Transactions
+------------
+
+Transactions are supported.
+
+Type Support
+------------
+
+PostgreSQL allows defining new types at runtime, so the driver must
+build a mapping of available types. This is currently done once at
+startup.
+
+Type support is currently limited. Parameter binding and bulk
+ingestion support int16, int32, int64, and string. Reading result
+sets is limited to int32, int64, float, double, and string.
diff --git a/docs/source/cpp/driver/sqlite.rst b/docs/source/driver/cpp/sqlite.rst
similarity index 52%
rename from docs/source/cpp/driver/sqlite.rst
rename to docs/source/driver/cpp/sqlite.rst
index 02e4457..6bdae99 100644
--- a/docs/source/cpp/driver/sqlite.rst
+++ b/docs/source/driver/cpp/sqlite.rst
@@ -21,11 +21,17 @@ SQLite Driver
The SQLite driver provides access to SQLite databases.
+Status
+======
+
+The SQLite driver is essentially a "reference" driver that was used
+during ADBC development. It generally supports most ADBC features but
+has not received attention to optimization.
+
Installation
============
-The SQLite driver is shipped as a standalone library. See
-:ref:`Installation <cpp-install-sqlite>`.
+The SQLite driver is shipped as a standalone library.
Usage
=====
@@ -60,3 +66,47 @@ shared across all connections.
with adbc_driver_sqlite.dbapi.connect() as conn:
pass
+
+Supported Features
+==================
+
+Bulk Ingestion
+--------------
+
+Bulk ingestion is supported. The mapping from Arrow types to SQLite
+types is the same as below.
+
+Partitioned Result Sets
+-----------------------
+
+Partitioned result sets are not supported.
+
+Transactions
+------------
+
+Transactions are supported.
+
+Type Inference/Type Support
+---------------------------
+
+SQLite does not enforce that values in a column have the same type.
+The SQLite driver will attempt to infer the best Arrow type for a
+column as the result set is read. When reading the first batch of
+data, the driver will be in "type promotion" mode. The inferred type
+of each column begins as INT64, and will convert to DOUBLE, then
+STRING, if needed. After that, reading more batches will attempt to
+convert to the inferred types. An error will be raised if this is not
+possible (e.g. if a string value is read but the column was inferred
+to be of type INT64).
+
+In the future, other behaviors may also be supported.
+
+Bound parameters will be translated to SQLite's integer,
+floating-point, or text types as appropriate. Supported Arrow types
+are: signed and unsigned integers, (large) strings, float, and double.
+
+Driver-specific options:
+
+``adbc.sqlite.query.batch_rows``
+ The size of batches to read. Hence, this also controls how many
+ rows are read to infer the Arrow type.
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/driver/java/flight_sql.rst
similarity index 71%
copy from docs/source/cpp/driver/index.rst
copy to docs/source/driver/java/flight_sql.rst
index 8bbe521..90f6372 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/driver/java/flight_sql.rst
@@ -15,16 +15,19 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
+==========
+Flight SQL
+==========
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+The Flight SQL Driver provides access to any database implementing a
+:doc:`arrow:format/FlightSql` compatible endpoint.
-.. toctree::
- :maxdepth: 1
+Installation
+============
- flight_sql
- postgresql
- sqlite
+Add a dependency on ``org.apache.arrow.adbc:adbc-driver-flight-sql``.
+
+Usage
+=====
+
+Provide the parameter ``adbc.url`` when creating the database.
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/driver/java/index.rst
similarity index 80%
copy from docs/source/cpp/driver/index.rst
copy to docs/source/driver/java/index.rst
index 8bbe521..614754e 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/driver/java/index.rst
@@ -15,16 +15,17 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
-
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+====
+Java
+====
.. toctree::
:maxdepth: 1
+ :caption: Drivers
flight_sql
- postgresql
- sqlite
+ jdbc
+
+The ADBC project ships some drivers. Others may (eventually) be
+available from database vendors or third parties. The drivers here
+implement the Java API standard.
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/driver/java/jdbc.rst
similarity index 74%
copy from docs/source/cpp/driver/index.rst
copy to docs/source/driver/java/jdbc.rst
index 8bbe521..6409c96 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/driver/java/jdbc.rst
@@ -15,16 +15,18 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
+============
+JDBC Adapter
+============
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+The JDBC Adapter provides access to any database with a JDBC driver.
-.. toctree::
- :maxdepth: 1
+Installation
+============
- flight_sql
- postgresql
- sqlite
+Add a dependency on ``org.apache.arrow.adbc:adbc-driver-jdbc``.
+
+Usage
+=====
+
+Provide the parameter ``adbc.url`` when creating the database.
diff --git a/docs/source/python/index.rst b/docs/source/go/index.rst
similarity index 91%
copy from docs/source/python/index.rst
copy to docs/source/go/index.rst
index e41b85c..570eae9 100644
--- a/docs/source/python/index.rst
+++ b/docs/source/go/index.rst
@@ -15,13 +15,11 @@
.. specific language governing permissions and limitations
.. under the License.
-======
-Python
-======
+===
+Go
+===
.. toctree::
:maxdepth: 2
- ../cpp/install
- ../cpp/driver/index
- api/index
+.. note:: Under construction
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1938240..eb1064d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,33 +27,39 @@ query parameters. These APIs are then implemented by drivers (or a
driver manager) that use some underlying protocol to work with
specific databases.
-ADBC aims to provide applications with a single API to work with
-multiple databases, both Arrow-native and not. Application code
-should not need to juggle conversions from non-Arrow-native
-datasources alongside bindings for multiple Arrow-native database
-protocols. And Arrow Flight SQL by itself cannot solve this problem,
-because it's a specific wire protocol that not all databases will
-implement.
+ADBC aims to provide applications with a single, Arrow-based API to
+work with multiple databases, whether Arrow-native or not.
+Application code should not need to juggle conversions from
+non-Arrow-native datasources alongside bindings for multiple
+Arrow-native database protocols.
.. toctree::
:maxdepth: 1
- :caption: Specifications:
+ :caption: Specifications
format/specification
format/versioning
format/comparison
+.. toctree::
+ :maxdepth: 2
+ :caption: Drivers
+
+ driver/cpp/index
+ driver/java/index
+
.. toctree::
:maxdepth: 1
- :caption: Supported Environments:
+ :caption: Language-Specific APIs
C/C++ <cpp/index>
+ Go <go/index>
Java <java/index>
Python <python/index>
.. toctree::
:maxdepth: 1
- :caption: Contributing:
+ :caption: Contributing
contributing
nightly
diff --git a/docs/source/nightly.rst b/docs/source/nightly.rst
index 6f8b6f8..5540ef5 100644
--- a/docs/source/nightly.rst
+++ b/docs/source/nightly.rst
@@ -56,12 +56,12 @@ Example::
* - Linux
- Yes ✅
- - No ❌
+ - Yes ✅
* - macOS
- Yes ✅
- - No ❌
+ - Yes ✅
* - Windows
- - No ❌
+ - No ✅
- No ❌
diff --git a/docs/source/python/api/adbc_driver_manager.rst b/docs/source/python/api/adbc_driver_manager.rst
index 231b561..dfa9fe8 100644
--- a/docs/source/python/api/adbc_driver_manager.rst
+++ b/docs/source/python/api/adbc_driver_manager.rst
@@ -17,9 +17,9 @@
.. default-domain:: py
-===================
-adbc_driver_manager
-===================
+=======================
+``adbc_driver_manager``
+=======================
Low-Level API
=============
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/python/api/adbc_driver_postgresql.rst
similarity index 69%
copy from docs/source/cpp/driver/index.rst
copy to docs/source/python/api/adbc_driver_postgresql.rst
index 8bbe521..397f979 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/python/api/adbc_driver_postgresql.rst
@@ -15,16 +15,22 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
+.. default-domain:: py
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+==========================
+``adbc_driver_postgresql``
+==========================
-.. toctree::
- :maxdepth: 1
+Low-Level API
+=============
- flight_sql
- postgresql
- sqlite
+.. automodule:: adbc_driver_postgresql
+
+.. autofunction:: adbc_driver_postgresql.connect
+
+DBAPI 2.0 API
+=============
+
+.. automodule:: adbc_driver_postgresql.dbapi
+
+.. autofunction:: adbc_driver_postgresql.dbapi.connect
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/python/api/adbc_driver_sqlite.rst
similarity index 71%
rename from docs/source/cpp/driver/index.rst
rename to docs/source/python/api/adbc_driver_sqlite.rst
index 8bbe521..49aa566 100644
--- a/docs/source/cpp/driver/index.rst
+++ b/docs/source/python/api/adbc_driver_sqlite.rst
@@ -15,16 +15,22 @@
.. specific language governing permissions and limitations
.. under the License.
-=======
-Drivers
-=======
+.. default-domain:: py
-The project ships with a number of drivers for particular database
-protocols/databases. More may be available from third parties.
+======================
+``adbc_driver_sqlite``
+======================
-.. toctree::
- :maxdepth: 1
+Low-Level API
+=============
- flight_sql
- postgresql
- sqlite
+.. automodule:: adbc_driver_sqlite
+
+.. autofunction:: adbc_driver_sqlite.connect
+
+DBAPI 2.0 API
+=============
+
+.. automodule:: adbc_driver_sqlite.dbapi
+
+.. autofunction:: adbc_driver_sqlite.dbapi.connect
diff --git a/docs/source/python/api/index.rst b/docs/source/python/api/index.rst
index 1dd99a0..89afe14 100644
--- a/docs/source/python/api/index.rst
+++ b/docs/source/python/api/index.rst
@@ -20,6 +20,8 @@ Python API Reference
====================
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
adbc_driver_manager
+ adbc_driver_postgresql
+ adbc_driver_sqlite
diff --git a/docs/source/python/driver_manager.rst b/docs/source/python/driver_manager.rst
new file mode 100644
index 0000000..8234a0f
--- /dev/null
+++ b/docs/source/python/driver_manager.rst
@@ -0,0 +1,66 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you 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.
+
+.. py:currentmodule:: adbc_driver_manager
+
+==============
+Driver Manager
+==============
+
+The driver manager is a library that provides bindings to the ADBC C
+API. It delegates to dynamically-loaded drivers. This allows
+applications to use multiple drivers simultaneously, and decouple
+themselves from the specific driver.
+
+The Python driver manager provides both low-level bindings that are
+essentially the same as the C API. If PyArrow is installed, it also
+provides high-level bindings that implement the DBAPI_ (PEP 249)
+standard.
+
+.. _DBAPI: https://peps.python.org/pep-0249/
+
+Installation
+============
+
+.. code-block:: shell
+
+ pip install adbc_driver_manager
+
+Usage
+=====
+
+First create a :py:class:`AdbcDatabase`, passing ``driver`` and
+(optionally) ``entrypoint``. ``driver`` must be the name of a library
+to load, or the path to a library to load. ``entrypoint``, if
+provided, should be the name of the symbol that serves as the ADBC
+entrypoint (see :cpp:type:`AdbcDriverInitFunc`). Then, create a
+:py:class:`AdbcConnection`.
+
+.. code-block:: python
+
+ import adbc_driver_manager
+ with adbc_driver_manager.AdbcDatabase(driver="adbc_driver_sqlite") as db:
+ with adbc_driver_manager.AdbcConnection(db) as conn:
+ pass
+
+The Python bindings for each driver abstract these steps for you
+behind a convenient ``connect`` function.
+
+API Reference
+=============
+
+See the API reference: :doc:`./api/adbc_driver_manager`.
diff --git a/docs/source/python/index.rst b/docs/source/python/index.rst
index e41b85c..a27e1f7 100644
--- a/docs/source/python/index.rst
+++ b/docs/source/python/index.rst
@@ -22,6 +22,5 @@ Python
.. toctree::
:maxdepth: 2
- ../cpp/install
- ../cpp/driver/index
+ driver_manager
api/index
diff --git a/python/adbc_driver_manager/adbc_driver_manager/__init__.py b/python/adbc_driver_manager/adbc_driver_manager/__init__.py
index ff19744..2d91d82 100644
--- a/python/adbc_driver_manager/adbc_driver_manager/__init__.py
+++ b/python/adbc_driver_manager/adbc_driver_manager/__init__.py
@@ -45,6 +45,7 @@ from ._lib import (
NotSupportedError,
OperationalError,
ProgrammingError,
+ Warning,
)
from ._version import __version__
@@ -72,4 +73,5 @@ __all__ = [
"NotSupportedError",
"OperationalError",
"ProgrammingError",
+ "Warning",
]