Prepare the deprecation shim for arcadedb-embedded (26.11.1): points to arcadedb, the native build

.github/workflows/test-python-bindings.yml

@@ -13,6 +13,7 @@ on:
     paths:
       - 'bindings/python/src/**'
       - 'bindings/python/tests/**'
+      - 'bindings/python/deprecation/**'
       - 'bindings/python/examples/**'
       - 'bindings/python/scripts/**'
       - 'bindings/python/pyproject.toml'
@@ -25,6 +26,7 @@ on:
     paths:
       - 'bindings/python/src/**'
       - 'bindings/python/tests/**'
+      - 'bindings/python/deprecation/**'
       - 'bindings/python/examples/**'
       - 'bindings/python/scripts/**'
       - 'bindings/python/pyproject.toml'

.github/workflows/test-python-examples.yml

@@ -12,6 +12,7 @@ on:
     paths:
       - 'bindings/python/src/**'
       - 'bindings/python/tests/**'
+      - 'bindings/python/deprecation/**'
       - 'bindings/python/examples/**'
       - 'bindings/python/scripts/**'
       - 'bindings/python/pyproject.toml'
@@ -24,6 +25,7 @@ on:
     paths:
       - 'bindings/python/src/**'
       - 'bindings/python/tests/**'
+      - 'bindings/python/deprecation/**'
       - 'bindings/python/examples/**'
       - 'bindings/python/scripts/**'
       - 'bindings/python/pyproject.toml'

bindings/python/AGENTS.md

