Attachment & AttachmentMetadata

These classes represent file attachments and their metadata. Both are available as globals in all script actions — no import is needed.

AttachmentMetadata

Lightweight metadata describing a file attachment, without the actual file content.

Constructor

meta = AttachmentMetadata(
    file_name="report.pdf",
    file_type="application/pdf",
    file_size=1024,
    url="https://example.com/files/report.pdf",
    record_id="ABC123",
)

Parameter	Type	Required	Default	Description
`file_name`	str	Yes	—	The file name (e.g. `"report.pdf"`).
`file_type`	str \| None	No	`None`	MIME type (e.g. `"application/pdf"`).
`file_size`	int \| None	No	`None`	File size in bytes.
`url`	str \| None	No	`None`	Download URL for the attachment.
`record_id`	str \| int \| None	No	`None`	ID of the parent record.

Methods

match(other)

meta.match(other_meta)  # -> bool

Returns True if file_name matches and file_size matches (when both are set). Used to detect duplicate attachments.

Attachment

Full attachment data including the base64-encoded file content.

Constructor

attachment = Attachment(
    file_name="report.pdf",
    base64_data=base64.b64encode(raw_bytes),
    url="https://example.com/files/report.pdf",
)

Parameter	Type	Required	Default	Description
`file_name`	str	Yes	—	The file name.
`base64_data`	bytes	Yes	—	Base64-encoded file content. Must be `bytes`, not `str`.
`url`	str \| None	No	—	Source or download URL.
`file_type`	str \| None	No	Auto-guessed	MIME type. Auto-detected from `file_name` if omitted.
`file_size`	int \| None	No	Auto-calculated	Size in bytes. Auto-calculated from `base64_data` if omitted.
`record_id`	str \| int \| None	No	`None`	ID of the parent record.

Note: file_type is auto-guessed from the file name extension if not provided. file_size is auto-calculated from the decoded base64_data length if not provided.

Properties

Property	Type	Description
`file_name`	str	The file name.
`file_type`	str	MIME type (auto-guessed if not set).
`file_size`	int	Size in bytes (auto-calculated if not set).
`base64_data`	bytes	Base64-encoded content.
`url`	str \| None	Source URL.
`record_id`	str \| int \| None	Parent record ID.

Methods

decoded_data()

raw_bytes = attachment.decoded_data()  # -> bytes

Returns the decoded (raw) file content as bytes.

base64_string()

b64_str = attachment.base64_string()  # -> str

Returns the base64 data as a string (rather than bytes).

load_from_path(path) (class method)

attachment = Attachment.load_from_path("/path/to/file.pdf")

Creates an Attachment by reading a file from disk. Automatically sets file_name, file_type, file_size, url (to the path), and base64_data.

Common Patterns

Downloading an attachment

meta = context.attachment_metadata
response = await context.connection.request("GET", meta.url, raise_on_error=True)

attachment = Attachment(
    file_name=meta.file_name,
    file_type=meta.file_type,
    url=meta.url,
    base64_data=base64.b64encode(response.content),
    record_id=context.record_id,
)

Uploading an attachment

file_data = context.attachment.decoded_data()
response = await context.connection.request("POST",
    f"/api/table/{context.table_name}/{context.record_id}/attachments",
    files={"file": (context.attachment.file_name, file_data, context.attachment.file_type)})

Listing attachment metadata

response = await context.connection.request("GET",
    f"/api/table/{context.table_name}/{context.record_id}/attachments")
data = response.json()

return [AttachmentMetadata(
    file_name=item["file_name"],
    file_type=item.get("content_type"),
    file_size=item.get("size_bytes"),
    url=item.get("download_url"),
    record_id=context.record_id,
) for item in data]