# 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/) \| 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/)).
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/)
- [tinker_cookbook.stores.LocalStorage](https://tinker-docs.thinking-machines-ai/cookbook/api-reference/stores/localstorage/)
- [tinker_cookbook.stores.RunRegistry.primary_storage](https://tinker-docs.thinking-machines.ai/cookbook/api-reference/stores/runregistry/#runregistry-primary_storage)
- [tinker_cookbook.stores.RunRegistry.storage_for](https://tinker-docs.thinking-machines.ai/cookbook/api-reference/stores/runregistry/#runregistry-storage_for)
- [tinker_cookbook.stores.storage_from_uri](https://tinker-docs.thinking-machines.ai/cookbook/api-reference/stores/storage_from_uri/)
- [tinker_cookbook.stores.TrainingRunStore](https://tinker-docs.thinking-machines.ai/cookbook/api-reference/stores/trainingrunstore/)