Correct docstrings and incorrect typehints

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 - Updates `query_ipv4` method name to `query_address` to be more representative of what it actually does.
+- Corrections to some docstrings and typehints.
 
 ## [3.1.2] - 2024-11-18
 - Fixes a regression caused by [#258](https://github.com/dsgnr/portchecker.io/pull/258)

backend/api/app/helpers/query.py

@@ -20,7 +20,7 @@ def is_ip_address(address: str) -> bool:
     Attempts to parse the provided address string as an IP address.
     Returns `True` if the address is valid, otherwise `False`.
 
-    Parameters:
+    Args:
         address (str): The string to check for IP address validity.
 
     Returns:
@@ -40,7 +40,7 @@ def is_address_valid(address: str) -> bool:
     private and the environment variable `ALLOW_PRIVATE` is not set, an error is raised.
     IPv6 addresses are not supported and will raise a `ValueError`.
 
-    Parameters:
+    Args:
         address (str): The IPv4 address string to validate.
 
     Returns:
@@ -67,7 +67,7 @@ def is_valid_hostname(hostname: str) -> bool:
 
     Validates whether the provided hostname is resolveable.
 
-    Parameters:
+    Args:
         hostname (str): The hostname to validate.
 
     Returns:
@@ -90,27 +90,32 @@ def is_valid_hostname(hostname: str) -> bool:
         raise ValueError("Hostname does not appear to resolve") from socket_err
 
 
-def _check_port_status(address: str, port: int) -> list[str, int]:
+def _check_port_status(address: str, port: int) -> dict[str, int | bool]:
     """Check if a specific port on the provided address is open.
 
-    Returns a dictionary with the port and the connection status.
+    Args:
+        address (str): The IP address to check.
+        port (int): The port to check on the given address.
+
+    Returns:
+        dict[str, int | bool]: Returns a dictionary with the port and the connection status.
     """
     with socket.socket() as sock:
         sock.settimeout(1)  # Set a timeout of 1 second
         result = sock.connect_ex((address, port))  # 0 if open, non-zero if closed
         return {"port": port, "status": result == 0}
 
 
-def check_ports(address: str, ports: dict[int]) -> list[dict[str, int]]:
+def check_ports(address: str, ports: list[int]) -> list[dict[str, int | bool]]:
     """Check multiple ports for the provided address with threading.
 
     Args:
-        address (str): The IP address to check.
+        address (str): The hostname or IPv4 address to query.
         ports (list[int]): List of ports to check on the given address.
-        max_threads (int): Maximum number of threads to use. Default is 10.
 
     Returns:
-        list[dict[str, int]]: A list of dictionaries containing port numbers and their statuses.
+        list[dict[str, int | bool]]:
+            A list of dictionaries containing the ports checked and their statuses.
     """
     results = []
     with ThreadPoolExecutor() as executor:
@@ -133,7 +138,7 @@ def query_address(address: str, ports: list[int]) -> list[dict]:
     a resolvable hostname. Then attempts to establish a socket connection to each port
     provided in `ports`.
 
-    Parameters:
+    Args:
         address (str): The hostname or IPv4 address to query.
         ports (list[int]): A list of port numbers to check for connectability.
 
@@ -167,7 +172,7 @@ def get_requester(request: Request) -> str:
 
     If none of these headers are found, the function raises a `ValueError`.
 
-    Parameters:
+    Args:
         request (Request): The HTTP request containing headers.
 
     Returns:

backend/api/app/routes/v2.py

@@ -14,7 +14,7 @@
     APISchema,
     HostAnnotation,
     PortAnnotation,
-    PortCheckAnnotation,
+    PortCheckStrAnnotation,
     RequesterAnnotation,
 )
 
@@ -43,7 +43,7 @@ def my_ip(request: Request) -> RequesterAnnotation:
 @get("/api/{host:str}/{port:int}", media_type=MediaType.TEXT, sync_to_thread=False)
 def get_port_check(
     request: Request, host: HostAnnotation, port: PortAnnotation
-) -> PortCheckAnnotation:
+) -> PortCheckStrAnnotation:
     """
     A `GET` endpoint to check the status of a specific port on a given
     resolvable hostname or IPv4 address.

backend/api/app/schemas/api.py

@@ -33,6 +33,14 @@
     Le(65535),
 ]
 
+PortCheckStrAnnotation = Annotated[
+    str,
+    Parameter(
+        description="Whether the port was connectable",
+        examples=[Example(value="True")],
+    ),
+]
+
 PortCheckAnnotation = Annotated[
     bool,
     Parameter(