Lapidary

Python DSL for Web API clients.

Why

Web API clients follow a relatively small set of patterns and implementing them is rather repetitive task. Encapsulating these patterns in form of a DSL library frees its users from coding the same patterns over and over again.

How

Lapidary is an internal (in-python) DSL made of decorators and annotations, that can be used to describe Web APIs similarly to OpenAPI. (lapidary-render can convert a large subset of OpenAPI 3.0 to Lapidary).

At runtime, the library interprets user-provided function declarations (without bodies), and makes them behave as declared. If a function accepts parameter of type X and returns Y, Lapidary will try to convert X to HTTP request and the response to Y.

Example:

class CatClient(ClientBase):
    """This class is a working API client"""

    def __init__(self):
        super().__init__(
            base_url='https://example.com/api',
        )

    @get('/cat')
    async def list_cats(self: Self) -> Annotated[
        tuple[list[Cat], CatListMeta],
        Responses({
            '2XX': Response(
                Body({
                    'application/json': list[Cat],
                }),
                CatListMeta
            ),
        })
    ]:
       pass

client = CatClient()
cats_body, cats_meta = await client.list_cats()