# Storage

## timenet.storage

Shared physical storage helpers for TimeF readers.

### parquet

Bounded caches for packed payload tables and Signal values row groups.

#### PayloadTableCache

Cache complete packed payload files up to a byte budget, without retaining file handles.

The least recently used files leave first. The newest file stays even when it alone exceeds
the budget, so a large file is still read once.

##### nbytes `property`

```
nbytes: int
```

The decoded bytes of the payload files the cache holds.

##### close

```
close() -> None
```

Release decoded payloads, keeping the cache reusable.

##### read\_table

```
read_table(
    version: DatasetVersion, path: str, schema: Schema
) -> Table
```

Read a payload file once while it remains in the cache.

The file's schema is checked once, when the file enters the cache.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `version` | `DatasetVersion` | The release that holds the payload file. | *required* |
| `path` | `str` | The payload file, relative to the release root. | *required* |
| `schema` | `Schema` | The exact Arrow schema the payload file must have, including nullability. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `Table` | The cached payload table. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFFormatError` | If the payload file cannot be read or has a different schema. |

#### SignalRowGroupCache

Cache values arrays and a bounded number of open Signal shard files.

##### close

```
close() -> None
```

Close shard files and release decoded groups, keeping the cache reusable.

##### read\_values

```
read_values(
    version: DatasetVersion, path: str, row_group: int
) -> Array
```

Read and resolve the values column once per cached row group.

Returns:

| Type | Description |
| --- | --- |
| `Array` | The cached values array. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFFormatError` | If the file, row group, or values column cannot be read. |