Skip to content

Client.images¤

detail ¤

detail(
    pk: str | None = None,
    api_url: str | None = None,
    **params: Any
) -> gcapi.models.HyperlinkedImage

Retrieve a specific resource by primary key, URL, or search parameters.

Parameters:

  • pk (str | None, default: None ) –

    Primary key of the resource to retrieve.

  • api_url (str | None, default: None ) –

    Direct API URL of the resource to retrieve.

  • **params (Any, default: {} ) –

    Search parameters to find a unique resource, such as slug="your-slug".

Returns:

Raises:

  • ValueError –

    If more than one or none of pk, api_url, or params are specified.

  • ObjectNotFound –

    If no resource is found matching the criteria.

  • MultipleObjectsReturned –

    If multiple resources match the search parameters.

download ¤

download(
    *,
    output_directory: str | Path,
    filename: str | None = None,
    image_type: str | None = None,
    pk: str | None = None,
    url: str | None = None,
    files: list | None = None,
    **params: Any
) -> list[Path]

Download image files to local filesystem.

Parameters:

  • output_directory (str | Path) –

    Directory to save downloaded files.

  • filename (str | None, default: None ) –

    Optional, base filename for downloaded files. Extension is added automatically.

  • image_type (str | None, default: None ) –

    Restrict download to a particular image type.

  • pk (str | None, default: None ) –

    Primary key of the image to download.

  • url (str | None, default: None ) –

    API URL of the image to download.

  • files (list | None, default: None ) –

    List of file objects to download directly.

  • **params (Any, default: {} ) –

    Additional parameters for image detail lookup.

Returns:

  • list[Path] –

    List of Path objects for downloaded files.

Raises:

  • ValueError –

    If not exactly one of pk, url, files, or params is specified.

iterate_all ¤

iterate_all(
    params: dict[str, Any] | None = None,
) -> Iterator[gcapi.models.HyperlinkedImage]

Iterate through all resources from the API endpoint across all pages.

This method automatically handles pagination and yields individual resources from all pages until all resources have been retrieved.

Parameters:

  • params (dict[str, Any] | None, default: None ) –

    Query parameters to include in the API requests.

Yields:

list ¤

list(
    params: dict[str, Any] | None = None,
) -> list[gcapi.models.HyperlinkedImage]

Retrieve a raw list of resources from the API endpoint.

Parameters:

  • params (dict[str, Any] | None, default: None ) –

    Query parameters to include in the API request.

Returns:

  • list[HyperlinkedImage] –

    Raw JSON response from the API containing the list of resources.

page ¤

page(
    offset: int = 0,
    limit: int = 100,
    params: dict[str, Any] | None = None,
) -> PageResult[gcapi.models.HyperlinkedImage]

Retrieve a paginated set of resources from the API endpoint.

Parameters:

  • offset (int, default: 0 ) –

    The starting index for pagination (zero-based).

  • limit (int, default: 100 ) –

    The maximum number of results to return in this page.

  • params (dict[str, Any] | None, default: None ) –

    Additional query parameters to include in the API request.

Returns: