matelab-python-sdk 0.1.0a7__tar.gz → 0.1.0a8__tar.gz

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/AGENTS.md

@@ -62,6 +62,8 @@
 - mutation 默认不自动重试。multipart 或 stream 只有在确认可重放时才能重试；download stream 不自动重放，
   必须支持显式关闭。
 - HTTP/transport、Provider business/authentication、Wire Contract/schema 和 client usage 错误必须稳定区分。
+- 每个公开 `MatelabError` 必须直接提供稳定的集成级 `category` 和保守的 `retryable`；Provider kind 和 HTTP
+  status 只用于诊断，下游不得重新解释 Provider 数字 code 才能决定恢复类别。
 - password、token、SSO code/key、临时附件凭证、原始文件内容和敏感 payload 不得进入日志、异常或提交内容。
 
 ## 测试与质量门槛

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.0a8 - 2026-08-04
+
+- Adds a unified `MatelabErrorCategory` and conservative `retryable` flag to every public SDK error, centralizing
+  Provider error semantics so integrations no longer reinterpret `MatelabProviderErrorKind`.
+
 ## 0.1.0a7 - 2026-08-04
 
 - Replaces the hand-maintained wire-validation rule tables with deterministic generated JSON Schema 2020-12 rules.

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matelab-python-sdk
-Version: 0.1.0a7
+Version: 0.1.0a8
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author-email: 朱天念 <zhutiannian@gmail.com>
 License-Expression: Apache-2.0
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a7`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a8`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
 The SDK is pinned to the immutable `matelab-spec v0.3.0` Contract Release. The sole release pin is
@@ -58,7 +58,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a7-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a8-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -85,25 +85,29 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 
 ### Error handling
 
-Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
-
-| Error | Meaning and normal response |
-|---|---|
-| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
-| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
-| `MatelabProviderError` | The Provider returned a non-authentication error; inspect its stable `kind` and do not assume a mutation was applied. |
-| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
-| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
-
-`MatelabProviderError.kind` is a `MatelabProviderErrorKind`: `REJECTED` covers input, permission, and business
-rejections; `SERVER` identifies Provider server failures; `VALIDATION` identifies multi-error validation failures; and
-`UNKNOWN` safely represents all other non-success, non-authentication Provider codes. Authentication codes are hidden
-behind `MatelabAuthenticationError`; raw Provider codes are not part of the public error interface.
+Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
+`retryable: bool`, so an integration can copy the message, category, and retry flag without inspecting subclasses or
+Provider details:
+
+| Error | Category | Retryable | Meaning and normal response |
+|---|---|---:|---|
+| `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
+| `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
+| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route by `category`, with `kind` available only for diagnosis. |
+| `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
+
+For `MatelabProviderError`, the SDK maps `REJECTED` to `BUSINESS`, `VALIDATION` to `VALIDATION`, and `SERVER` or
+`UNKNOWN` to `UPSTREAM`. `MatelabProviderError.kind` remains a `MatelabProviderErrorKind` diagnostic, but integrations
+do not need it for recovery routing. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider
+codes are not part of the public error interface.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
 success code it does not allow raises `MatelabProtocolError` rather than assigning an error kind.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
-never attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol
-error.
+never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
+interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
+mutation idempotency or outcome; an integration may add a narrower operation-specific retry policy only when it owns
+that evidence.
 
 ### Session ownership
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/README.md

@@ -2,7 +2,7 @@
 
 Reusable async Python client for the Matelab Integration Contract.
 
-The current alpha is `0.1.0a7`. `[project].version` in `pyproject.toml` is the sole SDK version source;
+The current alpha is `0.1.0a8`. `[project].version` in `pyproject.toml` is the sole SDK version source;
 `uv.lock` only mirrors that source.
 
 The SDK is pinned to the immutable `matelab-spec v0.3.0` Contract Release. The sole release pin is
@@ -31,7 +31,7 @@ To test the same artifact a downstream Consumer will install, build and install
 
 ```bash
 uv build --no-build-isolation --out-dir dist/release
-python -m pip install dist/release/matelab_python_sdk-0.1.0a7-py3-none-any.whl
+python -m pip install dist/release/matelab_python_sdk-0.1.0a8-py3-none-any.whl
 ```
 
 Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
@@ -58,25 +58,29 @@ explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`
 
 ### Error handling
 
