x4d-devkit 0.53.0rc1__tar.gz → 0.53.0rc2__tar.gz

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.53.0rc1
+Version: 0.53.0rc2
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.53.0rc1"
+version = "0.53.0rc2"
 description = "Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation"
 readme = "README.md"
 license = "Apache-2.0"

x4d_devkit-0.53.0rc2/tests/test_image_schema_registry_client.py

@@ -0,0 +1,161 @@
+"""Typed image Schema authoring against a strict in-memory registry."""
+
+from copy import deepcopy
+import hashlib
+import json
+
+import httpx
+import pytest
+
+from x4d_devkit import X4DClient
+from x4d_devkit._image_contract import canonical
+from x4d_devkit.image_schema import parse_image_schema_body
+from tests.image_fixtures import schema_body
+
+
+def etag(value):
+    return '"sha256:' + hashlib.sha256(canonical(value)).hexdigest() + '"'
+
+
+class Registry:
+    def __init__(self):
+        self.rows = {}
+        self.project = None
+        self.tamper = None
+
+    def record(self, body, status):
+        return {
+            "contract_version": "x4d-image-label-schema-record-v1",
+            "status": status,
+            "body": body,
+            "fingerprint": parse_image_schema_body(body).identity.fingerprint,
+        }
+
+    def reply(self, value, status=200):
+        if self.tamper:
+            value = self.tamper(deepcopy(value))
+        return httpx.Response(status, json=value, headers={"ETag": etag(value)})
+
+    def __call__(self, request):
+        path = request.url.path.removeprefix("/api/v1")
+        body = json.loads(request.content) if request.content else None
+        match = request.headers.get("If-Match")
+        if path == "/image-schemas/validate":
+            return httpx.Response(200, json=self.record(body["body"], "draft"))
+        if path == "/label-schemas" and request.method == "POST":
+            key = (body["body"]["schema_id"], body["body"]["version"])
+            self.rows[key] = self.record(body["body"], "draft")
+            return self.reply(self.rows[key], 201)
+        if path.startswith("/label-schemas/"):
+            _, _, schema_id, _, version, *action = path.split("/")
+            row = self.rows[(schema_id, version)]
+            if request.method == "GET":
+                return self.reply(row)
+            if match != etag(row):
+                return httpx.Response(412, json={"detail": "changed"})
+            if request.method == "DELETE":
+                del self.rows[(schema_id, version)]
+                return httpx.Response(204)
+            if action == ["publish"]:
+                row["status"] = "active"
+            elif action == ["deprecate"]:
+                row["status"] = "deprecated"
+            else:
+                row["body"] = body["body"]
+                row["fingerprint"] = parse_image_schema_body(body["body"]).identity.fingerprint
+            return self.reply(row)
+        if path == "/projects/7/label-schema":
+            if request.method == "PUT":
+                if match != etag(self.project):
+                    return httpx.Response(412, json={"detail": "changed"})
+                self.project = {**self.project, "label_schema": self.rows[(body["schema_id"], body["version"])]}
+            return self.reply(self.project)
+        raise AssertionError(path)
+
+
+@pytest.fixture
+def setup():
+    registry = Registry()
+    with X4DClient("http://x4d.test", token="test") as client:
+        client._http.close()
+        client._http = httpx.Client(base_url="http://x4d.test", transport=httpx.MockTransport(registry))
+        yield client.image_schemas, registry
+
+
+def draft_body(version="2.0.0"):
+    body = schema_body()
+    body["version"] = version
+    return body
+
+
+def test_draft_update_publish_and_bind_round_trip(setup):
+    api, registry = setup
+    body = draft_body()
+    assert api.validate(body).to_dict()["status"] == "draft"
+    entry = api.create_draft(body)
+    assert entry.record.to_dict()["status"] == "draft"
+    edited = deepcopy(body)
+    edited["description"] = "Edited draft"
+    entry = api.update_draft(edited, etag=entry.etag)
+    assert entry.record.body["description"] == "Edited draft"
+    assert api.get_entry(schema_id="test_image", version="2.0.0") == entry
+    entry = api.publish(entry)
+    assert entry.record.to_dict()["status"] == "active"
+    registry.project = {
+        "contract_version": "x4d-image-project-label-schema-v1",
+        "project_id": 7,
+        "label_schema": registry.record(schema_body(), "active"),
+    }
+    project = api.get_project_entry(7)
+    bound = api.bind_project(project, schema_id="test_image", version="2.0.0")
+    assert bound.value.to_dict()["label_schema"]["body"]["version"] == "2.0.0"
+    deprecated = api.deprecate(entry, reason="replaced")
+    assert deprecated.record.to_dict()["status"] == "deprecated"
+
+
+def test_stale_etag_is_rejected_by_the_server(setup):
+    api, _ = setup
+    first = api.create_draft(draft_body())
+    api.update_draft({**draft_body(), "description": "one"}, etag=first.etag)
+    with pytest.raises(httpx.HTTPStatusError):
+        api.update_draft({**draft_body(), "description": "two"}, etag=first.etag)
+
+
+def test_delete_draft_needs_the_current_etag(setup):
+    api, registry = setup
+    entry = api.create_draft(draft_body())
+    api.delete_draft(entry)
+    assert registry.rows == {}
+
+
+def test_invalid_body_never_reaches_the_server(setup):
+    api, registry = setup
+    body = draft_body()
+    body["categories"][0]["geometry_type"] = "circle"
+    with pytest.raises(ValueError):
+        api.create_draft(body)
+    assert registry.rows == {}
+
+
+@pytest.mark.parametrize("field", ["status", "body"])
+def test_a_response_for_another_record_or_lifecycle_is_rejected(setup, field):
+    api, registry = setup
+    entry = api.create_draft(draft_body())
+
+    def tamper(value):
+        if field == "status":
+            value["status"] = "draft"
+        else:
+            value["body"]["description"] = "something else"
+            value["fingerprint"] = parse_image_schema_body(value["body"]).identity.fingerprint
+        return value
+
+    registry.tamper = tamper
+    with pytest.raises(ValueError, match="another Schema"):
+        api.publish(entry)
+
+
+def test_a_weak_or_missing_etag_is_refused_locally(setup):
+    api, _ = setup
+    with pytest.raises(ValueError, match="strong ETag"):
+        api.update_draft(draft_body(), etag="W/\"x\"")

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/tests/test_sdk_api.py

@@ -11,7 +11,7 @@ from x4d_devkit.eval.matching import MetricData
 
 
 def test_package_version_is_current_release():
-    assert x4d_devkit.__version__ == "0.53.0rc1"
+    assert x4d_devkit.__version__ == "0.53.0rc2"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/x4d_devkit/client/__init__.py

@@ -43,9 +43,15 @@ from x4d_devkit.client.reconstruction import (
 from x4d_devkit.client.services import ServicesAPI
 from x4d_devkit.client.test_sets import TestSetsAPI
 
-from x4d_devkit.client.image_schemas import ImageSchemasAPI
+from x4d_devkit.client.image_schemas import (
+    ImageProjectSchemaEntry,
+    ImageSchemaEntry,
+    ImageSchemasAPI,
+)
 
 __all__ = [
+    "ImageProjectSchemaEntry",
+    "ImageSchemaEntry",
     "ImageSchemasAPI",
     "ImageWorkSessionsAPI",
     "ImageExportsAPI",

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/x4d_devkit/client/client.py

@@ -173,6 +173,22 @@ class X4DClient:
         resp.raise_for_status()
         return parse_i_json(resp.content, path=f"POST {self._url(path)} response")
 
+    def put(self, path: str, **kwargs):
+        resp = self._http.put(self._url(path), **kwargs)
+        resp.raise_for_status()
+        return parse_i_json(resp.content, path=f"PUT {self._url(path)} response")
+
+    def exchange(self, method: str, path: str, **kwargs):
+        """One request returning ``(strict JSON or None for 204, ETag or None)``."""
+        resp = self._http.request(method, self._url(path), **kwargs)
+        resp.raise_for_status()
+        value = (
+            parse_i_json(resp.content, path=f"{method} {self._url(path)} response")
+            if resp.content
+            else None
+        )
+        return value, resp.headers.get("ETag")
+
     def delete(self, path: str, **kwargs):
         resp = self._http.delete(self._url(path), **kwargs)
         resp.raise_for_status()

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/x4d_devkit/client/image_schemas.py

@@ -1,7 +1,12 @@
 """Separate native image registry reads and explicit admin upgrade/migration adapters."""
 
-from x4d_devkit._image_contract import fields, integer, require
+from dataclasses import dataclass
+import re
+
+from x4d_devkit._image_contract import ImageDocument, fields, integer, require, text
 from x4d_devkit.image_schema import (
+    ImageSchemaRecord,
+    parse_image_schema_body,
     parse_image_schema_record,
     parse_image_project_schema,
 )
@@ -23,6 +28,39 @@ from x4d_devkit.image_schema_migration import (
 from x4d_devkit.label_schema import LabelSchemaBinding
 
 
+_STRONG_ETAG = re.compile(r'"sha256:[0-9a-f]{64}"')
+
+
+@dataclass(frozen=True)
+class ImageSchemaEntry:
+    """A registry record with the strong ETag its next write must match."""
+
+    record: ImageSchemaRecord
+    etag: str
+
+
+@dataclass(frozen=True)
+class ImageProjectSchemaEntry:
+    """A project's image Schema binding with its strong ETag."""
+
+    value: ImageDocument
+    etag: str
+
+
+def _etag(value, path):
+    require(
+        type(value) is str and _STRONG_ETAG.fullmatch(value) is not None,
+        "Registry write requires a strong ETag",
+        path,
+    )
+    return value
+
+
+def _version_path(schema_id, version):
+    LabelSchemaBinding(schema_id, version)
+    return f"/label-schemas/{schema_id}/versions/{version}"
+
+
 class ImageSchemasAPI:
     def __init__(self, client):
         self._client = client
@@ -161,3 +199,119 @@ class ImageSchemasAPI:
 
     def migration_request(self, preview, idempotency_key):
         return build_image_schema_migration_request(preview, idempotency_key)
+
+    # Registry authoring. The server validates with the same Devkit; every
+    # response is checked to be exactly the requested record and lifecycle.
+
+    def _entry(self, method, path, *, expect, status, etag=None, **kwargs):
+        headers = {"If-Match": _etag(etag, "image_schemas.etag")} if etag else None
+        value, returned = self._client.exchange(method, path, headers=headers, **kwargs)
+        record = parse_image_schema_record(value)
+        require(
+            record.body == expect and record.to_dict()["status"] == status,
+            "Registry returned another Schema or lifecycle",
+            "image_schemas.record",
+        )
+        return ImageSchemaEntry(record, _etag(returned, "image_schemas.response_etag"))
+
+    def validate(self, body):
+        """Server-side validation preview; returns the would-be draft record."""
+        expect = parse_image_schema_body(body).to_dict()
+        record = parse_image_schema_record(
+            self._client.post("/image-schemas/validate", json={"body": expect})
+        )
+        require(
+            record.body == expect and record.to_dict()["status"] == "draft",
+            "Validation returned another Schema",
+            "image_schemas.validate",
+        )
+        return record
+
+    def get_entry(self, *, schema_id, version):
+        value, etag = self._client.exchange("GET", _version_path(schema_id, version))
+        record = parse_image_schema_record(value)
+        require(
+            (record.schema_id, record.version) == (schema_id, version),
+            "Registry returned another Schema",
+            "image_schemas.identity",
+        )
+        return ImageSchemaEntry(record, _etag(etag, "image_schemas.response_etag"))
+
+    def create_draft(self, body):
+        expect = parse_image_schema_body(body).to_dict()
+        return self._entry(
+            "POST", "/label-schemas", expect=expect, status="draft", json={"body": expect}
+        )
+
+    def update_draft(self, body, *, etag):
+        expect = parse_image_schema_body(body).to_dict()
+        return self._entry(
+            "PUT",
+            _version_path(expect["schema_id"], expect["version"]),
+            expect=expect,
+            status="draft",
+            etag=etag,
+            json={"body": expect},
+        )
+
+    def publish(self, entry):
+        """Publish exactly the draft in ``entry``; published versions are immutable."""
+        body = entry.record.body
+        return self._entry(
+            "POST",
+            _version_path(body["schema_id"], body["version"]) + "/publish",
+            expect=body,
+            status="active",
+            etag=entry.etag,
+        )
+
+    def deprecate(self, entry, *, reason):
+        body = entry.record.body
+        return self._entry(
+            "POST",
+            _version_path(body["schema_id"], body["version"]) + "/deprecate",
+            expect=body,
+            status="deprecated",
+            etag=entry.etag,
+            json={"reason": text(reason, "image_schemas.reason")},
+        )
+
+    def delete_draft(self, entry):
+        body = entry.record.body
+        value, _ = self._client.exchange(
+            "DELETE",
+            _version_path(body["schema_id"], body["version"]),
+            headers={"If-Match": _etag(entry.etag, "image_schemas.etag")},
+        )
+        require(value is None, "Draft deletion returns no document", "image_schemas.delete")
+
+    def get_project_entry(self, project_id):
+        integer(project_id, "project_id", minimum=1)
+        value, etag = self._client.exchange("GET", f"/projects/{project_id}/label-schema")
+        parsed = parse_image_project_schema(value)
+        require(parsed.to_dict()["project_id"] == project_id, "Registry returned another project", "image_schemas.project_id")
+        return ImageProjectSchemaEntry(parsed, _etag(etag, "image_schemas.response_etag"))
+
+    def bind_project(self, project_entry, *, schema_id, version):
+        """Make an active version the project default; existing Clips keep theirs."""
+        project_id = project_entry.value.to_dict()["project_id"]
+        LabelSchemaBinding(schema_id, version)
+        value, etag = self._client.exchange(
+            "PUT",
+            f"/projects/{project_id}/label-schema",
+            headers={"If-Match": _etag(project_entry.etag, "image_schemas.etag")},
+            json={
+                "contract_version": "x4d-label-schema-binding-v2",
+                "schema_id": schema_id,
+                "version": version,
+            },
+        )
+        parsed = parse_image_project_schema(value).to_dict()
+        bound = parsed["label_schema"]["body"]
+        require(
+            parsed["project_id"] == project_id
+            and (bound["schema_id"], bound["version"]) == (schema_id, version),
+            "Registry bound another Schema",
+            "image_schemas.bind_project",
+        )
+        return ImageProjectSchemaEntry(parse_image_project_schema(parsed), _etag(etag, "image_schemas.response_etag"))

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/x4d_devkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.53.0rc1
+Version: 0.53.0rc2
 Summary: Official X-4D external SDK and CLI for datasets, platform APIs, training bridges, and automation
 Author: windzu
 License-Expression: Apache-2.0

{x4d_devkit-0.53.0rc1 → x4d_devkit-0.53.0rc2}/x4d_devkit.egg-info/SOURCES.txt

@@ -35,6 +35,7 @@ tests/test_image_preannotation.py
 tests/test_image_reference.py
 tests/test_image_review.py
 tests/test_image_schema_migration.py
+tests/test_image_schema_registry_client.py
 tests/test_image_schema_upgrade.py
 tests/test_image_work_session.py
 tests/test_inference_input.py