Add documentation for HTTP APIs, small refactoring

Sphinx documentation pages and some additional docstrings have
been added.
The "api" module in gvm.http.core is renamed to "_api" and
url_join is now a class method of HttpApiConnector.

Author: timopollmeier

docs/api/api.rst

@@ -16,5 +16,6 @@ utilities and xml helpers.
     connections
     transforms
     protocols
+    http
     errors
     other

docs/api/http.rst

@@ -0,0 +1,12 @@
+.. _http:
+
+HTTP APIs
+---------
+
+.. automodule:: gvm.http
+
+.. toctree::
+    :maxdepth: 1
+
+    httpcore
+    openvasdv1

docs/api/httpcore.rst

@@ -0,0 +1,28 @@
+.. _httpcore:
+
+HTTP core classes
+^^^^^^^^^^^^^^^^^
+
+Connector
+#########
+
+.. automodule:: gvm.http.core.connector
+
+.. autoclass:: HttpApiConnector
+    :members:
+
+Headers
+#######
+
+.. automodule:: gvm.http.core.headers
+
+.. autoclass:: ContentType
+    :members:
+
+Response
+########
+
+.. automodule:: gvm.http.core.response
+
+.. autoclass:: HttpResponse
+    :members:

docs/api/openvasdv1.rst

@@ -0,0 +1,9 @@
+.. _openvasdv1:
+
+openvasd v1
+^^^^^^^^^^^
+
+.. automodule:: gvm.http.openvasd.openvasd1
+
+.. autoclass:: OpenvasdHttpApiV1
+    :members:

gvm/http/__init__.py

@@ -1,3 +1,11 @@
 # SPDX-FileCopyrightText: 2025 Greenbone AG
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Package for supported Greenbone HTTP APIs.
+
+Currently only `openvasd version 1`_ is supported.
+
+.. _openvasd version 1:
+    https://greenbone.github.io/scanner-api/#/
+"""

gvm/http/core/__init__.py

@@ -1,3 +1,7 @@
 # SPDX-FileCopyrightText: 2025 Greenbone AG
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+HTTP core classes
+"""

gvm/http/core/api.py renamed to gvm/http/core/_api.py

@@ -2,6 +2,10 @@
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+"""
+Base class module for GVM HTTP APIs
+"""
+
 from typing import Optional
 
 from gvm.http.core.connector import HttpApiConnector

gvm/http/core/connector.py

@@ -2,27 +2,17 @@
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+"""
+Module for handling GVM HTTP API connections
+"""
+
 import urllib.parse
 from typing import Optional, Tuple, Dict, Any
 
 from requests import Session
 
 from gvm.http.core.response import HttpResponse
 
-
-def url_join(base: str, rel_path: str) -> str:
-    """
-    Combines a base URL and a relative path into one URL.
-
-    Unlike `urrlib.parse.urljoin` the base path will always be the parent of the relative path as if it
-    ends with "/".
-    """
-    if base.endswith("/"):
-        return urllib.parse.urljoin(base, rel_path)
-    else:
-        return urllib.parse.urljoin(base + "/", rel_path)
-
-
 class HttpApiConnector:
     """
     Class for connecting to HTTP based API servers, sending requests and receiving the responses.
@@ -35,6 +25,19 @@ def _new_session(cls):
         """
         return Session()
 
+    @classmethod
+    def url_join(cls, base: str, rel_path: str) -> str:
+        """
+        Combines a base URL and a relative path into one URL.
+
+        Unlike `urrlib.parse.urljoin` the base path will always be the parent of the relative path as if it
+        ends with "/".
+        """
+        if base.endswith("/"):
+            return urllib.parse.urljoin(base, rel_path)
+        else:
+            return urllib.parse.urljoin(base + "/", rel_path)
+
     def __init__(
             self,
             base_url: str,
@@ -93,7 +96,7 @@ def delete(
         Return:
             The HTTP response.
         """
-        url = url_join(self.base_url, rel_path)
+        url = self.url_join(self.base_url, rel_path)
         r = self._session.delete(url, params=params, headers=headers)
         if raise_for_status:
             r.raise_for_status()
@@ -119,7 +122,7 @@ def get(
         Return:
             The HTTP response.
         """
-        url = url_join(self.base_url, rel_path)
+        url = self.url_join(self.base_url, rel_path)
         r = self._session.get(url, params=params, headers=headers)
         if raise_for_status:
             r.raise_for_status()
@@ -147,7 +150,7 @@ def post_json(
         Return:
             The HTTP response.
         """
-        url = url_join(self.base_url, rel_path)
+        url = self.url_join(self.base_url, rel_path)
         r = self._session.post(url, json=json, params=params, headers=headers)
         if raise_for_status:
             r.raise_for_status()

gvm/http/core/headers.py

@@ -1,6 +1,11 @@
 # SPDX-FileCopyrightText: 2025 Greenbone AG
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Module for handling special HTTP headers
+"""
+
 from dataclasses import dataclass
 from typing import Self, Dict, Optional
 

gvm/http/core/response.py

@@ -1,6 +1,11 @@
 # SPDX-FileCopyrightText: 2025 Greenbone AG
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Module for abstracting HTTP responses
+"""
+
 from dataclasses import dataclass
 from typing import Any, Dict, Self, Optional
 from requests import Request, Response
@@ -14,9 +19,16 @@ class HttpResponse:
     Class representing an HTTP response.
     """
     body: Any
+    "The body of the response"
+
     status: int
+    "HTTP status code of the response"
+
     headers: Dict[str, str]
+    "Dict containing the headers of the response"
+
     content_type: Optional[ContentType]
+    "The content type of the response if it was included in the headers"
 
     @classmethod
     def from_requests_lib(cls, r: Response) -> Self: