x4d-devkit 0.48.0rc5__tar.gz → 0.48.0rc7__tar.gz

{x4d_devkit-0.48.0rc5 → x4d_devkit-0.48.0rc7}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "x4d-devkit"
-version = "0.48.0rc5"
+version = "0.48.0rc7"
 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.0rc7/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.0rc5 → x4d_devkit-0.48.0rc7}/tests/test_image_export.py

@@ -215,6 +215,9 @@ def job(status="queued"):
         "created_at": NOW,
         "completed_at": NOW if terminal else None,
         "can_cancel": not terminal,
+        "completion_counts": {"unprocessed": 2, "complete": 0, "confirmed_empty": 0}
+        if status in {"packaging", "validating", "uploading", "completed"}
+        else None,
     }
 
 
@@ -255,6 +258,14 @@ def test_invalid_job_states_fail(change):
         value["completed_at"] = NOW
     if change == "infinite":
         value["progress"]["rate"] = float("inf")
+    if change == "counts":
+        value["completion_counts"] = {
+            "unprocessed": -1,
+            "complete": 0,
+            "confirmed_empty": 0,
+        }
+    if change == "unsealed":
+        value["status"] = value["progress"]["stage"] = "packaging"
     with pytest.raises((ImageContractError, ValueError)):
         parse_image_export_job(value)
 
@@ -276,6 +287,7 @@ def test_typed_client_scope_and_ephemeral_download_do_not_forward_credentials():
                     "clip_ids": ["clip_test"],
                     "excluded": [],
                     "scope_token": "opaque-token",
+                    "completed_scope_count": 0,
                     "expires_at": NOW,
                 },
             )
@@ -387,3 +399,16 @@ def test_archive_member_history_is_not_retained(tmp_path, monkeypatch):
     monkeypatch.setattr(tarfile.TarFile, "next", measured)
     validate_image_export_bundle(path)
     assert max(history) <= 1
+
+
+def test_completed_job_reports_zero_authoritative_scopes_and_rejects_unknown_counts():
+    value = job("completed")
+    assert parse_image_export_job(value).to_dict()["completion_counts"]["complete"] == 0
+    for counts in (
+        None,
+        {"unprocessed": True, "complete": 0, "confirmed_empty": 0},
+        {"complete": 2},
+    ):
+        value["completion_counts"] = counts
+        with pytest.raises(ImageContractError):
+            parse_image_export_job(value)

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

x4d_devkit-0.48.0rc7/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.0rc7/x4d_devkit/client/accounts.py

@@ -0,0 +1,111 @@
+"""Typed adapters for platform-owned account capabilities."""
+
+from x4d_devkit.accounts import (
+    account_integer,
+    parse_account_page,
+    parse_account_record,
+    validate_account_password,
+    validate_account_role,
+    validate_project_types,
+    validate_username,
+)
+
+
+class AccountsAPI:
+    def __init__(self, client):
+        self._client = client
+
+    def me(self):
+        return parse_account_record(self._client.get("/users/me"))
+
+    def get(self, user_id):
+        account_integer(user_id, "user_id", minimum=1)
+        return self._record(self._client.get(f"/users/{user_id}"), user_id)
+
+    def list(self, *, page=1, page_size=50):
+        account_integer(page, "page", minimum=1)
+        account_integer(page_size, "page_size", minimum=1)
+        if page_size > 100:
+            raise ValueError("page_size exceeds 100")
+        result = parse_account_page(
+            self._client.get("/users", params={"page": page, "page_size": page_size})
+        )
+        if result["page"] != page or result["page_size"] != page_size:
+            raise ValueError("account page belongs to another request")
+        return result
+
+    def create(self, *, username, password, role, project_types):
+        body = {
+            "username": validate_username(username),
+            "password": validate_account_password(password),
+            "role": validate_account_role(role),
+            "project_types": validate_project_types(project_types),
+        }
+        result = parse_account_record(self._client.post("/users", json=body))
+        if (
+            result.username != username
+            or result.role != role
+            or list(result.project_types) != project_types
+        ):
+            raise ValueError("created account belongs to another request")
+        return result
+
+    def update(self, user_id, *, expected_revision, role, project_types, is_active):
+        account_integer(user_id, "user_id", minimum=1)
+        account_integer(expected_revision, "expected_revision")
+        if type(is_active) is not bool:
+            raise ValueError("is_active must be boolean")
+        body = {
+            "expected_revision": expected_revision,
+            "role": validate_account_role(role),
+            "project_types": validate_project_types(project_types),
+            "is_active": is_active,
+        }
+        result = self._record(
+            self._client.post(f"/users/{user_id}/update", json=body), user_id
+        )
+        if result.revision < expected_revision or any(
+            result.to_dict()[key] != body[key]
+            for key in ("role", "project_types", "is_active")
+        ):
+            raise ValueError("updated account belongs to another request")
+        return result
+
+    def reset_password(self, user_id, *, expected_revision, password):
+        account_integer(user_id, "user_id", minimum=1)
+        account_integer(expected_revision, "expected_revision")
+        result = self._record(
+            self._client.post(
+                f"/users/{user_id}/reset-password",
+                json={
+                    "expected_revision": expected_revision,
+                    "password": validate_account_password(password),
+                },
+            ),
+            user_id,
+        )
+        if result.revision <= expected_revision:
+            raise ValueError("password reset did not advance the account revision")
+        return result
+
+    def change_password(self, *, current_password, new_password):
+        if type(current_password) is not str or not current_password:
+            raise ValueError("current_password must be explicit text")
+        result = parse_account_record(
+            self._client.post(
+                "/users/me/password",
+                json={
+                    "current_password": current_password,
+                    "new_password": validate_account_password(new_password),
+                },
+            )
+        )
+        self._client.set_token(None)
+        return result
+
+    @staticmethod
+    def _record(value, user_id):
+        result = parse_account_record(value)
+        if result.id != user_id:
+            raise ValueError("account response belongs to another user")
+        return result

