rapid-api-client 0.1.0__tar.gz

rapid_api_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sébastien MB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rapid_api_client-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.1
+Name: rapid-api-client
+Version: 0.1.0
+Summary: Rapidly develop your API clients using decorators and annotations
+Author: Sébastien MB
+Author-email: seb@essembeh.org
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx (>=0.27.2,<0.28.0)
+Requires-Dist: pydantic (>=2.9.2,<3.0.0)
+Description-Content-Type: text/markdown
+
+![Github](https://img.shields.io/github/tag/essembeh/rapid-api-client.svg)
+![PyPi](https://img.shields.io/pypi/v/rapid-api-client.svg)
+![Python](https://img.shields.io/pypi/pyversions/rapid-api-client.svg)
+![CI](https://github.com/essembeh/python-helloworld/actions/workflows/poetry.yml/badge.svg)
+
+
+# Rapid Api Client
+
+Library to rapidly develop API clients based on [Pydantic](https://docs.pydantic.dev/) and [Httpx](https://www.python-httpx.org/) using *decorators* and *annotations*.
+
+This project is largely inspired by [FastAPI](https://fastapi.tiangolo.com/).
+
+
+# Usage 
+
+Install the project
+
+```sh
+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)
+
+```python
+class GithubIssuesApi(RapidApi):
+
+    @get("/repos/{owner}/{repo}/issues", response_class=RootModel[List[Issue]])
+    def list_issues(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
+
+```
+
+Use it 
+
+```python
+    for issue in GithubIssuesApi().list_issues("essembeh", "rapid-api-client").root:
+        print("Issue:", issue)
+```
+
+# Features
+
+## Http method
+
+Any HTTP method can be used with `http` decorator
+
+```python
+class MyApi(RapidApi)
+
+    @http("/anything") # default is GET
+    def get(self): ...
+
+    @http("/anything", method="POST")
+    def post(self): ...
+
+    @http("/anything", method="DELETE)
+    def delete(self): ...
+```
+
+Convenient decorators are available like `get`, `post`, `delete`, `put`, `patch`
+
+```python
+class MyApi(RapidApi)
+
+    @get("/anything")
+    def get(self): ...
+
+    @post("/anything")
+    def post(self): ...
+
+    @delete("/anything")
+    def delete(self): ...
+```
+
+
+## Response class
+
+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.
+
+> Note: When a `response_class` is given, the `raise_for_status()` is always called to ensure the http response is OK
+
+```python
+class User(BaseModel): ...
+
+class MyApi(RapidApi)
+
+    # this method return a httpx.Response
+    @get("/user/me")
+    def get_user_resp(self): ...
+
+    # this method returns a User class
+    @get("/user/me", response_class=User)
+    def get_user(self): ...
+```
+
+
+## Path parameters
+
+Like `fastapi` you can use your method arguments to build the api path to call.
+
+```python
+class MyApi(RapidApi)
+
+    @get("/user/{user_id}")
+    def get_user(self, user_id: Annotated[int, Path()]): ...
+
+    # Path parameters dans have a default value
+    @get("/user/{user_id}")
+    def get_user(self, user_id: Annotated[int, Path()] = 1): ...
+
+```
+
+## Query parameters
+
+You can add `query parameters` to your request using the `Query` annotation.
+
+```python
+class MyApi(RapidApi)
+
+    @get("/issues")
+    def get_issues(self, sort: Annotated[str, Query()]): ...
+
+    # Query parameters can have a default value
+    @get("/issues")
+    def get_issues_default(self, sort: Annotated[str, Query()] = "date"): ...
+
+    # Query parameters can have an alias to change the key in the http request
+    @get("/issues")
+    def get_issues_alias(self, sort: Annotated[str, Query(alias="sort-by")] = "date"): ...
+```
+
+
+## Header parameter
+
+You can add `headers` to your request using the `Header` annotation.
+
+```python
+class MyApi(RapidApi)
+
+    @get("/issues")
+    def get_issues(self, version: Annotated[str, Header()]): ...
+
+    # Headers can have a default value
+    @get("/issues")
+    def get_issues(self, version: Annotated[str, Header()] = "1"): ...
+
+    # Headers can have an alias to change the key in the http request
+    @get("/issues")
+    def get_issues(self, version: Annotated[str, Header(alias="X-API-Version")] = "1"): ...
+```
+
+## Body parameter
+
+

rapid_api_client-0.1.0/README.md

@@ -0,0 +1,153 @@
+![Github](https://img.shields.io/github/tag/essembeh/rapid-api-client.svg)
+![PyPi](https://img.shields.io/pypi/v/rapid-api-client.svg)
+![Python](https://img.shields.io/pypi/pyversions/rapid-api-client.svg)
+![CI](https://github.com/essembeh/python-helloworld/actions/workflows/poetry.yml/badge.svg)
+
+
+# Rapid Api Client
+
+Library to rapidly develop API clients based on [Pydantic](https://docs.pydantic.dev/) and [Httpx](https://www.python-httpx.org/) using *decorators* and *annotations*.
+
+This project is largely inspired by [FastAPI](https://fastapi.tiangolo.com/).
+
+
+# Usage 
+
+Install the project
+
+```sh
+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)
+
+```python
+class GithubIssuesApi(RapidApi):
+
+    @get("/repos/{owner}/{repo}/issues", response_class=RootModel[List[Issue]])
+    def list_issues(self, owner: Annotated[str, Path()], repo: Annotated[str, Path()]): ...
+
+```
+
+Use it 
+
+```python
+    for issue in GithubIssuesApi().list_issues("essembeh", "rapid-api-client").root:
+        print("Issue:", issue)
+```
+
+# Features
+
+## Http method
+
+Any HTTP method can be used with `http` decorator
+
+```python
+class MyApi(RapidApi)
+
+    @http("/anything") # default is GET
+    def get(self): ...
+
+    @http("/anything", method="POST")
+    def post(self): ...
+
+    @http("/anything", method="DELETE)
+    def delete(self): ...
+```
+
+Convenient decorators are available like `get`, `post`, `delete`, `put`, `patch`
+
+```python
+class MyApi(RapidApi)
+
+    @get("/anything")
+    def get(self): ...
+
+    @post("/anything")
+    def post(self): ...
+
+    @delete("/anything")
+    def delete(self): ...
+```
+
+
+## Response class
+
+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.
+
+> Note: When a `response_class` is given, the `raise_for_status()` is always called to ensure the http response is OK
+
+```python
+class User(BaseModel): ...
+
+class MyApi(RapidApi)
+
+    # this method return a httpx.Response
+    @get("/user/me")
+    def get_user_resp(self): ...
+
+    # this method returns a User class
+    @get("/user/me", response_class=User)
+    def get_user(self): ...
+```
+
+
+## Path parameters
+
+Like `fastapi` you can use your method arguments to build the api path to call.
+
+```python
+class MyApi(RapidApi)
+
+    @get("/user/{user_id}")
+    def get_user(self, user_id: Annotated[int, Path()]): ...
+
+    # Path parameters dans have a default value
+    @get("/user/{user_id}")
+    def get_user(self, user_id: Annotated[int, Path()] = 1): ...
+
+```
+
+## Query parameters
+
+You can add `query parameters` to your request using the `Query` annotation.
+
+```python
+class MyApi(RapidApi)
+
+    @get("/issues")
+    def get_issues(self, sort: Annotated[str, Query()]): ...
+
+    # Query parameters can have a default value
+    @get("/issues")
+    def get_issues_default(self, sort: Annotated[str, Query()] = "date"): ...
+
+    # Query parameters can have an alias to change the key in the http request
+    @get("/issues")
+    def get_issues_alias(self, sort: Annotated[str, Query(alias="sort-by")] = "date"): ...
+```
+
+
+## Header parameter
+
+You can add `headers` to your request using the `Header` annotation.
+
+```python
+class MyApi(RapidApi)
+
+    @get("/issues")
+    def get_issues(self, version: Annotated[str, Header()]): ...
+
+    # Headers can have a default value
+    @get("/issues")
+    def get_issues(self, version: Annotated[str, Header()] = "1"): ...
+
+    # Headers can have an alias to change the key in the http request
+    @get("/issues")
+    def get_issues(self, version: Annotated[str, Header(alias="X-API-Version")] = "1"): ...
+```
+
+## Body parameter
+

rapid_api_client-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "rapid-api-client"
+version = "0.1.0"
+description = "Rapidly develop your API clients using decorators and annotations"
+authors = ["Sébastien MB <seb@essembeh.org>"]
+readme = "README.md"
+classifiers = [
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: AsyncIO",
+    "Framework :: Pydantic",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Homepage = "https://github.com/essembeh/rapid-api-client"
+Repository = "https://github.com/essembeh/rapid-api-client"
+Issues = "https://github.com/essembeh/rapid-api-client/issues"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pydantic = "^2.9.2"
+httpx = "^0.27.2"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.3"
+pytest-asyncio = "^0.24.0"
+pytest-cov = "^5.0.0"
+pytest-dotenv = {extras = ["cli"], version = "^0.5.2"}
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

rapid_api_client-0.1.0/rapid_api_client/__init__.py

@@ -0,0 +1,21 @@
+from importlib.metadata import version
+
+from .client import delete, get, http, patch, post, put
+from .model import Body, FileBody, Header, Path, PydanticBody, Query, RapidApi
+
+__version__ = version(__name__)
+__all__ = [
+    "Body",
+    "FileBody",
+    "Header",
+    "Path",
+    "PydanticBody",
+    "Query",
+    "RapidApi",
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "http",
+]

rapid_api_client-0.1.0/rapid_api_client/client.py

@@ -0,0 +1,110 @@
+from dataclasses import dataclass, field
+from functools import partial, wraps
+from inspect import Signature, signature
+from typing import Any, Callable, Dict, Mapping, Self, Tuple, Type, TypeVar
+
+from httpx import Client, Request, Response
+from pydantic import BaseModel
+
+from .model import Body, FileBody, Header, Path, Query, RapidApi
+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
+
+
+def build_request(
+    client: Client,
+    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 client.build_request(
+        method, path, headers=headers, params=params, content=content, files=files
+    )
+
+
+def http(
+    path: str, method: str = "GET", response_class: Type[RESP] = Response
+) -> Callable[[Callable], Callable[..., RESP]]:
+    def decorator(func: Callable) -> Callable[..., RESP]:
+        sig = signature(func)
+        custom_parameters = CustomParameters.from_sig(sig)
+
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> RESP:
+            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
+            )
+            response = client.send(request)
+            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")

rapid_api_client-0.1.0/rapid_api_client/model.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+from httpx import Client
+from pydantic import BaseModel
+
+
+@dataclass
+class RapidApi:
+    client: Client = field(default_factory=Client)
+
+
+class CustomParameter: ...
+
+
+class Path(CustomParameter): ...
+
+
+@dataclass
+class Query(CustomParameter):
+    alias: str | None = None
+
+
+@dataclass
+class Header(CustomParameter):
+    alias: str | None = None
+
+
+class Body(CustomParameter):
+    def serialize(self, body: Any) -> str | bytes:
+        return body
+
+
+@dataclass
+class FileBody(Body):
+    alias: str | None = None
+
+    def serialize(self, body: Any) -> str | bytes:
+        return body
+
+
+@dataclass
+class PydanticBody(Body):
+    prettyprint: bool = False
+
+    def serialize(self, body: Any) -> str | bytes:
+        assert isinstance(body, BaseModel)
+        return body.model_dump_json(indent=2 if self.prettyprint else None)

rapid_api_client-0.1.0/rapid_api_client/utils.py

@@ -0,0 +1,18 @@
+from inspect import Parameter
+from typing import Any, Dict, Type, TypeVar, get_args
+
+from rapid_api_client.model import CustomParameter
+
+CP = TypeVar("CP", bound=CustomParameter)
+
+
+def filter_none_values(values: Dict[str, Any | None]) -> Dict[str, Any]:
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def find_annotation(param: Parameter, cls: Type[CP]) -> CP | None:
+    if param.annotation:
+        for an in get_args(param.annotation):
+            if isinstance(an, cls):
+                return an
+    return None