Add example for base_http_client

Author: andy-takker

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ default_language_version:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-ast
@@ -23,7 +23,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.10
+    rev: v0.7.2
     hooks:
       - id: ruff
         args: [--fix]

Makefile

@@ -1,6 +1,6 @@
 PROJECT_NAME = base_http_client
 
-develop:
+develop: clean_dev
 	python3.10 -m venv .venv
 	.venv/bin/pip install -U pip poetry
 	.venv/bin/poetry config virtualenvs.create false
@@ -21,4 +21,7 @@ mypy-ci: ##@Linting Run mypy
 	mypy ./$(PROJECT_NAME) --config-file ./pyproject.toml
 
 rst-ci: ##@Linting Run rst-lint
-	rst-lint --encoding utf-8 README.rst
+	rst-lint --encoding utf-8 README.rst
+
+clean_dev:
+	rm -rf .venv

README.rst

@@ -26,13 +26,13 @@ Installing from PyPI_:
 
 .. code-block:: bash
 
-   pip3 install base-http-client
+   pip install base-http-client
 
 Installing from github.com:
 
 .. code-block:: bash
 
-   pip3 install git+https://github.com/andy-takker/base_http_client
+   pip install git+https://github.com/andy-takker/base_http_client
 
 The package contains several extras and you can install additional dependencies
 if you specify them in this way.
@@ -45,18 +45,52 @@ For example, with msgspec_:
 
 Complete table of extras below:
 
-+-----------------------------------------------+----------------------------------+
-| example                                       | description                      |
-+===============================================+==================================+
-| ``pip3 install "base-http-client[msgspec]"``  | For using msgspec_ structs       |
-+-----------------------------------------------+----------------------------------+
-| ``pip3 install "base-http-client[orjson]"``   | For fast parsing json by orjson_ |
-+-----------------------------------------------+----------------------------------+
-| ``pip3 install "base-http-client[pydantic]"`` | For using pydantic_ models       |
-+-----------------------------------------------+----------------------------------+
++----------------------------------------------+----------------------------------+
+| example                                      | description                      |
++==============================================+==================================+
+| ``pip install "base-http-client[msgspec]"``  | For using msgspec_ structs       |
++----------------------------------------------+----------------------------------+
+| ``pip install "base-http-client[orjson]"``   | For fast parsing json by orjson_ |
++----------------------------------------------+----------------------------------+
+| ``pip install "base-http-client[pydantic]"`` | For using pydantic_ models       |
++----------------------------------------------+----------------------------------+
 
-Using
-~~~~~
+Quick start guide
+-----------------
+
+BaseHttpClient
+~~~~~~~~~~~~~~
+
+Simple HTTP Client for `https://catfact.ninja`. See full example in `examples/base_http_client.py`_
+
+.. code-block:: python
+
+   from base_http_client.client import (
+       DEFAULT_TIMEOUT,
+       BaseHttpClient,
+       ResponseHandlersType,
+   )
+   from base_http_client.handlers.pydantic import parse_model
+   from base_http_client.timeout import TimeoutType
+
+
+   class CatfactClient(BaseHttpClient):
+       RANDOM_CATFACT_HANDLERS: ResponseHandlersType = MappingProxyType(
+            {
+                 HTTPStatus.OK: parse_model(CatfactSchema),
+            }
+       )
+
+      async def fetch_random_cat_fact(
+          self,
+          timeout: TimeoutType = DEFAULT_TIMEOUT,
+      ) -> CatfactSchema:
+          return await self._make_req(
+              method=hdrs.METH_GET,
+              url=self._url / "fact",
+              handlers=self.RANDOM_CATFACT_HANDLERS,
+              timeout=timeout,
+          )
 
 
 
@@ -65,4 +99,6 @@ Using
 .. _aiohttp: https://pypi.org/project/aiohttp/
 .. _msgspec: https://github.com/jcrist/msgspec
 .. _orjson: https://github.com/ijl/orjson
-.. _pydantic: https://github.com/pydantic/pydantic
+.. _pydantic: https://github.com/pydantic/pydantic
+
+.. _examples/base_http_client.py: https://github.com/andy-takker/base_http_client/blob/master/examples/base_http_client.py

base_http_client/__init__.py

@@ -1,5 +1,5 @@
 from base_http_client.client import BaseHttpClient
-from base_http_client.timeout import TimeoutType
 from base_http_client.handlers.base import ResponseHandlersType
+from base_http_client.timeout import TimeoutType
 
 __all__ = ("BaseHttpClient", "TimeoutType", "ResponseHandlersType")

base_http_client/client.py

@@ -8,6 +8,7 @@
     ResponseHandlersType,
     apply_handler,
 )
+
 from .timeout import TimeoutType, get_timeout
 
 

base_http_client/handlers/json.py

@@ -4,14 +4,13 @@
 
 from aiohttp import ClientResponse
 
-
 try:
     import orjson as json
 except ImportError:
     import json  # type: ignore
 
 
-def json_parser(
+def parse_json(
     parser: Callable,
     loads: Callable = json.loads,
 ) -> Callable[[ClientResponse], Awaitable[Any]]:

base_http_client/handlers/msgspec.py

@@ -8,7 +8,7 @@
 T = TypeVar("T", bound=Struct)
 
 
-def struct_parser(struct: type[T]) -> Callable[[ClientResponse], Awaitable[T]]:
+def parse_struct(struct: type[T]) -> Callable[[ClientResponse], Awaitable[T]]:
     async def _parse(response: ClientResponse) -> T:
         return decode(await response.read(), type=struct)
 

base_http_client/handlers/pydantic.py

@@ -7,7 +7,7 @@
 T = TypeVar("T", bound=BaseModel)
 
 
-def model_parser(model: type[T]) -> Callable[[ClientResponse], Awaitable[T]]:
+def parse_model(model: type[T]) -> Callable[[ClientResponse], Awaitable[T]]:
     async def _parse(response: ClientResponse) -> T:
         return model.model_validate_json(await response.read())
 

examples/base_http_client.py

@@ -0,0 +1,49 @@
+import asyncio
+from http import HTTPStatus
+from types import MappingProxyType
+
+from aiohttp import ClientSession, hdrs
+from pydantic import BaseModel
+
+from base_http_client.client import (
+    DEFAULT_TIMEOUT,
+    BaseHttpClient,
+    ResponseHandlersType,
+)
+from base_http_client.handlers.pydantic import parse_model
+from base_http_client.timeout import TimeoutType
+
+
+class CatfactSchema(BaseModel):
+    fact: str
+    length: int
+
+
+class CatfactClient(BaseHttpClient):
+    RANDOM_CATFACT_HANDLERS: ResponseHandlersType = MappingProxyType(
+        {
+            HTTPStatus.OK: parse_model(CatfactSchema),
+        }
+    )
+
+    async def fetch_random_cat_fact(
+        self,
+        timeout: TimeoutType = DEFAULT_TIMEOUT,
+    ) -> CatfactSchema:
+        return await self._make_req(
+            method=hdrs.METH_GET,
+            url=self._url / "fact",
+            handlers=self.RANDOM_CATFACT_HANDLERS,
+            timeout=timeout,
+        )
+
+
+async def main() -> None:
+    async with ClientSession() as session:
+        client = CatfactClient(session=session, url="https://catfact.ninja")
+        fact = await client.fetch_random_cat_fact()
+        print(fact)  # noqa: T201
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "base-http-client"
-version = "0.2.5"
+version = "0.2.6"
 description = "Typical HTTP Client based on aiohttp"
 authors = ["Sergey Natalenko <[email protected]>"]
 license = "MIT"
@@ -35,6 +35,7 @@ packages = [
 
 [tool.poetry.urls]
 "Source" = "https://github.com/andy-takker/base_http_client"
+"Bug Tracker" = "https://github.com/andy-takker/base_http_client/issues"
 
 [tool.poetry.dependencies]
 python = "^3.10"
@@ -60,6 +61,65 @@ pytest = "^8.3.3"
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+python_files = "test_*"
+python_functions = "test_*"
+python_classes = "TestSuite*"
+addopts = "-p no:cacheprovider"
+
+[tool.coverage.run]
+branch = true
+source = ["base_http_client", "test_http_service"]
+command_line = "-m pytest"
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.coverage.xml]
+output = "coverage.xml"
+
+[tool.ruff]
+line-length = 88
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".venv",
+]
+indent-width = 4
+target-version = "py310"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+select = [
+    "BLE",
+    "C90",
+    "E",
+    "F",
+    "G",
+    "I",
+    "ICN",
+    "ISC",
+    "PLE",
+    "Q",
+    "RUF006",
+    "RUF100",
+    "T10",
+    "T20",
+    "TID",
+    "UP",
+    "W",
+]
+ignore = ["ISC001"]
+fixable = ["ALL"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["base_http_client", "test_http_service", "tests"]
+
 [tool.mypy]
 plugins = ["pydantic.mypy"]
 check_untyped_defs = true

test_http_service/service.py

@@ -5,8 +5,8 @@
 from aiohttp.test_utils import TestServer
 from aiohttp.web_app import Application
 
-from test_http_service.models import MockRoute, MockService
 from test_http_service.handlers import get_default_handler
+from test_http_service.models import MockRoute, MockService
 
 
 @asynccontextmanager