From 55f6065806af9fe8f8d59e811f8c763f7a55c420 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Thu, 29 Oct 2026 07:49:44 +0900 Subject: [PATCH] Docs: uv commands for every install step; give the index table's first column room - pip install -> uv add, pip install --pre -> uv add --prerelease allow, pip show -> uv tree --depth 1, pip uninstall -> uv remove (README, index, installation, quickstart, which-package); the "Migrate from the old names" step 1 names whichever old package you have, because uv remove fails on a package that is not a dependency. Installer-neutral wording where pip was described ("the installer"); the 3.15 row says what each installer does. - index table: cols 1,3,3,2 -> 2,3,3,2 (the first column was 11% and split package names). - check_no_embedded_name.py: the step-1 allowlist phrase follows the new command. Closes #122 Co-Authored-By: Claude Opus 5.5 --- README.md | 6 +++--- docs/modules/ROOT/pages/index.adoc | 12 +++++------ docs/modules/ROOT/pages/installation.adoc | 12 +++++------ docs/modules/ROOT/pages/quickstart.adoc | 4 ++-- docs/modules/ROOT/pages/which-package.adoc | 24 +++++++++++----------- scripts/check_no_embedded_name.py | 2 +- 6 files changed, 30 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 897f274..e3f4318 100644 --- a/README.md +++ b/README.md @@ -19,12 +19,12 @@ Both packages `import arcadedb`, and they have the same public API. Install one, ## Install ```bash -pip install arcadedb # native, the default (or: uv add arcadedb) -pip install arcadedb-jvm # JVM, for heavy long-running loads (or: uv add arcadedb-jvm) +uv add arcadedb # native, the default +uv add arcadedb-jvm # JVM, for heavy long-running loads ``` -> Transition note: the first release of this layout is 26.11.1. Until `arcadedb` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain `pip install arcadedb` or `uv add arcadedb` installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs `pip install --pre arcadedb` (or `uv add --prerelease allow arcadedb`). The same holds for `arcadedb-jvm`. +> Transition note: the first release of this layout is 26.11.1. Until `arcadedb` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain `uv add arcadedb` installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs `uv add --prerelease allow arcadedb`. The same holds for `arcadedb-jvm`. > Old names: `arcadedb-jvm` was formerly `arcadedb-embedded`, and `arcadedb` was formerly `arcadedb-embedded-native` (archived on PyPI). A last `arcadedb-embedded` release will be a deprecation shim that installs `arcadedb`, the native build. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 0a3cb70..a9c4574 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -6,25 +6,25 @@ These packages run the ArcadeDB engine inside your Python process, with no network hop and no server to start. Two packages exist, and both use the import name `{import-name}`: -[cols="1,3,3,2"] +[cols="2,3,3,2"] |=== | Package | Engine | Pick it for | Install | `{native-pkg-name}` (the default) | Native: the engine compiled by GraalVM Community Edition, loaded with `ctypes`. No JVM, no JPype. | Scripts, notebooks, tests, CLIs, serverless functions and agents. -| `pip install {native-pkg-name}` +| `uv add {native-pkg-name}` | `{jvm-pkg-name}` | JVM: the Java engine in your process through https://jpype.readthedocs.io/[JPype], with a bundled Java 25 runtime. | Heavy, long-running loads, and the Java-object APIs. -| `pip install {jvm-pkg-name}` +| `uv add {jvm-pkg-name}` |=== 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. // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -NOTE: *Transition note.* The first release of this layout is 26.11.1, and `{native-pkg-name}` may first appear as pre-releases, `26.11.1.devN`. Until a final 26.11.1 is on PyPI, these pre-releases are all there is, and a plain `pip install {native-pkg-name}` or `uv add {native-pkg-name}` installs the newest one. See xref:installation.adoc[Installation]. +NOTE: *Transition note.* The first release of this layout is 26.11.1, and `{native-pkg-name}` may first appear as pre-releases, `26.11.1.devN`. Until a final 26.11.1 is on PyPI, these pre-releases are all there is, and a plain `uv add {native-pkg-name}` installs the newest one. See xref:installation.adoc[Installation]. ArcadeDB is a multi-model database: graph, document, key/value, vector and time series data live in one database, and you query it with SQL or openCypher. The bindings expose the two calls you need for that, `db.command(...)` and `db.query(...)`. @@ -69,8 +69,8 @@ ArcadeDB reaches Python in two ways. Pick by where the engine should run. | One per call | Setup -| `pip install {native-pkg-name}` or `pip install {jvm-pkg-name}` -| A running server (the official Docker image `arcadedata/arcadedb`), plus `pip install arcadedb-driver` +| `uv add {native-pkg-name}` or `uv add {jvm-pkg-name}` +| A running server (the official Docker image `arcadedata/arcadedb`), plus `uv add arcadedb-driver` |=== Choose the embedded bindings for a single script, a notebook, or an application with one Python process that owns its data. Choose the {arcadedb-docs-url}/how-to/connectivity/drivers/python-http[HTTP driver] when more than one process, another language, or a remote machine must reach the same database, or when the server must outlive your Python process. diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index 9a2e86a..679c13d 100644 --- a/docs/modules/ROOT/pages/installation.adoc +++ b/docs/modules/ROOT/pages/installation.adoc @@ -13,12 +13,12 @@ Pick one of the two packages. Both import as `{import-name}`. If you are not sur | Package | Install | Pick this if | `{native-pkg-name}` (native, the default) -| `pip install {native-pkg-name}` + +| `uv add {native-pkg-name}` + `uv add {native-pkg-name}` | You write scripts, notebooks, tests, CLIs, serverless functions or agents. You want a fast start and a small footprint, and you need no JVM. | `{jvm-pkg-name}` (JVM) -| `pip install {jvm-pkg-name}` + +| `uv add {jvm-pkg-name}` + `uv add {jvm-pkg-name}` | Your load is heavy and long-running, so the JIT compiler pays off. Or you need the Java-object APIs, JVM options, `jvm_kwargs` or `start_jvm`. |=== @@ -26,7 +26,7 @@ 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. // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -NOTE: *Transition note.* The first release of this layout is 26.11.1. Until `{native-pkg-name}` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain `pip install {native-pkg-name}` or `uv add {native-pkg-name}` installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs `pip install --pre {native-pkg-name}` or `uv add --prerelease allow {native-pkg-name}`. The same holds for `{jvm-pkg-name}`. +NOTE: *Transition note.* The first release of this layout is 26.11.1. Until `{native-pkg-name}` passes its readiness bar, it may appear only as pre-releases, `26.11.1.devN`. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain `uv add {native-pkg-name}` installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs `uv add --prerelease allow {native-pkg-name}` or `uv add --prerelease allow {native-pkg-name}`. The same holds for `{jvm-pkg-name}`. // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name NOTE: *Old names.* The JVM package was formerly `arcadedb-embedded`. It is now `{jvm-pkg-name}`, the same build. The native package was formerly `arcadedb-embedded-native`. It is now `{native-pkg-name}`, and the old project is archived. A last `arcadedb-embedded` release will install `{native-pkg-name}`, not `{jvm-pkg-name}`. See xref:which-package.adoc#old-names[Old names]. @@ -39,7 +39,7 @@ The JVM package is self-contained. It carries a Java 25 runtime for its platform * Python 3.11 to 3.14 for both packages. The native package also supports Python 3.15: it is one `py3-none` wheel that loads its library with `ctypes`, and the CI runs a subset of the tests on 3.15. `{jvm-pkg-name}` does not install on 3.15 yet, because its dependency JPype has no 3.15 wheel: its `requires-python` is `>=3.11,<3.15`, so pip says that no version fits instead of building JPype from source. The cap goes when JPype ships a 3.15 wheel. The CI tests the JVM wheel on all four versions 3.11 to 3.14 on Linux x86_64, and on 3.11 and 3.14 on the other platforms (xref:development/ci.adoc[Continuous integration]). * One of the four platforms below. The Windows wheel of the native build is the newest, and its test run is the least proven of the four. It needs the Microsoft Visual C++ runtime (`VCRUNTIME140.dll`), which every CPython for Windows already brings. -Every wheel is platform-specific and built on a native runner of its platform, so pip needs no hint to pick the right one. Each package is one file for each platform, tagged `py3-none-`, and it serves every Python version it supports. The native wheel does so because it loads its library with `ctypes`. The JVM wheel carries a JRE for its platform, and nothing in it is compiled against CPython: JPype, its dependency, has its own wheel for each Python version. +Every wheel is platform-specific and built on a native runner of its platform, so the installer needs no hint to pick the right one. Each package is one file for each platform, tagged `py3-none-`, and it serves every Python version it supports. The native wheel does so because it loads its library with `ctypes`. The JVM wheel carries a JRE for its platform, and nothing in it is compiled against CPython: JPype, its dependency, has its own wheel for each Python version. [cols="2,3,3"] |=== @@ -62,10 +62,10 @@ Every wheel is platform-specific and built on a native runner of its platform, s | `win_amd64` |=== -Each native wheel is about 38 MB. These platforms are not built, and pip finds no wheel for them: +Each native wheel is about 38 MB. These platforms are not built, and the installer finds no wheel for them: * *Intel Macs* (macOS x86_64). Apple has sold only Apple Silicon Macs since 2023, and macOS 26 is the last release for Intel Macs. On an Intel Mac, run the Linux wheel in Docker or in a Linux virtual machine. -* *Alpine Linux and other musl-based distributions.* The Linux wheels are for glibc. pip then says `No matching distribution found` (for a wheel file you downloaded: `is not a supported wheel on this platform`). Use a glibc image, for example `python:3.12-slim`. +* *Alpine Linux and other musl-based distributions.* The Linux wheels are for glibc, so the installer reports that no wheel matches the platform. Use a glibc image, for example `python:3.12-slim`. * *Windows on ARM.* * *Linux with an older glibc than the table*, for example Amazon Linux 2 and CentOS 7. diff --git a/docs/modules/ROOT/pages/quickstart.adoc b/docs/modules/ROOT/pages/quickstart.adoc index bd9325c..9c1175e 100644 --- a/docs/modules/ROOT/pages/quickstart.adoc +++ b/docs/modules/ROOT/pages/quickstart.adoc @@ -10,11 +10,11 @@ This page builds a small database from scratch. You need one of the two packages | Package | Install | Pick this if | `{native-pkg-name}` (native, the default) -| `pip install {native-pkg-name}` +| `uv add {native-pkg-name}` | Scripts, notebooks, tests, CLIs, serverless functions, agents. | `{jvm-pkg-name}` (JVM) -| `pip install {jvm-pkg-name}` +| `uv add {jvm-pkg-name}` | Heavy, long-running loads, or the Java-object APIs. |=== diff --git a/docs/modules/ROOT/pages/which-package.adoc b/docs/modules/ROOT/pages/which-package.adoc index d1f2a38..bf3b7db 100644 --- a/docs/modules/ROOT/pages/which-package.adoc +++ b/docs/modules/ROOT/pages/which-package.adoc @@ -18,14 +18,14 @@ Two packages give you the ArcadeDB engine inside your Python process. Both use t [source,shell,subs="attributes+"] ---- -pip install {native-pkg-name} # native, the default -pip install {jvm-pkg-name} # JVM, for heavy long-running loads +uv add {native-pkg-name} # native, the default +uv add {jvm-pkg-name} # JVM, for heavy long-running loads ---- If you are not sure, install `{native-pkg-name}`. You can switch later: your code does not change (see <>). // REMOVE WHEN: the old arcadedb-embedded* shims are retired and two releases have shipped with the two-package layout allow-old-name -NOTE: *Transition note.* The first release of this layout is 26.11.1. Until the native build passes its readiness bar, `{native-pkg-name}` may appear only as pre-releases, `26.11.1.devN`. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain `pip install {native-pkg-name}` or `uv add {native-pkg-name}` installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs `pip install --pre {native-pkg-name}` (or `uv add --prerelease allow {native-pkg-name}`). The same holds for `{jvm-pkg-name}`. The readiness bar is listed in xref:development/release.adoc[Release]. +NOTE: *Transition note.* The first release of this layout is 26.11.1. Until the native build passes its readiness bar, `{native-pkg-name}` may appear only as pre-releases, `26.11.1.devN`. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain `uv add {native-pkg-name}` installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs `uv add --prerelease allow {native-pkg-name}` (or `uv add --prerelease allow {native-pkg-name}`). The same holds for `{jvm-pkg-name}`. The readiness bar is listed in xref:development/release.adoc[Release]. [[which-one-do-i-have]] == Check which one you have @@ -35,14 +35,14 @@ NOTE: *Transition note.* The first release of this layout is 26.11.1. Until the python -c "import {import-name}; print({import-name}.__backend__)" ---- -It prints `native` or `jvm`. You can also ask pip: +It prints `native` or `jvm`. You can also ask uv: [source,shell,subs="attributes+"] ---- -pip show {native-pkg-name} {jvm-pkg-name} +uv tree --depth 1 ---- -`pip show` prints a block for each package that is installed, and a warning for the one that is not. In a correct environment exactly one of the two is installed. +`uv tree --depth 1` lists the direct dependencies of your project. In a correct environment exactly one of `{native-pkg-name}` and `{jvm-pkg-name}` is among them. == What changes between them @@ -78,7 +78,7 @@ The API is the same. The runtime is not. These are the differences you can plan | Python versions | 3.11 to 3.15. On 3.15 the CI runs a subset of the tests. -| 3.11 to 3.14. JPype has no 3.15 wheel yet, so pip refuses the package on 3.15. +| 3.11 to 3.14. JPype has no 3.15 wheel yet, so the package does not install on 3.15: pip refuses it, and uv tries to build JPype and fails. | Platforms | Linux x86_64 and aarch64 (glibc 2.28 or later), macOS arm64, Windows x64. The Windows wheel is the newest: it is built in CI, and its test run is the least proven of the four. Not built: Intel Mac, Alpine (musl), Windows on ARM. See xref:installation.adoc#requirements[Requirements]. @@ -102,12 +102,12 @@ Both packages run the same ArcadeDB engine, with the same SQL and openCypher and [[switching]] == Switch from one to the other -The two wheels refuse to work together. If both are installed, `import arcadedb` raises an `ImportError` that names both packages. The reason is that both wheels write into the same `arcadedb` directory, and pip would overwrite files of one with files of the other without a message. So remove both and install the one you want: +The two wheels refuse to work together. If both are installed, `import arcadedb` raises an `ImportError` that names both packages. The reason is that both wheels write into the same `arcadedb` directory, and the installer would overwrite files of one with files of the other without a message. So remove both and install the one you want: [source,shell,subs="attributes+"] ---- -pip uninstall {native-pkg-name} {jvm-pkg-name} -pip install {jvm-pkg-name} +uv remove {native-pkg-name} {jvm-pkg-name} +uv add {jvm-pkg-name} ---- There is no extra to select a build: `{native-pkg-name}[jvm]` does not exist. Your code stays as it is, because both import as `{import-name}`. Only code that uses a JVM-only API (see the table above) needs a change when you move to the native build. @@ -138,8 +138,8 @@ The packages had other names until 26.10.x. Search results and old tutorials may [[migrate]] === Migrate from the old names -. Remove the old package: `pip uninstall arcadedb-embedded arcadedb-embedded-native`. -. Install the new one: `pip install {jvm-pkg-name}` if you used `arcadedb-embedded`, or `pip install {native-pkg-name}` if you used `arcadedb-embedded-native`. Add `--pre` while the transition note above applies. +. Remove the old package: `uv remove arcadedb-embedded`, or `uv remove arcadedb-embedded-native` if that is the one you have. +. Install the new one: `uv add {jvm-pkg-name}` if you used `arcadedb-embedded`, or `uv add {native-pkg-name}` if you used `arcadedb-embedded-native`. Add `--prerelease allow` while the transition note above applies. . Change the import: `import arcadedb_embedded` and `import arcadedb_native` both become `import {import-name}`. The builds are the same as in the table above, so the rest of your code stays. Releases of the new layout start with 26.11.1. The 26.10.x wheels were built in a separate repository of the humemai organisation. diff --git a/scripts/check_no_embedded_name.py b/scripts/check_no_embedded_name.py index 61eb8df..d9ddbcd 100644 --- a/scripts/check_no_embedded_name.py +++ b/scripts/check_no_embedded_name.py @@ -65,7 +65,7 @@ r"|This package was published as arcadedb-embedded until 26\.10\.x; install arcadedb now\." r"|formerly `?arcadedb[_-]embedded" # The "Migrate from the old names" steps must name the old packages (one phrase per step): - r"|pip uninstall arcadedb[_-]embedded" # step 1, what to remove + r"|uv remove arcadedb[_-]embedded" # step 1, what to remove r"|if you used `arcadedb[_-]embedded" # step 2, which new package replaces which old one r"|`import arcadedb_embedded` and `import arcadedb_native` both become", # step 3, the import change re.IGNORECASE,