From 15e34d52025ba7591673836e04bd5a34e6dfa1d8 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 10 Jul 2024 00:38:56 -0400 Subject: [PATCH] docs: clarify that driver manager is probably not what you want Fixes #1981. --- docs/source/python/driver_manager.rst | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/source/python/driver_manager.rst b/docs/source/python/driver_manager.rst index 8234a0f44c..3204a8e0b6 100644 --- a/docs/source/python/driver_manager.rst +++ b/docs/source/python/driver_manager.rst @@ -43,23 +43,34 @@ Installation 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 +.. 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: + + - :func:`adbc_driver_sqlite.dbapi.connect` + - :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. + +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 :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: + + # 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 -The Python bindings for each driver abstract these steps for you -behind a convenient ``connect`` function. - API Reference =============