Draft: adding documentation

Author: s-bose

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+  - requirements: requirements.docs.txt

arrest/__init__.py

@@ -0,0 +1,4 @@
+# flake8: noqa
+from .http import Methods
+from .resource import Resource
+from .service import Service

arrest/config.py

@@ -1,7 +1,6 @@
 # pylint: disable=W0707
 import inspect
 import json
-from functools import partial
 from typing import Any, Mapping, Type, cast
 
 import httpx
@@ -20,6 +19,39 @@
 
 
 class Resource:
+    """
+    A python class used to define a RESTful resource.
+
+    Usage:
+
+    ```python
+    >>> from arrest import Resource
+
+    >>> user_resource = Resource(name="user", route="/users", handlers=[("GET", "/")])
+    ```
+
+    **Parameters:**
+
+    * **name** - *(optional)* A unique name for the resource. If not present, will be picked
+    from `route`
+    * **route** - A unique route for the resource. Must begin with a slash.
+    * **headers** - *(optional)* A dictionary of header values to be used for all handlers
+    under this resource. Defaults to `{"Content-Type": "application/json}`.
+    * **timeout** - *(optional)* Timeout (in seconds) for all HTTP requests from this resource.
+    Defaults to 60.
+    * **response_model** - *(optional)* Pydantic response model to parse all responses under
+    the resource.
+    * **handlers** - *(optional)* - a list of handlers for the resource.
+
+    Handlers can be provided as a list of tuple, dictionary or instances of `ResourceHandler`
+
+    If provided as a dict or `ResourceHandler`, the keys / fields have to be set according to
+    the `ResourceHandler` definiion.
+
+    If provided as a tuple, at minimum 2 entries `(method, route)` or a maximum of 5 entries
+    (method, route, request, response, callback) can be defined.
+    """
+
     def __init__(
         self,
         name: str | None = None,
@@ -30,7 +62,7 @@ def __init__(
         response_model: Type[BaseModel] | None = None,
         handlers: list[ResourceHandler]
         | list[Mapping[str, Any]]
-        | list[tuple[Any, ...]] = [],
+        | list[tuple[Any, ...]] = None,
     ) -> None:
         self.base_url = "/"  # will be filled once bound to a service
         self.route = route
@@ -48,12 +80,6 @@ def __init__(
 
         self.routes: dict[HandlerKey, ResourceHandler] = {}
 
-        self.get = partial(self.request, method=Methods.GET)
-        self.post = partial(self.request, method=Methods.POST)
-        self.put = partial(self.request, method=Methods.PUT)
-        self.patch = partial(self.request, method=Methods.PATCH)
-        self.delete = partial(self.request, method=Methods.DELETE)
-
         self.initialize_handlers(handlers=handlers)
 
     def initialize_handlers(
@@ -136,14 +162,21 @@ def _bind_handler(
 
     async def request(
         self,
-        url: str,
         method: Methods,
+        url: str,
         request: BaseModel | None = None,
         **kwargs,
     ) -> Any | None:
         """
-        Parameters
-        ----------
+        Makes an HTTP request against a handler route
+
+        Usage:
+
+        ```python
+        >>> user_resource.user.request(method="GET")
+        ```
+
+        **Parameters:**
 
         request : BaseModel
             pydantic object containing the necessary fields to make an http
@@ -187,6 +220,111 @@ async def request(
 
         return response
 
+    async def get(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP GET` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.GET, url=url, request=request, **kwargs
+        )
+
+    async def post(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP POST` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.POST, url=url, request=request, **kwargs
+        )
+
+    async def put(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP PUT` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.PUT, url=url, request=request, **kwargs
+        )
+
+    async def patch(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP PATCH` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.PATCH, url=url, request=request, **kwargs
+        )
+
+    async def delete(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP GET` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.DELETE, url=url, request=request, **kwargs
+        )
+
+    async def head(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP HEAD` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.HEAD, url=url, request=request, **kwargs
+        )
+
+    async def options(
+        self,
+        url: str,
+        request: BaseModel | None = None,
+        **kwargs,
+    ):
+        """
+        Makes a `HTTP OPTIONS` request
+
+        see `request()`
+        """
+        return await self.request(
+            method=Methods.OPTIONS, url=url, request=request, **kwargs
+        )
+
     def extract_request_params(
         self,
         request_type: Type[BaseModel] | None,
@@ -311,6 +449,9 @@ async def __make_request(
                     case Methods.HEAD:
                         response = await client.head(url=url, params=query_params)
 
+                    case Methods.OPTIONS:
+                        response = await client.options(url=url, params=query_params)
+
                 status_code = response.status_code
                 logger.debug(
                     f"{method!s} {url} returned with status code {status_code!s}"

arrest/resource.py

@@ -0,0 +1,7 @@
+# API Documentation
+
+## `Resource`
+
+::: arrest.resource.Resource
+    :docstring:
+    :members: get post put patch delete head options request

docs/api-documentation.md

@@ -0,0 +1,10 @@
+div.autodoc-docstring {
+  padding-left: 20px;
+  margin-bottom: 30px;
+  border-left: 5px solid rgba(230, 230, 230);
+}
+
+div.autodoc-members {
+  padding-left: 20px;
+  margin-bottom: 15px;
+}

docs/css/custom.css

@@ -0,0 +1,43 @@
+# Getting Started
+
+Assuming you already have arrest installed in your system, let us create a simple connection.
+We have a REST endpoint `http://example.com/api/v1` which has a resource `/user` with method `GET`
+
+```python
+
+from arrest import Service, Resource
+
+example_svc = Service(
+    name="example",
+    url="http://example.com/api/v1",
+    resources=[
+        Resource(
+            name="user",
+            route="/user",
+            handlers=[
+                ("GET", "/")
+            ]
+        )
+    ]
+)
+```
+
+Now that our service is defined, we can proceed to use it elsewhere.
+
+```python
+
+await example_svc.user.get("/")
+```
+
+If we want to enable exception handling, simply import `ArrestHTTPException`, or more generic `ArrestError`
+
+```python
+from arrest.exceptions import ArrestHTTPException
+
+try:
+    resp = await example_svc.user.get("/")
+except ArrestHTTPException as exc:
+    print(f"{exc.status_code} {exc.data}")
+
+return resp
+```