{x4d_devkit-0.48.0rc5 → x4d_devkit-0.48.0rc7}/x4d_devkit/client/client.py

@@ -15,6 +15,7 @@ from typing import TYPE_CHECKING
 import httpx
 
 from x4d_devkit.client._origin import validated_origin
+from x4d_devkit.client.accounts import AccountsAPI
 from x4d_devkit.client.assets import AssetsAPI
 from x4d_devkit.client.checkpoints import CheckpointsAPI
 from x4d_devkit.client.bags import BagsAPI
@@ -67,6 +68,7 @@ class X4DClient:
             base_url=self._api_url, headers=headers, timeout=timeout
         )
         self.assets = AssetsAPI(self)
+        self.accounts = AccountsAPI(self)
         self.bags = BagsAPI(self)
         self.capabilities = CapabilitiesAPI(self)
         self.clip_work_sessions = ClipWorkSessionsAPI(self)

{x4d_devkit-0.48.0rc5 → x4d_devkit-0.48.0rc7}/x4d_devkit/image_export.py

@@ -29,8 +29,8 @@ from x4d_devkit.json_contract import parse_i_json
 EXPORT_CONTRACT = "x4d-image-export-v1"
 INDEX_CONTRACT = "x4d-image-export-index-v1"
 SCOPES_CONTRACT = "x4d-image-human-scopes-v1"
-PREVIEW_CONTRACT = "x4d-image-export-preview-v1"
-JOB_CONTRACT = "x4d-image-export-job-v1"
+PREVIEW_CONTRACT = "x4d-image-export-preview-v2"
+JOB_CONTRACT = "x4d-image-export-job-v2"
 PAGE_CONTRACT = "x4d-image-export-page-v1"
 DOWNLOAD_CONTRACT = "x4d-image-export-download-v1"
 COMPONENTS = (*IMAGE_CLIP_COMPONENTS, "identity")
@@ -409,6 +409,7 @@ def parse_image_export_preview(value):
             "excluded",
             "scope_token",
             "expires_at",
+            "completed_scope_count",
         },
         "export_preview",
     )
@@ -418,6 +419,8 @@ def parse_image_export_preview(value):
         "contract_version",
     )
     _scope(value)
+    if value["completed_scope_count"] is not None:
+        integer(value["completed_scope_count"], "completed_scope_count")
     _ids(value["clip_ids"])
     if value["clip_id"] is not None:
         require(
@@ -467,6 +470,7 @@ def parse_image_export_job(value):
             "created_at",
             "completed_at",
             "can_cancel",
+            "completion_counts",
         },
         "export_job",
     )
@@ -528,6 +532,17 @@ def parse_image_export_job(value):
         "failure needs exactly one explicit error",
         "error",
     )
+    counts = value["completion_counts"]
+    if counts is not None:
+        fields(counts, set(COMPLETION_STATES), "completion_counts")
+        for count in counts.values():
+            integer(count, "completion_counts")
+    require(
+        value["status"] not in {"packaging", "validating", "uploading", "completed"}
+        or counts is not None,
+        "sealed export must report authoritative completion",
+        "completion_counts",
+    )
     if value["status"] == "completed":
         _artifact(value["artifact"], value["export_id"])
     else:

{x4d_devkit-0.48.0rc5 → x4d_devkit-0.48.0rc7}/x4d_devkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: x4d-devkit
-Version: 0.48.0rc5
+Version: 0.48.0rc7
 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.0rc5 → x4d_devkit-0.48.0rc7}/x4d_devkit.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 LICENSE
 README.md
 pyproject.toml
+tests/test_accounts.py
 tests/test_annotation_contract.py
 tests/test_annotation_reference.py
 tests/test_assets_client.py
@@ -65,6 +66,7 @@ tests/test_work_session.py
 tests/test_work_session_validation_reuse.py
 x4d_devkit/__init__.py
 x4d_devkit/_image_contract.py
+x4d_devkit/accounts.py
 x4d_devkit/annotation_contract.py
 x4d_devkit/annotation_reference.py
 x4d_devkit/audit.py
@@ -105,6 +107,7 @@ x4d_devkit.egg-info/requires.txt
 x4d_devkit.egg-info/top_level.txt
 x4d_devkit/client/__init__.py
 x4d_devkit/client/_origin.py
+x4d_devkit/client/accounts.py
 x4d_devkit/client/annotation_reference.py
 x4d_devkit/client/assets.py
 x4d_devkit/client/bags.py