x4d-devkit 0.48.0rc6__tar.gz → 0.48.0rc8__tar.gz

{x4d_devkit-0.48.0rc6 → x4d_devkit-0.48.0rc8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.48.0rc6
+Version: 0.48.0rc8
 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.48.0rc6 → x4d_devkit-0.48.0rc8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.48.0rc6"
+version = "0.48.0rc8"
 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.48.0rc8/tests/test_accounts.py

@@ -0,0 +1,198 @@
+from copy import deepcopy
+import json
+
+import httpx
+import pytest
+
+from x4d_devkit.accounts import (
+    ACCOUNT_CONTRACT,
+    ACCOUNT_PAGE_CONTRACT,
+    parse_account_page,
+    parse_account_record,
+    validate_account_password,
+    validate_project_types,
+)
+from x4d_devkit.client import X4DClient
+
+
+def record(**changes):
+    return {
+        "contract_version": ACCOUNT_CONTRACT,
+        "id": 7,
+        "username": "annotator",
+        "role": "visitor",
+        "is_active": True,
+        "project_types": ["2d"],
+        "revision": 3,
+        **changes,
+    }
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        {"id": True},
+        {"id": 0},
+        {"revision": -1},
+        {"revision": True},
+        {"is_active": 1},
+        {"username": " user"},
+        {"username": "user\x00"},
+        {"role": "editor"},
+        {"project_types": ["2D"]},
+        {"project_types": ["2d", "2d"]},
+        {"project_types": ["3d", "2d"]},
+        {"project_types": "2d"},
+        {"password": "must-never-appear"},
+        {"contract_version": "x4d-account-v0"},
+    ],
+)
+def test_account_rejects_noncanonical_data_without_secret_echo(change):
+    with pytest.raises(ValueError) as error:
+        parse_account_record(record(**change))
+    assert "must-never-appear" not in str(error.value)
+
+
+@pytest.mark.parametrize("grants", [[], ["2d"], ["3d"], ["2d", "3d"]])
+def test_account_roundtrip_detaches_grants(grants):
+    value = record(project_types=grants)
+    parsed = parse_account_record(value)
+    detached = parsed.to_dict()
+    assert detached == value
+    detached["project_types"].append("mutated")
+    assert parsed.to_dict() == value
+    assert validate_project_types(grants) == grants
+
+
+@pytest.mark.parametrize(
+    "password", ["short", " " * 12, "x" * 73, "密" * 25, "secret\ud800"]
+)
+def test_password_limits_are_bytes_and_do_not_echo_credentials(password):
+    with pytest.raises(ValueError) as error:
+        validate_account_password(password)
+    assert password not in str(error.value)
+
+
+def test_page_rejects_duplicates_excess_and_private_fields():
+    page = {
+        "contract_version": ACCOUNT_PAGE_CONTRACT,
+        "page": 1,
+        "page_size": 10,
+        "total": 1,
+        "items": [record()],
+    }
+    assert parse_account_page(page) == page
+    for changes in (
+        {"items": [record(), record()]},
+        {"page_size": 101},
+        {"secret": "hidden"},
+    ):
+        with pytest.raises(ValueError):
+            parse_account_page({**page, **changes})
+
+
+def test_typed_client_uses_only_account_capabilities_and_clears_changed_credentials():
+    requests = []
+    current = record()
+
+    def handler(request):
+        requests.append(request)
+        path = request.url.path
+        if request.method == "GET" and path == "/api/v1/users":
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": ACCOUNT_PAGE_CONTRACT,
+                    "page": 1,
+                    "page_size": 10,
+                    "total": 1,
+                    "items": [current],
+                },
+            )
+        if path.endswith("/update"):
+            body = json.loads(request.content)
+            for key in ("role", "project_types", "is_active"):
+                current[key] = body[key]
+            current["revision"] += 1
+        elif path.endswith("/reset-password") or path.endswith("/me/password"):
+            current["revision"] += 1
+        return httpx.Response(200, json=deepcopy(current))
+
+    with X4DClient(api_url="http://platform.test", token="private-token") as client:
+        client._http.close()
+        client._http = httpx.Client(
+            base_url=client.api_url,
+            headers={"Authorization": "Bearer private-token"},
+            transport=httpx.MockTransport(handler),
+        )
+        assert client.accounts.list(page_size=10)["items"][0]["id"] == 7
+        assert client.accounts.get(7).id == client.accounts.me().id == 7
+        assert (
+            client.accounts.create(
+                username="annotator",
+                password="private-password",
+                role="visitor",
+                project_types=["2d"],
+            ).id
+            == 7
+        )
+        assert (
+            client.accounts.update(
+                7,
+                expected_revision=3,
+                role="visitor",
+                project_types=["2d", "3d"],
+                is_active=True,
+            ).revision
+            == 4
+        )
+        assert (
+            client.accounts.reset_password(
+                7, expected_revision=4, password="replacement-password"
+            ).revision
+            == 5
+        )
+        assert (
+            client.accounts.change_password(
+                current_password="replacement-password", new_password="another-password"
+            ).revision
+            == 6
+        )
+        assert "Authorization" not in client._http.headers
+    assert all(request.url.host == "platform.test" for request in requests)
+    assert all(
+        request.headers["Authorization"] == "Bearer private-token"
+        for request in requests
+    )
+    assert json.loads(requests[-1].content) == {
+        "current_password": "replacement-password",
+        "new_password": "another-password",
+    }
+
+
+def test_client_rejects_foreign_responses_and_invalid_requests_before_io():
+    with X4DClient(api_url="http://platform.test") as client:
+        client._http.close()
+        client._http = httpx.Client(
+            base_url=client.api_url,
+            transport=httpx.MockTransport(
+                lambda request: httpx.Response(200, json=record(id=8))
+            ),
+        )
+        with pytest.raises(ValueError, match="another user"):
+            client.accounts.get(7)
+        with pytest.raises(ValueError, match="UTF-8"):
+            client.accounts.create(
+                username="user",
+                password="密" * 25,
+                role="visitor",
+                project_types=["2d"],
+            )
+        with pytest.raises(ValueError, match="boolean"):
+            client.accounts.update(
+                7,
+                expected_revision=3,
+                role="visitor",
+                project_types=["2d"],
+                is_active=1,
+            )

