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/15 21:52:31 UTC
[arrow-adbc] branch main updated: docs: add basic installation instructions and tutorial (#244)
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 7439261 docs: add basic installation instructions and tutorial (#244)
7439261 is described below
commit 743926163958de0c265e214a907cbe5fb49bcbc1
Author: David Li <li...@gmail.com>
AuthorDate: Thu Dec 15 16:52:25 2022 -0500
docs: add basic installation instructions and tutorial (#244)
Fixes #241.
---
ci/scripts/docs_build.sh | 1 +
docs/source/conf.py | 11 +++
docs/source/contributing.rst | 5 +-
docs/source/driver/cpp/flight_sql.rst | 10 +-
docs/source/driver/cpp/postgresql.rst | 14 +++
docs/source/driver/cpp/sqlite.rst | 15 +++
docs/source/index.rst | 6 ++
docs/source/nightly.rst | 10 +-
docs/source/python/index.rst | 1 +
docs/source/python/quickstart.rst | 178 ++++++++++++++++++++++++++++++++++
10 files changed, 244 insertions(+), 7 deletions(-)
diff --git a/ci/scripts/docs_build.sh b/ci/scripts/docs_build.sh
index 58cb6c1..917d982 100755
--- a/ci/scripts/docs_build.sh
+++ b/ci/scripts/docs_build.sh
@@ -27,6 +27,7 @@ main() {
pushd "$source_dir/docs"
make html
+ make doctest
}
main "$@"
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8bfe871..6b20ada 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -33,6 +33,7 @@ extensions = [
"breathe",
"numpydoc",
"sphinx.ext.autodoc",
+ "sphinx.ext.doctest",
"sphinx.ext.intersphinx",
"sphinx_copybutton",
"sphinx_design",
@@ -70,6 +71,16 @@ breathe_projects = {
"adbc": "../../c/apidoc/xml/",
}
+# -- Options for doctest -----------------------------------------------------
+
+doctest_global_setup = """
+try:
+ import adbc_driver_sqlite
+ import adbc_driver_sqlite.dbapi # noqa: F401
+except ImportError:
+ adbc_driver_sqlite = None
+"""
+
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
index 5458239..04d6578 100644
--- a/docs/source/contributing.rst
+++ b/docs/source/contributing.rst
@@ -15,11 +15,14 @@
.. specific language governing permissions and limitations
.. under the License.
+.. _contributing:
+
============
Contributing
============
-To contribute, see CONTRIBUTING.md_ in the repository.
+To contribute, and for build instructions, see CONTRIBUTING.md_ in the
+repository.
.. _CONTRIBUTING.md:
https://github.com/apache/arrow-adbc/blob/main/CONTRIBUTING.md
diff --git a/docs/source/driver/cpp/flight_sql.rst b/docs/source/driver/cpp/flight_sql.rst
index d8ae7a6..63974fc 100644
--- a/docs/source/driver/cpp/flight_sql.rst
+++ b/docs/source/driver/cpp/flight_sql.rst
@@ -26,7 +26,9 @@ Installation
============
The Flight SQL driver is shipped as part of the Arrow C++ libraries
-and PyArrow.
+and PyArrow. See the `main Arrow project website
+<https://arrow.apache.org/install/>`_ for instructions. Version >= 11
+is required.
Usage
=====
@@ -116,8 +118,10 @@ These options map 1:1 with the options in FlightClientOptions:
``arrow.flight.sql.client_option.private_key``
The private key to use for mTLS.
-``arrow.flight.sql.client_option.generic_int_option.``
-``arrow.flight.sql.client_option.generic_string_option.``
+``arrow.flight.sql.client_option.generic_int_option.<OPTION_NAME>``
+ Option prefixes used to specify generic transport-layer options.
+
+``arrow.flight.sql.client_option.generic_string_option.<OPTION_NAME>``
Option prefixes used to specify generic transport-layer options.
``arrow.flight.sql.client_option.disable_server_verification``
diff --git a/docs/source/driver/cpp/postgresql.rst b/docs/source/driver/cpp/postgresql.rst
index 1dd47af..c39d7cf 100644
--- a/docs/source/driver/cpp/postgresql.rst
+++ b/docs/source/driver/cpp/postgresql.rst
@@ -41,6 +41,20 @@ Installation
The PostgreSQL driver is shipped as a standalone library.
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ See :ref:`contributing` to build and install the package from source.
+
+ .. tab-item:: Python
+ :sync: python
+
+ .. code-block:: shell
+
+ pip install adbc_driver_postgresql
+
Usage
=====
diff --git a/docs/source/driver/cpp/sqlite.rst b/docs/source/driver/cpp/sqlite.rst
index 6bdae99..3b2b380 100644
--- a/docs/source/driver/cpp/sqlite.rst
+++ b/docs/source/driver/cpp/sqlite.rst
@@ -33,6 +33,21 @@ Installation
The SQLite driver is shipped as a standalone library.
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ See :ref:`contributing` to build and install the package from source.
+
+ .. tab-item:: Python
+ :sync: python
+
+ .. code-block:: shell
+
+ pip install adbc_driver_sqlite
+
+
Usage
=====
diff --git a/docs/source/index.rst b/docs/source/index.rst
index eb1064d..f913ae0 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -48,6 +48,12 @@ Arrow-native database protocols.
driver/cpp/index
driver/java/index
+.. toctree::
+ :maxdepth: 1
+ :caption: Tutorials
+
+ python/quickstart
+
.. toctree::
:maxdepth: 1
:caption: Language-Specific APIs
diff --git a/docs/source/nightly.rst b/docs/source/nightly.rst
index 5540ef5..750edd0 100644
--- a/docs/source/nightly.rst
+++ b/docs/source/nightly.rst
@@ -41,11 +41,15 @@ Python
Packages can be installed from an alternative package index:
https://gemfury.com/arrow-adbc-nightlies
+.. warning:: You MUST explicitly specify the version, since otherwise
+ pip will install the latest version by lexicographical
+ ordering, which will likely be some random, old build.
+
Example::
- $ pip install \
- --extra-index-url https://gemfury.com/arrow-adbc-nightlies \
- adbc_driver_manager
+ pip install \
+ --extra-index-url https://repo.fury.io/arrow-adbc-nightlies \
+ adbc_driver_manager==0.0.0+g265a1b6
.. list-table:: Supported platforms for nightly Python wheels
:header-rows: 1
diff --git a/docs/source/python/index.rst b/docs/source/python/index.rst
index a27e1f7..862ee9d 100644
--- a/docs/source/python/index.rst
+++ b/docs/source/python/index.rst
@@ -22,5 +22,6 @@ Python
.. toctree::
:maxdepth: 2
+ quickstart
driver_manager
api/index
diff --git a/docs/source/python/quickstart.rst b/docs/source/python/quickstart.rst
new file mode 100644
index 0000000..8177607
--- /dev/null
+++ b/docs/source/python/quickstart.rst
@@ -0,0 +1,178 @@
+.. 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.
+
+===================
+Quickstart (Python)
+===================
+
+Here we'll briefly tour basic features of ADBC with the SQLite driver.
+
+Installation
+============
+
+.. code-block:: shell
+
+ pip install adbc_driver_manager adbc_driver_sqlite pyarrow
+
+DBAPI (PEP 249)-style API
+=========================
+
+If PyArrow is installed, ADBC provides a high-level API in the style
+of the DBAPI standard.
+
+.. testcleanup:: dbapi
+
+ cursor.close()
+ conn.close()
+
+Creating a Connection
+---------------------
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> import adbc_driver_sqlite.dbapi
+ >>> conn = adbc_driver_sqlite.dbapi.connect()
+
+In application code, the connection must be closed after usage or
+memory may leak. Connections can be used as context managers to
+accomplish this.
+
+Creating a Cursor
+-----------------
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> cursor = conn.cursor()
+
+In application code, the cursor must be closed after usage or memory
+may leak. Cursors can be used as context managers to accomplish this.
+
+Executing a Query
+-----------------
+
+We can execute a query and get the results via the normal,
+row-oriented DBAPI interface:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> cursor.execute("SELECT 1, 2.0, 'Hello, world!'")
+ >>> cursor.fetchone()
+ (1, 2.0, 'Hello, world!')
+ >>> cursor.fetchone()
+
+We can also get the results as Arrow data via a non-standard method:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> cursor.execute("SELECT 1, 2.0, 'Hello, world!'")
+ >>> cursor.fetch_arrow_table()
+ pyarrow.Table
+ 1: int64
+ 2.0: double
+ 'Hello, world!': string
+ ----
+ 1: [[1]]
+ 2.0: [[2]]
+ 'Hello, world!': [["Hello, world!"]]
+
+Parameterized Queries
+---------------------
+
+We can bind parameters in our queries:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> cursor.execute("SELECT ? + 1 AS the_answer", parameters=(41,))
+ >>> cursor.fetch_arrow_table()
+ pyarrow.Table
+ the_answer: int64
+ ----
+ the_answer: [[42]]
+
+Ingesting Bulk Data
+-------------------
+
+So far we've mostly demonstrated the usual DBAPI interface. The ADBC
+APIs also offer additional methods. For example, we can insert a
+table of Arrow data into a new database table:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> import pyarrow
+ >>> table = pyarrow.table([[1, 2], ["a", None]], names=["ints", "strs"])
+ >>> cursor.adbc_ingest("sample", table)
+ 2
+ >>> cursor.execute("SELECT COUNT(DISTINCT ints) FROM sample")
+ >>> cursor.fetchall()
+ [(2,)]
+
+We can also append to an existing table:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> table = pyarrow.table([[2, 3], [None, "c"]], names=["ints", "strs"])
+ >>> cursor.adbc_ingest("sample", table, mode="append")
+ 2
+ >>> cursor.execute("SELECT COUNT(DISTINCT ints) FROM sample")
+ >>> cursor.fetchall()
+ [(3,)]
+
+Getting Database/Driver Metadata
+--------------------------------
+
+We can get information about the driver and the database using another
+extension method, this time on the connection itself:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> conn.adbc_get_info()["vendor_name"]
+ 'SQLite'
+ >>> conn.adbc_get_info()["driver_name"]
+ 'ADBC SQLite Driver'
+
+We can also query for tables and columns in the database. This gives
+a nested structure describing all the catalogs, schemas, tables, and
+columns:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> info = conn.adbc_get_objects().read_all().to_pylist()
+ >>> main_catalog = info[0]
+ >>> schema = main_catalog["catalog_db_schemas"][0]
+ >>> tables = schema["db_schema_tables"]
+ >>> tables[0]["table_name"]
+ 'sample'
+ >>> [column["column_name"] for column in tables[0]["table_columns"]]
+ ['ints', 'strs']
+
+We can get the Arrow schema of a table:
+
+.. doctest:: dbapi
+ :skipif: adbc_driver_sqlite is None
+
+ >>> conn.adbc_get_table_schema("sample")
+ ints: int64
+ strs: string