onedata-lambda-sdk 1.0.0__tar.gz

onedata_lambda_sdk-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+build
+dist
+onedata_lambda_sdk.egg-info
+__pycache__
+.venv/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+*-tests-results.xml
+.vscode/
+.idea/
+*.iml

onedata_lambda_sdk-1.0.0/LICENSE.txt

@@ -0,0 +1,24 @@
+MIT License
+===========
+
+    Copyright (C) 2022: Onedata (onedata.org)
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use, copy,
+    modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.

onedata_lambda_sdk-1.0.0/Makefile

@@ -0,0 +1,61 @@
+.DEFAULT_GOAL := help
+.PHONY: help sync format format-check static-analysis type-check lint test check build publish clean
+
+bold := $(shell tput bold)
+normal := $(shell tput sgr0)
+blue := $(shell tput setaf 4)
+
+define print_target
+	@echo ""
+	@echo "$(blue)$(bold)$@:$(normal)"
+endef
+
+# `make help` groups targets by `##@ section` banners and lists each `target: ## description`.
+help:
+	@awk 'BEGIN{FS=":.*## "} /^##@ /{printf "\n%s:\n",substr($$0,5)} /^[a-z][a-zA-Z0-9_-]*:.*## /{printf "  %-20s %s\n",$$1,$$2}' $(MAKEFILE_LIST)
+
+##@ dev
+
+sync: ## sync the dev env (uv sync)
+	$(call print_target)
+	uv sync
+
+##@ checks
+
+format: ## ruff format + autofix
+	$(call print_target)
+	uv run ruff format .
+	uv run ruff check --fix .
+
+format-check: ## ruff format --check
+	$(call print_target)
+	uv run ruff format --check .
+
+static-analysis: ## ruff check
+	$(call print_target)
+	uv run ruff check .
+
+type-check: ## mypy
+	$(call print_target)
+	uv run mypy onedata_lambda_sdk
+
+lint: format-check static-analysis type-check ## format-check + static-analysis + type-check
+	@:
+
+test: ## pytest (+ coverage, junit for CI)
+	$(call print_target)
+	uv run pytest --cov=onedata_lambda_sdk --cov-report=term-missing --junitxml=onedata-lambda-sdk-tests-results.xml
+
+check: lint test ## lint + test
+	@:
+
+##@ build & release
+
+build: ## uv build (sdist + wheel)
+	uv build
+
+publish: ## uv publish
+	uv publish
+
+clean: ## remove build artifacts
+	rm -rf build dist *.egg-info

