finished docs + tests

Author: s-bose

README.md

@@ -23,8 +23,7 @@ pip install arrest
 
 ```python
 
-from arrest.resource import Resource
-from arrest.service import Service
+from arrest import Resource, Service
 from arrest.exceptions import ArrestHTTPException
 
 

arrest/defaults.py

@@ -1,4 +1 @@
-from arrest.http import ContentType
-
-HEADER_DEFAULTS = {"Content-Type": ContentType.APPLICATION_JSON}
 TIMEOUT_DEFAULT = 60  # sec

arrest/exceptions.py

@@ -5,6 +5,9 @@ class BaseException(Exception):
 class ArrestError(BaseException):
     """used in error situations"""
 
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
 
 class ArrestHTTPException(ArrestError):
     def __init__(self, status_code: int, data: dict | str) -> None:
@@ -17,9 +20,16 @@ def __init__(self, message: str):
         self.message = message
 
 
-class HandlerNotFound(ArrestError):
-    pass
+class HandlerNotFound(NotFoundException):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class ResourceNotFound(NotFoundException):
+    def __init__(self, message: str):
+        super().__init__(message)
 
 
 class ConversionError(ArrestError):
-    pass
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)

arrest/handler.py

@@ -42,9 +42,7 @@ class ResourceHandler(BaseModel):
     path_regex: Pattern | None = None
     param_types: dict[str, type] | None = None
 
-    def parse_path(
-        self, method: Methods, path: str | AnyUrl, **kwargs
-    ) -> str | AnyUrl | None:
+    def parse_path(self, method: Methods, path: str | AnyUrl, **kwargs) -> str | AnyUrl | None:
         if method != self.method:
             return None
 
@@ -57,9 +55,7 @@ def __parse_exact_path(self, path: str | AnyUrl) -> str | AnyUrl | None:
         if self.path_regex.fullmatch(path):
             return path
 
-    def __resolve_path_param(
-        self, path: str | AnyUrl, **kwargs
-    ) -> str | AnyUrl | None:
+    def __resolve_path_param(self, path: str | AnyUrl, **kwargs) -> str | AnyUrl | None:
         params = self.__extract_path_params(path)
         if params is None:
             return None

arrest/http.py

@@ -17,7 +17,3 @@ class Methods(StrEnum):
     DELETE = "DELETE"
     HEAD = "HEAD"
     OPTIONS = "OPTIONS"
-
-
-class ContentType(StrEnum):
-    APPLICATION_JSON = "application/json"

arrest/params.py

@@ -16,9 +16,7 @@ class ParamTypes(Enum):
 class Param(FieldInfo):
     _param_type: ParamTypes
 
-    def __init__(
-        self, default: Any = PydanticUndefined, **kwargs: Unpack[_FieldInfoInputs]
-    ) -> None:
+    def __init__(self, default: Any = PydanticUndefined, **kwargs: Unpack[_FieldInfoInputs]) -> None:
         kwargs = dict(default=default, **kwargs)
         super().__init__(**kwargs)
 
@@ -36,9 +34,7 @@ class Body(Param):
 
 
 class Params:
-    def __init__(
-        self, *, header: httpx.Headers, query: httpx.QueryParams, body: Any
-    ) -> None:
+    def __init__(self, *, header: httpx.Headers, query: httpx.QueryParams, body: Any) -> None:
         self.header = header
         self.query = query
         self.body = body

arrest/resource.py

@@ -9,13 +9,13 @@
 from pydantic.version import VERSION as PYDANTIC_VERSION
 
 from arrest.converters import compile_path
-from arrest.defaults import HEADER_DEFAULTS, TIMEOUT_DEFAULT
-from arrest.exceptions import ArrestError, ArrestHTTPException, HandlerNotFound
+from arrest.defaults import TIMEOUT_DEFAULT
+from arrest.exceptions import ArrestHTTPException, HandlerNotFound
 from arrest.handler import HandlerKey, ResourceHandler
 from arrest.http import Methods
 from arrest.logging import logger
 from arrest.params import Param, Params, ParamTypes
-from arrest.utils import extract_model_field, join_url, jsonify
+from arrest.utils import extract_model_field, join_url, jsonify, validate_request_model
 
 
 class Resource:
@@ -43,7 +43,7 @@ def __init__(
         name: Optional[str] = None,
         *,
         route: Optional[str],
-        headers: Optional[dict] = HEADER_DEFAULTS,
+        headers: Optional[dict] = None,
         timeout: Optional[int] = TIMEOUT_DEFAULT,
         response_model: Optional[Type[BaseModel]] = None,
         handlers: Union[
@@ -133,11 +133,9 @@ async def request(
 
         params: dict = {}
 
-        if not (
-            match := self.get_matching_handler(method=method, path=path, **kwargs)
-        ):
+        if not (match := self.get_matching_handler(method=method, path=path, **kwargs)):
             logger.warning("no matching handler found for request")
-            raise HandlerNotFound("no matching handler found for request")
+            raise HandlerNotFound(message="no matching handler found for request")
 
         handler, url = match
 
@@ -161,9 +159,9 @@ async def request(
                     callback_response = await handler.callback(response)
                 else:
                     callback_response = handler.callback(response)
-            except Exception as exc:
+            except Exception:
                 logger.warning("something went wrong during callback", exc_info=True)
-                raise ArrestError(str(exc)) from exc
+                raise
             return callback_response
 
         return response
@@ -344,27 +342,24 @@ def extract_request_params(
         """
 
         header_params = headers or {}
-        header_params |= self.headers
+        if self.headers:
+            header_params |= self.headers
         query_params = query or {}
         body_params = {}
 
         if request_type:
             # perform type validation on `request_data`
-            request_data = request_type.model_validate(request_data)
+            request_data = validate_request_model(type_=request_type, obj=request_data)
 
         if isinstance(request_data, BaseModel):
             # extract pydantic fields into `Query`, `Body` and `Header`
             model_fields: dict = (
-                request_data.__fields__
-                if PYDANTIC_VERSION.startswith("2.")
-                else request_data.model_fields
+                request_data.__fields__ if PYDANTIC_VERSION.startswith("2.") else request_data.model_fields
             )
 
             for field, field_info in model_fields.items():
                 field_info = cast(Param, field_info)
-                if not hasattr(field_info, "_param_type") and isinstance(
-                    field_info, FieldInfo
-                ):
+                if not hasattr(field_info, "_param_type") and isinstance(field_info, FieldInfo):
                     body_params |= extract_model_field(request_data, field)
                 elif field_info._param_type == ParamTypes.query:
                     query_params |= extract_model_field(request_data, field)
@@ -416,9 +411,7 @@ async def __make_request(
             params.body,
         )
         try:
-            async with httpx.AsyncClient(
-                timeout=self.timeout, headers=headers
-            ) as client:
+            async with httpx.AsyncClient(timeout=self.timeout, headers=headers) as client:
                 match method:
                     case Methods.GET:
                         response = await client.get(url=url, params=query_params)
@@ -452,19 +445,15 @@ async def __make_request(
                         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}"
-                )
+                logger.debug(f"{method!s} {url} returned with status code {status_code!s}")
                 response.raise_for_status()
                 response_body = response.json()
 
                 # parse response to pydantic model
                 parsed_response = response_body
                 if response_type:
                     if isinstance(response_body, list):
-                        parsed_response = [
-                            response_type(**item) for item in response_body
-                        ]
+                        parsed_response = [response_type(**item) for item in response_body]
                     elif isinstance(response_body, dict):
                         parsed_response = response_type(**response_body)
                     else:
@@ -477,9 +466,7 @@ async def __make_request(
         # exception handling
         except httpx.HTTPStatusError as exc:
             err_response_body = exc.response.json()
-            raise ArrestHTTPException(
-                status_code=exc.response.status_code, data=err_response_body
-            ) from exc
+            raise ArrestHTTPException(status_code=exc.response.status_code, data=err_response_body) from exc
 
         except httpx.TimeoutException:
             raise ArrestHTTPException(
@@ -502,9 +489,7 @@ def get_matching_handler(
                 url = join_url(self.base_url, self.route, parsed_path)
                 return handler, url
 
-    def _bind_handler(
-        self, base_url: str | None = None, *, handler: ResourceHandler
-    ) -> None:
+    def _bind_handler(self, base_url: str | None = None, *, handler: ResourceHandler) -> None:
         """
         compose a fully-qualified url by joining base service url, resource url
         and handler url,
@@ -514,18 +499,14 @@ def _bind_handler(
         """
 
         base_url = base_url or self.base_url
-        handler.path_regex, handler.path_format, handler.param_types = compile_path(
-            handler.route
-        )
+        handler.path_regex, handler.path_format, handler.param_types = compile_path(handler.route)
 
         self.routes[HandlerKey(*(handler.method, handler.path_format))] = handler
 
     def initialize_handlers(
         self,
         base_url: str | None = None,
-        handlers: list[ResourceHandler]
-        | list[Mapping[str, Any]]
-        | list[tuple[Any, ...]] = None,
+        handlers: list[ResourceHandler] | list[Mapping[str, Any]] | list[tuple[Any, ...]] = None,
     ) -> None:
         """
         specifically used to inject `base_url` from a Service class to
@@ -541,18 +522,12 @@ def initialize_handlers(
         for _handler in handlers:
             try:
                 if isinstance(_handler, dict):
-                    self._bind_handler(
-                        base_url=base_url, handler=ResourceHandler(**_handler)
-                    )
+                    self._bind_handler(base_url=base_url, handler=ResourceHandler(**_handler))
                 elif isinstance(_handler, tuple):
                     if len(_handler) < 2:
-                        raise ValueError(
-                            "Too few arguments to unpack. Expected atleast 2"
-                        )
+                        raise ValueError("Too few arguments to unpack. Expected atleast 2")
                     if len(_handler) > 5:
-                        raise ValueError(
-                            f"Too many arguments to unpack. Expected 5, got {len(_handler)}"
-                        )
+                        raise ValueError(f"Too many arguments to unpack. Expected 5, got {len(_handler)}")
 
                     method, route, rest = (
                         _handler[0],

arrest/service.py

@@ -2,7 +2,7 @@
 from functools import partial
 from typing import Any, Optional
 
-from arrest.exceptions import NotFoundException
+from arrest.exceptions import ResourceNotFound
 from arrest.http import Methods
 from arrest.resource import Resource
 
@@ -69,10 +69,8 @@ async def request(self, path: str, method: Methods, **kwargs):
         resource, suffix = parts[0], "/".join(parts[1:])
 
         if resource not in self.resources:
-            raise NotFoundException(message=f"resource {resource} not found")
-        return await self.resources[resource].request(
-            path=f"/{suffix}", method=method, **kwargs
-        )
+            raise ResourceNotFound(message=f"resource {resource} not found")
+        return await self.resources[resource].request(path=f"/{suffix}", method=method, **kwargs)
 
     def __getattr__(self, key: str) -> Resource | Any:  # pragma: no cover
         if hasattr(self, key):

arrest/utils.py

@@ -1,5 +1,5 @@
 import posixpath
-import typing
+from typing import Any, Type
 from urllib.parse import urljoin
 
 import orjson
@@ -31,5 +31,11 @@ def extract_model_field(model: BaseModel, field: str) -> dict:
     return value
 
 
-def jsonify(obj: typing.Any) -> typing.Any:
+def jsonify(obj: Any) -> Any:
     return orjson.loads(orjson.dumps(obj))
+
+
+def validate_request_model(type_: Type[BaseModel], obj: Any) -> BaseModel:
+    if PYDANTIC_VERSION.startswith("2."):
+        return type_.model_validate(obj)
+    return type_.parse_obj(obj)

docs/api.md

@@ -27,3 +27,37 @@
 ## `ResourceHandler`
 
 ::: arrest.handler.ResourceHandler
+
+## Exceptions
+
+### ArrestError
+::: arrest.exceptions.ArrestError
+base class for all Exception. Used in situations that are not one of the following
+
+### ArrestHTTPException
+::: arrest.exceptions.ArrestHTTPException
+used for exceptions during HTTP calls
+
+* `.status_code` - **str** status code of the exception, 500 for internal server error
+* `.data` - **str** json response for the exception
+
+### NotFoundException
+::: arrest.exceptions.NotFoundException
+base class for all NotFound-type exceptions
+
+### HandlerNotFound
+::: arrest.exceptions.HandlerNotFound
+raised when no matching handler is found for the requested path
+
+* `.message` - **str**
+
+### ResourceNotFound
+::: arrest.exceptions.ResourceNotFound
+raised when no matching resource is found for the service
+
+* `.message` - **str**
+
+
+### ConversionError
+::: arrest.exceptions.ConversionError
+raised when Arrest cannot convert path-parameter type using any of the existing converters