HTTP API

The HTTP API provides utilities for making HTTP requests and handling HTTP-related functionality.

Core Components

HTTPClient

get async

get(_resp: type[T] | T = dict, *, url: str, options: HTTPOptions | None = None) -> T

Send a GET request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

post async

post(_resp: type[T] | T = dict, *, url: str, content: Any | BaseModel | FormData | None, options: HTTPOptions | None = None) -> T

Send a POST request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models).	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

put async

put(_resp: type[T] | T = dict, *, url: str, content: Any | BaseModel | FormData | None, options: HTTPOptions | None = None) -> T

Send a PUT request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models).	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

patch async

patch(_resp: type[T] | T = dict, *, url: str, content: Any | BaseModel | FormData | None, options: HTTPOptions | None = None) -> T

Send a PATCH request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models).	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

delete async

delete(_resp: type[T] | T = dict, *, url: str, options: HTTPOptions | None = None) -> T

Send a DELETE request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
url	str	The URL to send the request to.	required
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None

Returns:

Name	Type	Description
T	T	The response from the server.

Raises:

Type	Description
HTTPStatusError	If an error occurs during the HTTP request.

stream

stream(_resp: type[T] | T = dict, *, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], url: str, content: Any | BaseModel | FormData | None = None, options: HTTPOptions | None = None, as_observable: Literal[True] = True) -> Observable[T]

stream(_resp: type[T] | T = dict, *, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], url: str, content: Any | BaseModel | FormData | None = None, options: HTTPOptions | None = None, as_observable: Literal[False]) -> _AsyncGeneratorContextManager[Response]

stream(_resp: type[T] | T = dict, *, method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH'], url: str, content: Any | BaseModel | FormData | None = None, options: HTTPOptions | None = None, as_observable: bool = True) -> Observable[T] | _AsyncGeneratorContextManager[Response]

Send a streaming request to a desired endpoint.

Parameters:

Name	Type	Description	Default
_resp	type[T] | T	The expected response type. Defaults to dict.	dict
method	Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']	The HTTP method to use for the request.	required
url	str	The URL to send the request to.	required
content	Any | BaseModel | None	The content to include in the request body (supports pydantic models). Defaults to None.	None
options	HTTPOptions | None	Additional options for the request. Defaults to None.	None
as_observable	bool	When True (default), returns an Observable; when False, returns an async context manager for manual streaming.	True

Returns:

Type	Description
Observable[T] | _AsyncGeneratorContextManager[Response]	Observable[T] | _AsyncGeneratorContextManager[Response]: Stream subscription helper or the raw streaming context manager.

Raises:

Type	Description
HTTPError	If an error occurs during the HTTP request.

HTTPOptions

Bases: TypedDict

Source code in ascender/common/http/types/http_options.py

class HTTPOptions(TypedDict):
    params: NotRequired[QueryParamTypes]
    headers: NotRequired[HeaderTypes]
    cookies: NotRequired[CookieTypes]
    auth: NotRequired[AuthTypes]
    follow_redirects: NotRequired[bool]
    timeout: NotRequired[TimeoutTypes]

provideHTTPClient

provideHTTPClient(base_url: str = '', interceptors: list[InterceptorFn | type[Interceptor]] = [], verify: SSLContext | str | bool = True, cert: CertTypes | None = None, trust_env: bool = True, client_instance: type[HTTPClient] = HTTPClient, **additional_configs) -> Provider

Provide a configured HTTPClient instance.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL for the HTTP client. Defaults to "".	''
interceptors	list[InterceptorFn | type[Interceptor]]	A list of interceptor functions or classes to use with the HTTP client. Defaults to [].	[]
verify	SSLContext | str | bool	Whether to verify SSL certificates. Defaults to True.	True
cert	CertTypes | None	The SSL certificate to use. Defaults to None.	None
trust_env	bool	Whether to trust the system's CA certificates. Defaults to True.	True
client_instance	type[HTTPClient]	The HTTP client class to use. Defaults to HTTPClient.	HTTPClient
**additional_configs		Additional keyword arguments forwarded to the HTTP client constructor.	{}

Returns:

Name	Type	Description
Provider	Provider	A provider for the HTTP client instance.

Interceptor

Bases: ABC

handle_request abstractmethod async

handle_request(request: InterceptorIn) -> Request

handle_response async

handle_response(response: Response)

InterceptorFn module-attribute

InterceptorFn = Callable[[Request], Awaitable[Request]]

FormData

A form data container for HTTP multipart/form-data requests.

This class provides an interface similar to the JavaScript FormData API for building multipart form data. It supports string values and file uploads via FileData.

Note

UploadFile values cannot be passed directly to the constructor. They must be added using the append() or set() methods, which handle the conversion to FileData internally.

__init__

__init__(**entries: str | FileData) -> None

Initialize FormData with key-value pairs.

Parameters:

Name	Type	Description	Default
**entries	str | FileData	Key-value pairs where values can be strings or FileData objects. Note: UploadFile values are not accepted here. Use append() or set() instead.	{}

FileData

See Also

• HTTP Client Guide - Comprehensive HTTP client guide
• Controllers - Controller request/response handling
• HTTPX Documentation - Underlying HTTP library (for http exception handling and advanced usage)