Implement registry loading for tar.zst files

.github/workflows/tests.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        pyversion: ["3.x", "3.9"]
+        pyversion: ["3.x", "3.11", "3.13"]
     steps:
       - uses: actions/checkout@v7
       - name: Set up Python ${{ matrix.pyversion }}
@@ -28,7 +28,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install ruff pytest pytest-cov click
-          pip install -e . -e test/juliapkg_test_editable_setuptools
+          pip install -e ".[zstd]" -e test/juliapkg_test_editable_setuptools
       - name: Lint with ruff
         run: |
           ruff format --check

CHANGELOG.md

@@ -1,7 +1,10 @@
 # Changelog
 
 ## Unreleased
+* Support `.tar.zst` Julia registries. On Python 3.11–3.13, install
+  `juliapkg[zstd]` to enable this support; Python 3.14+ supports it natively.
 * Read only the first `juliapkg.json` for each package found on `sys.path`, matching import.
+* Require Python 3.11+.
 
 ## v0.1.27 (2026-09-19)
 * Add `bindir()` function.

README.md

@@ -145,3 +145,15 @@ will not attempt to download Julia or any packages.
 
 Resolving will fail if Julia is not already installed. It is up to you to install any
 required Julia packages.
+
+### Zstandard-compressed Julia registries
+
+On Python 3.11–3.13, looking up package UUIDs in `.tar.zst` Julia registries
+(for example, when calling `add()` without a UUID) requires the optional extra:
+
+```sh
+pip install "juliapkg[zstd]"
+```
+
+This extra installs the Zstandard backport only on Python below 3.14. Python 3.14
+and later support these registries through the standard library.

pyproject.toml

@@ -10,14 +10,15 @@ dependencies = [
     "tomli >=2.0,<3.0",
 ]
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
 ]
 
 [project.optional-dependencies]
 cli = ["click >=8.0,<9.0"]
+zstd = ["backports.zstd; python_version < '3.14'"]
 
 [dependency-groups]
 dev = ["pytest", "pre-commit", "juliapkg_test_editable_setuptools"]

src/juliapkg/registry.py

@@ -1,4 +1,5 @@
 import os
+import sys
 import tarfile
 
 # we can switch to tomllib when we require python 3.11+
@@ -36,8 +37,21 @@ def _load_registry_index(reg):
     regpath = reg["path"]
     if not os.path.exists(regpath):
         raise ValueError(f"registry does not exist: {regpath}")
-    if regpath.endswith(".tar.gz"):
-        with tarfile.open(regpath) as reg:
+    if regpath.endswith((".tar.gz", ".tar.zst")):
+        registry_tarfile = tarfile
+        if regpath.endswith(".tar.zst") and sys.version_info < (3, 14):
+            try:
+                from backports.zstd import tarfile as registry_tarfile
+            except ModuleNotFoundError as exc:
+                if exc.name not in {"backports", "backports.zstd"}:
+                    raise
+                raise ImportError(
+                    "Reading .tar.zst Julia registries on Python <3.14 requires "
+                    "the optional Zstandard backport. Install it with "
+                    '`python -m pip install "juliapkg[zstd]"` '
+                    '(or `uv add "juliapkg[zstd]"`).'
+                ) from exc
+        with registry_tarfile.open(regpath) as reg:
             regidx = tomli.load(reg.extractfile("Registry.toml"))
     elif os.path.isdir(regpath):
         with open(os.path.join(regpath, "Registry.toml"), "rb") as fp:

test/test_registry.py

@@ -0,0 +1,55 @@
+import io
+import sys
+import tarfile
+
+import pytest
+
+from juliapkg import registry
+
+
+@pytest.fixture(autouse=True)
+def clear_registry_cache(monkeypatch):
+    monkeypatch.setattr(registry, "_REGISTRY_INDEX_CACHE", {})
+
+
+@pytest.mark.parametrize("compression", ["gz", "zst"])
+def test_load_registry_index(tmp_path, compression):
+    archive = tarfile
+    if compression == "zst" and sys.version_info < (3, 14):
+        archive = pytest.importorskip("backports.zstd.tarfile")
+    path = tmp_path / f"registry.tar.{compression}"
+    content = b'[packages]\nexample-uuid = {name = "Example"}\n'
+    with archive.open(path, f"w:{compression}") as tar:
+        info = archive.TarInfo("Registry.toml")
+        info.size = len(content)
+        tar.addfile(info, io.BytesIO(content))
+    assert registry._load_registry_index(
+        {"path": str(path), "git-tree-sha1": "example"}
+    ) == {"packages": {"example-uuid": {"name": "Example"}}}
+
+
+def test_missing_backport(tmp_path, monkeypatch):
+    monkeypatch.setattr(registry.sys, "version_info", (3, 13))
+    monkeypatch.setitem(sys.modules, "backports.zstd", None)
+    path = tmp_path / "registry.tar.zst"
+    path.touch()
+    with pytest.raises(ImportError, match=r"juliapkg\[zstd\]"):
+        registry._load_registry_index({"path": str(path), "git-tree-sha1": "example"})
+
+
+def test_invalid_registry_is_not_skipped(tmp_path, monkeypatch):
+    bad = tmp_path / "bad.tar.gz"
+    bad.write_bytes(b"invalid archive")
+    good = tmp_path / "good"
+    good.mkdir()
+    (good / "Registry.toml").write_text('[packages]\nexample = {name = "Example"}')
+    monkeypatch.setattr(
+        registry,
+        "_find_registries",
+        lambda: [
+            {"path": str(bad), "git-tree-sha1": "bad"},
+            {"path": str(good), "git-tree-sha1": "good"},
+        ],
+    )
+    with pytest.raises(tarfile.ReadError):
+        registry._find_uuid("Example")