This is an automated email from the ASF dual-hosted git repository.
jiayu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sedona-db.git
The following commit(s) were added to refs/heads/main by this push:
new 39aaa40 docs(python/sedonadb): Ensure Python examples use `sedona.db`
imports (#96)
39aaa40 is described below
commit 39aaa406728d539ffbf7f45bd830b9dce537d36a
Author: Dewey Dunnington <[email protected]>
AuthorDate: Tue Sep 16 23:50:30 2025 -0500
docs(python/sedonadb): Ensure Python examples use `sedona.db` imports (#96)
---
python/sedonadb/python/sedonadb/context.py | 34 +++++++++---------
python/sedonadb/python/sedonadb/dataframe.py | 54 ++++++++++++----------------
python/sedonadb/python/sedonadb/dbapi.py | 20 ++++++++++-
python/sedonadb/python/sedonadb/utility.py | 49 +++++++++++++++++++++++++
4 files changed, 107 insertions(+), 50 deletions(-)
diff --git a/python/sedonadb/python/sedonadb/context.py
b/python/sedonadb/python/sedonadb/context.py
index 13eebea..32f9dee 100644
--- a/python/sedonadb/python/sedonadb/context.py
+++ b/python/sedonadb/python/sedonadb/context.py
@@ -21,6 +21,7 @@ from typing import Any, Dict, Iterable, Literal, Optional,
Union
from sedonadb._lib import InternalContext, configure_proj_shared
from sedonadb.dataframe import DataFrame, _create_data_frame
+from sedonadb.utility import sedona # noqa: F401
class SedonaContext:
@@ -53,9 +54,9 @@ class SedonaContext:
Examples:
- >>> import sedonadb, pandas as pd
- >>> con = sedonadb.connect()
- >>> con.create_data_frame(pd.DataFrame({"x": [1,
2]})).head(1).show()
+ >>> import pandas as pd
+ >>> sd = sedona.db.connect()
+ >>> sd.create_data_frame(pd.DataFrame({"x": [1,
2]})).head(1).show()
┌───────┐
│ x │
│ int64 │
@@ -75,17 +76,16 @@ class SedonaContext:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geom").to_view("foofy")
- >>> con.view("foofy").show()
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geom").to_view("foofy")
+ >>> sd.view("foofy").show()
┌────────────┐
│ geom │
│ geometry │
╞════════════╡
│ POINT(0 1) │
└────────────┘
- >>> con.drop_view("foofy")
+ >>> sd.drop_view("foofy")
"""
return DataFrame(self._impl, self._impl.view(name))
@@ -98,10 +98,9 @@ class SedonaContext:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geom").to_view("foofy")
- >>> con.drop_view("foofy")
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geom").to_view("foofy")
+ >>> sd.drop_view("foofy")
"""
self._impl.drop_view(name)
@@ -121,9 +120,9 @@ class SedonaContext:
Examples:
- >>> import sedonadb
+ >>> sd = sedona.db.connect()
>>> url =
"https://github.com/apache/sedona-testing/raw/refs/heads/main/data/parquet/geoparquet-1.1.0.parquet";
- >>> sedonadb.connect().read_parquet(url)
+ >>> sd.read_parquet(url)
<sedonadb.dataframe.DataFrame object at ...>
"""
@@ -149,8 +148,8 @@ class SedonaContext:
Examples:
- >>> import sedonadb
- >>> sedonadb.connect().sql("SELECT ST_Point(0, 1) as geom")
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geom")
<sedonadb.dataframe.DataFrame object at ...>
"""
@@ -207,8 +206,7 @@ def configure_proj(
Examples:
- >>> import sedonadb
- >>> sedonadb.configure_proj("auto")
+ >>> sedona.db.configure_proj("auto")
"""
if preset is not None:
if preset == "pyproj":
diff --git a/python/sedonadb/python/sedonadb/dataframe.py
b/python/sedonadb/python/sedonadb/dataframe.py
index 8bbe16f..b24fed5 100644
--- a/python/sedonadb/python/sedonadb/dataframe.py
+++ b/python/sedonadb/python/sedonadb/dataframe.py
@@ -19,6 +19,8 @@ from pathlib import Path
from typing import TYPE_CHECKING, Union, Optional, Any, Iterable
from sedonadb._options import global_options
+from sedonadb.utility import sedona # noqa: F401
+
if TYPE_CHECKING:
import pandas
@@ -44,9 +46,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> df = con.sql("SELECT 1 as one")
+ >>> sd = sedona.db.connect()
+ >>> df = sd.sql("SELECT 1 as one")
>>> df.schema
SedonaSchema with 1 field:
one: non-nullable Int64
@@ -67,9 +68,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> df = con.sql("SELECT * FROM (VALUES ('one'), ('two'),
('three')) AS t(val)")
+ >>> sd = sedona.db.connect()
+ >>> df = sd.sql("SELECT * FROM (VALUES ('one'), ('two'),
('three')) AS t(val)")
>>> df.head(1).show()
┌──────┐
│ val │
@@ -91,9 +91,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> df = con.sql("SELECT * FROM (VALUES ('one'), ('two'),
('three')) AS t(val)")
+ >>> sd = sedona.db.connect()
+ >>> df = sd.sql("SELECT * FROM (VALUES ('one'), ('two'),
('three')) AS t(val)")
>>> df.limit(1).show()
┌──────┐
│ val │
@@ -118,9 +117,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> df = con.sql("SELECT * FROM (VALUES ('one'), ('two'),
('three')) AS t(val)")
+ >>> sd = sedona.db.connect()
+ >>> df = sd.sql("SELECT * FROM (VALUES ('one'), ('two'),
('three')) AS t(val)")
>>> df.count()
3
@@ -162,10 +160,9 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geom").to_view("foofy")
- >>> con.view("foofy").show()
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geom").to_view("foofy")
+ >>> sd.view("foofy").show()
┌────────────┐
│ geom │
│ geometry │
@@ -187,9 +184,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geom").to_memtable().show()
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geom").to_memtable().show()
┌────────────┐
│ geom │
│ geometry │
@@ -215,9 +211,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geometry").to_arrow_table()
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geometry").to_arrow_table()
pyarrow.Table
geometry: extension<geoarrow.wkb<WkbType>> not null
----
@@ -249,9 +244,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geometry").to_pandas()
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geometry").to_pandas()
geometry
0 POINT (0 1)
@@ -296,12 +290,11 @@ class DataFrame:
Examples:
- >>> import sedonadb
>>> import tempfile
- >>> con = sedonadb.connect()
+ >>> sd = sedona.db.connect()
>>> td = tempfile.TemporaryDirectory()
>>> url =
"https://github.com/apache/sedona-testing/raw/refs/heads/main/data/parquet/geoparquet-1.1.0.parquet";
- >>> con.read_parquet(url).to_parquet(f"{td.name}/tmp.parquet")
+ >>> sd.read_parquet(url).to_parquet(f"{td.name}/tmp.parquet")
"""
@@ -347,9 +340,8 @@ class DataFrame:
Examples:
- >>> import sedonadb
- >>> con = sedonadb.connect()
- >>> con.sql("SELECT ST_Point(0, 1) as geometry").show()
+ >>> sd = sedona.db.connect()
+ >>> sd.sql("SELECT ST_Point(0, 1) as geometry").show()
┌────────────┐
│ geometry │
│ geometry │
diff --git a/python/sedonadb/python/sedonadb/dbapi.py
b/python/sedonadb/python/sedonadb/dbapi.py
index cfa8a43..fd43171 100644
--- a/python/sedonadb/python/sedonadb/dbapi.py
+++ b/python/sedonadb/python/sedonadb/dbapi.py
@@ -17,10 +17,28 @@
import adbc_driver_manager.dbapi
import sedonadb.adbc
+from sedonadb.utility import sedona # noqa: F401
def connect(**kwargs) -> "Connection":
- """Connect to Sedona via ADBC."""
+ """Connect to Sedona via Python DBAPI
+
+ Creates a DBAPI-compatible connection as a thin wrapper around the
+ ADBC Python driver manager's DBAPI compatibility layer. Support for
+ DBAPI is experimental.
+
+ Args:
+ kwargs: Extra keyword arguments passed to
+ `adbc_driver_manager.dbapi.Connection()`.
+
+ Examples:
+
+ >>> con = sedona.dbapi.connect()
+ >>> with con.cursor() as cur:
+ ... cur.execute("SELECT 1 as one")
+ ... cur.fetchall()
+ [(1,)]
+ """
db = None
conn = None
diff --git a/python/sedonadb/python/sedonadb/utility.py
b/python/sedonadb/python/sedonadb/utility.py
new file mode 100644
index 0000000..38f10a0
--- /dev/null
+++ b/python/sedonadb/python/sedonadb/utility.py
@@ -0,0 +1,49 @@
+# 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.
+
+
+class Sedona:
+ """Mock sedona Python module
+
+ The Apache Sedaona Python ecosystem is centered around the apache-sedona
Python
+ package which provides the `sedona` modules. To decouple the maintenance
and
+ provide fine-grained dependency control for projects that need it, sedonadb
+ is distributed as a standalone package. This mock `sedona` module lets us
write
+ user-facing docstrings that use the documented install/import without
requiring
+ a circular dependency on apache-sedona for testing.
+ """
+
+ @property
+ def db(self):
+ import sedonadb
+
+ return sedonadb
+
+ @property
+ def testing(self):
+ import sedonadb.testing
+
+ return sedonadb.testing
+
+ @property
+ def dbapi(self):
+ import sedonadb.dbapi
+
+ return sedonadb.dbapi
+
+
+sedona = Sedona()