@@ -17,6 +17,7 @@ Paths in this file are relative to the repository root (the directory that conta
 | reporting an engine bug upstream, sending a low-hanging engine fix, or checking an upstream fix to one of our issues | `bindings/python/docs/development/upstream-issues.md` |
 | the periodic `bindings/python` update to ArcadeData/arcadedb (retired 2026-10-25; the bindings continue in ArcadeData/arcadedb-python) | `bindings/python/docs/development/upstream-bindings-pr.md` |
 | releasing | `bindings/python/docs/development/release.md` |
+| publishing the last `arcadedb-embedded` release (the deprecation shim), or telling users how to move | `bindings/python/deprecation/README.md`, `bindings/python/deprecation/MIGRATION.md` |
 | debugging a build, JVM or test failure | `bindings/python/docs/development/troubleshooting.md` |
 | making a performance claim, or working around an engine bug | `bindings/python/docs/guide/performance.md`, `bindings/python/docs/guide/known-issues.md`, `bindings/python/docs/benchmarks/protocol.md` |
 

bindings/python/deprecation/MIGRATION.md

@@ -0,0 +1,45 @@
+# Migrating from arcadedb-embedded
+
+The ArcadeDB Python bindings moved from `humemai/arcadedb-embedded-python` to [ArcadeData/arcadedb-python](https://github.com/ArcadeData/arcadedb-python), under new PyPI names: `arcadedb` (the native build) and `arcadedb-jvm` (the JVM build). `arcadedb-embedded` was the JVM package. Its last release is a shim that installs `arcadedb`, the native build. If you need the JVM build, install `arcadedb-jvm` yourself. This repository is archived after the move. Documentation: [docs.arcadedb.com/arcadedb-python](https://docs.arcadedb.com/arcadedb-python/). To decide between the two packages, read [Which package?](https://docs.arcadedb.com/arcadedb-python/which-package.html).
+
+`arcadedb-embedded-native` (the native preview package) is archived: no further releases and no shim. No files of it remain on PyPI today (its simple index lists none). Install `arcadedb` instead: it is the native build, and its import name is `arcadedb`, not `arcadedb_native`.
+
+## Install and import
+
+| Before | After (native build) | After (JVM build) |
+|---|---|---|
+| `uv add arcadedb-embedded` | `uv add arcadedb` | `uv add arcadedb-jvm` |
+| `uv add 'arcadedb-embedded[arrow,pandas]'` | `uv add 'arcadedb[arrow,pandas]'` | `uv add 'arcadedb-jvm[arrow,pandas]'` |
+| `uv add arcadedb-embedded` | `uv add arcadedb` | `uv add arcadedb-jvm` |
+| `import arcadedb_embedded` | `import arcadedb` | `import arcadedb` |
+| `from arcadedb_embedded import open_database` | `from arcadedb import open_database` | `from arcadedb import open_database` |
+| `arcadedb_embedded.core`, `arcadedb_embedded.jvm`, ... | `arcadedb.core`, ... | `arcadedb.core`, `arcadedb.jvm`, ... |
+
+The package for `arcadedb-embedded` users is now `arcadedb`, which is the native build: the engine runs as a native library, without a JVM. It is a different runtime from the one you had. If your code needs the JVM build, for example because it uses Java classes through JPype, install `arcadedb-jvm`: it is the same JVM build as `arcadedb-embedded`, so nothing changes at run time. The extra `vector` of `arcadedb-embedded` (numpy) is the extra `numpy` of `arcadedb`; `arrow`, `pandas` and `polars` keep their names. `arcadedb` defines no other extras: the old `test`, `dev` and `examples` do not exist there.
+
+Both new packages provide the module `arcadedb`, so an environment holds `arcadedb` or `arcadedb-jvm`, not both. Remove the old package first: `uv remove arcadedb-embedded`.
+
+## Version mapping
+
+From 26.11.1 the package version is the ArcadeDB engine version, as before.
+
+| Old | Last release | New |
+|---|---|---|
+| `arcadedb-embedded` (JVM, bundled JRE) | 26.10.2.post1 on PyPI, then the shim 26.11.1 | `arcadedb` 26.11.1 and later (native), or `arcadedb-jvm` 26.11.1 and later (JVM) |
+| `arcadedb-embedded-native` (preview, archived) | no further releases, no shim | `arcadedb` 26.11.1 and later |
+
+The 26.11.1 release of `arcadedb-embedded` is a shim and the last one. It installs `arcadedb` at exactly 26.11.1. Importing `arcadedb_embedded` then emits one `FutureWarning` and re-exports `arcadedb`, submodules included, so unchanged code keeps running until you edit the import. The warning says that the package is now `arcadedb`, that this is the native build, and that `arcadedb-jvm` is the JVM build. The shim never upgrades: for newer versions install `arcadedb` or `arcadedb-jvm`. Older releases of the old name stay on PyPI for pinned installs. The shim is published only after the native `arcadedb` 26.11.1 final release exists.
+
+## What stays the same
+
+- The Python API: the module is renamed, its classes and functions are the ones of the 26.11.1 bindings. A few features can differ between the two builds; Which package? lists them.
+- Python 3.11 to 3.14, and the Apache-2.0 license.
+- The extras `arrow`, `pandas` and `polars`, under the same names.
+- Where to look: the user guide and API reference move with the code to the new docs site, and the old `docs.humem.ai/arcadedb` pages redirect there.
+
+## What changes
+
+- The distribution and import names, as above.
+- The default runtime: `uv add arcadedb` installs the native build, not the JVM build.
+- Issues and pull requests go to [ArcadeData/arcadedb-python](https://github.com/ArcadeData/arcadedb-python/issues). Benchmarks stay with HumemAI, in [humemai/dbbench](https://github.com/humemai/dbbench).
+- Engine changes between 26.10.2 and 26.11.1: read the 26.11.1 release notes, as for any upgrade.

bindings/python/deprecation/README.md

@@ -0,0 +1,75 @@
+# Deprecation shim for the old PyPI name arcadedb-embedded
+
+The Python bindings move to [ArcadeData/arcadedb-python](https://github.com/ArcadeData/arcadedb-python) as `arcadedb` (the native build) and `arcadedb-jvm` (the JVM build), both importing as `arcadedb`. This folder holds the last release of the old name `arcadedb-embedded`: a pure-Python shim that depends on `arcadedb` at the same version, warns once, and re-exports it. The old JVM package therefore moves to the native build, on purpose (decided 2026-10-25). The warning and the README say so in plain words, name `arcadedb-jvm` as the way to keep the JVM build, and link the Which package? page of the new documentation. Users: see [MIGRATION.md](MIGRATION.md).
+
+`arcadedb-embedded-native` (the native preview package) is archived: no further releases and no shim. No files of it remain on PyPI today, so there is nothing to redirect; the shim README and MIGRATION.md tell people to install `arcadedb` (import name `arcadedb`, not `arcadedb_native`).
+
+| Folder | PyPI project | Depends on | Version |
+|---|---|---|---|
+| `arcadedb-embedded/` | `arcadedb-embedded` (old JVM package) | `arcadedb==26.11.1` (the native build) | 26.11.1 |
+
+The shim module is `arcadedb_embedded`. The mapping above lives in one place, `TARGETS` in `build_shims.py`, together with the one assumption behind it: `arcadedb` provides the import name `arcadedb` (the layout says so, but it has no real release yet). `EXTRAS` there maps the extras of the old package to the extras of `arcadedb` (`vector`, the numpy extra, becomes `numpy`; `arcadedb` has no `vector`), and `NATIVE_EXTRAS` is the set the native `arcadedb` wheel defines (`numpy`, `arrow`, `pandas`, `polars`; source: ArcadeData/arcadedb-python, branch `native-two-dist`, `native/wheel/pyproject.toml`). `build_shims.py` fails when the shim forwards anything else, so re-read that file when the native wheel's extras change. `build_shims.py` refuses to build when the shim's `pyproject.toml` (name, description, dependencies, extras, `Replaced by` URL) or its `_NEW_DIST` and `_NEW_MODULE` constants disagree with `TARGETS`. The real package in `bindings/python/src` is not changed and does not warn: the benchmark harness imports it until the split.
+
+**This shim publishes only after the native `arcadedb` 26.11.1 FINAL exists.** It pins `arcadedb==26.11.1`, and a `26.11.1.devN` release does not satisfy that pin. Until the final release is out, do not publish this shim: `uv add arcadedb-embedded` would fail to resolve.
+
+## Build and test (never uploads)
+
+```bash
+python3 bindings/python/deprecation/build_shims.py --out /tmp/shims        # uv build, wheel + sdist
+taskset -c 0-3 uv run pytest bindings/python/tests/test_deprecation_shims.py   # needs the real wheel installed, like the rest of the suite
+```
+
+`build_shims.py` checks each version with `scripts/check_version.py` first; add `--check-pypi` on cutover day to check it is the next version on PyPI (it fails once that version is published).
+
+## Cutover day
+
+1. Release the native `arcadedb` 26.11.1 FINAL from ArcadeData/arcadedb-python first (and `arcadedb-jvm` 26.11.1, which the warning names). Check that PyPI serves it (`curl -sf https://pypi.org/pypi/arcadedb/26.11.1/json` succeeds): the shim pins this exact version. If the first final `arcadedb` is not out (only `26.11.1.devN`), do not publish the shim.
+2. Never push a `26.11.1` tag in this repository: `release-python-packages.yml` would build and publish the real wheels under `arcadedb-embedded`.
+3. Build and check: `python3 bindings/python/deprecation/build_shims.py --out dist --check-pypi && uvx twine check dist/*`.
+4. Publish the shim. Trusted publishing works only from a workflow, so either (a) register a trusted publisher on the PyPI project `arcadedb-embedded` (repository `humemai/arcadedb-embedded-python`, workflow `publish-deprecation-shims.yml`, environment `pypi`), add the workflow below to `.github/workflows/` (and to `FORK_GITHUB_ALLOWLIST` in `sync-upstream.sh` if another sync will still run), and dispatch it with `publish` on; or (b) upload from a laptop with `uvx twine upload dist/*` and a project-scoped API token.
+5. In a clean environment, `uv run --no-project --with arcadedb-embedded==26.11.1 python -W default -c "import arcadedb_embedded, importlib.metadata as m; print(m.version('arcadedb'))"` installs `arcadedb` (the native build, not `arcadedb-jvm`: it prints `26.11.1`) and shows one FutureWarning that names `arcadedb-jvm` for the JVM build.
+
+```yaml
+name: Publish deprecation shims
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "Upload to PyPI (off: build and check only)"
+        type: boolean
+        default: false
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Setup UV package manager
+        run: |
+          installer="$(mktemp)"
+          curl -LsSf --retry 5 --retry-all-errors --retry-delay 5 -o "$installer" https://astral.sh/uv/0.12.0/install.sh
+          sh "$installer"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - run: python3 bindings/python/deprecation/build_shims.py --out dist --check-pypi
+      - run: uvx twine check dist/*.whl dist/*.tar.gz
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: shims
+          path: dist/
+  publish:
+    needs: build
+    if: inputs.publish
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: shims
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+```

bindings/python/deprecation/arcadedb-embedded/README.md

@@ -0,0 +1,40 @@
+# arcadedb-embedded has moved to arcadedb
+
+**This package is deprecated. 26.11.1 is its last release.** The ArcadeDB Python bindings now live in the ArcadeData organization, under a new package name. The package is now [`arcadedb`](https://pypi.org/project/arcadedb/), which is the **native build**: the engine runs as a native library, without a JVM. If you need the JVM build, install [`arcadedb-jvm`](https://pypi.org/project/arcadedb-jvm/) instead.
+
+**The runtime changes for users of the old name.** `arcadedb-embedded` was the JVM build; `arcadedb` is the native build. Both new packages are imported as `arcadedb`.
+
+| | Old | New |
+|---|---|---|
+| PyPI package | `arcadedb-embedded` | [`arcadedb`](https://pypi.org/project/arcadedb/) (native build) or [`arcadedb-jvm`](https://pypi.org/project/arcadedb-jvm/) (JVM build) |
+| Import | `import arcadedb_embedded` | `import arcadedb` |
+| Source and issues | `humemai/arcadedb-embedded-python` (archived) | [ArcadeData/arcadedb-python](https://github.com/ArcadeData/arcadedb-python) |
+| Documentation | `docs.humem.ai/arcadedb` | [docs.arcadedb.com/arcadedb-python](https://docs.arcadedb.com/arcadedb-python/) |
+
+## What to do
+
+```bash
+uv remove arcadedb-embedded
+uv add arcadedb
+```
+
+Then change `import arcadedb_embedded` to `import arcadedb` (and `from arcadedb_embedded import X` to `from arcadedb import X`).
+
+`arcadedb-embedded` was the JVM build, so `arcadedb` is a different runtime. If your code needs the JVM build, for example because it uses Java classes through JPype or a long-running load that suits the JVM, install it instead:
+
+```bash
+uv remove arcadedb-embedded
+uv add arcadedb-jvm
+```
+
+[Which package?](https://docs.arcadedb.com/arcadedb-python/which-package.html) explains the difference. `arcadedb` and `arcadedb-jvm` both provide the module `arcadedb`: install one of them in an environment, not both.
+
+## What this release does
+
+It is a shim. It installs `arcadedb==26.11.1`, and `import arcadedb_embedded` emits one `FutureWarning` and then gives you the `arcadedb` module, submodules included, so existing code keeps running. It is pinned to `arcadedb==26.11.1` and gets no updates: to receive newer ArcadeDB versions, switch to `arcadedb` (or `arcadedb-jvm`).
+
+The extras `vector`, `arrow`, `pandas` and `polars` are forwarded to `arcadedb`. The old `vector` extra (numpy) maps to the `numpy` extra of `arcadedb`, which defines `numpy`, `arrow`, `pandas` and `polars`; the old `test`, `dev` and `examples` extras do not exist there.
+
+The sibling package `arcadedb-embedded-native` (the native preview) is archived: no further releases, no shim. Install `arcadedb` instead; its import name is `arcadedb`, not `arcadedb_native`.
+
+Older `arcadedb-embedded` releases stay on PyPI for pinned installs. For the full old-to-new table, see the [migration guide](https://github.com/humemai/arcadedb-embedded-python/blob/main/bindings/python/deprecation/MIGRATION.md).

bindings/python/deprecation/arcadedb-embedded/pyproject.toml

@@ -0,0 +1,47 @@
+# Deprecation shim for arcadedb-embedded (the last release). Built by ../build_shims.py; see ../README.md.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arcadedb-embedded"
+version = "26.11.1"
+description = "Deprecated: arcadedb-embedded has moved to arcadedb (import arcadedb), now the native build, not the JVM build; for the JVM build use arcadedb-jvm. Last release, a thin shim."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Taewoon Kim", email = "taewoon@humem.ai" }]
+keywords = ["arcadedb", "deprecated", "moved", "database"]
+classifiers = [
+    "Development Status :: 7 - Inactive",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+]
+# The shim installs exactly the package it points to, at the same version.
+dependencies = ["arcadedb==26.11.1"]
+
+# The extras people installed from the old name, forwarded to the extras of `arcadedb` (the native wheel defines numpy, arrow, pandas and polars; the old `vector` extra was numpy). build_shims.py checks this block.
+[project.optional-dependencies]
+vector = ["arcadedb[numpy]==26.11.1"]
+arrow = ["arcadedb[arrow]==26.11.1"]
+pandas = ["arcadedb[pandas]==26.11.1"]
+polars = ["arcadedb[polars]==26.11.1"]
+
+[project.urls]
+Homepage = "https://github.com/ArcadeData/arcadedb-python"
+Documentation = "https://docs.arcadedb.com/arcadedb-python/"
+Source = "https://github.com/ArcadeData/arcadedb-python"
+Issues = "https://github.com/ArcadeData/arcadedb-python/issues"
+"Replaced by" = "https://pypi.org/project/arcadedb/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arcadedb_embedded"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", "pyproject.toml"]