---
sidebar:
  label: roboto.action_runtime.file_changeset
  order: 3
title: roboto.action_runtime.file_changeset
---
## Module Contents

### FilesChangesetFileManager

```python
class roboto.action_runtime.file_changeset.FilesChangesetFileManager
```

`from roboto import FilesChangesetFileManager`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L34-L235)

This class is used to pre-write tags/metadata updates to files which haven't been uploaded yet, but will be at the conclusion of an action, by virtue of being in that action's output directory.

It uses a "file changeset" file to accumulate these pending updates during an action's runtime, and then applies them automatically at the end of an action, after the action's output directory has been uploaded.

The most common way to get access to this would be via [`roboto.action_runtime.InvocationContext`](/reference/python-sdk/roboto/action_runtime/invocation_context#roboto.action_runtime.invocation_context.InvocationContext).

#### FilesChangesetFileManager.put_fields()

```python
def put_fields(relative_path: str, metadata: dict[str, Any])
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L107-L129)

Adds metadata key/value pairs to a to-be-uploaded file which is expected to be written to `${ROBOTO_OUTPUT_DIR}/relative_path` by the end of the user portion of an action's runtime.

This can be called multiple times throughout the runtime of an action, and will be accumulated accordingly. Order of calls matters.

**Usage**

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
file_changeset_manager = context.file_changeset_manager

# This would reference a file at ${ROBOTO_OUTPUT_DIR}/images/front0_raw_000734.jpg
file_changeset_manager.put_fields("images/front0_raw_000734.jpg", {"cars": 2, "trucks": 3})

# Actually there was a 3rd car I missed in the first pass, and a plane, let me fix that...
file_changeset_manager.put_fields("images/front0_raw_000734.jpg", {"cars": 3, "planes": 1})
```

**Parameters**

- **relative_path** (`str`)
- **metadata** (`dict[str, Any]`)

#### FilesChangesetFileManager.put_tags()

```python
def put_tags(relative_path: str, tags: list[str])
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L61-L80)

Adds tags to a to-be-uploaded file which is expected to be written to `${ROBOTO_OUTPUT_DIR}/relative_path` by the end of the user portion of an action's runtime.

This can be called multiple times throughout the runtime of an action, and will be accumulated accordingly. Order of calls matters.

**Usage**

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
file_changeset_manager = context.file_changeset_manager

# This would reference a file at ${ROBOTO_OUTPUT_DIR}/images/front0_raw_000734.jpg
file_changeset_manager.put_tags("images/front0_raw_000734.jpg", ["cloudy", "rainy"]})
```

**Parameters**

- **relative_path** (`str`)
- **tags** (`list[str]`)

#### FilesChangesetFileManager.remove_fields()

```python
def remove_fields(relative_path: str, keys: list[str])
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L131-L154)

Removes metadata key/value pairs from a to-be-uploaded file which is expected to be written to `${ROBOTO_OUTPUT_DIR}/relative_path` by the end of the user portion of an action's runtime. You'll generally only need this to remove values which were added by a previous call to [`put_fields()`](/reference/python-sdk/roboto/action_runtime/file_changeset#roboto.action_runtime.file_changeset.FilesChangesetFileManager.put_fields).

This can be called multiple times throughout the runtime of an action, and will be accumulated accordingly. Order of calls matters.

**Usage**

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
file_changeset_manager = context.file_changeset_manager

# This would reference a file at ${ROBOTO_OUTPUT_DIR}/images/front0_raw_000734.jpg
file_changeset_manager.put_fields("images/front0_raw_000734.jpg", {"cars": 2, "trucks": 3})

# Whoops, actually I don't want to count those trucks...
file_changeset_manager.remove_fields("images/front0_raw_000734.jpg", ["trucks"])
```

**Parameters**

- **relative_path** (`str`)
- **keys** (`list[str]`)

#### FilesChangesetFileManager.remove_tags()

```python
def remove_tags(relative_path: str, tags: list[str])
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L82-L105)

Removes tags from a to-be-uploaded file which is expected to be written to `${ROBOTO_OUTPUT_DIR}/relative_path` by the end of the user portion of an action's runtime. You'll generally only need this to remove tags which were added by a previous call to [`put_tags()`](/reference/python-sdk/roboto/action_runtime/file_changeset#roboto.action_runtime.file_changeset.FilesChangesetFileManager.put_tags).

This can be called multiple times throughout the runtime of an action, and will be accumulated accordingly. Order of calls matters.

**Usage**

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
file_changeset_manager = context.file_changeset_manager

# This would reference a file at ${ROBOTO_OUTPUT_DIR}/images/front0_raw_000734.jpg
file_changeset_manager.put_tags("images/front0_raw_000734.jpg", ["cloudy", "rainy"]})

# Actually this is just Seattle's aggressive mist, that's not really rainy...
file_changeset_manager.remove_tags("images/front0_raw_000734.jpg", ["rainy"]})
```

**Parameters**

- **relative_path** (`str`)
- **tags** (`list[str]`)

#### FilesChangesetFileManager.set_description()

```python
def set_description(relative_path: str, description: Optional[str])
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L156-L169)

Sets the human-readable description of a to-be-uploaded file which is expected to be written to `${ROBOTO_OUTPUT_DIR}/relative_path` by the end of the user portion of an action's runtime.

**Usage**

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
file_changeset_manager = context.file_changeset_manager

# This would reference a file at ${ROBOTO_OUTPUT_DIR}/images/front0_raw_000734.jpg
file_changeset_manager.set_description("images/front0_raw_000734.jpg", "This image was over-exposed")
```

**Parameters**

- **relative_path** (`str`)
- **description** (`Optional[str]`)

### FilesChangesetItem

```python
class roboto.action_runtime.file_changeset.FilesChangesetItem(/, **data: Any)
```

`from roboto.action_runtime.file_changeset import FilesChangesetItem`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L21-L31)

Bases: `pydantic.BaseModel`

A single row in the file metadata changeset .jsonl file.

**Parameters**

- **data** (`Any`)

**Attributes**

- **FilesChangesetItem.relative_path** (`str`): The path to the file relative to the `${ROBOTO_OUTPUT_DIR}` directory, which will correspond to the file's relative_path in a roboto dataset after upload.
- **FilesChangesetItem.update** (`roboto.domain.files.UpdateFileRecordRequest`): The file metadata update to apply to the file.

### logger

```python
roboto.action_runtime.file_changeset.logger
```

`from roboto.action_runtime.file_changeset import logger`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/action_runtime/file_changeset.py#L18-L18)