Merge pull request #14 from andy-takker/feature/update-docs

Add example for base_http_client

Author: andy-takker

.github/workflows/_publish.yaml

@@ -7,10 +7,9 @@ jobs:
   publish-to-pypi:
     name: Publish Python distribution to PyPI
     runs-on: ubuntu-22.04
-    # if: github.repository == 'andy-takker/base-http-client'
     environment:
       name: pypi
-      url: https://pypi.org/p/base-http-client/
+      url: https://pypi.org/p/asyncly/
     permissions:
       id-token: write
       contents: write

.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]
@@ -38,7 +38,7 @@ repos:
     hooks:
       - id: mypy
         name: mypy
-        entry: mypy ./base_http_client --config-file ./pyproject.toml
+        entry: mypy ./asyncly --config-file ./pyproject.toml
         language: python
         language_version: python3.10
         require_serial: true

Makefile

@@ -1,6 +1,6 @@
-PROJECT_NAME = base_http_client
+PROJECT_NAME = asyncly
 
-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

@@ -1,20 +1,20 @@
-Base HTTP Client
-================
+Asyncly
+=======
 
-.. image:: https://img.shields.io/pypi/v/base-http-client.svg
-   :target: https://pypi.python.org/pypi/base-http-client/
+.. image:: https://img.shields.io/pypi/v/asyncly.svg
+   :target: https://pypi.python.org/pypi/asyncly/
    :alt: Latest Version
 
-.. image:: https://img.shields.io/pypi/wheel/base-http-client.svg
-   :target: https://pypi.python.org/pypi/base-http-client/
+.. image:: https://img.shields.io/pypi/wheel/asyncly.svg
+   :target: https://pypi.python.org/pypi/asyncly/
 
-.. image:: https://img.shields.io/pypi/pyversions/base-http-client.svg
-   :target: https://pypi.python.org/pypi/base-http-client/
+.. image:: https://img.shields.io/pypi/pyversions/asyncly.svg
+   :target: https://pypi.python.org/pypi/asyncly/
 
-.. image:: https://img.shields.io/pypi/l/base-http-client.svg
-   :target: https://pypi.python.org/pypi/base-http-client/
+.. image:: https://img.shields.io/pypi/l/asyncly.svg
+   :target: https://pypi.python.org/pypi/asyncly/
 
-Base HTTP client for your integrations based on aiohttp_.
+Simple HTTP client and server for your integrations based on aiohttp_.
 
 Installation
 ------------
@@ -26,13 +26,13 @@ Installing from PyPI_:
 
 .. code-block:: bash
 
-   pip3 install base-http-client
+   pip install asyncly
 
 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/asyncly
 
 The package contains several extras and you can install additional dependencies
 if you specify them in this way.
@@ -41,28 +41,123 @@ For example, with msgspec_:
 
 .. code-block:: bash
 
