{/* GENERATED: scripts/sync-sdk-notes.mjs; edit the SDK owning docs first. */}

# Python client sessions and transport

`DreamLakeClient`, `RemoteClient`, and remote or hybrid `Episode` instances use
one credential order: an explicit client token, then `DREAMLAKE_API_KEY`, then
the session saved by `dreamlake login`. `Episode` delegates to `RemoteClient`.
Local Episodes do not need credentials. `DreamLakeClient` supports anonymous
requests; `RemoteClient` and remote Episodes raise `NotAuthenticatedError` when
no token is available.

`DreamLakeClient(transport=...)` applies the supplied synchronous httpx transport
to all DreamLake API requests, including upload authorization, node registration,
node lookup, account identity, downloads, and Bindrs. Existing request timeouts
and HTTP error propagation are preserved. An injected transport is borrowed:
the caller must keep it open for all SDK operations and close it afterward
(for example, wrap the whole sequence in `with transport:`). Individual
`client.http()` contexts close their HTTP clients without closing that shared
transport. Without injection, each HTTP client owns and closes its connection
pools, including after failed requests. Signed storage transfers and Qdrant
use their separate service connections; they do not inherit the DreamLake token.

The Python Bindr helpers retain their project/name arguments and flat
`{id, members, ...}` return shape. Names resolve exactly through the project
Bindr listing; reads then use `/bindrs/:id?recursive=true` and collect every member page.
Membership writes send one `{nodeId}` per request. `create_bindr()` atomically
creates the Bindr with its first node; additional nodes are filed sequentially.
`BindrMembershipError` (from `dreamlake.api._client`) exposes `bindr_id`, `completed_node_ids`, and
`failed_node_id`, and chains the original HTTP error. Confirmed filings remain;
a transport failure may leave the failed filing's outcome unknown.

Node ID strings, `{nodeId: ...}`, and legacy `{type: "node", id: ...}` inputs
are accepted. Legacy Bindr-as-member inputs and `dl.bindr(bindrs=[...])` are
rejected before any request: the current API represents nesting through a
Bindr's `parent`, and its reads include child filings. Downloads recognize
canonical `{nodeId: ...}` members.

## Source visibility

Source visibility is independent of signed-in share links and editors. Private
Sources keep their current authorized audience; Unlisted Sources are readable
by link but excluded from public profiles and listings; Public Sources are
listed for visitors. Link access is read-only and covers the whole Source.

```python
from uuid import uuid4

source = client.sources.detail("team", source_id)
client.sources.set_visibility(
    "team", source_id, "unlisted",
    expected_settings_revision=source["settingsRevision"],
    idempotency_key=str(uuid4()),
)
```

A stale revision is rejected. No request is automatically retried. On a lost or
invalid acknowledgment, read `detail()` again before deciding whether to retry.
The `metadata()` method accepts the same visibility and revision arguments.

## Folder and Bindr visibility

Ordinary folders and Bindrs support `private`, `unlisted` and `public`.
Unlisted objects are readable by direct link and excluded from public discovery.
Existing unset visibility retains inherited behavior. Project ADMIN is required
for a change, and independent private resource permissions remain in force.

```python
from dreamlake.api._client import DreamLakeClient

client = DreamLakeClient()
folder = client.folders.get_visibility(folder_id)
client.folders.set_visibility(
    folder_id, "unlisted", expected_updated_at=folder["updatedAt"]
)
bindr = client.bindrs.get_visibility(bindr_id)
client.bindrs.set_visibility(
    bindr_id, "unlisted", expected_updated_at=bindr["updatedAt"]
)
```

The methods address stable IDs, so reading an Unlisted object does not require
finding it in a public Project list. Folder reads return effective `visibility`
and nullable `explicitVisibility`; Bindr reads may omit visibility for inherited
legacy behavior. `updatedAt` is required for every visibility update. Invalid
inputs fail before any request. Writes are sent once; transport failures,
server errors or invalid acknowledgments raise `VisibilityWriteUnconfirmed`
(from `dreamlake.api.folder_visibility`). Read current metadata to reconcile an
uncertain response before deciding whether to retry.

`client.create_bindr(..., visibility="unlisted")` sets visibility at creation and
checks the acknowledgment before filing additional nodes. `dl.bindr(...,
visibility="unlisted")` sets it on a new or existing Bindr; existing Bindrs use a
fresh version read. Ordinary files inherit folder visibility. Sharing a Bindr
shares the grouping, without changing access to its members or Project.

Source: [Python SDK guide](https://github.com/fortyfive-labs/dreamlake/blob/3e27204b95f97fcafeaa05993fa3d74f6274057c/docs/api-client.md).
