Attachment¶

The attachment domain provides access to program and observation attachments.

Use attachment to:

Upload attachments to a program
Update or delete attachments
Download attachment content
List attachments for programs and observations

Quick Example¶

from pathlib import Path
from gpp_client import GPPClient
from gpp_client.generated import AttachmentType

async with GPPClient() as client:
   attachment_id = await client.attachment.upload(
      program_id="p-123",
      attachment_type=AttachmentType.FINDER,
      file_name="finder.png",
      file_path=Path("finder.png"),
   )

   saved_path = await client.attachment.download_by_id(
      attachment_id,
      save_to="~/Downloads",
   )

Upload¶

Upload a new attachment for a program:

attachment_id = await client.attachment.upload(
   program_id="p-123",
   attachment_type=AttachmentType.FINDER,
   file_name="finder.png",
   file_path="finder.png",
)

Provide exactly one of:

file_path
content

Warning

Exactly one of file_path or content must be provided.

Update and Delete¶

Update an existing attachment:

await client.attachment.update_by_id(
   attachment_id="a-123",
   file_name="updated-finder.png",
   file_path="updated-finder.png",
)

Delete an attachment:

await client.attachment.delete_by_id("a-123")

Download¶

Download an attachment by ID:

path = await client.attachment.download_by_id(
   attachment_id="a-123",
   save_to="~/Downloads",
   overwrite=False,
)

If save_to is omitted, the file is downloaded to the user’s home directory.

Tip

Use overwrite=True to replace an existing local file.

Listing Attachments¶

List attachments by observation ID:

result = await client.attachment.get_all_by_observation_id("o-123")

List attachments by observation reference:

result = await client.attachment.get_all_by_observation_reference("GN-2026A-Q-1-1")

List attachments by program ID:

result = await client.attachment.get_all_by_program_id("p-123")

List attachments by program reference:

result = await client.attachment.get_all_by_program_reference("GN-2026A-Q-1")

List attachments by proposal reference:

result = await client.attachment.get_all_by_proposal_reference("GN-2026A-Q-1")

Notes¶

Attachment operations use both REST and GraphQL:

Upload, update, delete, and download use REST endpoints
Listing attachments uses GraphQL queries

Download uses a presigned URL returned by the service.

API Reference¶

class gpp_client.domains.attachment.AttachmentDomain(*, graphql: GraphQLClient, rest: RESTClient, settings: GPPSettings)[source]¶

Bases: BaseDomain

Domain class for attachment-related operations.

async delete_by_id(attachment_id: str) → None[source]¶

Delete an attachment by its ID.

Parameters:: attachment_id (str) – The ID of the attachment to delete.
Raises:: GPPClientError – If the deletion fails.

async download_by_id(attachment_id: str, save_to: str | Path | None = None, overwrite: bool = False, chunk_size: int = 1048576) → Path[source]¶

Download an attachment by its ID.

Parameters:

attachment_id (str) – The ID of the attachment.
save_to (str | Path | None, optional) – The directory to save the downloaded attachment. If None, defaults to home directory.
overwrite (bool, default=False) – Whether to overwrite the file if it already exists.
chunk_size (int, default=1 MB) – The chunk size for downloading the file in bytes.

Returns:

The path to the downloaded file.

Return type:

Path

async get_all_by_observation_id(observation_id: str) → GetObservationAttachmentsById[source]¶

Get all attachments for an observation by observation ID.

Parameters:: observation_id (str) – The observation ID.
Returns:: The generated GraphQL response model.
Return type:: GetObservationAttachmentsById

async get_all_by_observation_reference(observation_reference: str) → GetObservationAttachmentsByReference[source]¶

Get all attachments for an observation by observation reference.

Parameters:: observation_reference (str) – The observation reference label.
Returns:: The generated GraphQL response model.
Return type:: GetObservationAttachmentsByReference

async get_all_by_program_id(program_id: str) → GetProgramAttachmentsById[source]¶

Get all attachments for a program by program ID.

Parameters:: program_id (str) – The program ID.
Returns:: The generated GraphQL response model.
Return type:: GetProgramAttachmentsById

async get_all_by_program_reference(program_reference: str) → GetProgramAttachmentsByReference[source]¶

Get all attachments for a program by program reference.

Parameters:: program_reference (str) – The program reference label.
Returns:: The generated GraphQL response model.
Return type:: GetProgramAttachmentsByReference

async get_all_by_proposal_reference(proposal_reference: str) → GetProgramAttachmentsByProposalReference[source]¶

Get all attachments for a program by proposal reference.

Parameters:: proposal_reference (str) – The proposal reference label.
Returns:: The generated GraphQL response model.
Return type:: GetProgramAttachmentsByProposalReference

async get_download_url_by_id(attachment_id: str) → str[source]¶

Get the download URL for an attachment by its ID.

Parameters:: attachment_id (str) – The ID of the attachment.
Returns:: The download URL for the attachment.
Return type:: str

async update_by_id(attachment_id: str, *, file_name: str, description: str | None = None, file_path: str | Path | None = None, content: bytes | None = None) → None[source]¶

Update an attachment by its ID.

Parameters:

attachment_id (str) – The ID of the attachment to update.
file_name (str) – The new file name for the attachment. This is required.
description (str | None, optional) – The new description for the attachment.
file_path (str | Path | None, optional) – The path to the new file content for the attachment.
content (bytes | None, optional) – The new file content as bytes.

Raises:

GPPClientError – If the update fails.
GPPValidationError – If a validation error occurs.

async upload(program_id: str, *, attachment_type: AttachmentType, file_name: str, description: str | None = None, file_path: str | Path | None = None, content: bytes | None = None) → str[source]¶

Upload a new attachment for a program.

Parameters:

program_id (str) – The program ID to associate the attachment with.
attachment_type (AttachmentType) – The attachment type.
file_name (str) – The file name to store for the attachment.
description (str | None, optional) – Optional attachment description.
file_path (str | Path | None, optional) – Path to a file whose contents will be uploaded. Mutually exclusive with content.
content (bytes | None, optional) – Raw bytes to upload. Mutually exclusive with file_path.

Returns:

The created attachment ID.

Return type:

str

Raises:

GPPClientError – If the upload fails or the response is invalid.
GPPValidationError – If a validation error occurs.