mantelo.internal.api

This module is highly inspired from the awesome slumber library. I decided to port it to mantelo (with some improvements) due to the lack of active development in slumber since 2018.

Please, do not use API directly, but use KeycloakAdmin instead.

Attributes

DecodedResponse	The decoded response as a dict, or as a string if no serializer is defined
HttpResponse	Either the decoded response or a tuple with the raw response and the decoded body

Classes

Store	The holder of all the state for a given resource.
Resource	The magic behind URL translation.
API	The main entry point for making HTTP calls to a specific API.

Functions

url_join(→ str)

Join any number of segments to a base URL.

Module Contents

type mantelo.internal.api.DecodedResponse = dict | str | bytes

The decoded response as a dict, or as a string if no serializer is defined or the body is empty. If the body cannot be decoded, the raw bytes are returned instead of throwing an error.

type mantelo.internal.api.HttpResponse = DecodedResponse | tuple[requests.Response, DecodedResponse]

Either the decoded response or a tuple with the raw response and the decoded body (see Resource.as_raw()).

mantelo.internal.api.url_join(base: str, *args: Any) → str

Join any number of segments to a base URL. Segments not of type string will be converted to strings using str().

class mantelo.internal.api.Store

The holder of all the state for a given resource. It is immutable, use evolve() to create a new instance with updated values.

base_url: str

The URL this resource targets.

session: requests.Session

The session to use for all HTTP requests.

serializers: list[mantelo.internal.serializers.BaseSerializer]

The serializers available for decoding the response’s data. The first serializer is the default one, used also for encoding the request’s data.

append_slash: bool = True

Whether to append a slash to the URL before making the request.

raw: bool = False

Whether to return the raw response object along with the decoded body.

property default_serializer: mantelo.internal.serializers.BaseSerializer

The serializer used to encode the request’s data.

get_serializer(content_type: str) → mantelo.internal.serializers.BaseSerializer | None

Get the first serializer that matches the given content type, if any.

evolve(**kwargs: Any) → Store

Create a new instance with the given values mutated.

class mantelo.internal.api.Resource(store: Store)

The magic behind URL translation.

It provides the magic of translating python code to URLs and HTTP calls. Each instance of a resource is tied to a specific URL, and can evolve to a new URL by calling an unknown property or attribute. To finally make an HTTP call, use one of the defined methods (get(), post(), etc).

By default, all HTTP calls return the decoded body (see HttpResponse), but you can also get hold of the raw response by calling as_raw().

Parameters:

store (_Store) – The store object that holds all the state for this resource.

__getattr__(item: str) → Resource

Add a path segment to the URL.

__call__(id: Any = None, /, url_override: str | None = None) → Resource

Add a path segment to the URL, or override the URL entirely.

Use it instead of __getattr__() either for readability (e.g. api.user("xxx")), or because the path segment isn’t valid Python (e.g. api("123")).

Parameters:

• id (any, optional) – The path segment to add to the URL.

• url_override (string, optional) – The URL to use instead of the current one.

Returns:

A new resource with the updated URL.

Return type:

Resource

as_raw() → Resource

Make the HTTP calls return both the raw response object and the decoded body.

get(**kwargs: Any) → HttpResponse

Do a GET request.

Parameters:

kwargs – The query parameters to send with the request.

Return type:

HttpResponse

options(**kwargs: Any) → HttpResponse

Do an OPTION request.

Parameters:

kwargs – The query parameters to send with the request.

Return type:

HttpResponse

head(**kwargs: Any) → HttpResponse

Do a HEAD request.

Parameters:

kwargs – The query parameters to send with the request.

Return type:

HttpResponse

post(data: dict | None = None, files: dict | None = None, **kwargs: Any) → HttpResponse

Do a POST request.

Parameters:

• data (dict, optional) – The data to send with the request.

• files (dict, optional) – The files to send with the request. Supersedes :param:data. See requests.post for more information.

• kwargs – The query parameters to send with the request.

Return type:

HttpResponse

patch(data: dict | None = None, files: dict | None = None, **kwargs: Any) → HttpResponse

Do a PATCH request. Parameters are the same as post().

Return type:

HttpResponse

put(data: dict | None = None, files: dict | None = None, **kwargs: Any) → HttpResponse

Do a PUT request. Parameters are the same as post().

Return type:

HttpResponse

delete(data: dict | None = None, files: dict | None = None, **kwargs: Any) → bool | tuple[requests.Response, bool]

Do a DELETE request. Parameters are the same as post().

Note: some APIs such as the Keycloak Admin REST Api do not follow the HTTP spec and expect a body in the request (e.g. DELETE /admin/realms/{realm}/users/{user-id}/role-mappings/clients/{client-id}).

Returns:

True if the request was successful, False for 3xx status codes.

Return type:

bool

url() → str

Get the URL that will be used for the next HTTP call.

class mantelo.internal.api.API(base_url: str, auth: requests.auth.AuthBase | None = None, append_slash: bool = True, session: requests.Session | None = None, serializers: list[mantelo.internal.serializers.BaseSerializer] | None = None, raw: bool = False)

Bases: Resource

The main entry point for making HTTP calls to a specific API.

Highly inspired by the awesome slumber library, this class defines default parameters for all the requests to an API, such as the base URL, the serializers to use, and the session to use for all requests. Once you have an API object, you can start making calls using, e.g. api.users.get().

Do NOT use it directly, see KeycloakAdmin instead.

Parameters:

• base_url (string) – The base URL for the API.

• auth (requests.auth.AuthBase, optional) – The authentication object to use for all requests.

• append_slash (bool, optional) – Whether to append a slash to the URL before making the request.

• session (requests.Session, optional) – The session to use for all request (API and authentication).

• serializers (list[BaseSerializer], optional) – The serializers to use for encoding and decoding the requests and responses. The first serializer in the list is used for encoding the request’s data. Supports JSON by default.

• raw (bool, optional) – Whether to return the raw response object along with the decoded body.