diff --git a/docs/source/cpp/driver_example.rst b/docs/source/cpp/driver_example.rst index b36134c5a2..0776b5e8ef 100644 --- a/docs/source/cpp/driver_example.rst +++ b/docs/source/cpp/driver_example.rst @@ -22,5 +22,28 @@ Driver Example .. recipe:: recipe_driver/driver_example.cc :language: cpp +Low-level testing +================= + .. recipe:: recipe_driver/driver_example_test.cc :language: cpp + +High-level testing +================== + +.. recipe:: recipe_driver/driver_example.py + +High-level tests can also be written in R using the ``adbcdrivermanager`` +package. + +.. code-block:: r + + library(adbcdrivermanager) + + drv <- adbc_driver("build/libdriver_example.dylib") + db <- adbc_database_init(drv, uri = paste0("file://", getwd())) + con <- adbc_connection_init(db) + + data.frame(col = 1:3) |> write_adbc(con, "example.arrows") + con |> read_adbc("SELECT * FROM example.arrows") |> as.data.frame() + unlink("example.arrows") diff --git a/docs/source/cpp/recipe_driver/driver_example.py b/docs/source/cpp/recipe_driver/driver_example.py new file mode 100644 index 0000000000..234cc2f780 --- /dev/null +++ b/docs/source/cpp/recipe_driver/driver_example.py @@ -0,0 +1,62 @@ +# 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. + +# RECIPE STARTS HERE +#: After verifying the basic driver functionality, we can use the +#: ``adbc_driver_manager`` Python package's built-in dbapi implementation +#: to expose a ready-to-go Pythonic database API. This is also useful for +#: high-level testing! +#: +#: First, we'll import pathlib for a few path calculations and the +#: ``adbc_driver_manager``'s ``dbapi`` module: +from pathlib import Path + +from adbc_driver_manager import dbapi +#: Next, we'll define a ``connect()`` function that wraps ``dbapi.connect()`` +#: with the location of the shared library we built using ``cmake`` in the previous +#: section. For the purposes of our tutorial, this will be in the CMake ``build/`` +#: directory. +def connect(uri: str): + build_dir = Path(__file__).parent / "build" + for lib in [ + "libdriver_example.dylib", + "libdriver_example.so", + "driver_example.dll", + ]: + driver_lib = build_dir / lib + if driver_lib.exists(): + return dbapi.connect( + driver=str(driver_lib.resolve()), db_kwargs={"uri": uri} + ) + + raise RuntimeError("Can't find driver shared object") +#: Next, we can give our driver a go! The two pieces we implemented in the driver +#: were the "bulk ingest" feature and "select all from", so let's see if it works! +if __name__ == "__main__": + import pyarrow + import os + + with connect(uri=Path(__file__).parent.as_uri()) as con: + data = pyarrow.table({"col": [1, 2, 3]}) + with con.cursor() as cur: + cur.adbc_ingest("example.arrows", data, mode="create") + + with con.cursor() as cur: + cur.execute("SELECT * FROM example.arrows") + print(cur.fetchall()) + + os.unlink(Path(__file__).parent / "example.arrows") diff --git a/docs/source/cpp/recipe_driver/driver_example_test.cc b/docs/source/cpp/recipe_driver/driver_example_test.cc index 5d06f01a9b..aba2298e16 100644 --- a/docs/source/cpp/recipe_driver/driver_example_test.cc +++ b/docs/source/cpp/recipe_driver/driver_example_test.cc @@ -17,9 +17,6 @@ // RECIPE STARTS HERE -/// Low-level testing -/// ================= -/// /// After we've written a sketch of the driver, the next step is to /// ensure that it can be loaded by the driver manager and that the /// database, connection, and statement instances can be initialized and