> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Caches and upload sources

Builders keep layer history, upload results, and URL-download metadata in one
Store. Helpers and direct builders accept `store=`. Tree kinds
separate reusable records from user sessions. Node data contains JSON values.
See [Build a Docker image](https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/building-images.md), [Tree stores](https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/reference/store.md), and [Reuse uploads and retain their sources](https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/caching.md) for retention,
connection scope, and upload provenance.

Upload reuse through the public file-transfer and store contracts.

## `class AsyncCachedFileTransfer`

```python theme={null}
class contree_sdk.upload_cache.AsyncCachedFileTransfer(transfer, store, *, scope, ttl, sources)
```

Cache content uploads; apply permissions from each current request.

ttl is required and measured from upload completion. Hits do not renew it.
Concurrent misses may upload the same content. The caller owns all components.

### Methods

#### `download_file()`

```python theme={null}
async def download_file(image_uuid, path, destination) -> int
```

Atomically save streamed content.

**image\_uuid** *required*

**path** *required*

**destination** *required*

**returns** `int`

The number of downloaded bytes.

#### `iter_file()`

```python theme={null}
def iter_file(image_uuid, path) -> AsyncGenerator[bytes, None]
```

Yield file content. Override this buffered fallback for streaming backends.

**image\_uuid** *required*

**path** *required*

**returns** `AsyncGenerator[bytes, None]`

**yields**

File content chunks. Close the generator if iteration stops early.

## `class CachedFileTransfer`

```python theme={null}
class contree_sdk.upload_cache.CachedFileTransfer(transfer, store, *, scope, ttl, sources)
```

Cache content uploads; apply permissions from each current request.

ttl is required and measured from upload completion. Hits do not renew it.
Concurrent misses may upload the same content. The caller owns all components.

### Methods

#### `download_file()`

```python theme={null}
def download_file(image_uuid, path, destination) -> int
```

Atomically save streamed content.

**image\_uuid** *required*

**path** *required*

**destination** *required*

**returns** `int`

The number of downloaded bytes.

#### `iter_file()`

```python theme={null}
def iter_file(image_uuid, path) -> Generator[bytes, None, None]
```

Yield file content. Override this buffered fallback for streaming backends.

**image\_uuid** *required*

**path** *required*

**returns** `Generator[bytes, None, None]`

**yields**

File content chunks. Close the generator if iteration stops early.

## `class UploadSnapshot`

```python theme={null}
class contree_sdk.upload_cache.UploadSnapshot(file, sha256, source, directory)
```

Source records kept in a separate namespace from upload store entries.

## `class AsyncFileSources`

```python theme={null}
class contree_sdk.file_sources.AsyncFileSources(store, scope, *, clock)
```

Source registry backed by records with implementation-defined retention in a caller-owned store.

Upload invalidation does not remove source records. A source is provenance,
not proof that the remote upload still exists or that the local file is unchanged.

## `class FileSource`

```python theme={null}
class contree_sdk.file_sources.FileSource(file_uuid, sha256, source, kind, recorded_at)
```

## `class SyncFileSources`

```python theme={null}
class contree_sdk.file_sources.SyncFileSources(store, scope, *, clock)
```

Source registry backed by records with implementation-defined retention in a caller-owned store.

Upload invalidation does not remove source records. A source is provenance,
not proof that the remote upload still exists or that the local file is unchanged.

Bind cache namespaces to a server and an authorization context.

## `class StoreScope`

```python theme={null}
class contree_sdk.scope.StoreScope(digest)
```

A non-secret digest separating endpoint, project, credential, and profile.

### Methods

#### `from_client()`

```python theme={null}
@classmethod
def from_client(client, *, profile) -> StoreScope
```

Derive a scope without storing credentials in cache keys or records.

**client** *required*

**profile** (default: '')

**returns** `StoreScope`

[`StoreScope`](./cache#contree_sdk.scope.StoreScope)

A scope that changes when endpoint, project, credential, or profile changes.