-Catch `MatelabError` for one application-level fallback, or a specific subclass when recovery differs:
-
-| Error | Meaning and normal response |
-|---|---|
-| `MatelabUsageError` | The call cannot be represented safely; correct its arguments. |
-| `MatelabAuthenticationError` | The Session is missing, expired, invalid, or rejected; refresh or authenticate again as appropriate. |
-| `MatelabProviderError` | The Provider returned a non-authentication error; inspect its stable `kind` and do not assume a mutation was applied. |
-| `MatelabTransportError` | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
-| `MatelabProtocolError` | The Provider response does not match the pinned Contract; treat it as Provider drift or an SDK defect. A mutation may already have been applied. |
-
-`MatelabProviderError.kind` is a `MatelabProviderErrorKind`: `REJECTED` covers input, permission, and business
-rejections; `SERVER` identifies Provider server failures; `VALIDATION` identifies multi-error validation failures; and
-`UNKNOWN` safely represents all other non-success, non-authentication Provider codes. Authentication codes are hidden
-behind `MatelabAuthenticationError`; raw Provider codes are not part of the public error interface.
+Catch `MatelabError` once at an integration seam. Every instance exposes a stable `category: MatelabErrorCategory` and
+`retryable: bool`, so an integration can copy the message, category, and retry flag without inspecting subclasses or
+Provider details:
+
+| Error | Category | Retryable | Meaning and normal response |
+|---|---|---:|---|
+| `MatelabAuthenticationError` | `AUTHENTICATION` | No | The Session or credentials cannot authenticate; obtain valid authentication before making a new call. |
+| `MatelabUsageError` | `VALIDATION` | No | The call cannot be represented safely; correct its arguments. |
+| `MatelabProviderError` | `BUSINESS`, `VALIDATION`, or `UPSTREAM` | No | The Provider rejected the request; route by `category`, with `kind` available only for diagnosis. |
+| `MatelabTransportError` | `UPSTREAM` | No | The HTTP exchange failed; `status_code` is present for HTTP failures, and a mutation outcome may be unknown. |
+| `MatelabProtocolError` | `UPSTREAM` | No | The response violates the pinned Contract; treat it as Provider drift or an SDK defect. |
+
+For `MatelabProviderError`, the SDK maps `REJECTED` to `BUSINESS`, `VALIDATION` to `VALIDATION`, and `SERVER` or
+`UNKNOWN` to `UPSTREAM`. `MatelabProviderError.kind` remains a `MatelabProviderErrorKind` diagnostic, but integrations
+do not need it for recovery routing. Authentication codes are hidden behind `MatelabAuthenticationError`; raw Provider
+codes are not part of the public error interface.
 Codes `0` and `10` remain operation-specific successes selected by the pinned Contract; an operation that receives a
 success code it does not allow raises `MatelabProtocolError` rather than assigning an error kind.
 `MatelabTransportError.status_code` remains available for HTTP failures. Provider response bodies and caller inputs are
-never attached to exceptions. Never automatically retry a mutation solely because it raised a transport or protocol
-error.
+never attached to exceptions. `retryable` means the identical SDK call is safe to replay without further
+interpretation. It is conservatively `False` for every current SDK error because the Contract does not guarantee
+mutation idempotency or outcome; an integration may add a narrower operation-specific retry policy only when it owns
+that evidence.
 
 ### Session ownership
 

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.1.0a7"
+version = "0.1.0a8"
 description = "Reusable async Python client for the Matelab Integration Contract"
 readme = "README.md"
 requires-python = ">=3.11"

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/scripts/check_installed_package.py

@@ -17,6 +17,9 @@ def main() -> None:
             raise RuntimeError(f"Public symbol {name} leaks a generated wire type.")
     if not files(matelab).joinpath("py.typed").is_file():
         raise RuntimeError("The installed wheel does not contain matelab/py.typed.")
+    error = matelab.MatelabUsageError("invalid input")
+    if error.category is not matelab.MatelabErrorCategory.VALIDATION or error.retryable:
+        raise RuntimeError("The installed package does not expose stable integration error semantics.")
 
 
 if __name__ == "__main__":

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/src/matelab/__init__.py

