matelab-python-sdk 0.1.0a1__py3-none-any.whl

matelab_python_sdk-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,538 @@
+Metadata-Version: 2.4
+Name: matelab-python-sdk
+Version: 0.1.0a1
+Summary: Reusable async Python client for the Matelab Integration Contract
+Author-email: 朱天念 <zhutiannian@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27.2
+Requires-Dist: pydantic<3,>=2.12.5
+Description-Content-Type: text/markdown
+
+# matelab-python-sdk
+
+Reusable async Python client for the Matelab Integration Contract.
+
+The current alpha is `0.1.0a1`. `[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.1.0` Contract Release. The sole release pin is
+`contracts/matelab-integration-v1.lock.json`, which records
+the source tag, commit, OpenAPI path, local snapshot path, and SHA-256.
+
+## Installation
+
+Python 3.11 or newer is required. Install the alpha from a package index with either:
+
+```bash
+uv add matelab-python-sdk
+```
+
+```bash
+python -m pip install matelab-python-sdk
+```
+
+Development installs use the locked checkout:
+
+```bash
+uv sync --frozen
+```
+
+To test the same artifact a downstream Consumer will install, build and install the wheel:
+
+```bash
+uv build --no-build-isolation --out-dir dist/release
+python -m pip install dist/release/matelab_python_sdk-0.1.0a1-py3-none-any.whl
+```
+
+Do not infer Provider compatibility from the SDK version alone. A release is also bound to the Contract
+tag, commit, and checksum recorded below.
+
+## Design
+
+The public module is intentionally small:
+
+```python
+from matelab import AsyncMatelab
+
+async with AsyncMatelab() as client:
+    session = await client.authenticate("user@example.org", "password")
+    assert client.session is session
+    notebooks = await client.notebooks.list()
+    notebook = notebooks.owned[0].ref
+    records = await client.records.list(notebook=notebook)
+    record = await client.records.read(notebook=notebook, record=records.records[0].ref)
+```
+
+`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another Provider API root
+explicitly when needed, for example `AsyncMatelab("https://custom.example/api")`.
+
+### Session ownership
+
+Each `AsyncMatelab` instance owns at most one current, process-local `Session`. The SDK injects its bearer
+token, refreshes it under a per-instance async lock, performs bounded safe retries, and exposes every token
+rotation through `client.session`. If refresh succeeds but the subsequent business request fails,
+`client.session` still contains the refreshed token pair.
+
+| SDK responsibility | Integrator responsibility |
+|---|---|
+| Bearer injection, expiry checks, refresh and bounded retry | Redis/database/file persistence and encryption |
+| Per-instance, in-process refresh serialization | Cross-process locking and conflict handling |
+| Contract validation of token and identity responses | Mapping `userid`/`session_id` to a persisted `Session` |
+| Latest immutable `Session` through `client.session` | Revocation, cleanup, and saving after each call |
+
+`Session`, `Token`, and `Identity` are immutable value objects, and token values are excluded from their
+representations. The SDK does not read tokens from environment variables and does not provide a session store.
+
+Credential authentication installs the returned Session on the client:
+
+```python
+async with AsyncMatelab() as client:
+    session = await client.authenticate(username, password)
+    assert client.session is session
+```
+
+External token exchange validates the original access-token identity, refreshes the supplied refresh token,
+validates the refreshed access-token identity, and rejects a userid mismatch. The existing client Session is
+replaced only after all three steps succeed:
+
+```python
+async with AsyncMatelab() as client:
+    session = await client.bind_external_tokens(access_token, refresh_token)
+    assert client.session is session
+```
+
+Restore a previously validated Session by passing it to the constructor. Construction performs no network request:
+
+```python
+persisted_session = await session_store.load(userid, session_id)
+
+async with AsyncMatelab(session=persisted_session) as client:
+    result = await handle_request(client)
+```
+
+A Web or MCP integration should create one client for one logical session, then save the latest Session in
+`finally`, including when a business call fails after refresh:
+
+```python
+persisted_session = await session_store.load(userid, session_id)
+client = AsyncMatelab(session=persisted_session, http_client=shared_http_client)
+
+try:
+    result = await handle_request(client)
+finally:
+    latest_session = client.session
+    try:
+        if latest_session is not None:
+            await session_store.save(userid, session_id, latest_session)
+    finally:
+        await client.aclose()
+```
+
+If several processes can use the same persisted session, the integration must place its own distributed lock
+around load, use, and save. The SDK lock only coordinates refreshes inside one `AsyncMatelab` instance.
+
+Different logical sessions require different clients. They may reuse the same externally managed HTTP connection
+pool, but must never share one global `AsyncMatelab` singleton:
+
+```python
+alice_client = AsyncMatelab(session=alice_session, http_client=shared_http_client)
+bob_client = AsyncMatelab(session=bob_session, http_client=shared_http_client)
+```
+
+`src/matelab/_generated` is a private wire layer. Applications should not depend on its file
+layout or generated class names. The distribution includes `py.typed`, so type checkers can consume the
+public annotations directly from an installed wheel.
+
+The current public domain scope includes authentication, group/user discovery, template and notebook
+lifecycle operations, record discovery/lifecycle operations, comment reads, and streaming record or
+comment attachment downloads, resumable file staging, literature discovery/lifecycle workflows, and
+personal cloud-drive management.
+
+## Implementation roadmap
+
+`docs/roadmap.md` is the complete SDK-only execution plan. It assigns all 71
+`matelab-spec v0.1.0` operations to ordered work packages, defines the machine-readable coverage that
+must be added, records Provider-risk gates, and specifies the final completion checks.
+
+The SDK exposes all 71 Contract operations through public domain interfaces. It deliberately excludes MCP
+migration, adjacent-repository changes, external
+publishing, and automatic mutation against a real Provider.
+
+Machine-readable status lives in
+`docs/operation-coverage.yaml`. An exact-coverage test keeps its 71
+operation IDs, methods, paths, work packages, and Provider issue references aligned with the pinned
+OpenAPI snapshot.
+
+| Domain | Implemented | Planned | Current public surface |
+|---|---:|---:|---|
+| Authentication | 4 | 0 | `authenticate`, `bind_external_tokens`, `refresh`, `resolve_identity`, `exchange_chat_sso_code` |
+| Groups and users | 2 | 0 | `groups.list`, `users.search` |
+| Notebooks | 6 | 0 | `notebooks.list/create/update/shares/share/update_share/unshare` |
+| Records | 18 | 0 | Discovery, reads, lifecycle, typed patch/attachments, relations, and downloads |
+| Comments | 5 | 0 | Read, staged attachment upload, create/update/delete, and download |
+| Templates | 13 | 0 | Discovery, content, lifecycle, sharing, groups, and marketplace |
+| File staging | 1 | 0 | Resumable fragment staging and compensating abort request |
+| Literature | 13 | 0 | Libraries, items, canonical metadata, comments, sharing, PDF lifecycle and streaming |
+| Cloud drive | 9 | 0 | Personal root/folders/files, staged binding, metadata, move/delete and streaming |
+| **Total** | **71** | **0** | No operation is intentionally unexposed |
+
+### Stability and known capability limits
+
+Coverage currently contains 15 `stable` and 56 `experimental` operations. The stable operation IDs are
+`resolveCurrentIdentity`, `loginTokenSet`, `refreshTokenSet`, `exchangeChatSsoCode`,
+`shareMultipleTemplatesWithUsers`, `removeTemplateFromGroup`, `deleteNotebookShare`, `listNotebooks`,
+`listNotebookRecords`, `exportRecords`, `deleteRecordsByUid`, `copyRecord`, `readRecord`,
+`deletePersonalLiteratureItem`, and `readLiteratureCreateTemplate`.
+
+Every other implemented operation is explicitly `experimental`; the exact per-operation list and its
+PVD/PCG references live in
+`docs/operation-coverage.yaml`. There are no `intentionally_unexposed`
+operations and no `planned` operations. Experimental support means the SDK validates and exposes the
+pinned Contract while preserving limitations such as unstable ordering/pagination, incomplete mutation
+acknowledgements, missing batch atomicity or idempotency, weak attachment ownership binding, and known
+Provider authorization gaps. It does not turn those limitations into SDK guarantees.
+
+Chat iframe SSO consumes a one-time code and shared key. Both arguments are treated as secrets, the request is never
+automatically retried, and the returned token set is stored in the same in-memory `Session` shape as credential login:
+
+```python
+session = await client.exchange_chat_sso_code(code="chat-sanitizedcode123", key="sanitized-shared-key")
+```
+
+Group and user discovery expose sharing identities without inventing Provider pagination:
+
+```python
+from matelab import UserSearchScope
+
+groups = await client.groups.list()
+targets = await client.users.search("Example Researcher", scope=UserSearchScope.SAME_INSTITUTE)
+```
+
+Both results explicitly report `provider_unspecified` ordering. Group members belong only to
+`groups.members_for`, not to every returned group. These two discovery interfaces are experimental because the
+Provider returns members for an unstable first group and user search is unpaged, unordered, and not field-minimized
+(PVD-006, PVD-029, PCG-011).
+
+Notebook create/update and direct sharing keep write acknowledgement separate from what a readback can prove:
+
+```python
+from matelab import NotebookMetadata, NotebookSharePermissionGrant
+
+created = await client.notebooks.create(NotebookMetadata(title="Example Notebook"))
+shares = await client.notebooks.share(notebook, [target.ref])
+updated = await client.notebooks.update_share(
+    shares.visible_after_write[0].ref, NotebookSharePermissionGrant(write=True, create=True)
+)
+```
+
+Create cannot return a notebook ref because the Provider returns no identity. Owned updates are read back by database
+ID and report matching, mismatched, or missing observations, containing PVD-003 false success without claiming an
+atomic guarantee. Share results similarly report post-write visibility rather than invented affected rows. A stored
+share mask of zero still has effective read access (PVD-010), and share-list order remains unspecified.
+
+Template discovery keeps a template database identity separate from direct-share, market-acquisition, and group
+relation identities:
+
+```python
+templates = await client.templates.list()
+market = await client.templates.search_market("calibration", page=1, page_size=20)
+content = await client.templates.read(templates.owned[0].ref)
+```
+
+The market result reports the Provider `total_count`, the requested and effective page sizes, and a `has_more`
+value explicitly marked as `derived_from_total`; it does not claim a stable order or continuation token. Canonical
+modules are mapped to public `TemplateModule` values and retain additive module attributes. Template reads remain
+experimental because Provider discovery ordering/pagination and historical `images` compatibility are not fully
+stable (PCG-003, PCG-009, PVD-013, PVD-022).
+
+Template writes remain separate operations: metadata, canonical modules, and usage HTML are not presented as one
+transaction. Metadata create returns the Provider template ID; copy explicitly returns no new identity because the
+Provider supplies none. Direct-share, market-acquisition, and group relation refs are distinct and are required by
+their matching removal methods. Mutation results report readback observations without inventing affected rows.
+Metadata and intro results explicitly report that they do not advance the marketplace revision (PVD-021).
+`UploadBindingRef.new()` creates the fresh hidden correlation value required by intro attachment binding, while the
+result still records that the Provider does not verify the uploader (PVD-026).
+
+Extended record reads stay behind the same `records` interface:
+
+```python
+from matelab import RecordFieldExtraction, RecordLocator
+
+exported = await client.records.export([RecordLocator(notebook=notebook, record=record)])
+matches = await client.records.search(
+    notebooks=[notebook], extractions=[RecordFieldExtraction(alias="notes", path=("Notes",))]
+)
+page = await client.records.page(notebook)
+deleted = await client.records.recycle_bin(notebook)
+relations = await client.records.relations(notebook=notebook, record=record)
+```
+
+`records.page` fixes the legacy request to `page_size=0&default=1`, preventing the known owner-preference writes
+described by PVD-039; its total is derived from the Provider's complete matching ID list. Public catalog records and
+deleted records use identities distinct from active `RecordRef`. Relation targets separately expose declared and
+resolved notebook IDs because the Provider may return dangling or incomplete identities. Search and relation order
+remain unspecified, and no continuation token is invented.
+
+Record creation keeps blank creation and structured import as separate capabilities:
+
+```python
+from matelab import RecordImportItem, RecordImportTemplate, TemplateRef
+
+blank = await client.records.create_blank(notebook=notebook, title="Blank Record", record_uid="caller-generated-uid")
+imported = await client.records.import_dataset(
+    notebook=notebook,
+    template=RecordImportTemplate(template=TemplateRef(template_id=8), title="Example Template"),
+    items=[RecordImportItem(record_uid="import-uid", title="Imported", data={"Notes": "value"})],
+)
+```
+
+A caller-supplied blank-record UID is read back; when the Provider generates it, the result explicitly has no
+invented identity. Import validates the complete batch with generated wire models but cannot map returned database
+IDs to individual inputs or promise atomicity (PCG-008). Delete means moving records into the recycle bin, not
+permanent deletion. Delete and restore results classify only post-write observations; restore never treats an active
+row with the same UID but a different database ID as proof of success (PCG-005). Record mutations are not
+automatically retried.
+
+Record patching exposes a deliberately narrower capability than the raw Provider operation. Scalar/module changes
+cannot smuggle Provider-native attachment strings; staged attachments use separate form-removal, table-replacement,
+files append/replace/remove, and rich-text types. Unsafe form replacement and table-file removal are absent, while a
+files/images removal is rejected when the observed module contains the same hash more than once (PVD-014 through
+PVD-016). `Record.content_sha256` can be supplied as a client-side precondition, but results explicitly label it as
+advisory read-before-write rather than Provider CAS. Database, active-browser, and unclassified acknowledgements
+remain distinct, and mutation retries stay disabled.
+
+Relation addition reads both endpoints and checks their resolved data server before writing; this reduces PVD-019
+risk but is not an atomic Provider authorization guarantee. Relation deletion refuses an observed cross-notebook
+target-ID collision because the Provider ignores target notebook identity (PVD-020), then reports readback and any
+other relation that disappeared without inventing an affected-row count.
+
+Comment upload follows the Provider's literal one-request `upload` field, not the incompatible Front fragment
+protocol (PVD-037). Comment creation derives an ID only from a unique post-write observation. Edit and delete require
+a currently observed caller-owned comment and read it back, containing the Provider's edit false-success behavior
+(PVD-004). Staged comment attachments have no Contract abort operation, and binding remains affected by PVD-026.
+
+Attachment bytes are streamed and must be consumed or closed explicitly:
+
+```python
+from matelab import ByteRange
+
+comments = await client.records.comments(notebook=notebook, record=record)
+attachment = comments.comments[0].attachments[0]
+async with await client.records.download_comment_attachment(attachment, byte_range=ByteRange.from_start(0)) as download:
+    async for chunk in download:
+        consume(chunk)
+```
+
+`DownloadStream` exposes status, content type, length, range, and disposition metadata without buffering the
+complete file. Streams are not automatically replayed. `ByteRange` deliberately rejects `bytes=0-0` (PVD-002).
+Comment attachment refs preserve the notebook/record/comment context where they were observed, but they are not
+Provider authorization credentials: current Providers do not verify that association (PVD-038).
+
+Cross-domain staging keeps resumable state and completed-file identity separate:
+
+```python
+import hashlib
+
+from matelab import StagedFile
+
+pdf_bytes = b"sanitized PDF bytes"
+staged = await client.uploads.stage(
+    pdf_bytes,
+    filename="example.pdf",
+    fragment_size=len(pdf_bytes),
+    complete_sha256=hashlib.sha256(pdf_bytes).hexdigest(),
+)
+assert isinstance(staged, StagedFile)
+```
+
+For multiple fragments, pass `StagedFileFragment.session` into the next call. `next_offset` is explicitly a
+caller-side total derived from declared fragment sizes; the Provider does not confirm an offset. A final result
+contains the Provider hash, size, temporary row identity and fresh hidden binding value, but does not claim that a
+later literature/cloud operation checks the uploader or consumes the file exactly once. `uploads.abort` exposes the
+Provider's legacy code-2 cancellation signal as compensating cleanup that is not independently verified (PVD-028).
+Staging mutations are never automatically retried.
+
+Literature identities distinguish the personal library, shared libraries and pending incoming copies:
+
+```python
+from matelab import DoiMetadataSource, LiteratureMetadata
+
+libraries = await client.literature.libraries()
+page = await client.literature.list(libraries.personal.ref)
+detail = await client.literature.read(page.items[0].ref)
+schema = await client.literature.creation_schema()
+
+if schema.metadata_extraction_available:
+    candidates = await client.literature.extract_metadata(DoiMetadataSource("10.0000/example"))
+
+created = await client.literature.create(
+    LiteratureMetadata(title="Example import", doi="10.0000/example"), staged_pdf=staged
+)
+assert created.created_item is None
+```
+
+Create never guesses the new item from list position because the Provider returns no ID. Canonical update reads the
+item first and refuses to drop source/hidden fields unless `allow_source_metadata_loss=True` is explicit (PVD-027).
+PDF replace/delete are separate, read-back-verified mutations and are not presented as atomic with metadata
+(PCG-010). Permanent personal deletion is named `permanently_delete`, reports snapshot verification, and is marked
+non-recoverable. Sharing requires list-observed item summaries, user-search summaries and a resolved caller identity;
+its result deliberately contains no invented per-recipient IDs or batch atomicity (PVD-012, PVD-036).
+
+Literature comments use one public save intent: detail is read first, an existing caller-owned comment is edited, and
+otherwise a comment is created. Multiple caller-owned comments are rejected as ambiguous (PVD-035). A staged
+attachment can replace one `matelab-staged-file` marker; raw temporary URLs are rejected. These checks contain common
+misuse but do not repair the Provider's cross-user UID lookup (PVD-026). Shared-library reads and writes remain
+experimental because the Provider permission JOIN is not scoped to the current user (PVD-011); successful SDK calls
+must not be treated as independent authorization proof. Literature PDF downloads reuse `DownloadStream` and the
+stable `ByteRange` subset.
+
+The personal cloud-drive surface keeps root, folder, final file and temporary staging identities separate:
+
+```python
+from matelab import CloudFolderMetadata
+
+listing = await client.cloud_drive.list()
+folder_result = await client.cloud_drive.create_folder(CloudFolderMetadata(name="Example data"))
+bound = await client.cloud_drive.bind_staged_file(staged, target=folder_result.folder)
+
+if bound.observed is not None:
+    renamed = await client.cloud_drive.update_file(
+        bound.observed, filename="example-renamed.pdf", description="Sanitized description"
+    )
+```
+
+`CloudDriveListing` contains a typed file page, complete folder tree, quota usage and personal-root permissions rather
+than flattening them into one ambiguous collection. Folder browse results retain their location; filename searches
+are explicitly root-wide and return `location=None` because the Provider omits each match's folder ID. Ordering has
+no stable ID tie-breaker (PCG-003, PVD-013).
+
+Folder create returns the Provider ID and all folder mutations read back the complete tree. Staged finalize accepts a
+completed `StagedFile`, then paginates the target folder and returns a final `CloudFileRef` only for one exact
+filename/hash/size observation. This is useful evidence, not an uploader-ownership guarantee: the Provider binds by
+temporary row ID without checking its owner (PVD-031), and finalize atomicity/idempotency remain absent (PCG-012).
+Batch move and permanent delete keep Provider item results as `None`, report only post-write observations and do not
+claim atomicity. Permanent deletion is named `permanently_delete_files` and marked non-recoverable. Cloud downloads
+resolve bytes from the final file identity and reuse `DownloadStream`, thumbnail/preview choices and the PVD-002-safe
+range subset. Cloud mutations are not automatically retried.
+
+To run the implementation as a persistent Codex goal, start a task in this repository and use:
+
+> 完整阅读并严格遵循 `AGENTS.md`、`README.md` 和 `docs/roadmap.md`。创建并持续执行一个 goal：
+> 只修改当前仓库，按照 roadmap 从第一个未完成 work package 开始，完成 71-operation 精确覆盖和全部
+> SDK 领域 interface；每个 package 通过局部验证后自动继续，最终让 generation `--check`、Ruff、
+> Ruff format、Basedpyright、Pytest 和 package build 全部通过。不要修改相邻仓库，不执行生产 Provider
+> mutation，不 commit、push、tag 或发布。
+
+Owned/shared `NotebookRef`, public `PublicNotebookRef`, `RecordRef`, and `RecordVersionRef` keep
+Provider identifiers distinct. Historical reads first re-read the authorized current record and confirm
+that the requested version is still present in its `modify_log`; both reads write Provider audit entries.
+
+Errors are separated into Provider business errors, authentication errors, HTTP/transport errors,
+Integration Contract response errors, and client-side usage errors. Token values and sensitive response
+fields are redacted from error text and retained diagnostic payloads.
+
+## Development
+
+```bash
+uv sync
+uv run python scripts/generate_models.py
+uv run python scripts/generate_models.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pytest
+uv build
+```
+
+The generator first verifies the contract lock, OpenAPI release metadata, and snapshot digest. It then
+creates a temporary OpenAPI 3.1 generation projection, resolves references without network access, and
+generates private component, operation-response, and parameter models. The projection only flattens pure
+object inheritance that the generator cannot otherwise preserve correctly; the checked-in release
+snapshot remains unchanged. `--check` performs the same validation and deterministic generation without
+writing the checked-in models. The current lock resolves `datamodel-code-generator 0.71.0` and
+`hatchling 1.31.0`. Published metadata requires `httpx>=0.27.2,<1` and
+`pydantic>=2.12.5,<3`; the build backend requires `hatchling>=1.27,<2`. These lower bounds are verified
+against the complete test suite on the supported Python boundary versions rather than inferred from
+`uv.lock`. The exact toolchain remains locked for development and release builds. Basedpyright and its
+Node wheel retain the compatible exact pair `basedpyright==1.39.9` and
+`nodejs-wheel-binaries==22.20.0`.
+
+## Opt-in Provider consumer smoke
+
+`tests/provider/test_provider_smoke.py` exercises the consumer flow through only the public SDK interface:
+credential authentication, extraction of the returned token pair, exchange through a new
+`AsyncMatelab.bind_external_tokens` instance, userid consistency checks, owned/shared notebook discovery,
+record listing, and current-record reading. It is not Provider Verification and is skipped by default.
+
+Prefer an explicitly isolated Provider. A production target requires explicit authorization for the current run
+and a dedicated test fixture. Authentication and external-token refresh persist Provider token state, and
+`GET /eln_items/item_view` writes a Provider audit entry even though it is a read operation. The smoke therefore
+requires explicit target and write acknowledgements:
+
+```dotenv
+MATELAB_PROVIDER_SMOKE=1
+MATELAB_PROVIDER_SMOKE_ISOLATED=1
+MATELAB_PROVIDER_SMOKE_ALLOW_WRITES=1
+```
+
+For an explicitly authorized production test fixture, leave `MATELAB_PROVIDER_SMOKE_ISOLATED` empty and use:
+
+```dotenv
+MATELAB_PROVIDER_SMOKE_PRODUCTION_ACKNOWLEDGED=1
+```
+
+Fill the git-ignored local `.env.test` with exactly one target acknowledgement and the fixture:
+
+- `MATELAB_PROVIDER_SMOKE_BASE_URL`
+- `MATELAB_PROVIDER_SMOKE_USERNAME`
+- `MATELAB_PROVIDER_SMOKE_PASSWORD`
+- `MATELAB_PROVIDER_SMOKE_EXPECTED_USERID`
+- `MATELAB_PROVIDER_SMOKE_NOTEBOOK_ID`
+- `MATELAB_PROVIDER_SMOKE_RECORD_DATABASE_ID`
+- `MATELAB_PROVIDER_SMOKE_RECORD_UID`
+
+The userid and both record identifiers are checked before the record read so an ambiguous or incorrect
+fixture fails safely. With the environment prepared:
+
+```bash
+uv run --env-file .env.test pytest -m provider tests/provider/test_provider_smoke.py
+```
+
+The file is never loaded implicitly, so the normal test suite remains safely skipped. Never use production without
+explicit authorization for that run, and never commit its credentials.
+
+## Reproducible release build
+
+Build from a clean release commit (or its tag) and set the archive timestamp to that commit's
+committer timestamp. `pyproject.toml` declares the supported Hatchling range, while `uv.lock` supplies the
+exact version used by the frozen, no-build-isolation release environment:
+
+```bash
+export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
+uv sync --frozen
+uv run python scripts/generate_models.py --check
+uv build --no-build-isolation --out-dir dist/release
+uv run python scripts/check_release.py dist/release/*.whl dist/release/*.tar.gz
+(cd dist/release && sha256sum *.whl *.tar.gz > SHA256SUMS)
+```
+
+Rebuilding the same commit with the same locked environment and `SOURCE_DATE_EPOCH` must produce
+byte-identical wheel and source distribution hashes. The release is bound to `matelab-spec v0.1.0`,
+commit `236795db1aa7a784ad9df936e9547e8d529be53f`, and OpenAPI SHA-256
+`62ca07dcd7a0b3f80eb381a0d1447316f69faa751bafb8ab7c6a751e619d8164`.

matelab_python_sdk-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,22 @@
+matelab/__init__.py,sha256=3iX8xyk434Yh8j_tsinsgW1bnMwgrv_dqGQEIspSFf8,9741
+matelab/_transport.py,sha256=qMaioZcP5RfIxl5rr2FzY2Gn_zHAa-vJbjDNxapii-4,20223
+matelab/client.py,sha256=U54F-s8APVXppCjaMo-ALcQQCFM-VOzWoB_taeCdhXM,8168
+matelab/cloud_drive.py,sha256=NDVobVI-3MDRbbN_M6uRgM4apI6RUglk3ZAEdeaP90g,33306
+matelab/errors.py,sha256=7o5h5cjbGkUfpL-8W5hF9WaYJMlBH9xN8Uk2grSZwjg,1209
+matelab/groups.py,sha256=w0OgFtWwBcQqFUCvO_p52uIxKch-Soh3lFIgm0MNj94,2471
+matelab/literature.py,sha256=uMAXqDowj5JwSMed6b3koGHZBHF22GVqExO1kv2fmCY,51970
+matelab/models.py,sha256=AuIlyERpIVUYF2DgIhtC7LsmG4hLpHz28ae4hvyrEik,655
+matelab/notebooks.py,sha256=ykmpvziHGMtYt9vrMe97NSwcVTHsc4FRBStLNAhyDvc,19154
+matelab/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+matelab/records.py,sha256=9HiFdu9c8VqlbgSYhayOOXxZBSZeOMMHbkNm0a0-Xd4,107223
+matelab/streaming.py,sha256=KcRx8QiBpaH198OY3YKdIFyx3bAikNf1sGHXXUKvoU4,3056
+matelab/templates.py,sha256=YpnCZ6WIMI7JEPYfdKNIzfuCMA9iwQx2qA473AvWpfk,31584
+matelab/uploads.py,sha256=_H6WdE_hvPdJeWdRdeh-0g9pm8EdxdcKKsv6hPMxObc,10182
+matelab/users.py,sha256=oU-FU0RNyNaSu6MBEL_2uP627AI7ZZWzQM7irwyJ1WY,2528
+matelab/_generated/__init__.py,sha256=jmGbXLLe3JorsGU7OUdF8iKGewFMRqkCzgyFAw7C15w,79
+matelab/_generated/models.py,sha256=uAsP0DYFGcanOxhn5-ISEXkoi_MDHhJylqwow-4MOBc,92551
+matelab_python_sdk-0.1.0a1.dist-info/METADATA,sha256=YMcK5wX333aTqUf4QrNsRiUUrUHctCe79BJCHKjSjAQ,27968
+matelab_python_sdk-0.1.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+matelab_python_sdk-0.1.0a1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+matelab_python_sdk-0.1.0a1.dist-info/licenses/NOTICE,sha256=Hc4scCJTof5VL3JCPI2aaewnnzCejIHUGuBVYBf-klc,98
+matelab_python_sdk-0.1.0a1.dist-info/RECORD,,

matelab_python_sdk-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any