rapid-api-client 0.2.0__tar.gz → 0.3.1__tar.gz

{rapid_api_client-0.2.0 → rapid_api_client-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rapid-api-client
-Version: 0.2.0
+Version: 0.3.1
 Summary: Rapidly develop your API clients using decorators and annotations
 Author: Sébastien MB
 Author-email: seb@essembeh.org
@@ -38,10 +38,15 @@ Description-Content-Type: text/markdown
 
 # Rapid Api Client
 
-Library to rapidly develop asynchronous API clients based on [Pydantic](https://docs.pydantic.dev/) and [Httpx](https://www.python-httpx.org/) using *decorators* and *annotations*.
+Library to **rapidly** develop *API clients* in Python, based on [Pydantic](https://docs.pydantic.dev/) and [Httpx](https://www.python-httpx.org/), using almost only *decorators* and *annotations*.
 
-This project is largely inspired by [FastAPI](https://fastapi.tiangolo.com/).
+✨ Main features:
+- ✏️ You don't write any code, you only declare the endpoints using *decorators* and *annotations*.
+- 🚚 Support *Pydantic* to automatically parse and validate reponses (and also for posting content).
+- 🏗️ Does not reimplement the low-level http-related logic, it simply uses `httpx.AsyncClient` like you would do and you can customize it.
+- ⚡️ Asynchronous, because `httpx` and `asyncio` are just amazingly fast.
 
+🙏 This project is inspired by [FastAPI](https://fastapi.tiangolo.com/), I always wanted a library to create an API client that is as simple as *FastAPI* for handling the server-side part.
 
 # Usage 
 
@@ -51,12 +56,15 @@ Install the project
 pip install rapid-api-client
 ```
 
-Declare your API using decorators and annotations (the method does not need any code, it will be generated by the decorator)
+Declare your API endpoints using decorators and annotations, **the method does not need any code, it will be generated by the decorator**, just write `...` or `pass` or whatever, it won't be called anyway 🙈.
 
 ```python
 class GithubIssuesApi(RapidApi):
 
-    @get("/repos/{owner}/{repo}/issues", response_class=RootModel[List[Issue]])
+    @get("/repos/{owner}/{repo}/issues", response_class=TypeAdapter(List[Issue]))
+    async def list_issues(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
+
+    @get("/repos/{owner}/{repo}/releases", response_class=TypeAdapter(List[Release]))
     async def list_issues(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
 
 ```
@@ -66,7 +74,7 @@ Use it
 ```python
     api = GithubIssuesApi(client)
     issues = await api.list_issues("essembeh", "rapid-api-client", state="closed")
-    for issue in issues.root:
+    for issue in issues:
         print(f"Issue: {issue.title} [{issue.url}]")
 ```
 
@@ -79,13 +87,13 @@ Any HTTP method can be used with `http` decorator
 ```python
 class MyApi(RapidApi)
 
-    @http("/anything") # default is GET
+    @http("GET", "/anything")
     async def get(self): ...
 
-    @http("/anything", method="POST")
+    @http("POST", "/anything")
     async def post(self): ...
 
-    @http("/anything", method="DELETE")
+    @http("DELETE", "/anything")
     async def delete(self): ...
 ```
 
@@ -109,9 +117,15 @@ class MyApi(RapidApi)
 
 By default methods return a `httpx.Response` object and the http return code is not tested (you have to call `resp.raise_for_status()` if you need to ensure the response is OK).
 
-But you can also specify a *Pydantic model class* to automatically parse the response.
+But you can also specify a class so that the response is parsed, you can use:
+- `httpx.Response` to get the response itself, this is the default behavior
+- `str` to get the `response.text` 
+- `bytes` to get the `response.content` 
+- Any *Pydantic* model class (subclass of `BaseModel`), the *json* will be automatically validated
+- Any *Pydantic-xml* model class (subclass of `BaseXmlModel`), the *xml* will be automatically validated
+- Any `TypeAdapter` to parse the *json*, see [pydantic doc](https://docs.pydantic.dev/latest/api/type_adapter/)
 
-> Note: When a `response_class` is given, the `raise_for_status()` is always called to ensure the http response is OK
+> Note: When `response_class` is given (and is not `httpx.Response`), the `raise_for_status()` is always called to ensure the http response is OK
 
 ```python
 class User(BaseModel): ...
@@ -227,3 +241,7 @@ class MyApi(RapidApi)
     async def post_xml(self, body: Annotated[ResponseXmlRootModel, PydanticXmlBody()]): ...
 
  ```
+
+ # Examples
+
+ See [example directory](./examples/) for some examples

{rapid_api_client-0.2.0 → rapid_api_client-0.3.1}/README.md

@@ -6,10 +6,15 @@
 
 # Rapid Api Client
 
-Library to rapidly develop asynchronous API clients based on [Pydantic](https://docs.pydantic.dev/) and [Httpx](https://www.python-httpx.org/) using *decorators* and *annotations*.
+Library to **rapidly** develop *API clients* in Python, based on [Pydantic](https://docs.pydantic.dev/) and [Httpx](https://www.python-httpx.org/), using almost only *decorators* and *annotations*.
 
-This project is largely inspired by [FastAPI](https://fastapi.tiangolo.com/).
+✨ Main features:
+- ✏️ You don't write any code, you only declare the endpoints using *decorators* and *annotations*.
+- 🚚 Support *Pydantic* to automatically parse and validate reponses (and also for posting content).
+- 🏗️ Does not reimplement the low-level http-related logic, it simply uses `httpx.AsyncClient` like you would do and you can customize it.
+- ⚡️ Asynchronous, because `httpx` and `asyncio` are just amazingly fast.
 
+🙏 This project is inspired by [FastAPI](https://fastapi.tiangolo.com/), I always wanted a library to create an API client that is as simple as *FastAPI* for handling the server-side part.
 
 # Usage 
 
@@ -19,12 +24,15 @@ Install the project
 pip install rapid-api-client
 ```
 
-Declare your API using decorators and annotations (the method does not need any code, it will be generated by the decorator)
+Declare your API endpoints using decorators and annotations, **the method does not need any code, it will be generated by the decorator**, just write `...` or `pass` or whatever, it won't be called anyway 🙈.
 
 ```python
 class GithubIssuesApi(RapidApi):
 
-    @get("/repos/{owner}/{repo}/issues", response_class=RootModel[List[Issue]])
+    @get("/repos/{owner}/{repo}/issues", response_class=TypeAdapter(List[Issue]))
+    async def list_issues(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
+
+    @get("/repos/{owner}/{repo}/releases", response_class=TypeAdapter(List[Release]))
     async def list_issues(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
 
 ```
@@ -34,7 +42,7 @@ Use it
 ```python
     api = GithubIssuesApi(client)
     issues = await api.list_issues("essembeh", "rapid-api-client", state="closed")
-    for issue in issues.root:
+    for issue in issues:
         print(f"Issue: {issue.title} [{issue.url}]")
 ```
 
@@ -47,13 +55,13 @@ Any HTTP method can be used with `http` decorator
 ```python
 class MyApi(RapidApi)
 
-    @http("/anything") # default is GET
+    @http("GET", "/anything")
     async def get(self): ...
 
-    @http("/anything", method="POST")
+    @http("POST", "/anything")
     async def post(self): ...
 
-    @http("/anything", method="DELETE")
+    @http("DELETE", "/anything")
     async def delete(self): ...
 ```
 
@@ -77,9 +85,15 @@ class MyApi(RapidApi)
 
 By default methods return a `httpx.Response` object and the http return code is not tested (you have to call `resp.raise_for_status()` if you need to ensure the response is OK).
 
-But you can also specify a *Pydantic model class* to automatically parse the response.
+But you can also specify a class so that the response is parsed, you can use:
+- `httpx.Response` to get the response itself, this is the default behavior
+- `str` to get the `response.text` 
+- `bytes` to get the `response.content` 
+- Any *Pydantic* model class (subclass of `BaseModel`), the *json* will be automatically validated
+- Any *Pydantic-xml* model class (subclass of `BaseXmlModel`), the *xml* will be automatically validated
+- Any `TypeAdapter` to parse the *json*, see [pydantic doc](https://docs.pydantic.dev/latest/api/type_adapter/)
 
-> Note: When a `response_class` is given, the `raise_for_status()` is always called to ensure the http response is OK
+> Note: When `response_class` is given (and is not `httpx.Response`), the `raise_for_status()` is always called to ensure the http response is OK
 
 ```python
 class User(BaseModel): ...
@@ -194,4 +208,8 @@ class MyApi(RapidApi)
     @post("/post")
     async def post_xml(self, body: Annotated[ResponseXmlRootModel, PydanticXmlBody()]): ...
 
- ```
+ ```
+
+ # Examples
+
+ See [example directory](./examples/) for some examples

{rapid_api_client-0.2.0 → rapid_api_client-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "rapid-api-client"
-version = "0.2.0"
+version = "0.3.1"
 description = "Rapidly develop your API clients using decorators and annotations"
 authors = ["Sébastien MB <seb@essembeh.org>"]
 readme = "README.md"

{rapid_api_client-0.2.0 → rapid_api_client-0.3.1}/rapid_api_client/client.py

@@ -1,15 +1,28 @@
 from dataclasses import dataclass, field
 from functools import partial, wraps
 from inspect import Signature, signature
-from typing import Any, Awaitable, Callable, Dict, Mapping, Self, Tuple, Type, TypeVar
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    Mapping,
+    Self,
+    Tuple,
+    Type,
+    TypeVar,
+    overload,
+)
 
 from httpx import AsyncClient, Request, Response
-from pydantic import BaseModel
+from pydantic import BaseModel, TypeAdapter
+from pydantic_xml import BaseXmlModel
 
-from .model import Body, FileBody, Header, Path, Query, RapidApi, pydantic_xml
+from .model import Body, FileBody, Header, Path, Query, RapidApi
 from .utils import filter_none_values, find_annotation
 
-RESP = TypeVar("RESP", bound=BaseModel | Response)
+BM = TypeVar("BM", bound=BaseModel)
+T = TypeVar("T")
 
 
 @dataclass
@@ -76,15 +89,71 @@ def build_request(
     )
 
 
+def handle_response(
+    response: Response,
+    response_class: Type[Response | str | bytes | BM] | TypeAdapter[T],
+) -> Response | str | bytes | BM | T:
+    # do not check response status code if we return the Response itself
+    if response_class is Response:
+        return response
+    # before parsing the response, check its status
+    response.raise_for_status()
+    if response_class is str:
+        return response.text
+    if response_class is bytes:
+        return response.content
+    if isinstance(response_class, TypeAdapter):
+        return response_class.validate_json(response.content)
+    if issubclass(response_class, BaseXmlModel):
+        return response_class.from_xml(response.content)
+    if issubclass(response_class, BaseModel):
+        return response_class.model_validate_json(response.content)
+    raise ValueError(f"Response class not supported: {response_class}")
+
+
+@overload
 def http(
-    path: str, method: str = "GET", response_class: Type[RESP] = Response
-) -> Callable[[Callable], Callable[..., Awaitable[RESP]]]:
-    def decorator(func: Callable) -> Callable[..., Awaitable[RESP]]:
+    method: str, path: str, response_class: Type[Response] = Response
+) -> Callable[[Callable], Callable[..., Awaitable[Response]]]: ...
+
+
+@overload
+def http(
+    method: str, path: str, response_class: Type[str]
+) -> Callable[[Callable], Callable[..., Awaitable[str]]]: ...
+
+
+@overload
+def http(
+    method: str, path: str, response_class: Type[bytes]
+) -> Callable[[Callable], Callable[..., Awaitable[bytes]]]: ...
+
+
+@overload
+def http(
+    method: str, path: str, response_class: Type[BM]
+) -> Callable[[Callable], Callable[..., Awaitable[BM]]]: ...
+
+
+@overload
+def http(
+    method: str, path: str, response_class: TypeAdapter[T]
+) -> Callable[[Callable], Callable[..., Awaitable[T]]]: ...
+
+
+def http(
+    method: str,
+    path: str,
+    response_class: Type[BM | str | bytes | Response] | TypeAdapter[T] = Response,
+) -> Callable[[Callable], Callable[..., Awaitable[BM | str | bytes | Response | T]]]:
+    def decorator(
+        func: Callable,
+    ) -> Callable[..., Awaitable[BM | str | bytes | Response | T]]:
         sig = signature(func)
         custom_parameters = CustomParameters.from_sig(sig)
 
         @wraps(func)
-        async def wrapper(*args, **kwargs) -> RESP:
+        async def wrapper(*args, **kwargs) -> BM | str | bytes | Response | T:
             assert isinstance(
                 args[0], RapidApi
             ), f"{args[0]} should be an instance of RapidApi"
@@ -93,23 +162,15 @@ def http(
                 client, sig, custom_parameters, method, path, args, kwargs
             )
             response = await client.send(request)
-            if pydantic_xml is not None and issubclass(
-                response_class, pydantic_xml.BaseXmlModel
-            ):
-                response.raise_for_status()
-                return response_class.from_xml(response.content)
-            if issubclass(response_class, BaseModel):
-                response.raise_for_status()
-                return response_class.model_validate_json(response.content)
-            return response
+            return handle_response(response, response_class)
 
         return wrapper
 
     return decorator
 
 
-get = partial(http, method="GET")
-post = partial(http, method="POST")
-delete = partial(http, method="DELETE")
-put = partial(http, method="PUT")
-patch = partial(http, method="PATCH")
+get = partial(http, "GET")
+post = partial(http, "POST")
+delete = partial(http, "DELETE")
+put = partial(http, "PUT")
+patch = partial(http, "PATCH")