@@ -115,6 +115,7 @@ from matelab.domains.users import UserRef, UserSummary
 from matelab.errors import (
     MatelabAuthenticationError,
     MatelabError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
     MatelabProviderErrorKind,
@@ -165,6 +166,7 @@ __all__ = [
     "LiteratureStoredMetadata",
     "MatelabAuthenticationError",
     "MatelabError",
+    "MatelabErrorCategory",
     "MatelabProtocolError",
     "MatelabProviderError",
     "MatelabProviderErrorKind",

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/src/matelab/errors.py

@@ -1,9 +1,21 @@
 from enum import StrEnum
 
 
+class MatelabErrorCategory(StrEnum):
+    """Stable integration-level recovery category for an SDK error."""
+
+    AUTHENTICATION = "authentication"
+    BUSINESS = "business"
+    VALIDATION = "validation"
+    UPSTREAM = "upstream"
+
+
 class MatelabError(Exception):
     """Base class for stable Matelab SDK errors."""
 
+    category: MatelabErrorCategory = MatelabErrorCategory.UPSTREAM
+    retryable: bool = False
+
 
 class MatelabProviderErrorKind(StrEnum):
     """Stable interpretation of a Provider error envelope."""
@@ -20,15 +32,25 @@ class MatelabProviderError(MatelabError):
     def __init__(self, message: str, *, kind: MatelabProviderErrorKind) -> None:
         super().__init__(message)
         self.kind = kind
+        self.category = {
+            MatelabProviderErrorKind.REJECTED: MatelabErrorCategory.BUSINESS,
+            MatelabProviderErrorKind.SERVER: MatelabErrorCategory.UPSTREAM,
+            MatelabProviderErrorKind.VALIDATION: MatelabErrorCategory.VALIDATION,
+            MatelabProviderErrorKind.UNKNOWN: MatelabErrorCategory.UPSTREAM,
+        }[kind]
 
 
 class MatelabAuthenticationError(MatelabError):
     """The Matelab session cannot authenticate Provider requests."""
 
+    category = MatelabErrorCategory.AUTHENTICATION
+
 
 class MatelabUsageError(MatelabError):
     """The requested SDK operation cannot be represented safely."""
 
+    category = MatelabErrorCategory.VALIDATION
+
 
 class MatelabTransportError(MatelabError):
     """The HTTP exchange with the Provider failed."""

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/tests/test_client.py

@@ -10,6 +10,7 @@ from matelab import (
     Identity,
     MatelabAuthenticationError,
     MatelabError,
+    MatelabErrorCategory,
     MatelabProtocolError,
     MatelabProviderError,
     MatelabProviderErrorKind,
@@ -365,17 +366,19 @@ def test_session_models_reject_invalid_values_and_extra_fields() -> None:
 
 
 @pytest.mark.parametrize(
-    ("code", "kind"),
+    ("code", "kind", "category"),
     [
-        (2, MatelabProviderErrorKind.REJECTED),
-        (3, MatelabProviderErrorKind.SERVER),
-        (4, MatelabProviderErrorKind.VALIDATION),
-        (11, MatelabProviderErrorKind.UNKNOWN),
-        (99, MatelabProviderErrorKind.UNKNOWN),
+        (2, MatelabProviderErrorKind.REJECTED, MatelabErrorCategory.BUSINESS),
+        (3, MatelabProviderErrorKind.SERVER, MatelabErrorCategory.UPSTREAM),
+        (4, MatelabProviderErrorKind.VALIDATION, MatelabErrorCategory.VALIDATION),
+        (11, MatelabProviderErrorKind.UNKNOWN, MatelabErrorCategory.UPSTREAM),
+        (99, MatelabProviderErrorKind.UNKNOWN, MatelabErrorCategory.UPSTREAM),
     ],
 )
 @pytest.mark.asyncio
-async def test_provider_error_codes_are_hidden_behind_stable_kinds(code: int, kind: MatelabProviderErrorKind) -> None:
+async def test_provider_error_codes_are_hidden_behind_stable_semantics(
+    code: int, kind: MatelabProviderErrorKind, category: MatelabErrorCategory
+) -> None:
     async def handler(_: Request) -> Response:
         return Response(200, json={"code": code, "msg": "rejected", "errcode": code, "errmsg": "rejected"})
 
@@ -386,6 +389,8 @@ async def test_provider_error_codes_are_hidden_behind_stable_kinds(code: int, ki
 
     assert isinstance(caught.value, MatelabError)
     assert caught.value.kind is kind
+    assert caught.value.category is category
+    assert caught.value.retryable is False
     assert not hasattr(caught.value, "code")
 
 
@@ -400,6 +405,8 @@ async def test_provider_authentication_codes_are_hidden_behind_authentication_er
         with pytest.raises(MatelabAuthenticationError) as caught:
             _ = await client.authenticate("alice@example.org", "bad-password")
 
+    assert caught.value.category is MatelabErrorCategory.AUTHENTICATION
+    assert caught.value.retryable is False
     assert not hasattr(caught.value, "code")
 
 

matelab_python_sdk-0.1.0a8/tests/test_errors.py

@@ -0,0 +1,65 @@
+import pytest
+
+from matelab import (
+    MatelabAuthenticationError,
+    MatelabError,
+    MatelabErrorCategory,
+    MatelabProtocolError,
+    MatelabProviderError,
+    MatelabProviderErrorKind,
+    MatelabTransportError,
+    MatelabUsageError,
+)
+
+
+def test_error_category_values_are_stable_for_integrations() -> None:
+    assert {category.name: category.value for category in MatelabErrorCategory} == {
+        "AUTHENTICATION": "authentication",
+        "BUSINESS": "business",
+        "VALIDATION": "validation",
+        "UPSTREAM": "upstream",
+    }
+
+
+@pytest.mark.parametrize(
+    ("error", "category"),
+    [
+        pytest.param(MatelabError("failure"), MatelabErrorCategory.UPSTREAM, id="base"),
+        pytest.param(MatelabAuthenticationError("failure"), MatelabErrorCategory.AUTHENTICATION, id="authentication"),
+        pytest.param(MatelabUsageError("failure"), MatelabErrorCategory.VALIDATION, id="usage"),
+        pytest.param(MatelabTransportError("failure"), MatelabErrorCategory.UPSTREAM, id="transport"),
+        pytest.param(MatelabProtocolError("failure"), MatelabErrorCategory.UPSTREAM, id="protocol"),
+    ],
+)
+def test_public_errors_expose_integration_category_and_conservative_retryability(
+    error: MatelabError, category: MatelabErrorCategory
+) -> None:
+    assert error.category is category
+    assert error.retryable is False
+
+
+@pytest.mark.parametrize(
+    ("kind", "category"),
+    [
+        (MatelabProviderErrorKind.REJECTED, MatelabErrorCategory.BUSINESS),
+        (MatelabProviderErrorKind.SERVER, MatelabErrorCategory.UPSTREAM),
+        (MatelabProviderErrorKind.VALIDATION, MatelabErrorCategory.VALIDATION),
+        (MatelabProviderErrorKind.UNKNOWN, MatelabErrorCategory.UPSTREAM),
+    ],
+)
+def test_provider_error_kind_is_diagnostic_and_category_is_integration_semantics(
+    kind: MatelabProviderErrorKind, category: MatelabErrorCategory
+) -> None:
+    error = MatelabProviderError("failure", kind=kind)
+
+    assert error.kind is kind
+    assert error.category is category
+    assert error.retryable is False
+
+
+def test_transport_error_preserves_http_status_without_changing_integration_semantics() -> None:
+    error = MatelabTransportError("failure", status_code=503)
+
+    assert error.status_code == 503
+    assert error.category is MatelabErrorCategory.UPSTREAM
+    assert error.retryable is False

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/tests/typing/consumer.py

@@ -1,5 +1,7 @@
 from matelab import (
     AsyncMatelab,
+    MatelabError,
+    MatelabErrorCategory,
     NotebookCollection,
     NotebookRef,
     RecordAttachmentChange,
@@ -21,6 +23,12 @@ from matelab import (
 )
 
 
+def consume_error(error: MatelabError) -> tuple[MatelabErrorCategory, bool]:
+    category: MatelabErrorCategory = error.category
+    retryable: bool = error.retryable
+    return category, retryable
+
+
 async def consume_public_types(client: AsyncMatelab) -> tuple[Session | None, NotebookCollection]:
     notebooks: NotebookCollection = await client.notebooks.list()
     session: Session | None = client.session

{matelab_python_sdk-0.1.0a7 → matelab_python_sdk-0.1.0a8}/uv.lock

@@ -352,7 +352,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.1.0a7"
+version = "0.1.0a8"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },