Preparing code for docs generation, black formatting, updating examples

Author: michalpokusa

adafruit_httpserver/methods.py

@@ -1,13 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_httpserver.methods.HTTPMethod`
+====================================================
+* Author(s): Michał Pokusa
+"""
 
 class HTTPMethod:
-    """HTTP method."""
+    """Enum with HTTP methods."""
 
     GET = "GET"
+    """GET method."""
+
     POST = "POST"
+    """POST method."""
+
     PUT = "PUT"
+    """PUT method"""
+
     DELETE = "DELETE"
+    """DELETE method"""
+
     PATCH = "PATCH"
+    """PATCH method"""
+
     HEAD = "HEAD"
+    """HEAD method"""
+
     OPTIONS = "OPTIONS"
+    """OPTIONS method"""
+
     TRACE = "TRACE"
+    """TRACE method"""
+
     CONNECT = "CONNECT"
+    """CONNECT method"""

adafruit_httpserver/mime_type.py

@@ -1,3 +1,12 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_httpserver.mime_type.MIMEType`
+====================================================
+* Author(s): Dan Halbert, Michał Pokusa
+"""
+
 class MIMEType:
     """Common MIME types.
     From https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
@@ -78,12 +87,12 @@ class MIMEType:
     ZIP = "application/zip"
     _7Z = "application/x-7z-compressed"
 
-
     @staticmethod
     def from_file_name(filename: str):
         """Return the mime type for the given filename. If not known, return "text/plain"."""
         attr_name = filename.split(".")[-1].upper()
 
-        if attr_name[0].isdigit(): attr_name = "_" + attr_name
+        if attr_name[0].isdigit():
+            attr_name = "_" + attr_name
 
         return getattr(MIMEType, attr_name, MIMEType.TXT)

adafruit_httpserver/request.py

@@ -1,27 +1,57 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_httpserver.request.HTTPRequest`
+====================================================
+* Author(s): Dan Halbert, Michał Pokusa
+"""
+
 try:
     from typing import Dict, Tuple
 except ImportError:
     pass
 
 
 class HTTPRequest:
+    """
+    Incoming request, constructed from raw incoming bytes, that is passed as first argument to route handlers.
+    """
 
     method: str
+    """Request method e.g. "GET" or "POST"."""
+
     path: str
+    """Path of the request."""
+
     query_params: Dict[str, str]
+    """
+    Query/GET parameters in the request.
+
+    Example::
+
+            request  = HTTPRequest(raw_request=b"GET /?foo=bar HTTP/1.1...")
+            request.query_params
+            # {"foo": "bar"}
+    """
+
     http_version: str
+    """HTTP version, e.g. "HTTP/1.1"."""
 
     headers: Dict[str, str]
-    body: bytes | None
+    """Headers from the request."""
+
+    body: bytes
+    """Body of the request, as bytes."""
 
     raw_request: bytes
+    """Raw bytes passed to the constructor."""
 
-    def __init__(
-        self, raw_request: bytes = None
-    ) -> None:
+    def __init__(self, raw_request: bytes = None) -> None:
         self.raw_request = raw_request
 
-        if raw_request is None: raise ValueError("raw_request cannot be None")
+        if raw_request is None:
+            raise ValueError("raw_request cannot be None")
 
         empty_line_index = raw_request.find(b"\r\n\r\n")
 
@@ -35,7 +65,6 @@ def __init__(
         except Exception as error:
             raise ValueError("Unparseable raw_request: ", raw_request) from error
 
-
     @staticmethod
     def _parse_start_line(header_bytes: bytes) -> Tuple[str, str, Dict[str, str], str]:
         """Parse HTTP Start line to method, path, query_params and http_version."""
@@ -44,7 +73,8 @@ def _parse_start_line(header_bytes: bytes) -> Tuple[str, str, Dict[str, str], st
 
         method, path, http_version = start_line.split()
 
-        if "?" not in path: path += "?"
+        if "?" not in path:
+            path += "?"
 
         path, query_string = path.split("?", 1)
 
@@ -58,7 +88,6 @@ def _parse_start_line(header_bytes: bytes) -> Tuple[str, str, Dict[str, str], st
 
         return method, path, query_params, http_version
 
-
     @staticmethod
     def _parse_headers(header_bytes: bytes) -> Dict[str, str]:
         """Parse HTTP headers from raw request."""

adafruit_httpserver/response.py

@@ -1,17 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_httpserver.response.HTTPResponse`
+====================================================
+* Author(s): Dan Halbert, Michał Pokusa
+"""
+
 try:
     from typing import Optional, Dict, Union
     from socket import socket
+    from socketpool import SocketPool
 except ImportError:
     pass
 
 from errno import EAGAIN, ECONNRESET
 import os
 
-from socketpool import SocketPool
 
 from .mime_type import MIMEType
 from .status import HTTPStatus, CommonHTTPStatus
 
+
 class HTTPResponse:
     """Details of an HTTP response. Use in `HTTPServer.route` decorator functions."""
 
@@ -33,7 +43,7 @@ def __init__(
         content_type: str = MIMEType.TXT,
         filename: Optional[str] = None,
         root_path: str = "",
-        http_version: str = "HTTP/1.1"
+        http_version: str = "HTTP/1.1",
     ) -> None:
         """
         Creates an HTTP response.
@@ -65,7 +75,7 @@ def _construct_response_bytes(
         headers = headers or {}
 
         headers.setdefault("Content-Type", content_type)
-        headers.setdefault("Content-Length", content_length if content_length is not None else len(body))
+        headers.setdefault("Content-Length", content_length or len(body))
         headers.setdefault("Connection", "close")
 
         for header, value in headers.items():
@@ -75,7 +85,7 @@ def _construct_response_bytes(
 
         return response
 
-    def send(self, conn: Union[SocketPool.Socket, socket.socket]) -> None:
+    def send(self, conn: Union["SocketPool.Socket", "socket.socket"]) -> None:
         """
         Send the constructed response over the given socket.
         """
@@ -85,60 +95,60 @@ def send(self, conn: Union[SocketPool.Socket, socket.socket]) -> None:
                 file_length = os.stat(self.root_path + self.filename)[6]
                 self._send_file_response(
                     conn,
-                    filename = self.filename,
-                    root_path = self.root_path,
-                    file_length = file_length,
-                    headers = self.headers,
+                    filename=self.filename,
+                    root_path=self.root_path,
+                    file_length=file_length,
+                    headers=self.headers,
                 )
             except OSError:
                 self._send_response(
                     conn,
-                    status = CommonHTTPStatus.NOT_FOUND_404,
-                    content_type = MIMEType.TXT,
-                    body = f"{CommonHTTPStatus.NOT_FOUND_404} {self.filename}",
+                    status=CommonHTTPStatus.NOT_FOUND_404,
+                    content_type=MIMEType.TXT,
+                    body=f"{CommonHTTPStatus.NOT_FOUND_404} {self.filename}",
                 )
         else:
             self._send_response(
                 conn,
-                status = self.status,
-                content_type = self.content_type,
-                headers = self.headers,
-                body = self.body,
+                status=self.status,
+                content_type=self.content_type,
+                headers=self.headers,
+                body=self.body,
             )
 
     def _send_response(
         self,
-        conn: Union[SocketPool.Socket, socket.socket],
+        conn: Union["SocketPool.Socket", "socket.socket"],
         status: HTTPStatus,
         content_type: str,
         body: str,
-        headers: Dict[str, str] = None
+        headers: Dict[str, str] = None,
     ):
         self._send_bytes(
             conn,
             self._construct_response_bytes(
-                status = status,
-                content_type = content_type,
-                headers = headers,
-                body = body,
-            )
+                status=status,
+                content_type=content_type,
+                headers=headers,
+                body=body,
+            ),
         )
 
     def _send_file_response(
         self,
-        conn: Union[SocketPool.Socket, socket.socket],
+        conn: Union["SocketPool.Socket", "socket.socket"],
         filename: str,
         root_path: str,
         file_length: int,
-        headers: Dict[str, str] = None
+        headers: Dict[str, str] = None,
     ):
         self._send_bytes(
             conn,
             self._construct_response_bytes(
-                status = self.status,
-                content_type = MIMEType.from_file_name(filename),
-                content_length = file_length,
-                headers = headers,
+                status=self.status,
+                content_type=MIMEType.from_file_name(filename),
+                content_length=file_length,
+                headers=headers,
             ),
         )
         with open(root_path + filename, "rb") as file:
@@ -147,7 +157,7 @@ def _send_file_response(
 
     @staticmethod
     def _send_bytes(
-        conn: Union[SocketPool.Socket, socket.socket],
+        conn: Union["SocketPool.Socket", "socket.socket"],
         buffer: Union[bytes, bytearray, memoryview],
     ):
         bytes_sent = 0
@@ -157,5 +167,7 @@ def _send_bytes(
             try:
                 bytes_sent += conn.send(view[bytes_sent:])
             except OSError as exc:
-                if exc.errno == EAGAIN: continue
-                if exc.errno == ECONNRESET: return
+                if exc.errno == EAGAIN:
+                    continue
+                if exc.errno == ECONNRESET:
+                    return

adafruit_httpserver/route.py

@@ -1,20 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+`adafruit_httpserver.route.HTTPRoute`
+====================================================
+* Author(s): Dan Halbert, Michał Pokusa
+"""
+
 from .methods import HTTPMethod
 
 
-class HTTPRoute:
-    def __init__(
-        self,
-        path: str = "",
-        method: HTTPMethod = HTTPMethod.GET
-    ) -> None:
+class _HTTPRoute:
+    """Route definition for different paths, see `HTTPServer.route`."""
+
+    def __init__(self, path: str = "", method: HTTPMethod = HTTPMethod.GET) -> None:
 
         self.path = path
         self.method = method
 
     def __hash__(self) -> int:
         return hash(self.method) ^ hash(self.path)
 
-    def __eq__(self, other: "HTTPRoute") -> bool:
+    def __eq__(self, other: "_HTTPRoute") -> bool:
         return self.method == other.method and self.path == other.path
 
     def __repr__(self) -> str: