rapid-api-client 0.3.0__tar.gz → 0.3.2__tar.gz

{rapid_api_client-0.3.0 → rapid_api_client-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: rapid-api-client
-Version: 0.3.0
+Version: 0.3.2
 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,14 +56,17 @@ 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_releases(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
+
 ```
 
 Use it 
@@ -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): ...
 ```
 
@@ -101,7 +109,7 @@ class MyApi(RapidApi)
     async def post(self): ...
 
     @delete("/anything")
-    async ef delete(self): ...
+    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): ...
@@ -231,3 +245,4 @@ class MyApi(RapidApi)
  # Examples
 
  See [example directory](./examples/) for some examples
+

{rapid_api_client-0.3.0 → rapid_api_client-0.3.2}/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,14 +24,17 @@ 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_releases(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
+
 ```
 
 Use it 
@@ -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): ...
 ```
 
@@ -69,7 +77,7 @@ class MyApi(RapidApi)
     async def post(self): ...
 
     @delete("/anything")
-    async ef delete(self): ...
+    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): ...
@@ -198,4 +212,4 @@ class MyApi(RapidApi)
 
  # Examples
 
- See [example directory](./examples/) for some examples
+ See [example directory](./examples/) for some examples

{rapid_api_client-0.3.0 → rapid_api_client-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "rapid-api-client"
-version = "0.3.0"
+version = "0.3.2"
 description = "Rapidly develop your API clients using decorators and annotations"
 authors = ["Sébastien MB <seb@essembeh.org>"]
 readme = "README.md"
@@ -44,6 +44,8 @@ pytest-asyncio = "^0.24.0"
 pytest-cov = "^5.0.0"
 pytest-dotenv = {extras = ["cli"], version = "^0.5.2"}
 pydantic-xml = "^2.13.0"
+mypy = "^1.11.2"
+pylint = "^3.3.1"
 
 [build-system]
 requires = ["poetry-core"]

{rapid_api_client-0.3.0 → rapid_api_client-0.3.2}/rapid_api_client/__init__.py

@@ -1,3 +1,7 @@
+"""
+rapid-api-client
+"""
+
 from importlib.metadata import version
 
 from .client import delete, get, http, patch, post, put

rapid_api_client-0.3.2/rapid_api_client/client.py

@@ -0,0 +1,218 @@
+"""
+Decorator used to build the httpx request
+"""
+
+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,
+    overload,
+)
+
+from httpx import AsyncClient, Request, Response
+from pydantic import BaseModel, TypeAdapter
+from pydantic_xml import BaseXmlModel
+
+from .model import Body, CustomParameter, FileBody, Header, Path, Query, RapidApi
+from .utils import filter_none_values, find_annotation
+
+BM = TypeVar("BM", bound=BaseModel)
+T = TypeVar("T")
+
+
+@dataclass
+class CustomParameters:
+    """
+    Class containing all custom parameters used to build the request.
+    """
+
+    path: Dict[str, Path] = field(default_factory=dict)
+    query: Dict[str, Query] = field(default_factory=dict)
+    headers: Dict[str, Header] = field(default_factory=dict)
+    body: Dict[str, Body] = field(default_factory=dict)
+
+    @classmethod
+    def from_sig(cls, sig: Signature) -> Self:
+        """
+        Iterate over parameters of given function to find annotated parameters
+        """
+        out = cls()
+        for parameter in sig.parameters.values():
+            annot: CustomParameter | None = None
+            if (annot := find_annotation(parameter, Path)) is not None:
+                out.path[parameter.name] = annot
+            if (annot := find_annotation(parameter, Query)) is not None:
+                out.query[parameter.name] = annot
+            if (annot := find_annotation(parameter, Header)) is not None:
+                out.headers[parameter.name] = annot
+            if (annot := find_annotation(parameter, Body)) is not None:
+                out.body[parameter.name] = annot
+        return out
+
+
+def build_request(
+    client: AsyncClient,
+    sig: Signature,
+    parameters: CustomParameters,
+    method: str,
+    path: str,
+    args: Tuple[Any],
+    kwargs: Mapping[str, Any],
+    timeout: float | None,
+) -> Request:
+    """
+    Build the httpx request with given custom parameters.
+    """
+    # valuate arguments with default values
+    ba = sig.bind(*args, **kwargs)
+    ba.apply_defaults()
+
+    # resolve the api path
+    path = path.format(**{k: ba.arguments[k] for k in parameters.path})
+
+    build_kwargs: Dict[str, Any] = {}
+
+    build_kwargs["headers"] = filter_none_values(
+        {
+            annot.alias or param: ba.arguments[param]
+            for param, annot in parameters.headers.items()
+        }
+    )
+    build_kwargs["params"] = filter_none_values(
+        {
+            annot.alias or param: ba.arguments[param]
+            for param, annot in parameters.query.items()
+        }
+    )
+    for param, annot in parameters.body.items():
+        if (value := ba.arguments[param]) is not None:
+            if isinstance(annot, FileBody):
+                files = build_kwargs.setdefault("files", {})
+                files[annot.alias or param] = annot.serialize(value)
+            else:
+                build_kwargs["content"] = annot.serialize(value)
+
+    # handle extra optional kwargs
+    if timeout is not None:
+        build_kwargs["timeout"] = timeout
+
+    return client.build_request(method, path, **build_kwargs)
+
+
+def handle_response(
+    response: Response,
+    response_class: Type[Response | str | bytes | BM] | TypeAdapter[T],
+) -> Response | str | bytes | BM | T:
+    """
+    Parse the response given the expected class
+    """
+    # 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(
+    method: str,
+    path: str,
+    response_class: Type[Response] = Response,
+    timeout: float | None = None,
+) -> Callable[[Callable], Callable[..., Awaitable[Response]]]: ...
+
+
+@overload
+def http(
+    method: str,
+    path: str,
+    response_class: Type[str],
+    timeout: float | None = None,
+) -> Callable[[Callable], Callable[..., Awaitable[str]]]: ...
+
+
+@overload
+def http(
+    method: str,
+    path: str,
+    response_class: Type[bytes],
+    timeout: float | None = None,
+) -> Callable[[Callable], Callable[..., Awaitable[bytes]]]: ...
+
+
+@overload
+def http(
+    method: str,
+    path: str,
+    response_class: Type[BM],
+    timeout: float | None = None,
+) -> Callable[[Callable], Callable[..., Awaitable[BM]]]: ...
+
+
+@overload
+def http(
+    method: str,
+    path: str,
+    response_class: TypeAdapter[T],
+    timeout: float | None = None,
+) -> Callable[[Callable], Callable[..., Awaitable[T]]]: ...
+
+
+def http(
+    method: str,
+    path: str,
+    response_class: Type[BM | str | bytes | Response] | TypeAdapter[T] = Response,
+    timeout: float | None = None,
+) -> Callable[[Callable], Callable[..., Awaitable[BM | str | bytes | Response | T]]]:
+    """
+    Main decorator used to generate an http request and return its result
+    """
+
+    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) -> BM | str | bytes | Response | T:
+            assert isinstance(
+                args[0], RapidApi
+            ), f"{args[0]} should be an instance of RapidApi"
+            client = args[0].client
+            request = build_request(
+                client, sig, custom_parameters, method, path, args, kwargs, timeout
+            )
+            response = await client.send(request)
+            return handle_response(response, response_class)
+
+        return wrapper
+
+    return decorator
+
+
+get = partial(http, "GET")
+post = partial(http, "POST")
+delete = partial(http, "DELETE")
+put = partial(http, "PUT")
+patch = partial(http, "PATCH")

