ianmcook commented on code in PR #3388:
URL: https://github.com/apache/arrow-adbc/pull/3388#discussion_r2317204318
##########
docs/source/python/driver_manager.rst:
##########
@@ -43,34 +39,52 @@ Installation
Usage
=====
-.. warning:: This API is for low level usage only. **You almost certainly
- should not use this**, instead use the entrypoints provided by
- driver packages, for example:
+Using the driver manager is different from using the individual,
driver-specific
+packages such as ``adbc_driver_postgresql``.
- - :func:`adbc_driver_sqlite.dbapi.connect`
- - :func:`adbc_driver_sqlite.connect`
+With the driver-specific packages, you connect to the target database with the
+``connect`` method provided by the package you're using. For example,
+:func:`adbc_driver_postgresql.connect` or :func:`adbc_driver_sqlite.connect`.
-The Python bindings for each driver abstract the steps here for you behind a
-convenient ``connect`` function. For example, prefer
-:func:`adbc_driver_sqlite.connect` or :func:`adbc_driver_postgresql.connect`
-to manually constructing the connection as demonstrated here.
+With the driver manager package, you use a single package and API regardless of
+the database you're connecting to.
-To manually create a connection: 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 :c:type:`AdbcDriverInitFunc`). Then, create a
-:py:class:`AdbcConnection`.
+Low-Level API
+-------------
+
+First, create an :py:class:`AdbcDatabase`, passing ``driver`` and (optionally)
+``entrypoint``. Then, create an :py:class:`AdbcConnection`.
+
+.. note:: See :doc:`../format/driver_manifests` for more information on what
to pass as the ``driver`` argument and how the driver manager finds and loads
drivers.
.. code-block:: python
import adbc_driver_manager
- # You must build/locate the driver yourself
+ # Note: You must build/locate the driver yourself
with
adbc_driver_manager.AdbcDatabase(driver="PATH/TO/libadbc_driver_sqlite.so") as
db:
with adbc_driver_manager.AdbcConnection(db) as conn:
pass
+Connecting to a second database could be done in the same session using the
same
+code just with a different ``driver`` argument.
+
+DBAPI API
+---------
+
+Use the DBAPI_ API by calling the ``dbapi.connect`` method, passing ``driver``
+and (optionally) ``entrypoint``. These arguments work the same as with the
+low-level API.
+
+.. code-block:: python
+
+ from adbc_driver_manager import dbapi
+
+ # Note: You must build/locate the driver yourself
Review Comment:
```suggestion
# Note: You must install the driver shared library
(``.so``/``.dylib``/``.dll`` file) separately
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscr...@arrow.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