x4d_devkit-0.48.0rc8/tests/test_image_schema_upgrade.py

@@ -0,0 +1,239 @@
+from copy import deepcopy
+import json
+
+import httpx
+import pytest
+
+from x4d_devkit import X4DClient
+from x4d_devkit._image_contract import fingerprint
+from x4d_devkit.image_clip import build_image_identity
+from x4d_devkit.image_schema import (
+    parse_image_schema_body,
+    parse_image_schema_record,
+    build_image_schema_snapshot,
+)
+from x4d_devkit.image_schema_upgrade import (
+    RECEIPT_CONTRACT,
+    additive_image_schema_changes,
+    image_schema_upgrade_candidate,
+    build_image_schema_upgrade_preview,
+    build_image_schema_upgrade_request,
+    parse_image_schema_upgrade_preview,
+    parse_image_schema_upgrade_request,
+    parse_image_schema_upgrade_receipt,
+)
+from tests.image_fixtures import clip_payload, line_object
+
+
+def target(clip):
+    body = deepcopy(clip["label_schema"]["body"])
+    body["version"] = "1.1.0"
+    body["categories"][0]["attributes"].append(
+        {
+            "id": "optional",
+            "display_name": "Optional",
+            "type": "boolean",
+            "required": False,
+            "scopes": ["object", "segment"],
+            "values": [],
+        }
+    )
+    for category in body["categories"]:
+        for attribute in category["attributes"]:
+            if attribute["type"] == "enum":
+                attribute["values"].append({"id": "extra", "display_name": "Extra"})
+    return build_image_schema_snapshot(
+        parse_image_schema_record(
+            {
+                "contract_version": "x4d-image-label-schema-record-v1",
+                "status": "active",
+                "body": body,
+                "fingerprint": parse_image_schema_body(body).identity.fingerprint,
+            }
+        )
+    )
+
+
+def test_additive_upgrade_preserves_complete_human_geometry_ranges_and_completion():
+    clip = clip_payload()
+    clip["image_annotation"]["objects"] = [line_object()]
+    clip["identity"] = build_image_identity(clip)
+    snapshot = target(clip)
+    candidate = image_schema_upgrade_candidate(clip, snapshot).to_dict()
+    assert all(
+        candidate[key] == clip[key]
+        for key in clip
+        if key not in {"label_schema", "identity"}
+    )
+    assert (
+        candidate["identity"]["source_revision"] == clip["identity"]["source_revision"]
+    )
+    assert (
+        candidate["identity"]["annotation_revision"]
+        == clip["identity"]["annotation_revision"]
+    )
+    assert (
+        candidate["identity"]["schema_fingerprint"]
+        != clip["identity"]["schema_fingerprint"]
+    )
+    assert "optional" not in candidate["image_annotation"]["objects"][0]["attributes"]
+    preview = build_image_schema_upgrade_preview(clip, snapshot)
+    assert (
+        parse_image_schema_upgrade_preview(preview.to_dict()).to_dict()
+        == preview.to_dict()
+    )
+    request = build_image_schema_upgrade_request(preview, "explicit-test-key")
+    assert (
+        parse_image_schema_upgrade_request(request.to_dict()).to_dict()
+        == request.to_dict()
+    )
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "same-version",
+        "backwards",
+        "schema-id",
+        "category",
+        "geometry",
+        "view",
+        "attribute-remove",
+        "required",
+        "scope",
+        "enum-meaning",
+        "new-required",
+    ],
+)
+def test_incompatible_reinterpretations_require_a_separate_migration(change):
+    clip = clip_payload()
+    old, new = clip["label_schema"]["body"], target(clip)["body"]
+    if change == "same-version":
+        new["version"] = old["version"]
+    if change == "backwards":
+        new["version"] = "0.1.0"
+    if change == "schema-id":
+        new["schema_id"] = "another"
+    if change == "category":
+        new["categories"].pop()
+    if change == "geometry":
+        new["categories"][0]["geometry_type"] = "box_2d"
+    if change == "view":
+        new["task_views"][0]["display_name"] = "Reinterpreted"
+    if change == "attribute-remove":
+        new["categories"][0]["attributes"].pop(0)
+    if change == "required":
+        new["categories"][0]["attributes"][0]["required"] = True
+    if change == "scope":
+        new["categories"][0]["attributes"][0]["scopes"] = ["object"]
+    if change == "enum-meaning":
+        new["categories"][0]["attributes"][1]["values"][0]["display_name"] = (
+            "Different meaning"
+        )
+    if change == "new-required":
+        new["categories"][0]["attributes"][-1]["required"] = True
+    with pytest.raises(ValueError):
+        additive_image_schema_changes(old, new)
+
+
+@pytest.mark.parametrize(
+    "part",
+    ["digest", "source", "human", "schema", "changes", "foreign-clip", "unknown-field"],
+)
+def test_preview_rejects_tampered_transition_even_with_recomputed_fingerprint(part):
+    clip = clip_payload()
+    value = build_image_schema_upgrade_preview(clip, target(clip)).to_dict()
+    if part == "source":
+        value["after_identity"]["components"]["sample"] = "sha256:" + "a" * 64
+    if part == "human":
+        value["after_identity"]["annotation_revision"] = "sha256:" + "a" * 64
+    if part == "schema":
+        value["target_schema"]["body"]["version"] = "1.2.0"
+    if part == "changes":
+        value["changes"]["added_attributes"] = []
+    if part == "foreign-clip":
+        value["after_identity"]["clip_id"] = "foreign"
+    if part == "unknown-field":
+        value["automatic_repair"] = True
+    value["preview_fingerprint"] = (
+        "sha256:" + "0" * 64
+        if part == "digest"
+        else fingerprint({k: v for k, v in value.items() if k != "preview_fingerprint"})
+    )
+    with pytest.raises(ValueError):
+        parse_image_schema_upgrade_preview(value)
+
+
+def test_typed_image_schema_reads_and_upgrade_verify_the_exact_request():
+    clip = clip_payload()
+    snapshot = target(clip)
+    preview = build_image_schema_upgrade_preview(clip, snapshot).to_dict()
+    record = {
+        "contract_version": "x4d-image-label-schema-record-v1",
+        "status": "active",
+        "body": snapshot["body"],
+        "fingerprint": snapshot["identity"]["fingerprint"],
+    }
+    requests, bad = [], {"enabled": False}
+
+    def handler(request):
+        requests.append(request)
+        path = request.url.path
+        if path == "/api/v1/label-schemas":
+            assert request.url.params["project_type"] == "2d"
+            return httpx.Response(200, json={"items": [record], "total": 1})
+        if path == "/api/v1/projects/7/label-schema":
+            return httpx.Response(
+                200,
+                json={
+                    "contract_version": "x4d-image-project-label-schema-v1",
+                    "project_id": 7,
+                    "label_schema": record,
+                },
+            )
+        if path.startswith("/api/v1/label-schemas/"):
+            return httpx.Response(200, json=record)
+        if path.endswith("/preview"):
+            assert json.loads(request.content) == {
+                "project_id": 7,
+                "clip_id": "clip_test",
+                "target_schema": snapshot["identity"],
+            }
+            return httpx.Response(200, json=preview)
+        body = json.loads(request.content)
+        receipt = {
+            "contract_version": RECEIPT_CONTRACT,
+            "project_id": 7,
+            "clip_id": "clip_test",
+            "idempotency_key": body["idempotency_key"],
+            "preview_fingerprint": preview["preview_fingerprint"],
+            "identity": preview["after_identity"],
+            "changed": True,
+        }
+        if bad["enabled"]:
+            receipt["idempotency_key"] = "other-request"
+        return httpx.Response(200, json=receipt)
+
+    with X4DClient("http://x4d.test", token="test") as client:
+        client._http.close()
+        client._http = httpx.Client(
+            base_url="http://x4d.test", transport=httpx.MockTransport(handler)
+        )
+        assert client.image_schemas.list()["total"] == 1
+        assert (
+            client.image_schemas.get(
+                schema_id=snapshot["identity"]["schema_id"], version="1.1.0"
+            ).body
+            == snapshot["body"]
+        )
+        assert client.image_schemas.get_project(7).to_dict()["project_id"] == 7
+        parsed = client.image_schemas.preview_upgrade(clip=clip, target_schema=snapshot)
+        request = client.image_schemas.upgrade_request(parsed, "explicit-request")
+        receipt = client.image_schemas.commit_upgrade(request)
+        assert (
+            parse_image_schema_upgrade_receipt(receipt.to_dict()).to_dict()["identity"]
+            == preview["after_identity"]
+        )
+        bad["enabled"] = True
+        with pytest.raises(ValueError, match="another request"):
+            client.image_schemas.commit_upgrade(request)