-   pip3 install "base-http-client[msgspec]"
+   pip install "asyncly[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       |
-+-----------------------------------------------+----------------------------------+
-
-Using
-~~~~~
-
-
++-------------------------------------+----------------------------------+
+| example                             | description                      |
++========================================================================+
+| ``pip install "asyncly[msgspec]"``  | For using msgspec_ structs       |
++-------------------------------------+----------------------------------+
+| ``pip install "asyncly[orjson]"``   | For fast parsing json by orjson_ |
++-------------------------------------+----------------------------------+
+| ``pip install "asyncly[pydantic]"`` | For using pydantic_ models       |
++-------------------------------------+----------------------------------+
+
+Quick start guide
+-----------------
+
+HttpClient
+~~~~~~~~~~~~~~
+
+Simple HTTP Client for `https://catfact.ninja`. See full example in `examples/catfact_client.py`_
+
+.. code-block:: python
+
+   from asyncly import DEFAULT_TIMEOUT, BaseHttpClient, ResponseHandlersType
+   from asyncly.client.handlers.pydantic import parse_model
+   from asyncly.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,
+          )
+
+Test Async Server for client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the HTTP client, we create a server to which he will go and simulate real
+responses. You can dynamically change the responses from the server in
+a specific test.
+
+Let's prepare the fixtures:
+
+.. code-block:: python
+
+   @pytest.fixture
+   async def catafact_service() -> AsyncIterator[MockService]:
+       routes = [
+           MockRoute("GET", "/fact", "random_catfact"),
+       ]
+       async with start_service(routes) as service:
+           service.register(
+               "random_catfact",
+               JsonResponse({"fact": "test", "length": 4}),
+           )
+           yield service
+
+
+   @pytest.fixture
+   def catfact_url(catafact_service: MockService) -> URL:
+       return catafact_service.url
+
+
+   @pytest.fixture
+   async def catfact_client(catfact_url: URL) -> AsyncIterator[CatfactClient]:
+       async with ClientSession() as session:
+           client = CatfactClient(
+               client_name="catfact",
+               session=session,
+               url=catfact_url,
+           )
+           yield client
+
+Now we can use them in tests. See full example in `examples/test_catfact_client.py`_
+
+.. code-block:: python
+
+    async def test_fetch_random_catfact(catfact_client: CatfactClient) -> None:
+        # use default registered handler
+        fact = await catfact_client.fetch_random_cat_fact()
+        assert fact == CatfactSchema(fact="test", length=4)
+
+
+    async def test_fetch_random_catfact_timeout(
+        catfact_client: CatfactClient,
+        catafact_service: MockService,
+    ) -> None:
+        # change default registered handler to time error handler
+        catafact_service.register(
+            "random_catfact",
+            LatencyResponse(
+                wrapped=JsonResponse({"fact": "test", "length": 4}),
+                latency=1.5,
+            ),
+        )
+        with pytest.raises(asyncio.TimeoutError):
+            await catfact_client.fetch_random_cat_fact(timeout=1)
 
 
 .. _PyPI: https://pypi.org/
 .. _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/catfact_client.py: https://github.com/andy-takker/asyncly/blob/master/examples/catfact_client.py
+.. _examples/test_catfact_client.py: https://github.com/andy-takker/asyncly/blob/master/examples/test_catfact_client.py

asyncly/__init__.py

@@ -0,0 +1,12 @@
+from aiohttp.client import DEFAULT_TIMEOUT
+
+from asyncly.client.base import BaseHttpClient
+from asyncly.client.handlers.base import ResponseHandlersType
+from asyncly.client.timeout import TimeoutType
+
+__all__ = (
+    "BaseHttpClient",
+    "TimeoutType",
+    "ResponseHandlersType",
+    "DEFAULT_TIMEOUT",
+)

base_http_client/handlers/__init__.py asyncly/client/__init__.pybase_http_client/handlers/__init__.py renamed to asyncly/client/__init__.py

@@ -4,11 +4,11 @@
 from aiohttp.client import DEFAULT_TIMEOUT
 from yarl import URL
 
-from base_http_client.handlers.base import (
+from asyncly.client.handlers.base import (
     ResponseHandlersType,
     apply_handler,
 )
-from .timeout import TimeoutType, get_timeout
+from asyncly.client.timeout import TimeoutType, get_timeout
 
 
 class BaseHttpClient:
@@ -18,8 +18,10 @@ class BaseHttpClient:
     _session: ClientSession
     _client_name: str
 
-    def __init__(self, url: URL, session: ClientSession, client_name: str) -> None:
-        self._url = url
+    def __init__(
+        self, url: URL | str, session: ClientSession, client_name: str
+    ) -> None:
+        self._url = url if isinstance(url, URL) else URL(url)
         self._session = session
         self._client_name = client_name
 

base_http_client/client.py asyncly/client/base.pybase_http_client/client.py renamed to asyncly/client/base.py

@@ -4,7 +4,7 @@
 
 from aiohttp import ClientResponse
 
-from base_http_client.exceptions import UnhandledStatusException
+from asyncly.client.handlers.exceptions import UnhandledStatusException
 
 ResponseHandlersType = Mapping[HTTPStatus | int | str, Callable]