onedata_lambda_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: onedata-lambda-sdk
+Version: 1.0.0
+Summary: SDK for writing Onedata Automation lambdas
+Project-URL: Homepage, https://onedata.org
+Author: Bartosz Walkowicz
+License: MIT License
+        ===========
+        
+            Copyright (C) 2022: Onedata (onedata.org)
+        
+            Permission is hereby granted, free of charge, to any person
+            obtaining a copy of this software and associated documentation
+            files (the "Software"), to deal in the Software without
+            restriction, including without limitation the rights to use, copy,
+            modify, merge, publish, distribute, sublicense, and/or sell copies
+            of the Software, and to permit persons to whom the Software is
+            furnished to do so, subject to the following conditions:
+        
+            The above copyright notice and this permission notice shall be
+            included in all copies or substantial portions of the Software.
+        
+            THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+            EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+            MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+            NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+            HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+            WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+            FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+            OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE.txt
+Keywords: automation,lambda,onedata,openfaas
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: requests>=2.32
+Description-Content-Type: text/markdown
+
+# onedata-lambda-sdk
+
+The Python SDK for writing **Onedata Automation lambdas** — the containerized
+operations that run as job executors in automation workflows. You write one
+handler function; the SDK turns the raw OpenFaaS request into typed jobs, runs
+your handler, streams its results, sends the mandatory first heartbeat and keeps
+the batch alive while it streams, and shapes the response the provider expects.
+
+```python
+from onedata_lambda_sdk import Job, JobContext, per_job
+
+@per_job(max_workers=10)
+def handle(job: Job[dict], ctx: JobContext[dict]) -> dict:
+    return {"result": process(job.args)}
+```
+
+## Documentation
+
+The full authoring documentation lives in [`docs/`](docs/):
+
+- **[SDK overview](docs/_overview.md)** — the three-layer model (base image →
+  SDK → handler) and how a job batch flows.
+- **Guides** — [writing a handler](docs/guides/writing-a-handler.md),
+  [a single-lambda repo](docs/guides/single-lambda-repo.md),
+  [several lambdas in a uv workspace](docs/guides/shared-code-uv-workspace.md),
+  [developing against a vendored SDK wheel](docs/guides/local-sdk-vendored-wheel.md),
+  [testing](docs/guides/testing-a-lambda.md),
+  [streaming logs and stats](docs/guides/streaming-logs-and-stats.md), and
+  [file access](docs/guides/file-access.md).
+- **[Runtime internals](docs/internals/runtime-and-lifecycle.md)** — for SDK
+  maintainers.
+
+The platform-side contract this SDK implements — how Oneprovider invokes a
+lambda, the I/O and relay methods, heartbeats — is in the internal developer
+documentation under `docs/automation/internals/lambda/` in
+`onedata-dev-documentation`.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```bash
+pip install onedata-lambda-sdk
+```
+
+## Development
+
+```bash
+make sync     # create the .venv from the lockfile
+make check    # lint (ruff format-check + ruff check + mypy) + tests
+make test     # pytest with coverage
+```
+
+Run `make help` for the full target list.
+
+## Compatibility
+
+`onedata-lambda-sdk` targets the **v3 lambda model** (`run` / `@per_job` /
+`Job` / `JobContext`) and requires Oneprovider `21.02.5` or newer. A v3 lambda
+builds on the `onedata/lambda-base-slim:v3` base image — see
+[Lambda generations](docs/_overview.md#lambda-generations-v2-and-v3).

onedata_lambda_sdk-1.0.0/README.md

@@ -0,0 +1,61 @@
+# onedata-lambda-sdk
+
+The Python SDK for writing **Onedata Automation lambdas** — the containerized
+operations that run as job executors in automation workflows. You write one
+handler function; the SDK turns the raw OpenFaaS request into typed jobs, runs
+your handler, streams its results, sends the mandatory first heartbeat and keeps
+the batch alive while it streams, and shapes the response the provider expects.
+
+```python
+from onedata_lambda_sdk import Job, JobContext, per_job
+
+@per_job(max_workers=10)
+def handle(job: Job[dict], ctx: JobContext[dict]) -> dict:
+    return {"result": process(job.args)}
+```
+
+## Documentation
+
+The full authoring documentation lives in [`docs/`](docs/):
+
+- **[SDK overview](docs/_overview.md)** — the three-layer model (base image →
+  SDK → handler) and how a job batch flows.
+- **Guides** — [writing a handler](docs/guides/writing-a-handler.md),
+  [a single-lambda repo](docs/guides/single-lambda-repo.md),
+  [several lambdas in a uv workspace](docs/guides/shared-code-uv-workspace.md),
+  [developing against a vendored SDK wheel](docs/guides/local-sdk-vendored-wheel.md),
+  [testing](docs/guides/testing-a-lambda.md),
+  [streaming logs and stats](docs/guides/streaming-logs-and-stats.md), and
+  [file access](docs/guides/file-access.md).
+- **[Runtime internals](docs/internals/runtime-and-lifecycle.md)** — for SDK
+  maintainers.
+
+The platform-side contract this SDK implements — how Oneprovider invokes a
+lambda, the I/O and relay methods, heartbeats — is in the internal developer
+documentation under `docs/automation/internals/lambda/` in
+`onedata-dev-documentation`.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```bash
+pip install onedata-lambda-sdk
+```
+
+## Development
+
+```bash
+make sync     # create the .venv from the lockfile
+make check    # lint (ruff format-check + ruff check + mypy) + tests
+make test     # pytest with coverage
+```
+
+Run `make help` for the full target list.
+
+## Compatibility
+
+`onedata-lambda-sdk` targets the **v3 lambda model** (`run` / `@per_job` /
+`Job` / `JobContext`) and requires Oneprovider `21.02.5` or newer. A v3 lambda
+builds on the `onedata/lambda-base-slim:v3` base image — see
+[Lambda generations](docs/_overview.md#lambda-generations-v2-and-v3).

onedata_lambda_sdk-1.0.0/docs/_overview.md

@@ -0,0 +1,241 @@
+---
+audience: integrator
+source_modules:
+  - onedata-lambda-sdk/onedata_lambda_sdk/__init__.py
+  - onedata-lambda-sdk/onedata_lambda_sdk/runtime.py
+  - onedata-lambda-sdk/onedata_lambda_sdk/job.py
+  - onedata-lambda-sdk/onedata_lambda_sdk/perjob.py
+  - lambda-base/index.py
+  - lambda-base/templates/Dockerfile
+source_commits:
+  onedata-lambda-sdk: cf25bcd
+  lambda-base: 428785a
+---
+
+# Onedata Lambda SDK
+
+`onedata-lambda-sdk` is the Python SDK for writing **Onedata Automation
+lambdas** — the containerized operations that run as job executors inside
+automation workflows. You write a single handler function; the SDK turns the
+raw OpenFaaS request into typed jobs, runs your handler, streams its results,
+sends the mandatory first heartbeat and keeps the batch alive while it streams,
+and shapes the response the provider expects. Everything between the wire and
+your function is the SDK's job. (A long handler that does *not* stream still
+signals progress itself with `ctx.heartbeat()` — see
+[Writing a handler](guides/writing-a-handler.md).)
+
+## The three layers
+
+A lambda image is built from three layers, split by how often each changes
+and who owns it:
+
+```mermaid
+graph TB
+    OP[🖥️ Oneprovider]
+
+    subgraph Image["🐳 Lambda Docker Image"]
+        Base["🐕 lambda-base<br/>watchdog + index.py bootstrap"]
+        SDK["🧰 onedata-lambda-sdk SDK<br/>run() + ctx services"]
+        Handler["✍️ Handler<br/>your handle() function"]
+    end
+
+    RS["📤 Result Streamer sidecar"]
+    OC["📁 Oneclient sidecar"]
+
+    OP -->|"HTTP job batch"| Base
+    Base -->|"run(handler, raw)"| SDK
+    SDK -->|"invokes"| Handler
+    Handler -->|"uses"| SDK
+    Handler -.->|"writes /out/ files"| RS
+    Handler -.->|"reads/writes files"| OC
+
+    classDef ours fill:#4ECDC4,stroke:#0B7285,color:#000
+    classDef yours fill:#FFE4B5,stroke:#E8890C,color:#000
+    classDef external fill:#A8DADC,stroke:#1864AB,color:#000
+    class Base,SDK ours
+    class Handler yours
+    class OP,RS,OC external
+    style Image fill:#EAFBF9,stroke:#0B7285,color:#000
+```
+
+- **Base image** (`lambda-base`) — the OS, Python, the OpenFaaS watchdog, and
+  a thin, SDK-free bootstrap (`index.py`) that loads your handler and the SDK's
+  runtime. It changes rarely and is shared by every lambda. You build on it with
+  a one-line `FROM` and never edit its build logic.
+- **SDK** (`onedata-lambda-sdk`, this repo) — the runtime contract
+  (`run(handler, raw)`), the handler API (`Job`, `JobContext`), the
+  context-vended services (heartbeat, logging, result streaming), the wire
+  types, and the test helpers. **Required**: the base loads `run()` from the SDK
+  and the build fails if you don't declare it.
+- **Handler** — *your* code: a plain function registered as the single
+  `onedata.lambda` entry point. The only layer you write.
+
+> [!IMPORTANT]
+> The boundary that matters is **handler vs. everything else**. The base image
+> and the SDK are framework; your handler is the only code you own. Most of this
+> doc set is about that one function and the services it is handed.
+
+## Lambda generations: v2 and v3
+
+Throughout these docs (and the repo) you will see **v2** and **v3**. They name
+the **lambda generation** — the model a lambda is built against. A generation
+pins two things together:
+
+- **The handler shape** — v3 is `run` / `@per_job` / `Job` / `JobContext`
+  (this doc set); v2 was a single `handle(request, heartbeat_callback)`.
+- **The base image tag** — a v3 lambda builds on `onedata/lambda-base-slim:v3`.
+
+**v3 is the current generation and the only one these docs cover.**
+`onedata-lambda-sdk` is v3-only; v2 lambdas still run, but new lambdas are
+written for v3. See [Compatibility](../README.md#compatibility) for the
+Oneprovider line v3 targets.
+
+> [!NOTE]
+> The `v3` in a REST URL such as `/api/v3/oneprovider/data/...` is **unrelated** —
+> that is the Oneprovider data-API version, not the lambda generation.
+
+## Why the SDK owns the runtime
+
+<sub>source: `onedata-lambda-sdk/onedata_lambda_sdk/runtime.py#run`</sub>
+
+In earlier lambda images the per-request orchestration — heartbeats, output
+capture, mount-waiting — lived in the base image's entry point. In
+[v3](#lambda-generations-v2-and-v3) it lives in the SDK's `run()`, and the base
+image's `index.py` is a thin bootstrap that just calls it. Three consequences
+worth knowing:
+
+- **The runtime versions with the contract, not the image.** The wire shape,
+  the heartbeat protocol, and the result-relay format are SDK concerns; pinning
+  the SDK version pins all of them together. A base-image rebuild is no longer
+  needed to evolve the contract.
+- **Services are vended by the context, not imported.** Your handler receives a
+  `JobContext` and asks it for what it needs — `ctx.logger(name)`,
+  `ctx.result_streamer(name)`, `ctx.heartbeat()`. Because the runtime constructs
+  these, they can hook into the shared streaming flusher and the heartbeat path,
+  and they are swapped for in-memory fakes under test without touching your code.
+- **Failures always become a well-formed response.** Even a broken handler
+  import or a malformed request is caught and returned as a top-level
+  `{"exception": ...}` envelope, so the provider never sees a naked crash.
+
+## How a job batch flows
+
+Oneprovider does not call your handler per job — it POSTs a whole **batch** of
+jobs (one shared context plus a list of per-job arguments) and expects a batch
+of results back. The lifecycle of one request:
+
+```mermaid
+flowchart TD
+    OP[🖥️ Oneprovider] -->|"POST batch · ctx + argsBatch"| Base[🐕 index.py bootstrap]
+    Base -->|"run(handler, raw)"| R1
+
+    subgraph Runtime["🧰 SDK runtime · run()"]
+        direction TB
+        R1[1 · redirect stdout/stderr] --> R2[2 · await Oneclient mount]
+        R2 --> R3[3 · parse request]
+        R3 --> R4[4 · first heartbeat]
+        R4 --> R5[5 · build Jobs + JobContext]
+        R5 --> R6[6 · call handler — your code]
+        R6 --> R7[7 · assemble resultsBatch]
+    end
+
+    R4 -.->|"heartbeats"| OP
+    R6 -.->|"stream items"| Out[📤 /out streams · sidecar]
+    R7 -->|"envelope"| Base
+    Base -->|"stdout response"| OP
+
+    classDef ours fill:#4ECDC4,stroke:#0B7285,color:#000
+    classDef yours fill:#FFE4B5,stroke:#E8890C,color:#000
+    classDef external fill:#A8DADC,stroke:#1864AB,color:#000
+    class Base,R1,R2,R3,R4,R5,R7 ours
+    class R6 yours
+    class OP,Out external
+    style Runtime fill:#EAFBF9,stroke:#0B7285,color:#000
+```
+
+1. The base bootstrap reads the request from stdin and calls
+   `run(handler, raw)`.
+
+   <sub>source: `lambda-base/index.py#main`</sub>
+
+2. `run()` redirects the process's stdout/stderr to a file so a stray `print`
+   cannot corrupt the response.
+3. If the lambda uses a mounted Oneclient, it waits for the mount to become
+   ready **before doing anything else** — even before parsing the request. This
+   wait can take up to ~120 s, so it comes first; lambdas without a mount skip it.
+4. It parses the request, then delivers the **mandatory first heartbeat** —
+   telling Oneprovider the batch actually started — and vends a throttled
+   `heartbeat()` for the rest of the run.
+5. It builds the typed `Job` list and the shared `JobContext`, then calls your
+   handler.
+
+   <sub>source: `onedata-lambda-sdk/onedata_lambda_sdk/runtime.py#_build_jobs_and_context`</sub>
+
+6. Your handler runs (this is the only step you write).
+7. `run()` wraps the handler's return value in a `{"resultsBatch": [...]}`
+   envelope, drains any buffered output streams, and returns it; the base writes
+   it to stdout for the provider.
+
+## What you write, and what you get
+
+Your handler comes in two shapes, both covered in
+[Writing a handler](guides/writing-a-handler.md):
+
+```python
+# Batch style — you get the whole batch and return a list the same length.
+def handle(jobs: list[Job[Args]], ctx: JobContext[Config]) -> list[Result]:
+    ...
+
+# Per-job style — the SDK runs the loop; you handle one job at a time.
+@per_job(max_workers=10)
+def handle(job: Job[Args], ctx: JobContext[Config]) -> Result:
+    ...
+```
+
+`Args`, `Config`, and `Result` are your own `TypedDict`s, declared next to the
+handler — see
+[Type your arguments, config, and results](guides/writing-a-handler.md#type-your-arguments-config-and-results).
+`Job` carries that job's typed `args` and its `trace_id`; `JobContext` carries
+the typed task `config`, the read-only identity fields (space, user, provider,
+tokens), and the runtime **services**:
+
+| Service | What it does | Guide |
+|---------|--------------|-------|
+| `ctx.heartbeat()` | Signal progress on a long job (throttled by the runtime) | [Writing a handler](guides/writing-a-handler.md) |
+| `ctx.logger(name)` | Emit severity-filtered audit-log entries | [Streaming logs and stats](guides/streaming-logs-and-stats.md) |
+| `ctx.result_streamer(name)` | Append results / time-series measurements to a stream | [Streaming logs and stats](guides/streaming-logs-and-stats.md) |
+
+These are the things you would otherwise reimplement in every lambda — a
+heartbeat loop, an output writer, a log formatter. Reach for the service instead
+of hand-rolling it.
+
+## What the framework guarantees
+
+- **Per-job failure isolation** (with `@per_job`) — one job that raises becomes
+  an `AtmException` entry for *that job only*; the rest of the batch still
+  returns. See [Writing a handler](guides/writing-a-handler.md#failures).
+- **Expected vs. unexpected errors** — raising `JobException` reports a clean
+  message; any other exception is treated as a bug and reported with a full
+  traceback.
+- **Output integrity** — stdout/stderr are redirected during the run, so only
+  the serialized response reaches the provider.
+- **Liveness** — the first heartbeat is mandatory and automatic; the services
+  heartbeat as they flush, so a streaming handler stays alive without extra code.
+- **Result ordering** — results come back in input order even when jobs run in
+  parallel.
+
+What the SDK does **not** do: decide *how* you reach Onedata files (mounted vs.
+REST — see [File access](guides/file-access.md)), or define the lambda schema
+itself (that is authored alongside the workflow, per the platform docs).
+
+## What's next
+
+| Goal | Start with |
+|------|------------|
+| Write your first handler | [Writing a handler](guides/writing-a-handler.md) |
+| Ship one lambda from a single repo | [Single-lambda repo](guides/single-lambda-repo.md) |
+| Maintain several lambdas with shared code | [Shared code in a uv workspace](guides/shared-code-uv-workspace.md) |
+| Build a lambda against a locally-changed SDK | [Using a vendored SDK wheel](guides/local-sdk-vendored-wheel.md) |
+| Test a handler without Docker | [Testing a lambda](guides/testing-a-lambda.md) |
+| Emit logs, statistics, or streamed results | [Streaming logs and stats](guides/streaming-logs-and-stats.md) |
+| Read and write Onedata files | [File access](guides/file-access.md) |
+| Understand the runtime internals | [Runtime and lifecycle](internals/runtime-and-lifecycle.md) |

onedata_lambda_sdk-1.0.0/docs/guides/file-access.md

@@ -0,0 +1,171 @@
+---
+audience: integrator
+source_modules:
+  - onedata-lambda-sdk/onedata_lambda_sdk/oneclient.py
+  - onedata-lambda-sdk/onedata_lambda_sdk/job.py
+  - automation-examples/lambdas/calculate-checksum-mounted/src/calculate_checksum_mounted/handler.py
+  - automation-examples/lambdas/calculate-checksum-rest/src/calculate_checksum_rest/handler.py
+source_commits:
+  onedata-lambda-sdk: cf25bcd
+  automation-examples: 1a21949
+---
+
+# File access
+
+A lambda reaches Onedata files in one of two ways: through a **mounted
+Oneclient** (the space appears as a local filesystem) or through the
+**Oneprovider REST API** (you call HTTP with the job's access token). Which one a
+lambda uses is fixed by its schema; this guide shows how to write the handler for
+each, and how to choose.
+
+## When to use this
+
+- Your handler reads file content or writes file metadata.
+- You are deciding between a mounted and a REST lambda.
+- You are porting a [v2](../_overview.md#lambda-generations-v2-and-v3) lambda and
+  its file access broke (see the third-party-imports note below).
+
+> [!NOTE]
+> **Prerequisites.** The [handler model](writing-a-handler.md) — file access uses
+> the job's `args` (an `AtmFile`) and the context's identity fields. The
+> mount-vs-REST switch is `mountOneclient` in the schema's
+> `dockerExecutionOptions`.
+
+## Choosing mounted or REST
+
+The choice is a property of the lambda, set in its schema — the handler is then
+written for whichever it gets. Use this to decide:
+
+| Criterion | Mounted | REST |
+|-----------|---------|------|
+| Large files | preferred | slower |
+| POSIX operations (`xattr`, `stat`) | native | HTTP wrappers |
+| Startup latency | up to ~120 s mount wait | instant |
+| Metadata-only work | overkill | preferred |
+
+In short: mounted for heavy content and filesystem semantics, REST for
+metadata-light work and fast startup.
+
+## Read through a mounted Oneclient
+
+With `mountOneclient: true`, an Oneclient sidecar mounts the space and the SDK
+gives you the path to any file by its id. The runtime waits for the mount to be
+ready before your handler runs, so you can open files directly:
+
+```python
+from onedata_lambda_sdk import Job, JobContext, per_job
+from onedata_lambda_sdk.oneclient import mounted_file_path
+
+@per_job(max_workers=5)
+def handle(job: Job[JobArgs], ctx: JobContext[TaskConfig]) -> JobResult:
+    path = mounted_file_path(job.args["file"]["fileId"])
+    with open(path, "rb") as f:
+        data = f.read()
+    ...
+```
+
+`mounted_file_path(file_id)` returns `<mount>/.__onedata__file_id__<id>` —
+Oneclient exposes every file at this stable id-based path, so you open a file
+knowing only its id, without resolving where it sits in the tree. Use
+`mount_point()` if you need the mount root itself.
+
+> [!TIP]
+> **Source:** `onedata-lambda-sdk/onedata_lambda_sdk/oneclient.py#mounted_file_path`
+> and `#mount_point`. Reading the mount point from this one helper keeps your
+> lambda agreeing with the mount path the runtime waited on, rather than
+> hardcoding `/mnt/onedata`.
+
+Because it is a real filesystem, POSIX operations work directly — including
+extended attributes for metadata:
+
+```python
+import xattr
+xattr.xattr(path).set("checksum.sha256", value.encode())
+```
+
+> [!NOTE]
+> `xattr` is a third-party package, not part of the standard library — so it must
+> be listed in your `pyproject.toml` `dependencies`. The base image installs only
+> what you declare; an undeclared import fails at runtime. This is the same rule —
+> and the same common porting break — as for `requests` in the REST section below.
+
+> [!TIP]
+> **Source:** the full mounted example is
+> `automation-examples/lambdas/calculate-checksum-mounted/src/calculate_checksum_mounted/handler.py`.
+
+## Read through the REST API
+
+With `mountOneclient: false`, there is no filesystem — you call the Oneprovider
+data API using the context's `access_token` and `oneprovider_domain`:
+
+```python
+import requests
+
+def _file_url(ctx, file_id, subpath):
+    return f"https://{ctx.oneprovider_domain}/api/v3/oneprovider/data/{file_id}/{subpath}"
+
+response = requests.get(
+    _file_url(ctx, file_id, "content"),
+    headers={"x-auth-token": ctx.access_token},
+    stream=True,
+    verify=_verify_ssl(),
+    timeout=120,
+)
+response.raise_for_status()
+for chunk in response.iter_content(chunk_size=10 * 1024**2):
+    ...
+```
+
+Writing metadata is a `PUT` to the same base URL:
+
+```python
+requests.put(
+    _file_url(ctx, file_id, "metadata/xattrs"),
+    headers={"x-auth-token": ctx.access_token, "content-type": "application/json"},
+    json={"checksum.sha256": value},
+    verify=_verify_ssl(),
+    timeout=60,
+)
+```
+
+Honor the `VERIFY_SSL_CERTIFICATES` environment variable (verification is on
+unless it is set to `"false"`), and read it at call time so tests can flip it:
+
+```python
+def _verify_ssl() -> bool:
+    return os.environ.get("VERIFY_SSL_CERTIFICATES") != "false"
+```
+
+Without a local `stat`, you must request any file attributes you need (`type`,
+`name`, …) through the lambda's `argumentSpecs`, then read them off the
+`AtmFile` — for example `file["type"] != "REG"` to skip non-regular files.
+
+> [!WARNING]
+> **Declare every third-party import.** The
+> [v2](../_overview.md#lambda-generations-v2-and-v3) base image shipped `requests`
+> globally, so v2 REST lambdas often imported it without listing it. The v3 base
+> installs only what your `pyproject.toml` `dependencies` declare — `requests`,
+> `xattr`, and anything else outside the standard library. Add the import to
+> `dependencies`, or it fails at runtime. This is the most common v2→v3 porting
+> break.
+
+> [!TIP]
+> **Source:** the full REST example is
+> `automation-examples/lambdas/calculate-checksum-rest/src/calculate_checksum_rest/handler.py`,
+> and `ctx.access_token`/`ctx.oneprovider_domain` come from
+> `onedata-lambda-sdk/onedata_lambda_sdk/job.py#JobContext`.
+
+## What you get
+
+A handler that reads content and writes metadata against Onedata — using the
+mount helpers for filesystem access, or the provider REST API with the job's own
+token — and that fails cleanly per job when a read fails (a transport error
+raised as `JobException` becomes that job's `AtmException` entry).
+
+## Next steps
+
+- **Report progress while reading large files** —
+  [Streaming logs and stats](streaming-logs-and-stats.md).
+- **Test file access without a real mount or provider** —
+  [Testing a lambda](testing-a-lambda.md) (point the mount at a temp dir, or mock
+  the REST endpoint).