Lima-API is sync and async library that allows implements Rest APIs libs with python typing.
Project description
Lima-API
Lima-API is sync and async library that allows implements Rest APIs libs with python typing.
You could read more about it on our post (Spanish).
Howto use it
- Create your Pydantic models.
from pydantic import BaseModel from pydantic.fields import Field class Pet(BaseModel): identifier: int = Field(alias="id") name: str
- Create your exceptions extend from
lima_api.LimaException
import lima_api class PetNotFoundError(lima_api.LimaException): ... class InvalidDataError(lima_api.LimaException): ...
- Create your class extend from
lima_api.SyncLimaApi
orlima_api.LimaApi
.import lima_api ... class PetApi(lima_api.LimaApi): response_mapping = { 404: PetNotFoundError, }
- Create functions with the proper decorator.
import lima_api ... class PetApi(lima_api.LimaApi): ... @lima_api.get( "/pet/{petId}", response_mapping={ 400: InvalidDataError, } ) async def get_pet(self, *, petId: int) -> Pet: ...
- Create the client instance.
pet_client = PetApi("https://petstore.swagger.io/v2") async with pet_client: pet = await pet_client.get_pet(pet_id=1)
In some case you want remove APIs complexity( for example, pagination creating a private function with decorator and public one without it:
class StApi(lima_api.LimaApi):
@lima_api.get("/v1/rest/animal/search")
async def _animals_search(
self,
*,
page_number: int = lima_api.QueryParameter(alias="pageNumber"),
page_size: int = lima_api.QueryParameter(alias="pageSize", default=100),
) -> AnimalBaseResponse: ...
async def list_animals(self) -> AsyncIterator[AnimalBase]:
page_number = 0
page = await self._search(page_number=page_number)
while not page.page.lastPage:
for animal in page.animals:
yield animal
page_number += 1
page = await self._search(page_number=page_number)
for animal in page.animals:
yield animal
[!NOTE]
- Synchronous clients only support synchronous functions, and in the same way with asynchronous.
- You could see other code examples at docs/examples folder.
[!IMPORTANT]
- The Body param must be allways
BaseModel
calls and only one is valid- Functions wrapped by lima_api always must use *, in order to force use keywords for calling functions.
Parameters types
The functions parameters will mapping with the following criteria.
-
You could define the location of the param using
lima_api.LimaParameter
(one of the followingslima_api.PathParameter
,lima_api.QueryParameter
orlima_api.BodyParameter
) classes.from enum import Enum import lima_api from pydantic import BaseModel ... class PetUpdateStatus(BaseModel): name: str status: str class PetStatus(str, Enum): AVAILABLE = "available" PENDING = "pending" SOLD = "sold" class PetApi(lima_api.LimaApi): ... @lima_api.post( "/pets/{petId}", headers={"content-type": "application/x-www-form-urlencoded"}, response_mapping={405: InvalidDataError} ) async def get_update_pet( self, *, pet_id: int = lima_api.PathParameter(alias="petId"), data: PetUpdateStatus = lima_api.BodyParameter(), ) -> None: ... @lima_api.get("/pet/findByStatus") async def filter( self, *, status: list[PetStatus] = lima_api.QueryParameter(default=[]), ) -> list[Pet]: ...
-
The parameters that extend from
pydantic.BaseModel
will send to body by default except if the method isGET
, in this case will send as query params.from enum import Enum import lima_api from pydantic import BaseModel ... class PetStatus(str, Enum): AVAILABLE = "available" PENDING = "pending" SOLD = "sold" class PetFilterStatus(BaseModel): status: list[PetStatus] class PetApi(lima_api.LimaApi): ... @lima_api.get("/pet/findByStatus") async def filter(self, *, status: list[PetStatus]) -> list[Pet]: ... @lima_api.get("/pet/findByStatus") async def filter_by_obj(self, *, data: PetFilterStatus) -> list[Pet]: ...
-
At the end with the regex expressed in
LimaSettings.lima_bracket_regex
will get the names in the path params and macht the param names defined in the function.For example with
lima_bracket_regex = r"\[(.+?)\]"
@lima_api.get("/pets/[petId]") async def get_pet(self, petId: str) -> Pet: ...
Helps for developers
By default, lima-api don't log any information, whoever in some cases you need log information.
In order to solve this and becases the log level could be different for each case, we decide create the function def log(self, *, event: lima_api.LogEvent, **kwargs)
which could be overwritten.
Create requirement file locally
uv pip compile pyproject.toml --extra=test --extra=pydantic2 > requirements.txt
uv pip install requirements.txt
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.