Changes to docstrings

Author: michalpokusa

adafruit_httpserver/exceptions.py

@@ -48,7 +48,7 @@ class ResponseAlreadySentError(Exception):
 
 class ServingFilesDisabledError(Exception):
     """
-    Raised when ``root_path`` is not set and there is no handler for `request`.
+    Raised when ``root_path`` is not set and there is no handler for ``request``.
     """
 
 

adafruit_httpserver/mime_types.py

@@ -21,6 +21,10 @@ class MIMETypes:
     """
 
     DEFAULT = "text/plain"
+    """
+    Default MIME type for unknown files.
+    Can be changed using ``MIMETypes.configure(default_to=...)``.
+    """
 
     REGISTERED = {
         ".7z": "application/x-7z-compressed",
@@ -175,6 +179,13 @@ def configure(
         """
         Allows to globally configure the MIME types.
 
+        It is recommended to **always** call this method before starting the ``Server``.
+        Unregistering unused MIME types will **decrease overall memory usage**.
+
+        :param str default_to: The MIME type to use for unknown files.
+        :param List[str] keep_for: File extensions to keep. All other will be unregistered.
+        :param Dict[str, str] register: A dictionary mapping file extensions to MIME types.
+
         Example::
 
             MIMETypes.configure(
@@ -194,8 +205,10 @@ def configure(
     def get_for_filename(cls, filename: str, default: str = None) -> str:
         """
         Return the MIME type for the given file name.
+        If the file extension is not registered, ``default`` is returned.
 
         :param str filename: The file name to look up.
+        :param str default: Default MIME type to return if the file extension is not registered.
         """
         if default is None:
             default = cls.DEFAULT

adafruit_httpserver/request.py

@@ -20,12 +20,12 @@
 class Request:
     """
     Incoming request, constructed from raw incoming bytes.
-    It is passed as first argument to route handlers.
+    It is passed as first argument to all route handlers.
     """
 
     connection: Union["SocketPool.Socket", "socket.socket"]
     """
-    Socket object usable to send and receive data on the connection.
+    Socket object used to send and receive data on the connection.
     """
 
     client_address: Tuple[str, int]
@@ -42,7 +42,7 @@ class Request:
     """Request method e.g. "GET" or "POST"."""
 
     path: str
-    """Path of the request."""
+    """Path of the request, e.g. ``"/foo/bar"``."""
 
     query_params: Dict[str, str]
     """
@@ -56,7 +56,7 @@ class Request:
     """
 
     http_version: str
-    """HTTP version, e.g. "HTTP/1.1"."""
+    """HTTP version, e.g. ``"HTTP/1.1"``."""
 
     headers: Headers
     """
@@ -65,7 +65,7 @@ class Request:
 
     raw_request: bytes
     """
-    Raw 'bytes' passed to the constructor and body 'bytes' received later.
+    Raw 'bytes' that were received from the client.
 
     Should **not** be modified directly.
     """

adafruit_httpserver/response.py

@@ -73,8 +73,13 @@ def route_func(request):
     """The request that this is a response to."""
 
     http_version: str
+
     status: Status
+    """Status code of the response. Defaults to ``200 OK``."""
+
     headers: Headers
+    """Headers to be sent in the response."""
+
     content_type: str
     """
     Defaults to ``text/plain`` if not set.
@@ -180,7 +185,8 @@ def send(
     @staticmethod
     def _check_file_path_is_valid(file_path: str) -> bool:
         """
-        Checks if ``file_path`` is valid.
+        Checks if ``file_path`` does not contain backslashes or parent directory references.
+
         If not raises error corresponding to the problem.
         """
 

adafruit_httpserver/route.py

@@ -120,9 +120,6 @@ def route_func(request, my_parameter):
                 request.path == "/example/123" # True
                 my_parameter == "123" # True
         """
-        if not self._routes:
-            return None
-
         found_route, _route = False, None
 
         for _route in self._routes:

adafruit_httpserver/server.py

@@ -53,7 +53,7 @@ def route(self, path: str, methods: Union[str, List[str]] = GET) -> Callable:
         Decorator used to add a route.
 
         :param str path: URL path
-        :param str method: HTTP method: `"GET"`, `"POST"`, etc.
+        :param str methods: HTTP method(s): ``"GET"``, ``"POST"``, ``["GET", "POST"]`` etc.
 
         Example::
 
@@ -227,9 +227,8 @@ def _handle_request(self, request: Request, handler: Union[Callable, None]):
 
     def poll(self):
         """
-        Call this method inside your main event loop to get the server to
-        check for new incoming client requests. When a request comes in,
-        the application callable will be invoked.
+        Call this method inside your main loop to get the server to check for new incoming client
+        requests. When a request comes in, it will be handled by the handler function.
         """
         try:
             conn, client_address = self._sock.accept()
@@ -255,10 +254,10 @@ def poll(self):
                 return
             raise
 
-    def restrict_access(self, auths: List[Union[Basic, Bearer]]) -> None:
+    def require_authentication(self, auths: List[Union[Basic, Bearer]]) -> None:
         """
-        Restricts access to the whole ``Server``.
-        It applies to all routes and files in ``root_path``.
+        Requires authentication for all routes and files in ``root_path``.
+        Any non-authenticated request will be rejected with a 401 status code.
 
         Example::
 

adafruit_httpserver/status.py

@@ -32,37 +32,33 @@ def __eq__(self, other: "Status"):
 
 
 OK_200 = Status(200, "OK")
-"""200 OK"""
+
+CREATED_201 = Status(201, "Created")
+
+ACCEPTED_202 = Status(202, "Accepted")
 
 NO_CONTENT_204 = Status(204, "No Content")
-"""204 No Content"""
+
+PARTIAL_CONTENT_206 = Status(206, "Partial Content")
 
 TEMPORARY_REDIRECT_307 = Status(307, "Temporary Redirect")
-"""307 Temporary Redirect"""
 
 PERMANENT_REDIRECT_308 = Status(308, "Permanent Redirect")
-"""308 Permanent Redirect"""
 
 BAD_REQUEST_400 = Status(400, "Bad Request")
-"""400 Bad Request"""
 
 UNAUTHORIZED_401 = Status(401, "Unauthorized")
-"""401 Unauthorized"""
 
 FORBIDDEN_403 = Status(403, "Forbidden")
-"""403 Forbidden"""
 
 NOT_FOUND_404 = Status(404, "Not Found")
-"""404 Not Found"""
 
 METHOD_NOT_ALLOWED_405 = Status(405, "Method Not Allowed")
-"""405 Method Not Allowed"""
+
+TOO_MANY_REQUESTS_429 = Status(429, "Too Many Requests")
 
 INTERNAL_SERVER_ERROR_500 = Status(500, "Internal Server Error")
-"""500 Internal Server Error"""
 
 NOT_IMPLEMENTED_501 = Status(501, "Not Implemented")
-"""501 Not Implemented"""
 
 SERVICE_UNAVAILABLE_503 = Status(503, "Service Unavailable")
-"""503 Service Unavailable"""