{rapid_api_client-0.3.0 → rapid_api_client-0.3.2}/rapid_api_client/model.py

@@ -1,5 +1,9 @@
+"""
+Model classes
+"""
+
 from dataclasses import dataclass, field
-from typing import Any, Dict
+from typing import Any
 
 from httpx import AsyncClient
 from pydantic import BaseModel
@@ -12,58 +16,97 @@ except ImportError:  # pragma: nocover
 
 @dataclass
 class RapidApi:
-    client: AsyncClient = field(default_factory=AsyncClient)
-
+    """
+    Represent an API, a RapidApi subclass should have methods decorated with @http
+    which are endpoints
+    """
 
-class RequestModifier:
-    def update_headers(self, headers: Dict[str, str]) -> Dict[str, str]: ...
-
-    def update_query(self, query_parameters: Dict[str, str]) -> Dict[str, str]: ...
-
-    def update_path(self, path: str) -> str: ...
+    client: AsyncClient = field(default_factory=AsyncClient)
 
 
-class CustomParameter: ...
+class CustomParameter:
+    """
+    Meta class for annotations used to customize the request build
+    """
 
 
-class Path(CustomParameter): ...
+class Path(CustomParameter):
+    """
+    Annotation to declare an argument used to resolve the api path/url
+    """
 
 
 @dataclass
 class Query(CustomParameter):
+    """
+    Annotation to declare an argument used as a query parameter
+    """
+
     alias: str | None = None
 
 
 @dataclass
 class Header(CustomParameter):
+    """
+    Annotation to declare an argument used as a request header
+    """
+
     alias: str | None = None
 
 
 class Body(CustomParameter):
+    """
+    Annotation to declare an argument used as http content for post/put/...
+    """
+
     def serialize(self, body: Any) -> str | bytes:
+        """
+        Serialize the annotated parameter value
+        """
         return body
 
 
 @dataclass
 class FileBody(Body):
+    """
+    Annotation to declare an argument used as file to be uploaded
+    """
+
     alias: str | None = None
 
     def serialize(self, body: Any) -> str | bytes:
+        """
+        Serialize the annotated parameter value
+        """
         return body
 
 
 @dataclass
 class PydanticBody(Body):
+    """
+    Annotation to declare an argument to be serialized to json and used as http content
+    """
+
     prettyprint: bool = False
 
     def serialize(self, body: Any) -> str | bytes:
