From 3cb63b0d7ee031b212fd8c9649f26dab70247cc9 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Sat, 7 Nov 2026 10:50:56 +0900 Subject: [PATCH 1/2] Docs: embedded bindings or a driver? A chooser in the README and the docs People mix up the Python embedded bindings (arcadedb, arcadedb-jvm) and the official drivers (arcadedb-driver over HTTP, arcadedb-driver-grpc over gRPC). The index already compared the bindings with the HTTP driver only, and the README had one sentence. Add one 4-row table (what it is, needs a server, package and import name, use it when) in the README and on which-package.adoc, where the full section also has the rule of thumb, the naming note (arcadedb is the embedded package, arcadedb-driver is the client), the gRPC plugin requirement, the Bolt/PostgreSQL/MongoDB/Redis note, and links to the driver pages of the main manual. The index and installation pages get one pointer sentence each. Prose and links only, no new behaviour claim, no speed claim. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 15 ++++++- docs/modules/ROOT/pages/index.adoc | 4 ++ docs/modules/ROOT/pages/installation.adoc | 2 + docs/modules/ROOT/pages/which-package.adoc | 51 ++++++++++++++++++++-- 4 files changed, 67 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b6df9c5..dd063ac 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,19 @@ Python bindings for [ArcadeDB](https://arcadedb.com), the multi-model database ( Both packages `import arcadedb`, and they have the same public API. Install one, not both. Not sure which? Read [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc). +## Embedded bindings or drivers? + +This repository is the embedded bindings: the engine runs inside your Python process. The official [drivers](https://github.com/ArcadeData/arcadedb-drivers) are clients of a running ArcadeDB server. Do not mix them up. + +| | Embedded bindings (this repository) | Drivers | +|---|---|---| +| What it is | The ArcadeDB engine, inside your Python process | Python clients of an ArcadeDB server, HTTP (sync and async) or gRPC. They contain no engine | +| Needs a server? | No. An in-process HTTP server and Studio are optional | Yes: the Docker image `arcadedata/arcadedb` or any ArcadeDB server. The gRPC driver also needs the server's gRPC plugin | +| Package and import | `arcadedb` or `arcadedb-jvm`, `import arcadedb` | [`arcadedb-driver`](https://pypi.org/project/arcadedb-driver/), `import arcadedb_driver` (HTTP); [`arcadedb-driver-grpc`](https://pypi.org/project/arcadedb-driver-grpc/), `import arcadedb_driver_grpc` (gRPC) | +| Use it when | One process, no server: tests, notebooks, scripts, an agent that owns its data | Several clients, an existing server, a service boundary, or clients that are not Python | + +You can also use both, for example the bindings for a job and the HTTP driver for a shared server. Driver docs: [HTTP](https://docs.arcadedb.com/arcadedb/how-to/connectivity/drivers/python-http), [gRPC](https://docs.arcadedb.com/arcadedb/how-to/connectivity/drivers/python-grpc). More in [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc#embedded-or-driver). + ## Install ```bash @@ -66,8 +79,6 @@ This prints `Name: Alice` (the engine also logs to standard error). `create_data > New in 26.11.1: the `arcadedb-jvm` wheels carry the Studio web UI, which the server then serves. Studio used to bundle ApexCharts, which is no longer open source ([ArcadeData/arcadedb#10579](https://github.com/ArcadeData/arcadedb/issues/10579)), and [ArcadeData/arcadedb#10627](https://github.com/ArcadeData/arcadedb/pull/10627) replaced it with Apache ECharts. The earlier 26.10.x wheels on PyPI have no Studio. -For several processes, other languages, HA or replication, run the official Docker image `arcadedata/arcadedb` ([ArcadeDB server](https://docs.arcadedb.com)) and connect with [`arcadedb-driver`](https://pypi.org/project/arcadedb-driver/) (HTTP client, developed in [ArcadeData/arcadedb-drivers](https://github.com/ArcadeData/arcadedb-drivers)). - ## Packages on PyPI | Package | What it is | Status | diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index b6d11ef..5846bb3 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -23,6 +23,8 @@ These packages run the ArcadeDB engine inside your Python process, with no netwo Not sure which one? Take `{native-pkg-name}`, and read xref:which-package.adoc[Which package?] to decide for sure. Install one of them, not both. +These are the embedded bindings: the engine runs in your process. The official drivers (`{driver-pkg-name}` and `{grpc-driver-pkg-name}`) are clients of a running ArcadeDB server and contain no engine. To decide between the two, see xref:which-package.adoc#embedded-or-driver[Embedded bindings or a driver?]. + // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name NOTE: *First release.* The first release of this layout is 26.11.1, and both packages have a final release on PyPI. A plain `uv add {native-pkg-name}` installs the final. See xref:installation.adoc[Installation]. @@ -52,6 +54,8 @@ This page is the map. xref:installation.adoc[Installation] and xref:quickstart.a ArcadeDB reaches Python in two ways. Pick by where the engine should run. +The table compares the bindings with the HTTP driver. The gRPC driver (`{grpc-driver-pkg-name}`) is the other official client, and xref:which-package.adoc#embedded-or-driver[Embedded bindings or a driver?] covers both. + [cols="1,2,2"] |=== | | Embedded bindings (this component) | HTTP driver diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index 8dfca6b..a8ce4b5 100644 --- a/docs/modules/ROOT/pages/installation.adoc +++ b/docs/modules/ROOT/pages/installation.adoc @@ -23,6 +23,8 @@ Pick one of the two packages. Both import as `{import-name}`. If you are not sur Install one of them, not both. If both are installed, `import arcadedb` raises an `ImportError` that names both packages. See xref:which-package.adoc[Which package?] for the comparison, and for how to switch. +Both packages run the engine inside your Python process. If you want a client for a running ArcadeDB server instead, install a driver (`{driver-pkg-name}` or `{grpc-driver-pkg-name}`): see xref:which-package.adoc#embedded-or-driver[Embedded bindings or a driver?]. + // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name NOTE: *First release.* The first release of this layout is 26.11.1, and both packages have a final release on PyPI. A plain `uv add {native-pkg-name}` installs the final, and a later pre-release (`A.B.C.devN`) needs `uv add --prerelease allow {native-pkg-name}`. The same holds for `{jvm-pkg-name}`. diff --git a/docs/modules/ROOT/pages/which-package.adoc b/docs/modules/ROOT/pages/which-package.adoc index 6b3ab00..e8b7b2b 100644 --- a/docs/modules/ROOT/pages/which-package.adoc +++ b/docs/modules/ROOT/pages/which-package.adoc @@ -1,7 +1,52 @@ = Which package? -:description: Two PyPI packages carry the ArcadeDB engine for Python, arcadedb (native) and arcadedb-jvm (JVM). Both import as arcadedb. This page says which one to install. +:description: Embedded bindings or a driver, and which embedded package to install. The packages arcadedb (native) and arcadedb-jvm (JVM) run the engine in your process and import as arcadedb. The drivers are clients of a server. -Two packages give you the ArcadeDB engine inside your Python process. Both use the import name `{import-name}`, and they have the same public API. Install one of them, not both. +Two packages give you the ArcadeDB engine inside your Python process. Both use the import name `{import-name}`, and they have the same public API. Install one of them, not both. If you are not sure that you want the engine in your process at all, read the next section first. + +[[embedded-or-driver]] +== Embedded bindings or a driver? + +Python reaches ArcadeDB in two different ways, and the names look alike. The embedded bindings (this repository) run the engine inside your Python process. The official drivers (developed in https://github.com/ArcadeData/arcadedb-drivers[ArcadeData/arcadedb-drivers]) are clients that talk to a running ArcadeDB server. A driver contains no engine. + +[cols="1,2,2"] +|=== +| | Embedded bindings (this repository) | Drivers (ArcadeData/arcadedb-drivers) + +| What it is +| The ArcadeDB engine, running inside your Python process. +| Python clients of an ArcadeDB server: `{driver-pkg-name}` over HTTP (sync and async) and `{grpc-driver-pkg-name}` over gRPC. They contain no engine. + +| Needs a server? +| No. An in-process HTTP server and Studio are optional (`create_server()`). +| Yes: the official Docker image `arcadedata/arcadedb`, or any ArcadeDB server. The gRPC driver also needs the gRPC plugin of the server, enabled with `-Darcadedb.server.plugins=Grpc:com.arcadedb.server.grpc.GrpcServerPlugin`. + +| Package and import name +| `{native-pkg-name}` (native, the default) or `{jvm-pkg-name}` (JVM). Both: `import {import-name}`. +| `{driver-pkg-name}`: `import arcadedb_driver`. `{grpc-driver-pkg-name}`: `import arcadedb_driver_grpc`. + +| Use it when +| You need no server: one process, tests, notebooks, scripts, or an agent that owns its data. +| Several clients share the data, a server already exists, you want a service boundary, or some clients are not written in Python. +|=== + +A rule of thumb: + +* No server and one process (tests, notebooks, scripts, an agent that owns its data): use the embedded bindings. +* Several clients, an existing server, a service boundary or clients in other languages: use a driver. +* You can use both. For example, run a job with the embedded bindings, and let other programs reach a shared server through the HTTP driver. + +The name `{import-name}` on PyPI is the embedded package, and the driver is `{driver-pkg-name}`. So `uv add {native-pkg-name}` gives you the engine, and `uv add {driver-pkg-name}` gives you a client that needs a server. + +// REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name +The package formerly `arcadedb-embedded` is now a shim that installs `{native-pkg-name}` (see <>). + +The driver pages of the main manual: {arcadedb-docs-url}/how-to/connectivity/drivers/python-http[Python HTTP driver], {arcadedb-docs-url}/how-to/connectivity/drivers/python-grpc[Python gRPC driver], {arcadedb-docs-url}/how-to/connectivity/drivers/native-drivers[Native drivers] and the {arcadedb-docs-url}/tutorials/python-quickstart[Python quickstart]. The manual page for the embedded bindings is {arcadedb-docs-url}/how-to/connectivity/python-embedded[Python embedded]. + +The server also speaks the Bolt, PostgreSQL, MongoDB and Redis protocols, for compatibility with existing tools. You reach them with the standard clients (`neo4j`, `psycopg`, `pymongo`, `redis-py`). ArcadeDB has no client of its own for these four. See {arcadedb-docs-url}/api-integration[API and integration], {arcadedb-docs-url}/how-to/connectivity/bolt[Neo4j Bolt], {arcadedb-docs-url}/how-to/connectivity/postgres[PostgreSQL protocol], {arcadedb-docs-url}/reference/mongodb-ql/mongo[MongoDB] and {arcadedb-docs-url}/reference/redis-ql/redis[Redis]. + +== Native build or JVM build + +If you chose the embedded bindings, pick the build. [cols="1,2,3"] |=== @@ -118,7 +163,7 @@ There is no extra to select a build: `{native-pkg-name}[jvm]` does not exist. Yo == Server use -Neither package is a server deployment. They embed the engine in one Python process. For HTTP access, Studio, many processes, other programming languages or high availability, run the official Docker image `arcadedata/arcadedb` and connect with a driver (see <>). The xref:index.adoc#embedded-vs-http[Embedded bindings or the HTTP driver] section compares the two ways. +Neither package is a server deployment. They embed the engine in one Python process. For HTTP access, Studio, many processes, other programming languages or high availability, run the official Docker image `arcadedata/arcadedb` and connect with a driver (see <>). <> compares the two ways. // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name [[old-names]] From 4f0babbea0a5053b0c4b7e42103ad966b9a93427 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Sat, 7 Nov 2026 10:51:37 +0900 Subject: [PATCH 2/2] Docs: keep HA or replication among the reasons to use a driver (the old README sentence named it) Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 +- docs/modules/ROOT/pages/which-package.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dd063ac..57722cd 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ This repository is the embedded bindings: the engine runs inside your Python pro | What it is | The ArcadeDB engine, inside your Python process | Python clients of an ArcadeDB server, HTTP (sync and async) or gRPC. They contain no engine | | Needs a server? | No. An in-process HTTP server and Studio are optional | Yes: the Docker image `arcadedata/arcadedb` or any ArcadeDB server. The gRPC driver also needs the server's gRPC plugin | | Package and import | `arcadedb` or `arcadedb-jvm`, `import arcadedb` | [`arcadedb-driver`](https://pypi.org/project/arcadedb-driver/), `import arcadedb_driver` (HTTP); [`arcadedb-driver-grpc`](https://pypi.org/project/arcadedb-driver-grpc/), `import arcadedb_driver_grpc` (gRPC) | -| Use it when | One process, no server: tests, notebooks, scripts, an agent that owns its data | Several clients, an existing server, a service boundary, or clients that are not Python | +| Use it when | One process, no server: tests, notebooks, scripts, an agent that owns its data | Several clients, an existing server, a service boundary, HA or replication, or clients that are not Python | You can also use both, for example the bindings for a job and the HTTP driver for a shared server. Driver docs: [HTTP](https://docs.arcadedb.com/arcadedb/how-to/connectivity/drivers/python-http), [gRPC](https://docs.arcadedb.com/arcadedb/how-to/connectivity/drivers/python-grpc). More in [Which package?](https://github.com/ArcadeData/arcadedb-python/blob/main/docs/modules/ROOT/pages/which-package.adoc#embedded-or-driver). diff --git a/docs/modules/ROOT/pages/which-package.adoc b/docs/modules/ROOT/pages/which-package.adoc index e8b7b2b..0e86df0 100644 --- a/docs/modules/ROOT/pages/which-package.adoc +++ b/docs/modules/ROOT/pages/which-package.adoc @@ -32,7 +32,7 @@ Python reaches ArcadeDB in two different ways, and the names look alike. The emb A rule of thumb: * No server and one process (tests, notebooks, scripts, an agent that owns its data): use the embedded bindings. -* Several clients, an existing server, a service boundary or clients in other languages: use a driver. +* Several clients, an existing server, a service boundary, HA or replication, or clients in other languages: use a driver. * You can use both. For example, run a job with the embedded bindings, and let other programs reach a shared server through the HTTP driver. The name `{import-name}` on PyPI is the embedded package, and the driver is `{driver-pkg-name}`. So `uv add {native-pkg-name}` gives you the engine, and `uv add {driver-pkg-name}` gives you a client that needs a server.