Attachment¶

Manager for interacting with attachment resources.

class gpp_client.managers.attachment.AttachmentManager(client: GPPClient)[source]¶

Bases: BaseManager

Manager for interacting with attachment resources.

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, optional) – Whether to overwrite the file if it already exists. Default is False.
chunk_size (int, optional) – The chunk size for downloading the file in bytes. Default is 1 MB.

Returns:

The path to the downloaded file.

Return type:

Path

async get_all_by_observation(*, observation_reference: str | None, observation_id: str | None) → dict[str, Any][source]¶

Get all attachments associated with a given observation.

Parameters:

observation_reference (str | None) – The observation reference.
observation_id (str | None) – The observation ID.

Returns:

A dictionary containing attachment information.

Return type:

dict[str, Any]

async get_all_by_program(*, program_id: str | None, proposal_reference: str | None, program_reference: str | None) → dict[str, Any][source]¶

Get all attachments associated with a given program.

Parameters:

program_id (str | None) – The program ID.
proposal_reference (str | None) – The proposal reference.
program_reference (str | None) – The program reference.

Returns:

A dictionary containing attachment information.

Return type:

dict[str, Any]

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

get_result(result: dict[str, Any] | None, operation_name: str | None = None) → dict[str, Any]¶

Extract the payload for a given GraphQL operation.

Parameters:

result (dict[str, Any] | None) – The full GraphQL result.
operation_name (str | None, optional) – The name of the operation to extract. If None, and the result contains exactly one top-level key, that key is used.

Returns:

The extracted payload for the specified operation.

Return type:

dict[str, Any]

Raises:

GPPClientError – If the result is empty or invalid, or if the specified operation name is not found in the result.

get_single_result(payload: dict[str, Any], key: str) → dict[str, Any]¶

Extract exactly one item from a list-valued field in a GraphQL payload.

Parameters:

payload (dict[str, Any]) – The GraphQL payload containing the field.
key (str) – The key of the field to extract.

Returns:

The single item extracted from the field.

Return type:

dict[str, Any]

Raises:

GPPClientError – If the specified field is missing from the payload, is not a list, or does not contain exactly one item.

load_properties(*, properties: Any | None, from_json: str | Path | dict[str, Any] | None, cls: type[T]) → T¶

Return a validated properties object from exactly one data source.

Parameters:

properties (T, optional) – Preconstructed properties instance. Returned unchanged when provided.
from_json (str | Path | dict[str, Any], optional) – Path to a JSON file or a dictionary containing the JSON data.
cls (type[T]) – Concrete PropertiesInput class for validation. Required.

Returns:

Instance of cls representing the validated properties.

Return type:

Raises:

GPPValidationError – If validation fails or an error occurs loading the properties.

raise_error(exc_class: type[GPPError], exc: Exception, *, include_traceback: bool = False) → NoReturn¶

Raise a structured exception with contextual information.

Parameters:

exc_class (type[GPPError]) – The exception class to raise (must accept a string message).
exc (Exception) – The original exception to wrap.
include_traceback (bool, default=False) – Whether to include the original traceback using from exc.

Raises:

type[GPPError] – The raised exception of the specified type.

async raise_for_status(response, *, ok_statuses: set[int], default_message: str = 'Request failed') → None¶

Raise an exception if the HTTP response status is not OK.

Parameters:

response (aiohttp.ClientResponse) – The HTTP response to check.
ok_statuses (set[int]) – Set of acceptable HTTP status codes.
default_message (str, default="Request failed") – Default error message if the response has no content.

Raises:

GPPResponseError – If the response status is not in ok_statuses.

resolve_content(*, file_path: str | Path | None, content: bytes | None) → bytes¶

Resolve upload content bytes from exactly one source.

Parameters:

file_path (str | Path | None) – Path to a local file. If provided, it must exist and be a file.
content (bytes | None) – Raw bytes content.

Returns:

The resolved content bytes.

Return type:

bytes

Raises:

GPPValidationError – If both or neither of file_path and content are provided, or if file_path is invalid.
GPPClientError – If reading the file fails due to an unexpected I/O error.

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.

validate_single_identifier(**kwargs) → None¶

Validate that exactly one identifier is provided.

This helper checks that exactly one of the provided keyword arguments is non-None. It raises a ValueError otherwise.

Parameters:: **kwargs (dict[str, Optional[str]]) – A dictionary of identifier keyword arguments to validate.
Raises:: GPPValidationError – If none or more than one identifiers are provided.