Adjusting config (#8)

* Adjusting documentation

* RTD theme version

* Adding circle ci config

* Install rtd requirements

* requirements.txt no longer needed

Author: apetenchea

.circleci/config.yml

@@ -1,14 +1,30 @@
 version: 2.1
 
+executors:
+  python-container:
+    docker:
+      - image: cimg/python:3.12
+  python-vm:
+    machine:
+      - image: ubuntu-2204:current
+
 workflows:
   ci:
     jobs:
       - lint
+      - test:
+          name:  Python (<< matrix.python_version >>) - ArangoDB (<< matrix.arangodb_license >>, << matrix.arangodb_version >> << matrix.arangodb_config >>)
+          matrix:
+            parameters:
+              python_version: ["3.10"]
+              arangodb_config: ["single"]
+              arangodb_license: ["community"]
+              arangodb_version: ["3.12"]
 
 jobs:
   lint:
-    docker:
-      - image: python:latest
+    executor: python-container
+    resource_class: small
     steps:
       - checkout
       - run:
@@ -26,3 +42,54 @@ jobs:
       - run:
           name: Run mypy
           command: mypy ./arangoasync
+  test:
+    parameters:
+        python_version:
+            type: string
+        arangodb_config:
+            type: string
+        arangodb_license:
+            type: string
+        arangodb_version:
+            type: string
+    executor: python-vm
+    steps:
+      - checkout
+      - run:
+          name: Setup ArangoDB
+          command: |
+            chmod +x starter.sh
+            ./starter.sh ${{ matrix.arangodb_config }} ${{ matrix.arangodb_license }} ${{ matrix.arangodb_version }}
+      - restore_cache:
+          key: pip-and-local-cache
+      - run:
+          name: Setup Python
+          command: |
+            pyenv --version
+            pyenv install -f << parameters.python_version >>
+            pyenv global << parameters.python_version >>
+      - run:
+          name: Install Dependencies
+          command: pip install -e .[dev]
+      - run: docker ps -a
+      - run: docker logs arango
+      - run:
+          name: Run pytest
+          command: |
+            mkdir test-results
+
+            args=("--junitxml=test-results/junit.xml" "--log-cli-level=DEBUG" "--host" "localhost" "--port=8529")
+            if [ << parameters.arangodb_config >> = "cluster" ]; then
+              args+=("--cluster" "--port=8539" "--port=8549")
+            fi
+
+            if [ << parameters.arangodb_license >> = "enterprise" ]; then
+              args+=("--enterprise")
+            fi
+
+            echo "Running pytest with args: ${args[@]}"
+            pytest --cov=arango --cov-report=xml --cov-report term-missing --color=yes --code-highlight=yes "${args[@]}"
+      - store_artifacts:
+          path: test-results
+      - store_test_results:
+          path: test-results

.github/workflows/docs.yaml

@@ -24,5 +24,5 @@ jobs:
       - name: Install dependencies
         run: pip install .[dev]
 
-      - name: Generate Sphinx HTML
-        run: python -m sphinx -b html -W docs docs/_build
+      - name: Run Sphinx doctest
+        run: python -m sphinx -b doctest docs docs/_build

.readthedocs.yaml

@@ -20,5 +20,6 @@ sphinx:
 # to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
-   install:
-   - requirements: docs/requirements.txt
+  install:
+    - method: pip
+      path: .[dev]

arangoasync/http.py

@@ -15,19 +15,31 @@
 
 class HTTPClient(ABC):  # pragma: no cover
     """Abstract base class for HTTP clients.
+
     Custom HTTP clients should inherit from this class.
+
+    Example:
+        .. code-block:: python
+
+            class MyCustomHTTPClient(HTTPClient):
+                def create_session(self, host):
+                    pass
+                async def send_request(self, session, request):
+                    pass
     """
 
     @abstractmethod
     def create_session(self, host: str) -> Any:
         """Return a new session given the base host URL.
 
-        This method must be overridden by the user.
+        Note:
+            This method must be overridden by the user.
+
+        Args:
+            host (str): ArangoDB host URL.
 
-        :param host: ArangoDB host URL.
-        :type host: str
-        :returns: Requests session object.
-        :rtype: Any
+        Returns:
+            Requests session object.
         """
         raise NotImplementedError
 
@@ -39,37 +51,36 @@ async def send_request(
     ) -> Response:
         """Send an HTTP request.
 
-        This method must be overridden by the user.
+        Note:
+            This method must be overridden by the user.
 
-        :param session: Session object.
-        :type session: Any
-        :param request: HTTP request.
-        :type request: arangoasync.request.Request
-        :returns: HTTP response.
-        :rtype: arangoasync.response.Response
+        Args:
+            session (Any): Client session object.
+            request (Request): HTTP request.
+
+        Returns:
+            Response: HTTP response.
         """
         raise NotImplementedError
 
 
 class AioHTTPClient(HTTPClient):
-    """HTTP client implemented on top of [aiohttp](https://docs.aiohttp.org/en/stable/).
-
-    :param connector: Supports connection pooling.
-        By default, 100 simultaneous connections are supported, with a 60-second timeout
-        for connection reusing after release.
-    :type connector: aiohttp.BaseConnector | None
-    :param timeout: Timeout settings.
-        300s total timeout by default for a complete request/response operation.
-    :type timeout: aiohttp.ClientTimeout | None
-    :param read_bufsize: Size of read buffer (64KB default).
-    :type read_bufsize: int
-    :param auth: HTTP authentication helper.
-        Should be used for specifying authorization data in client API.
-    :type auth: aiohttp.BasicAuth | None
-    :param compression_threshold: Will compress requests to the server if
-        the size of the request body (in bytes) is at least the value of this
-        option.
-    :type compression_threshold: int
+    """HTTP client implemented on top of aiohttp_.
+
+    Args:
+        connector (aiohttp.BaseConnector | None): Supports connection pooling.
+            By default, 100 simultaneous connections are supported, with a 60-second
+            timeout for connection reusing after release.
+        timeout (aiohttp.ClientTimeout | None): Client timeout settings.
+            300s total timeout by default for a complete request/response operation.
+        read_bufsize (int): Size of read buffer (64KB default).
+        auth (aiohttp.BasicAuth | None): HTTP authentication helper.
+            Should be used for specifying authorization data in client API.
+        compression_threshold (int): Will compress requests to the server if the size
+            of the request body (in bytes) is at least the value of this option.
+
+    .. _aiohttp:
+        https://docs.aiohttp.org/en/stable/
     """
 
     def __init__(
@@ -95,11 +106,12 @@ def __init__(
     def create_session(self, host: str) -> ClientSession:
         """Return a new session given the base host URL.
 
-        :param host: ArangoDB host URL. Typically, the address and port of a coordinator
-            (e.g. "http://127.0.0.1:8529").
-        :type host: str
-        :returns: Session object.
-        :rtype: aiohttp.ClientSession
+        Args:
+            host (str): ArangoDB host URL. Must not include any paths. Typically, this
+                is the address and port of a coordinator (e.g. "http://127.0.0.1:8529").
+
+        Returns:
+            aiohttp.ClientSession: Session object, used to send future requests.
         """
         return ClientSession(
             base_url=host,
@@ -116,12 +128,12 @@ async def send_request(
     ) -> Response:
         """Send an HTTP request.
 
-        :param session: Session object.
-        :type session: aiohttp.ClientSession
-        :param request: HTTP request.
-        :type request: arangoasync.request.Request
-        :returns: HTTP response.
-        :rtype: arangoasync.response.Response
+        Args:
+            session (aiohttp.ClientSession): Session object used to make the request.
+            request (Request): HTTP request.
+
+        Returns:
+            Response: HTTP response.
         """
         method = request.method
         endpoint = request.endpoint

arangoasync/request.py

@@ -11,7 +11,7 @@
 
 
 class Method(Enum):
-    """HTTP methods."""
+    """HTTP methods enum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"""
 
     GET = auto()
     POST = auto()
@@ -25,31 +25,19 @@ class Method(Enum):
 class Request:
     """HTTP request.
 
-    :param method: HTTP method.
-    :type method: request.Method
-    :param endpoint: API endpoint.
-    :type endpoint: str
-    :param headers: Request headers.
-    :type headers: dict | None
-    :param params: URL parameters.
-    :type params: dict | None
-    :param data: Request payload.
-    :type data: Any
-    :param deserialize: Whether the response body should be deserialized.
-    :type deserialize: bool
-
-    :ivar method: HTTP method.
-    :vartype method: request.Method
-    :ivar endpoint: API endpoint, for example "_api/version".
-    :vartype endpoint: str
-    :ivar headers: Request headers.
-    :vartype headers: dict | None
-    :ivar params: URL (query) parameters.
-    :vartype params: dict | None
-    :ivar data: Request payload.
-    :vartype data: Any
-    :ivar deserialize: Whether the response body should be deserialized.
-    :vartype deserialize: bool
+    Args:
+        method (Method): HTTP method.
+        endpoint (str): API endpoint.
+        headers (dict | None): Request headers.
+        params (dict | None): URL parameters.
+        data (str | None): Request payload.
+
+    Attributes:
+        method (Method): HTTP method.
+        endpoint (str): API endpoint.
+        headers (dict | None): Request headers.
+        params (dict | None): URL parameters.
+        data (str | None): Request payload.
     """
 
     __slots__ = (
@@ -58,7 +46,6 @@ class Request:
         "headers",
         "params",
         "data",
-        "deserialize",
     )
 
     def __init__(
@@ -68,23 +55,22 @@ def __init__(
         headers: Optional[Headers] = None,
         params: Optional[Params] = None,
         data: Optional[str] = None,
-        deserialize: bool = True,
     ) -> None:
         self.method: Method = method
         self.endpoint: str = endpoint
         self.headers: Headers = self._normalize_headers(headers)
         self.params: Params = self._normalize_params(params)
         self.data: Optional[str] = data
-        self.deserialize: bool = deserialize
 
     @staticmethod
     def _normalize_headers(headers: Optional[Headers]) -> Headers:
         """Normalize request headers.
 
-        :param headers: Request headers.
-        :type headers: dict | None
-        :returns: Normalized request headers.
-        :rtype: dict
+        Parameters:
+            headers (dict | None): Request headers.
+
+        Returns:
+            dict: Normalized request headers.
         """
         driver_header = f"arangoasync/{__version__}"
         normalized_headers: Headers = {
@@ -103,10 +89,11 @@ def _normalize_headers(headers: Optional[Headers]) -> Headers:
     def _normalize_params(params: Optional[Params]) -> Params:
         """Normalize URL parameters.
 
-        :param params: URL parameters.
-        :type params: dict | None
-        :returns: Normalized URL parameters.
-        :rtype: dict
+        Parameters:
+            params (dict | None): URL parameters.
+
+        Returns:
+            dict: Normalized URL parameters.
         """
         normalized_params: Params = {}