# tinker_cookbook.stores.Storage

## *class* [**tinker_cookbook.stores.Storage**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L66)(*Protocol*)

Sync byte-level file I/O.

All paths are relative strings (e.g., `"runs/001/metrics.jsonl"`). The backend resolves them against its root.

Implementations must be **pickle-serializable** (for Ray/multiprocessing) — store only config (bucket, prefix, credentials path), not connections.

### [**url**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L76)(*path*)

Return a human-readable URI for a path.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L76) (*str*)

**Returns:** *str*

### [**read**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L88)(*path*)

Read entire file. Raises `FileNotFoundError` if missing.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L88) (*str*)

**Returns:** *bytes*

### [**write**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L92)(*path*, *data*)

Write data, creating parent dirs. Overwrites if exists.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L92) (*str*)
- [**data**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L92) (*bytes*)

**Returns:** *None*

### [**append**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L96)(*path*, *data*)

Append data to a file, creating if needed.

All backends must support this. Callers should keep individual appends small (< 4KB for POSIX atomicity). Cloud backends may implement via read-modify-write, append blobs (Azure), or internal buffering — the choice is transparent to callers.

On crash, the last append may be lost. Callers must tolerate this.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L96) (*str*)
- [**data**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L96) (*bytes*)

**Returns:** *None*

### [**exists**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L108)(*path*)

Return `True` if the file exists.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L108) (*str*)

**Returns:** *bool*

### [**stat**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L112)(*path*)

Get file size and mtime, or `None` if missing.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L112) (*str*)

**Returns:** *[StorageStat](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/storagestat/index.md) | None*

### [**read_range**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L116)(*path*, *offset*, *length*)

Read bytes from offset. If length is None, read to end.

Raises `FileNotFoundError` if missing. Maps to Range GET on cloud backends.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L116) (*str*)
- [**offset**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L116) (*int*)
- [**length**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L116) (*int | None*)

**Returns:** *bytes*

### [**list_dir**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L124)(*prefix*)

List immediate children under prefix. Returns names only.

For flat key-spaces (S3/GCS), this lists keys sharing the prefix up to the next `/` delimiter.

**Parameters:**

- [**prefix**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L124) (*str*)

**Returns:** *list[str]*

### [**remove**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L132)(*path*)

Delete a file. No error if missing.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L132) (*str*)

**Returns:** *None*

### [**remove_dir**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L136)(*path*)

Remove an empty directory. No error if missing or non-empty.

Cloud backends (S3/GCS) can treat this as a no-op since they don't have real directories.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L136) (*str*)

**Returns:** *None*

### [**flush**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/stores/storage.py#L144)()

Flush any buffered data to the backend.

No-op for backends that write directly (e.g. [`LocalStorage`](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/localstorage/index.md)). Cloud backends with local staging upload buffered data on flush. Called automatically by the context manager on exit.

**Returns:** *None*

## Referenced by

- [tinker_cookbook.stores.EvalStore](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/evalstore/index.md)
- [tinker_cookbook.stores.LocalStorage](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/localstorage/index.md)
- [tinker_cookbook.stores.RunRegistry.primary_storage](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/runregistry/#runregistry-primary_storage)
- [tinker_cookbook.stores.RunRegistry.storage_for](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/runregistry/#runregistry-storage_for)
- [tinker_cookbook.stores.storage_from_uri](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/storage_from_uri/index.md)
- [tinker_cookbook.stores.TrainingRunStore](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/stores/trainingrunstore/index.md)