+        """
+        Serialize the annotated parameter value
+        """
         assert isinstance(body, BaseModel)
         return body.model_dump_json(indent=2 if self.prettyprint else None)
 
 
 @dataclass
 class PydanticXmlBody(Body):
+    """
+    Annotation to declare an argument to be serialized to xml and used as http content
+    """
+
     def serialize(self, body: Any) -> str | bytes:
+        """
+        Serialize the annotated parameter value
+        """
         assert (
             pydantic_xml is not None
         ), "pydantic-xml must be installed to use PydanticXmlBody"

{rapid_api_client-0.3.0 → rapid_api_client-0.3.2}/rapid_api_client/utils.py

@@ -1,3 +1,7 @@
+"""
+Utility methods
+"""
+
 from inspect import Parameter
 from typing import Any, Dict, Type, TypeVar, get_args
 
@@ -7,10 +11,16 @@ CP = TypeVar("CP", bound=CustomParameter)
 
 
 def filter_none_values(values: Dict[str, Any | None]) -> Dict[str, Any]:
+    """
+    Return a new map with only key/value if the value is set.
+    """
     return {k: v for k, v in values.items() if v is not None}
 
 
 def find_annotation(param: Parameter, cls: Type[CP]) -> CP | None:
+    """
+    Check if the given parameter has an annotation which is or is a subclass of given type
+    """
     if param.annotation:
         for an in get_args(param.annotation):
             if isinstance(an, cls):

rapid_api_client-0.3.0/rapid_api_client/client.py

@@ -1,145 +0,0 @@
-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 httpx import AsyncClient, Request, Response
-from pydantic import BaseModel
-
-from .model import (
-    Body,
-    FileBody,
-    Header,
-    Path,
-    Query,
-    RapidApi,
-    pydantic_xml,
-)
-from .utils import filter_none_values, find_annotation
-
-RESP = TypeVar("RESP", bound=BaseModel | Response)
-
-
-@dataclass
-class CustomParameters:
-    path: Dict[str, Path] = field(default_factory=dict)
-    query: Dict[str, Query] = field(default_factory=dict)
-    headers: Dict[str, Header] = field(default_factory=dict)
-    body: Dict[str, Body] = field(default_factory=dict)
-
-    @classmethod
-    def from_sig(cls, signature: Signature) -> Self:
-        out = cls()
-        for parameter in signature.parameters.values():
-            if (annot := find_annotation(parameter, Path)) is not None:
-                out.path[parameter.name] = annot
-            if (annot := find_annotation(parameter, Query)) is not None:
-                out.query[parameter.name] = annot
-            if (annot := find_annotation(parameter, Header)) is not None:
-                out.headers[parameter.name] = annot
-            if (annot := find_annotation(parameter, Body)) is not None:
-                out.body[parameter.name] = annot
-        return out
-
-
-REQUEST_BUILDER = Callable[..., Request]
-
-
-def create_request(
-    client: AsyncClient,
-    request_builder: Callable[..., Request],
-    signature: Signature,
-    parameters: CustomParameters,
-    method: str,
-    path: str,
-    args: Tuple[Any],
-    kwargs: Mapping[str, Any],
-) -> Request:
-    # valuate arguments with default values
-    ba = signature.bind(*args, **kwargs)
-    ba.apply_defaults()
-
-    # resolve the api path
-    path = path.format(**{k: ba.arguments[k] for k in parameters.path})
-
-    headers = filter_none_values(
-        {
-            annot.alias or param: ba.arguments[param]
-            for param, annot in parameters.headers.items()
-        }
-    )
-
-    params = filter_none_values(
-        {
-            annot.alias or param: ba.arguments[param]
-            for param, annot in parameters.query.items()
-        }
-    )
-
-    content = None
-    files = {}
-    for param, annot in parameters.body.items():
-        if (value := ba.arguments[param]) is not None:
-            if isinstance(annot, FileBody):
-                files[annot.alias or param] = annot.serialize(value)
-            else:
-                content = annot.serialize(value)
-
-    return request_builder(
-        client,
-        method,
-        path,
-        headers=headers,
-        params=params,
-        content=content,
-        files=files,
-    )
-
-
-def http(
-    path: str,
-    method: str = "GET",
-    response_class: Type[RESP] = Response,
-    request_builder: Callable[..., Request] = AsyncClient.build_request,
-) -> Callable[[Callable], Callable[..., Awaitable[RESP]]]:
-    def decorator(func: Callable) -> Callable[..., Awaitable[RESP]]:
-        sig = signature(func)
-        custom_parameters = CustomParameters.from_sig(sig)
-
-        @wraps(func)
-        async def wrapper(*args, **kwargs) -> RESP:
-            assert isinstance(
-                args[0], RapidApi
-            ), f"{args[0]} should be an instance of RapidApi"
-            client = args[0].client
-            request = create_request(
-                client,
-                request_builder,
-                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 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")