matelab-python-sdk 0.2.0a6__tar.gz → 0.2.0a8__tar.gz

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/.github/workflows/release.yml

@@ -84,7 +84,7 @@ jobs:
           uv pip install \
             --python "${RUNNER_TEMP}/matelab-consumer/bin/python" \
             dist/release/*.whl \
-            "basedpyright>=1.40.1" \
+            "basedpyright>=1.40.2" \
             "nodejs-wheel-binaries==22.20.0"
           "${RUNNER_TEMP}/matelab-consumer/bin/python" scripts/check_installed_package.py
           "${RUNNER_TEMP}/matelab-consumer/bin/basedpyright" \

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.2.0a6
+Version: 0.2.0a8
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
 License-Expression: Apache-2.0
@@ -20,9 +20,9 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: httpx2>=2.13.1
+Requires-Dist: httpx2>=2.16.0
 Requires-Dist: jsonschema>=4.26.0
-Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic>=2.14.1
 Requires-Dist: typing-extensions>=4.16.0
 Description-Content-Type: text/markdown
 

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v2026.10.3",
-    "commit": "c668cff75b7fcedbee048a8f1c8792162bf4eb77"
+    "tag": "v2026.10.4",
+    "commit": "c422f4f7425ade81eb5a65d9448ca4ea8bcacc79"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "757017be241f1014f3b5966c2a0f89a4ef578a700ebd626c51d02a8ff92a6b2a"
+    "sha256": "1bc28a61647b7b8f38b86c8ea0085415616857f967c997031794a88deb2e377c"
   }
 }

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: "2026.10.3"
+  version: "2026.10.4"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -13,7 +13,7 @@ info:
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: b70f590571b860f043365c9f2d6f95818d595862
+    commit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
     verificationRuntime:
       baseUrl: http://127.0.0.1:18080/api
       container: matelab-test-server-1
@@ -56,9 +56,9 @@ info:
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: b70f590571b860f043365c9f2d6f95818d595862
-    previousReleaseEvidenceCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
-    lastProviderVerifiedCommit: b70f590571b860f043365c9f2d6f95818d595862
+    currentCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
+    previousReleaseEvidenceCommit: b70f590571b860f043365c9f2d6f95818d595862
+    lastProviderVerifiedCommit: 161c4560ae1cb6267d46841d6fe8adc8270ee1bc
     contractStatus: current-provider-aligned
     # Summary of changes adopted by current Supported Routes since the last
     # released contract, including contract corrections. The Provider diff is
@@ -66,29 +66,8 @@ info:
     # updates against that fixed release baseline; use [] if no relevant changes.
     # Entries are not per-change verification results or a cumulative history.
     incorporatedChanges:
-      - {operationId: stageTemporaryFile, change: byte-offset-continuation-and-45-character-session-limit}
-      - {operationId: stageTemporaryFile, change: abort-only-cleans-incomplete-bytes-and-workerman-errors-have-no-resume-anchor}
-      - {operationId: uploadRecordAttachment, change: single-fragment-hash-failure-rollback}
-      - {operationId: searchUsers, change: utf8-byte-minimum-without-a-keyword-length-cap-or-whitespace-filter}
-      - {operationId: listNotebookRecords, change: owner-id-or-email-selector-and-caller-defaults}
-      - {operationId: createBlankRecord, change: owner-id-or-email-selector-and-php-zero-title-rejection}
-      - {operationId: importRecordDataset, change: owner-and-template-owner-selectors-json-list-data-and-php-zero-string-rejection}
-      - {operationId: updateRecordData, change: owner-selector-numeric-extraction-selectors-and-module-specific-field-validation}
-      - {operationId: deleteRecordsByUid, change: owner-id-or-email-selector-and-caller-defaults}
-      - {operationId: saveNotebookMetadata, change: numeric-string-and-number-extraction-selectors}
-      - {operationId: searchRecordData, change: numeric-string-and-number-extraction-selectors}
-      - {operationId: addNotebookShare, change: provider-deduplicated-recipient-lists}
-      - {operationId: shareMultipleTemplatesWithUsers, change: list-limits-apply-after-provider-deduplication}
-      - {operationId: listLiteratureItems, change: duplicate-source-rating-and-keyword-filters-are-accepted}
-      - {operationId: shareLiteratureItems, change: provider-deduplicated-ids-and-optional-empty-recipient-list}
-      - {operationId: moveCloudDriveFiles, change: provider-deduplicated-file-ids}
-      - {operationId: deleteCloudDriveFiles, change: provider-deduplicated-file-ids}
-      - {operationId: listDeletedRecordPage, change: unpaged-zero-page-size-omits-count-and-page}
-      - {operationId: extractLiteratureMetadata, change: nonempty-doi-takes-precedence-over-staged-file-id}
-      - {operationId: saveTemplateContent, change: php-name-validation-and-json-body-checks-apply-only-on-write}
-      - {operationId: listTemplates, change: stored-keywords-accept-nonnull-json-values}
-      - {operationId: readTemplateContent, change: stored-module-names-and-language-are-returned-without-template-write-validation}
-      - {operationId: readRecord, change: record-update-names-and-stored-module-language-use-raw-response-types}
+      - {operationId: stageTemporaryFile, change: filename-extension-selects-continuation-bytes-and-abort-cleans-incomplete-extension-variants}
+      - {operationId: uploadRecordAttachment, change: temporary-bytes-retain-sanitized-source-extension}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -109,7 +88,7 @@ info:
         identity must come from token issuance. ELN-group and notebook-list
         calls still provide Consumer evidence for their canonical GET forms.
     - repository: /home/tnzhu/projects/matelab-front
-      commit: c6a2fef86ef215256556d340b964f56dded7d3ce
+      commit: 89332767c2f20de210baed1e1e42df56e7071ad6
       files:
         - src/App.vue
         - src/fn/index.js
@@ -1993,7 +1972,10 @@ paths:
         contracted abort, status, expiration, or idempotent retry. A hash
         mismatch in this one-fragment flow rolls back the temporary row and
         new bytes. Errors after import/update writing starts still do not prove
-        whether the stage was consumed. Raw identifiers identify the staging row;
+        whether the stage was consumed. Temporary bytes retain the multipart
+        filename's extension after removing non-ASCII-alphanumeric characters;
+        the response still reports the original source filename.
+        Raw identifiers identify the staging row;
         their filesystem components are sanitized and can alias (PVD-051).
       x-known-provider-issues: [PVD-014, PVD-051]
       security: [{bearerAuth: []}]
@@ -3703,11 +3685,18 @@ paths:
         successful response's `offset`. Omitting it defaults to zero and
         restarts incomplete bytes rather than appending. The final fragment
         returns the combined SHA-256, size, source filename, temporary row id,
-        and legacy preview query.
+        and legacy preview query. The multipart filename's final extension,
+        stripped of characters outside `[A-Za-z0-9]` with case preserved,
+        also selects the temporary bytes. Repeat that extension on every
+        fragment; changing it cannot continue the previous bytes and returns
+        code 2 when the requested offset has no matching file. A different
+        filename stem with the same sanitized extension can continue them.
 
         `abort=1` is the compensating cleanup operation. It requires the same
-        `uid` and `tempid`, omits `file`, and removes incomplete bytes only.
-        It preserves an already completed staging row and its bytes. Both
+        `uid` and `tempid` and omits `file`. If no completed row exists for
+        those identifiers, it removes incomplete bytes for all extension
+        variants, including the extensionless file. If a completed row exists,
+        it preserves the row and bytes without cleaning any variants. Both
         states return the standard HTTP 200 code-2 error envelope ("upload
         cancelled"); that response does not prove completed staging was deleted.
         Complete uploads must be consumed by their intended finalizer; this
@@ -7450,7 +7439,10 @@ components:
         file:
           type: string
           format: binary
-          description: Required for upload branches and omitted for abort.
+          description: |
+            Required for upload branches and omitted for abort. The multipart
+            filename's sanitized final extension selects the temporary bytes;
+            keep that extension unchanged throughout continuation.
       allOf:
         - if:
             required: [abort]

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/docs/api.md

@@ -5,15 +5,15 @@ See the [README](../README.md) for installation and quick start and [CONTEXT.md]
 
 ## Contract
 
-The SDK is pinned to the immutable `matelab-spec v2026.10.3` Contract Release. The sole pin,
+The SDK is pinned to the immutable `matelab-spec v2026.10.4` Contract Release. The sole pin,
 [contracts/matelab-integration-v1.lock.json](../contracts/matelab-integration-v1.lock.json), records peeled commit
-`c668cff75b7fcedbee048a8f1c8792162bf4eb77`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
-and SHA-256 `757017be241f1014f3b5966c2a0f89a4ef578a700ebd626c51d02a8ff92a6b2a`. The annotated tag object is
-`b1d3ff039c576032f69ec7116347af1ba441ba5f`.
+`c422f4f7425ade81eb5a65d9448ca4ea8bcacc79`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
+and SHA-256 `1bc28a61647b7b8f38b86c8ea0085415616857f967c997031794a88deb2e377c`. The annotated tag object is
+`72c52e2267598f9bde820f629bc62d5982f7081c`.
 
-The Contract uses Provider source evidence from `b70f590571b860f043365c9f2d6f95818d595862`; v2026.10.3 validation ran
+The Contract uses Provider source evidence from `161c4560ae1cb6267d46841d6fe8adc8270ee1bc`; v2026.10.4 validation ran
 against an isolated test instance and does not establish production behavior. The Front Consumer evidence
-`c6a2fef86ef215256556d340b964f56dded7d3ce` informs cross-Consumer capability review but does not define the SDK interface.
+`89332767c2f20de210baed1e1e42df56e7071ad6` informs cross-Consumer capability review but does not define the SDK interface.
 
 This snapshot covers the Workerman runtime with the `localhost` data-server branch for ELN records and attachments;
 remote data-server forwarding is outside its verified callable scope (PVD-049).
@@ -198,7 +198,8 @@ objects are outside the interface and are also rejected at runtime before a Prov
 checksum, or multipart content type. The SDK calculates the SHA-256 itself; streams are fully consumed into a
 `SpooledTemporaryFile`, rewound, and only then sent to the Provider. Temporary-file write, seek, read, and close
 operations run outside the event-loop thread, including after the spool rolls to disk. The Contract fixes attachment
-parts to `application/octet-stream`.
+parts to `application/octet-stream`. Temporary record-attachment bytes retain the source filename's final extension,
+stripped to ASCII letters and digits with case preserved; the response retains the original source filename.
 
 An exception raised by an async source is propagated unchanged after the SDK closes its temporary file. The SDK reads
 streams through end-of-file and imposes no upload-size policy; callers remain responsible for limits such as an HTTP
@@ -692,19 +693,25 @@ assert isinstance(staged, StagedFile)
 The SDK derives `fragment_size` and computes the complete SHA-256 for a single `bytes` fragment. File-like content
 must declare its fragment size. For multiple fragments, pass the returned `StagedUploadSession` into the next call and
 supply `complete_sha256` on the final call. `next_offset` is the Provider-acknowledged byte offset, checked against the
-declared fragment size and sent with the next fragment. The SDK verifies the returned filename and total size, and
-compares hashes when a local expected hash is available. A final result contains the Provider hash, temporary row
+declared fragment size and sent with the next fragment. Repeat the filename's final extension across fragments:
+the Provider removes characters outside `[A-Za-z0-9]` and preserves case, so `paper.P-d_f` and `renamed.Pdf` select
+the same bytes. Changing that sanitized extension cannot resume the upload and returns code 2 when no matching
+file exists at the requested offset. The SDK sends each filename unchanged, checks the returned filename and total
+size, and compares hashes when a local expected hash is available. A final result contains the Provider hash, temporary row
 identity and direct `binding`; it no longer embeds resumable session state. The temporary Provider URL and upload-session
 identity needed by internal binding and cleanup remain hidden. Callers do not need to
 splice either into content. The result does not claim that a later literature/cloud operation checks the uploader or
 consumes the file exactly once. `uploads.abort()` accepts either an active `StagedUploadSession` or a completed
-`StagedFile` and returns `None` for the Provider's code-2 cancellation signal. It removes incomplete bytes only;
-completed staging rows and bytes remain and must be consumed by their intended finalizer (PVD-052).
+`StagedFile` and returns `None` for the Provider's code-2 cancellation signal. Without a completed staging row, it
+removes all incomplete extension variants, including extensionless bytes. A completed row prevents any cleanup for
+that identity; completed staging must be consumed by its intended finalizer (PVD-052).
 Binding UIDs allow up to 100 characters; upload-session IDs allow up to 45 (PVD-024). Use fresh identities: different
 raw identifiers can alias after Provider filename sanitization (PVD-051). Workerman upload errors supply no usable
 resume offset (PVD-050). After a failed non-final fragment, cancel incomplete bytes and restart with fresh identities.
 An ambiguous final response can leave completed staging that `abort()` cannot delete.
 Staging mutations are never automatically retried.
+After upgrading from the previous Provider's extensionless storage, restart old incomplete uploads from offset zero
+or cancel them and use fresh session identities.
 
 Literature identities distinguish the personal library from shared libraries:
 

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v2026.10.3
+  release: v2026.10.4
   operation_count: 71
 
 operations:

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling>=1.32.4"]
+requires = ["hatchling>=1.33.0"]
 build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.2.0a6"
+version = "0.2.0a8"
 description = "Reusable async Python client for the Matelab Integration Contract"
 requires-python = ">=3.11"
 keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]
@@ -12,9 +12,9 @@ authors = [
     { name = "CMPDC, Institute of Physics, Chinese Academy of Sciences" },
 ]
 dependencies = [
-    "httpx2>=2.13.1",
+    "httpx2>=2.16.0",
     "jsonschema>=4.26.0",
-    "pydantic>=2.13.5",
+    "pydantic>=2.14.1",
     "typing-extensions>=4.16.0",
 ]
 readme = "README.md"
@@ -37,14 +37,14 @@ classifiers = [
 
 [dependency-groups]
 dev = [
-    "basedpyright>=1.40.1",
+    "basedpyright>=1.40.2",
     "nodejs-wheel-binaries==22.20.0",
-    "datamodel-code-generator>=0.83.0",
-    "hatchling>=1.32.4",
-    "pytest>=9.1.1",
-    "pytest-asyncio>=1.4.0",
+    "datamodel-code-generator>=0.87.0",
+    "hatchling>=1.33.0",
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1",
     "pyyaml>=6.0.3",
-    "ruff>=0.16.10",
+    "ruff>=0.17.3",
 ]
 
 [tool.ruff]
@@ -65,6 +65,7 @@ reportIncompatibleUnannotatedOverride = "error"
 markers = [
     "provider: opt-in smoke tests against an explicitly acknowledged real Provider target",
 ]
+asyncio_default_fixture_loop_scope = "function"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/matelab"]

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/src/matelab/_generated/models.py

@@ -2,7 +2,7 @@
 #
 # @generated by datamodel-codegen:
 #   filename:  openapi.yaml
-#   version:   0.83.0
+#   version:   0.87.0
 
 from enum import StrEnum
 from typing import Annotated, Any, Literal
@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "2026.10.3"
+OPENAPI_INFO_VERSION = "2026.10.4"
 
 
 class ResponseEnvelope(WireModel):
@@ -2759,7 +2759,10 @@ class StageTemporaryFileRequest(WireModel):
     """
     file: bytes | None = None
     """
-    Required for upload branches and omitted for abort.
+    Required for upload branches and omitted for abort. The multipart
+    filename's sanitized final extension selects the temporary bytes;
+    keep that extension unchanged throughout continuation.
+
     """
 
 

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/src/matelab/domains/uploads.py

@@ -79,6 +79,7 @@ class Uploads:
         complete_sha256: str | None = None,
         content_type: str = "application/octet-stream",
     ) -> StagedUploadSession | StagedFile:
+        """Stage bytes; preserve the sanitized, case-sensitive filename extension when resuming."""
         if session is None:
             session = StagedUploadSession(
                 binding=UploadBindingRef.new(), upload_session_id=f"tmp-{secrets.token_urlsafe(24)}"
@@ -162,7 +163,7 @@ class Uploads:
         )
 
     async def abort(self, upload: StagedUploadSession | StagedFile) -> None:
-        """Cancel incomplete bytes; completed files remain staged (PVD-052)."""
+        """Cancel incomplete extension variants; completed staging identities remain untouched (PVD-052)."""
         if isinstance(upload, StagedFile):
             # The completed file keeps this Provider identity private except for same-module cleanup.
             upload_session_id = upload._upload_session_id  # pyright: ignore[reportPrivateUsage]

{matelab_python_sdk-0.2.0a6 → matelab_python_sdk-0.2.0a8}/tests/test_uploads_and_literature.py

@@ -208,8 +208,14 @@ async def test_stage_single_bytes_creates_session_and_computes_hash(
 
 
 @pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("first_filename", "final_filename"), [("paper.pdf", "paper.pdf"), ("paper.P-d_f", "renamed.Pdf")]
+)
 async def test_stage_fragments_sends_acknowledged_offset_and_maps_completion_and_abort(
-    provider_session: Session, provider_envelope: Callable[..., dict[str, object]]
+    provider_session: Session,
+    provider_envelope: Callable[..., dict[str, object]],
+    first_filename: str,
+    final_filename: str,
 ) -> None:
     upload_session = StagedUploadSession(
         binding=UploadBindingRef(uid="lit-binding-123"), upload_session_id="lit-session-123"
@@ -225,11 +231,13 @@ async def test_stage_fragments_sends_acknowledged_offset_and_maps_completion_and
         assert _multipart_value(request, "uid") == "lit-binding-123"
         assert _multipart_value(request, "tempid") == "lit-session-123"
         if request_count == 1:
+            assert f'filename="{first_filename}"'.encode() in request.content
             assert _multipart_value(request, "offset") == "0"
             assert _multipart_value(request, "last") == "0"
             assert _multipart_value(request, "file") == _CHUNK_1.decode()
             return Response(200, json=provider_envelope(hash=_HASH_1, tempid="lit-session-123", offset=len(_CHUNK_1)))
         if request_count == 2:
+            assert f'filename="{final_filename}"'.encode() in request.content
             assert _multipart_value(request, "offset") == str(len(_CHUNK_1))
             assert _multipart_value(request, "last") == "1"
             assert _multipart_value(request, "hash") == _HASH_FULL
@@ -239,9 +247,9 @@ async def test_stage_fragments_sends_acknowledged_offset_and_maps_completion_and
                 json=provider_envelope(
                     id=412,
                     path="url_eln/temp",
-                    query=f"h={_HASH_FULL}&id=412&s={len(_FULL_CONTENT)}&f=paper.pdf",
+                    query=f"h={_HASH_FULL}&id=412&s={len(_FULL_CONTENT)}&f={final_filename}",
                     name="lit-session-123",
-                    filename="paper.pdf",
+                    filename=final_filename,
                     size=len(_FULL_CONTENT),
                     hash=_HASH_FULL,
                     future_field=True,
@@ -254,12 +262,12 @@ async def test_stage_fragments_sends_acknowledged_offset_and_maps_completion_and
     async with AsyncClient(base_url="https://matelab.example/api", transport=MockTransport(handler)) as http_client:
         client = AsyncMatelab("https://ignored.example", session=provider_session, http_client=http_client)
         progress = await client.uploads.stage(
-            _CHUNK_1, filename="paper.pdf", fragment_size=len(_CHUNK_1), session=upload_session, final=False
+            _CHUNK_1, filename=first_filename, fragment_size=len(_CHUNK_1), session=upload_session, final=False
         )
         assert isinstance(progress, StagedUploadSession)
         completed = await client.uploads.stage(
             _CHUNK_2,
-            filename="paper.pdf",
+            filename=final_filename,
             fragment_size=len(_CHUNK_2),
             session=progress,
             final=True,