{x4d_devkit-0.48.0rc6 → x4d_devkit-0.48.0rc8}/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.48.0rc6"
+    assert x4d_devkit.__version__ == "0.48.0rc8"
 
 
 def test_loader_exposes_and_enforces_only_current_schema(tmp_path):

x4d_devkit-0.48.0rc8/x4d_devkit/accounts.py

@@ -0,0 +1,147 @@
+"""Strict managed-account documents; the platform owns authorization."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import unicodedata
+from typing import Any
+
+from x4d_devkit.json_contract import ensure_i_json
+
+ACCOUNT_CONTRACT = "x4d-account-v1"
+ACCOUNT_PAGE_CONTRACT = "x4d-account-page-v1"
+
+
+def _require(condition: bool, message: str) -> None:
+    if not condition:
+        raise ValueError(message)
+
+
+def account_integer(value: Any, name: str, *, minimum=0) -> int:
+    _require(
+        type(value) is int and minimum <= value <= 2**53 - 1,
+        f"{name} must be an exact integer >= {minimum}",
+    )
+    return value
+
+
+def validate_username(value: Any) -> str:
+    _require(
+        type(value) is str
+        and 1 <= len(value) <= 64
+        and value == value.strip()
+        and not any(unicodedata.category(c).startswith("C") for c in value),
+        "username must be canonical text of 1–64 characters without controls",
+    )
+    return value
+
+
+def validate_account_password(value: Any) -> str:
+    _require(
+        type(value) is str and len(value) >= 8 and bool(value.strip()),
+        "password must contain at least 8 characters and not be blank",
+    )
+    try:
+        encoded = value.encode("utf-8")
+    except UnicodeError:
+        raise ValueError("password must be valid UTF-8") from None
+    _require(len(encoded) <= 72, "password must not exceed 72 UTF-8 bytes")
+    return value
+
+
+def validate_project_types(value: Any) -> list[str]:
+    _require(
+        type(value) is list
+        and all(type(v) is str and v in ("2d", "3d") for v in value)
+        and value == sorted(set(value)),
+        "project_types must be a sorted unique subset of ['2d', '3d']",
+    )
+    return list(value)
+
+
+def validate_account_role(value: Any) -> str:
+    _require(
+        type(value) is str and value in ("admin", "visitor"),
+        "role must be admin or visitor",
+    )
+    return value
+
+
+@dataclass(frozen=True)
+class AccountRecord:
+    """An immutable public account; contains no credentials."""
+
+    id: int
+    username: str
+    role: str
+    is_active: bool
+    project_types: tuple[str, ...]
+    revision: int
+
+    def to_dict(self) -> dict:
+        value = asdict(self)
+        value["contract_version"] = ACCOUNT_CONTRACT
+        value["project_types"] = list(self.project_types)
+        return value
+
+
+def parse_account_record(value: Any) -> AccountRecord:
+    ensure_i_json(value, path="account")
+    _require(
+        type(value) is dict
+        and set(value)
+        == {
+            "contract_version",
+            "id",
+            "username",
+            "role",
+            "is_active",
+            "project_types",
+            "revision",
+        },
+        "account fields do not match the current contract",
+    )
+    _require(
+        value["contract_version"] == ACCOUNT_CONTRACT, "unsupported account contract"
+    )
+    _require(type(value["is_active"]) is bool, "is_active must be boolean")
+    return AccountRecord(
+        account_integer(value["id"], "id", minimum=1),
+        validate_username(value["username"]),
+        validate_account_role(value["role"]),
+        value["is_active"],
+        tuple(validate_project_types(value["project_types"])),
+        account_integer(value["revision"], "revision"),
+    )
+
+
+def parse_account_page(value: Any) -> dict:
+    ensure_i_json(value, path="account_page")
+    _require(
+        type(value) is dict
+        and set(value) == {"contract_version", "page", "page_size", "total", "items"},
+        "account page fields do not match the current contract",
+    )
+    _require(
+        value["contract_version"] == ACCOUNT_PAGE_CONTRACT,
+        "unsupported account page contract",
+    )
+    page = account_integer(value["page"], "page", minimum=1)
+    size = account_integer(value["page_size"], "page_size", minimum=1)
+    total = account_integer(value["total"], "total")
+    _require(
+        size <= 100 and type(value["items"]) is list, "invalid account page size/items"
+    )
+    items = [parse_account_record(row).to_dict() for row in value["items"]]
+    _require(
+        len(items) <= min(size, total)
+        and len({row["id"] for row in items}) == len(items),
+        "account page has duplicate or excess items",
+    )
+    return {
+        "contract_version": ACCOUNT_PAGE_CONTRACT,
+        "page": page,
+        "page_size": size,
+        "total": total,
+        "items": items,
+    }

{x4d_devkit-0.48.0rc6 → x4d_devkit-0.48.0rc8}/x4d_devkit/client/__init__.py

@@ -42,7 +42,10 @@ 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
+
 __all__ = [
+    "ImageSchemasAPI",
     "ImageWorkSessionsAPI",
     "ImageExportsAPI",
     "CleanBasemapState",