fdl-cli 0.12.1__tar.gz → 0.13.0__tar.gz

{fdl_cli-0.12.1 → fdl_cli-0.13.0}/CHANGELOG.md

@@ -1,6 +1,17 @@
 # CHANGELOG
 
 
+## v0.13.0 (2026-11-01)
+
+### Features
+
+- Give each repository an id in fdl.json
+  ([`389ec96`](https://github.com/queria-io/fdl/commit/389ec96899d7c33fe0fbcf11d6d958de8b1fcb1a))
+
+init writes a UUID that never changes, so a copy of a repository can tell it holds the same one.
+  Repositories started without one still read.
+
+
 ## v0.12.1 (2026-10-30)
 
 ### Bug Fixes

{fdl_cli-0.12.1 → fdl_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fdl-cli
-Version: 0.12.1
+Version: 0.13.0
 Summary: Versions of a DuckLake catalog on object storage, kept the way Git keeps commits
 Project-URL: Homepage, https://fdl.flo8s.com/
 Project-URL: Documentation, https://fdl.flo8s.com/

{fdl_cli-0.12.1 → fdl_cli-0.13.0}/docs/spec.md

@@ -58,6 +58,7 @@ Paths are relative to the root, lower case, separated by `/`. The root is what a
 ```json
 {
   "fdl": "0.1",
+  "id": "5f0c8a52-6d3e-4f8e-9b1a-2c7d4e9f0a13",
   "data_dir": "data/",
   "catalog_formats": [
     { "ducklake": "1.1" },
@@ -67,6 +68,7 @@ Paths are relative to the root, lower case, separated by `/`. The root is what a
 ```
 
 - `fdl` is the version of this specification. A reader must not read a major version it does not know
+- `id` is a UUID written when the repository is started and never changed, so a copy of the repository can tell it holds the same one. A service that hosts repositories may use its own ID for the dataset here. Repositories started without one are still read
 - `data_dir` is where data files are. The default is `data/`. A repository whose files already sit under another name declares it here instead of moving them
 - `catalog_formats` lists the DuckLake formats published and until when (see "When the DuckLake format moves"). Without it, only `ducklake.duckdb`
 - Files with other names may sit at the root. Readers ignore them
@@ -276,7 +278,6 @@ A push from a stale working catalog is refused on two checks:
 - How to make a merge (a version with two parents)
 - A compatibility test suite for readers and writers
 - Withdrawal: removing past versions entirely, for example when personal data was published by mistake (`reason: withdrawn`, rewriting Parquet, and the fact that mirrors keep their copies)
-- A repository ID: an immutable `id` in `fdl.json`, so a mirror can tell it holds the same dataset
 - Signatures, for readers of a mirror: anyone can write a `version.json`
 - How to declare retention defaults in `fdl.json` (versions to keep, days)
 

{fdl_cli-0.12.1 → fdl_cli-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fdl-cli"
-version = "0.12.1"
+version = "0.13.0"
 description = "Versions of a DuckLake catalog on object storage, kept the way Git keeps commits"
 readme = "README.md"
 license = "MIT"

{fdl_cli-0.12.1 → fdl_cli-0.13.0}/src/fdl/repo.py

@@ -11,6 +11,7 @@ import hashlib
 import itertools
 import json
 import shutil
+import uuid
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterator
@@ -32,6 +33,9 @@ class NotFastForward(RepoError):
 class Config:
     fdl: str
     data_dir: str
+    #: Never changes, so a copy of the repository can tell it holds the same one.
+    #: None for repositories started before it was written.
+    id: str | None = None
 
 
 def init(store: Store, *, data_dir: str = layout.DEFAULT_DATA_DIR) -> Config:
@@ -42,7 +46,7 @@ def init(store: Store, *, data_dir: str = layout.DEFAULT_DATA_DIR) -> Config:
     """
     if not data_dir.endswith("/"):
         raise RepoError(f"data_dir has to end with '/': {data_dir!r}")
-    record = {"fdl": layout.FDL_VERSION, "data_dir": data_dir}
+    record = {"fdl": layout.FDL_VERSION, "id": str(uuid.uuid4()), "data_dir": data_dir}
     try:
         store.put(
             layout.CONFIG,
@@ -67,7 +71,11 @@ def read_config(store: Store) -> Config:
     major = str(record.get("fdl", "")).split(".")[0]
     if major != layout.FDL_VERSION.split(".")[0]:
         raise RepoError(f"written for fdl {record.get('fdl')}, this reads {layout.FDL_VERSION}")
-    return Config(fdl=record["fdl"], data_dir=record.get("data_dir", layout.DEFAULT_DATA_DIR))
+    return Config(
+        fdl=record["fdl"],
+        data_dir=record.get("data_dir", layout.DEFAULT_DATA_DIR),
+        id=record.get("id"),
+    )
 
 
 def read_version(store: Store, version_id: str) -> Version:

{fdl_cli-0.12.1 → fdl_cli-0.13.0}/tests/test_repo.py

@@ -7,6 +7,7 @@ version that comes out the other side.
 from __future__ import annotations
 
 import json
+import uuid
 from pathlib import Path
 
 import duckdb
@@ -64,11 +65,19 @@ def read_rows(store: LocalStore, version_id: str) -> list[tuple]:
 
 
 def test_init_writes_the_config_and_head(remote) -> None:
-    assert json.loads(remote.get(layout.CONFIG)) == {"fdl": "0.1", "data_dir": "data/"}
+    config = json.loads(remote.get(layout.CONFIG))
+    assert config == {"fdl": "0.1", "id": config["id"], "data_dir": "data/"}
+    assert uuid.UUID(config["id"])
     assert remote.get(layout.HEAD) == b"ref: refs/heads/main\n"
     assert repo.head(remote) is None
-    # Twice is harmless.
-    assert repo.init(remote).data_dir == "data/"
+    # Twice is harmless, and the id stays.
+    assert repo.init(remote) == repo.Config(fdl="0.1", data_dir="data/", id=config["id"])
+
+
+def test_a_repository_without_an_id_still_reads(tmp_path: Path) -> None:
+    store = LocalStore(tmp_path / "old")
+    store.put(layout.CONFIG, b'{"fdl": "0.1", "data_dir": "ducklake.duckdb.files/"}')
+    assert repo.read_config(store).id is None
 
 
 def test_commit_push_and_read_back(tmp_path: Path, remote) -> None: