saigon.rest

saigon.rest.client

class saigon.rest.client.AsyncRestClient(service_url, service_port=None, api_prefix='', authorizer=<saigon.rest.client.AsyncNoAuthRequestAuthorizer object>, http_client=None)

Bases: _RestClientBase

Async Rest Client.

Provides common functionalities for making HTTP requests, waiting for conditions, and handling S3 pre-signed URL uploads. It can be extended for specific backend services and authentication mechanisms.

async create_resource(response_type, endpoint, query_params=None, content=None, headers=None, service_port=None)

Sends a POST request to create a resource.

Parameters:

  • response_type (Type[ResponseContentTypeDef]) – The Pydantic model type to which the JSON response content should be deserialized.

  • endpoint (str) – The API endpoint path (e.g., “/items”).

  • query_params (Optional[Dict]) – Mapping of URL query parameters

  • content (Optional[RequestBodyContent]) – The request body. Accepts a Pydantic BaseModel instance (serialized according to Content-Type), a raw str, or raw bytes. Defaults to None. When headers includes a Content-Type override, the body is serialized accordingly; otherwise defaults to JSON serialization.

  • headers (Optional[dict]) – A dictionary of additional HTTP headers to send. May include Content-Type to control body serialization and Accept to control the expected response format. Defaults to None.

  • service_port (Optional[int]) – A specific port to use for this request, overriding the instance’s default port. Defaults to None.

Returns:

An instance of the response_type Pydantic model

populated with the response data.

Return type:

ResponseContentTypeDef

async delete_resource(endpoint, headers=None, service_port=None)

Sends a DELETE request to remove a resource.

Parameters:

  • endpoint (str) – The API endpoint path (e.g., “/items/123”).

  • headers (Optional[dict]) – A dictionary of additional HTTP headers to send. Defaults to None.

  • service_port (Optional[int]) – A specific port to use for this request, overriding the instance’s default port. Defaults to None.

async get_resource(response_type, endpoint, query_params=None, headers=None, service_port=None)

Sends a GET request to retrieve a resource.

Parameters:

  • response_type (Type[ResponseContentTypeDef]) – The Pydantic model type to which the JSON response content should be deserialized.

  • endpoint (str) – The API endpoint path (e.g., “/items/123”).

  • query_params (Optional[dict]) – An object containing query parameters. Its url_params_dict will be used. Defaults to None.

  • headers (Optional[dict]) – A dictionary of additional HTTP headers to send. Defaults to None.

  • service_port (Optional[int]) – A specific port to use for this request, overriding the instance’s default port. Defaults to None.

Returns:

An instance of the response_type Pydantic model

populated with the response data.

Return type:

ResponseContentTypeDef

class saigon.rest.client.BackendRestClient(alb_dns, service_port, api_version, http_client=None)

Bases: RestClient

A specific REST client for a backend service, built on RestClientBase.

This client is configured with a specific ALB DNS, service port, and API version, tailored for a typical backend service deployment.

class saigon.rest.client.RestClient(service_url, service_port=None, api_prefix='', authorizer=<saigon.rest.client.NoAuthRequestAuthorizer object>, http_client=None)

Bases: _RestClientBase

Async Rest Client.

Provides common functionalities for making HTTP requests, waiting for conditions, and handling S3 pre-signed URL uploads. It can be extended for specific backend services and authentication mechanisms.

create_resource(response_type, endpoint, query_params=None, content=None, headers=None, service_port=None)

Sends a POST request to create a resource.

Parameters:

  • response_type (Type[ResponseContentTypeDef]) – The Pydantic model type to which the JSON response content should be deserialized.

  • endpoint (str) – The API endpoint path (e.g., “/items”).

  • query_params (Optional[Dict]) – Mapping of URL query parameters

  • content (Optional[RequestBodyContent]) – The request body. Accepts a Pydantic BaseModel instance (serialized according to Content-Type), a raw str, or raw bytes. Defaults to None. When headers includes a Content-Type override, the body is serialized accordingly; otherwise defaults to JSON serialization.

  • headers (Optional[dict]) – A dictionary of additional HTTP headers to send. May include Content-Type to control body serialization and Accept to control the expected response format. Defaults to None.

  • service_port (Optional[int]) – A specific port to use for this request, overriding the instance’s default port. Defaults to None.

Returns:

An instance of the response_type Pydantic model

populated with the response data.

Return type:

ResponseContentTypeDef

delete_resource(endpoint, headers=None, service_port=None)

Sends a DELETE request to remove a resource.

Parameters:

  • endpoint (str) – The API endpoint path (e.g., “/items/123”).

  • headers (Optional[dict]) – A dictionary of additional HTTP headers to send. Defaults to None.

  • service_port (Optional[int]) – A specific port to use for this request, overriding the instance’s default port. Defaults to None.

get_resource(response_type, endpoint, query_params=None, headers=None, service_port=None)

Sends a GET request to retrieve a resource.

Parameters:

  • response_type (Type[ResponseContentTypeDef]) – The Pydantic model type to which the JSON response content should be deserialized.

  • endpoint (str) – The API endpoint path (e.g., “/items/123”).

  • query_params (Optional[dict]) – An object containing query parameters. Its url_params_dict will be used. Defaults to None.

  • headers (Optional[dict]) – A dictionary of additional HTTP headers to send. Defaults to None.

  • service_port (Optional[int]) – A specific port to use for this request, overriding the instance’s default port. Defaults to None.

Returns:

An instance of the response_type Pydantic model

populated with the response data.

Return type:

ResponseContentTypeDef

saigon.rest.client.upload_file_to_url(filepath, target_url, headers=None)

Uploads a file to an provided URL using a PUT.

Parameters:

  • filepath (pathlib.Path) – The path to the file to be uploaded.

  • target_url (str) – The target url where to PUT the request

  • headers (Dict | None) – Optional headers

Raises:

requests.exceptions.RequestException – If the HTTP PUT request to the pre-signed URL fails (non-2xx status code).