# Attachment

## class nominal.core.Attachment(rid, name, description, properties, labels, created_at, is_archived)

Bases: `HasRid`, `RefreshableGrpcMixin`[`Attachment`]

An uploaded file that can be attached to assets or runs.

### rid: str

### name: str

### description: str

### properties: Mapping[str, str]

### labels: Sequence[str]

### created_at: IntegralNanosecondsUTC

### is_archived: bool

### archive()

Archive this attachment.
Archived attachments are not deleted, but are hidden from the UI.

Refreshes this instance from the update response without an additional fetch.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the archive request fails.

### get_contents()

Retrieve the contents of this attachment.
Returns a file-like object in binary mode for reading.

The contents are streamed from object storage through a short-lived presigned URI, the same storage that
attachment uploads are written to. Close the returned stream when finished, e.g. with a `with` block.

Raises:
:   - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the download URI cannot be retrieved.
    - **requests.RequestException** – If downloading the contents fails.

Return type:
:   [*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)")

### refresh()

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### unarchive()

Unarchive this attachment, allowing it to be viewed in the UI.

Refreshes this instance from the update response without an additional fetch.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the unarchive request fails.

### update(*, name=None, description=None, properties=None, labels=None, is_archived=None)

Replace attachment metadata.
Updates the current instance, and returns it.

None leaves a field unchanged. Updates refresh this instance from the response;
when no fields are supplied, fetch the latest attachment instead.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Replacement name.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Replacement description. An empty string clears it.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Replacement properties. An empty mapping clears them.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Replacement labels. An empty sequence clears them.
    - **is_archived** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      True archives the attachment; False restores it.

Returns:
:   This instance with refreshed metadata.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

> **Note**
>
> This replaces the metadata rather than appending it. To append to labels or properties, merge them before
> calling this method. E.g.:
>
> ```python
> new_labels = ["new-label-a", "new-label-b", *attachment.labels]
> attachment = attachment.update(labels=new_labels)
> ```

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the update request fails.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### write(path, mkdir=True)

Write an attachment to the filesystem.

`path` should be the path you want to save to, i.e. a file, not a directory.