docs(python): replace List with Sequence for immutable returns (#417)

Author: 0x676e67

python/rnet/__init__.pyi

@@ -1,13 +1,13 @@
 import datetime
-import ipaddress
+from ipaddress import IPv4Address, IPv6Address
 from typing import (
     AsyncGenerator,
     Generator,
     Optional,
     Tuple,
     Any,
     Dict,
-    List,
+    Sequence,
     TypedDict,
     Unpack,
     NotRequired,
@@ -101,7 +101,7 @@ class SocketAddr:
     """
 
     def __str__(self) -> str: ...
-    def ip(self) -> ipaddress.IPv4Address | ipaddress.IPv6Address:
+    def ip(self) -> IPv4Address | IPv6Address:
         r"""
         Returns the IP address of the socket address.
         """
@@ -446,7 +446,7 @@ class Response:
     Get the headers of the response.
     """
 
-    cookies: List[Cookie]
+    cookies: Sequence[Cookie]
     r"""
     Get the cookies of the response.
     """
@@ -466,7 +466,7 @@ class Response:
     Get the local address of the response.
     """
 
-    history: List[History]
+    history: Sequence[History]
     r"""
     Get the redirect history of the Response.
     """
@@ -536,7 +536,7 @@ class WebSocket:
     Get the headers of the response.
     """
 
-    cookies: List[Cookie]
+    cookies: Sequence[Cookie]
     r"""
     Get the cookies of the response.
     """
@@ -563,7 +563,7 @@ class WebSocket:
         Send a message to the WebSocket.
         """
 
-    async def send_all(self, messages: List[Message]) -> None:
+    async def send_all(self, messages: Sequence[Message]) -> None:
         r"""
         Send multiple messages to the WebSocket.
         """
@@ -594,7 +594,7 @@ class ClientParams(TypedDict):
     Default request headers.
     """
 
-    orig_headers: NotRequired[List[str] | OrigHeaderMap]
+    orig_headers: NotRequired[Sequence[str] | OrigHeaderMap]
     """
     Original request headers (case-sensitive and order).
     """
@@ -771,12 +771,12 @@ class ClientParams(TypedDict):
     Disable proxy.
     """
 
-    proxies: NotRequired[List[Proxy]]
+    proxies: NotRequired[Sequence[Proxy]]
     """
     Proxy server list.
     """
 
-    local_address: NotRequired[str | ipaddress.IPv4Address | ipaddress.IPv6Address]
+    local_address: NotRequired[str | IPv4Address | IPv6Address]
     """
     Local bind address.
     """
@@ -823,7 +823,7 @@ class Request(TypedDict):
     The proxy to use for the request.
     """
 
-    local_address: NotRequired[ipaddress.IPv4Address | ipaddress.IPv6Address]
+    local_address: NotRequired[IPv4Address | IPv6Address]
     """
     Bind to a local IP Address.
     """
@@ -853,7 +853,7 @@ class Request(TypedDict):
     The headers to use for the request.
     """
 
-    orig_headers: NotRequired[List[str] | OrigHeaderMap]
+    orig_headers: NotRequired[Sequence[str] | OrigHeaderMap]
     """
     The original headers to use for the request.
     """
@@ -913,12 +913,12 @@ class Request(TypedDict):
     The basic authentication to use for the request.
     """
 
-    query: NotRequired[List[Tuple[str, str]] | Dict[str, str]]
+    query: NotRequired[Sequence[Tuple[str, str]] | Dict[str, str]]
     """
     The query parameters to use for the request.
     """
 
-    form: NotRequired[List[Tuple[str, str]] | Dict[str, str]]
+    form: NotRequired[Sequence[Tuple[str, str]] | Dict[str, str]]
     """
     The form parameters to use for the request.
     """
@@ -931,9 +931,9 @@ class Request(TypedDict):
     body: NotRequired[
         str
         | bytes
-        | list[tuple[str, str]]
-        | dict[str, str]
-        | dict[str, Any]
+        | Sequence[Tuple[str, str]]
+        | Dict[str, str]
+        | Dict[str, Any]
         | Generator[bytes, str, None]
         | AsyncGenerator[bytes, str]
     ]
@@ -957,7 +957,7 @@ class WebSocketRequest(TypedDict):
     The proxy to use for the request.
     """
 
-    local_address: NotRequired[str | ipaddress.IPv4Address | ipaddress.IPv6Address]
+    local_address: NotRequired[str | IPv4Address | IPv6Address]
     """
     Bind to a local IP Address.
     """
@@ -972,7 +972,7 @@ class WebSocketRequest(TypedDict):
     The headers to use for the request.
     """
 
-    orig_headers: NotRequired[List[str] | OrigHeaderMap]
+    orig_headers: NotRequired[Sequence[str] | OrigHeaderMap]
     """
     The original headers to use for the request.
     """
@@ -987,7 +987,7 @@ class WebSocketRequest(TypedDict):
     The cookies to use for the request.
     """
 
-    protocols: NotRequired[List[str]]
+    protocols: NotRequired[Sequence[str]]
     """
     The protocols to use for the request.
     """
@@ -1012,7 +1012,7 @@ class WebSocketRequest(TypedDict):
     The basic authentication to use for the request.
     """
 
-    query: NotRequired[List[Tuple[str, str]]]
+    query: NotRequired[Sequence[Tuple[str, str]]]
     """
     The query parameters to use for the request.
     """

python/rnet/blocking.py

@@ -14,7 +14,7 @@
 from typing import (
     Optional,
     Any,
-    List,
+    Sequence,
     Unpack,
 )
 
@@ -47,7 +47,7 @@ class Response:
     Get the headers of the response.
     """
 
-    cookies: List[Cookie]
+    cookies: Sequence[Cookie]
     r"""
     Get the cookies of the response.
     """
@@ -67,7 +67,7 @@ class Response:
     Get the local address of the response.
     """
 
-    history: List[History]
+    history: Sequence[History]
     r"""
     Get the redirect history of the Response.
     """
@@ -140,7 +140,7 @@ class WebSocket:
     Get the headers of the response.
     """
 
-    cookies: List[Cookie]
+    cookies: Sequence[Cookie]
     r"""
     Get the cookies of the response.
     """
@@ -169,13 +169,13 @@ def send(self, message: Message) -> None:
         * `message` - The message to send.
         """
 
-    def send_all(self, messages: List[Message]) -> None:
+    def send_all(self, messages: Sequence[Message]) -> None:
         r"""
         Send multiple messages to the WebSocket.
 
         # Arguments
 
-        * `messages` - The list of messages to send.
+        * `messages` - The sequence of messages to send.
         """
 
     def close(

python/rnet/cookie.py

@@ -8,7 +8,7 @@
 
 import datetime
 from enum import Enum, auto
-from typing import List, Optional, final
+from typing import Optional, Sequence, final
 
 __all__ = ["SameSite", "Cookie", "Jar"]
 
@@ -110,7 +110,7 @@ def get(self, name: str, url: str) -> Optional[Cookie]:
         """
         ...
 
-    def get_all(self) -> List[Cookie]:
+    def get_all(self) -> Sequence[Cookie]:
         r"""
         Get all cookies.
         """

python/rnet/header.py

@@ -11,7 +11,7 @@
 Set-Cookie, Accept-Encoding, etc.).
 """
 
-from typing import Dict, Iterator, List, Optional, Tuple
+from typing import Dict, Iterator, Optional, Sequence, Tuple
 
 __all__ = ["HeaderMap", "OrigHeaderMap"]
 
@@ -265,7 +265,7 @@ class OrigHeaderMap:
 
     def __init__(
         self,
-        init: Optional[List[str]] = None,
+        init: Optional[Sequence[str]] = None,
         capacity: Optional[int] = None,
     ) -> None:
         """

python/rnet/tls.py

@@ -8,7 +8,7 @@
 
 from enum import Enum, auto
 from pathlib import Path
-from typing import List, NotRequired, TypedDict, Unpack, final
+from typing import Sequence, NotRequired, TypedDict, Unpack, final
 
 __all__ = [
     "TlsVersion",
@@ -152,8 +152,8 @@ class CertStore:
 
     def __init__(
         self,
-        der_certs: List[bytes] | None = None,
-        pem_certs: List[str] | None = None,
+        der_certs: Sequence[bytes] | None = None,
+        pem_certs: Sequence[str] | None = None,
         default_paths: bool | None = None,
     ) -> None:
         """
@@ -167,7 +167,7 @@ def __init__(
         ...
 
     @staticmethod
-    def from_der_certs(certs: List[bytes]) -> "CertStore":
+    def from_der_certs(certs: Sequence[bytes]) -> "CertStore":
         """
         Creates a CertStore from a collection of DER-encoded certificates.
 
@@ -177,7 +177,7 @@ def from_der_certs(certs: List[bytes]) -> "CertStore":
         ...
 
     @staticmethod
-    def from_pem_certs(certs: List[str]) -> "CertStore":
+    def from_pem_certs(certs: Sequence[str]) -> "CertStore":
         """
         Creates a CertStore from a collection of PEM-encoded certificates.
 
@@ -243,15 +243,15 @@ class Params(TypedDict):
     All parameters for TLS connections.
     """
 
-    alpn_protocols: NotRequired[List[AlpnProtocol]]
+    alpn_protocols: NotRequired[Sequence[AlpnProtocol]]
     """
     Application-Layer Protocol Negotiation (RFC 7301).
 
     Specifies which application protocols (e.g., HTTP/2, HTTP/1.1) may be negotiated
     over a single TLS connection.
     """
 
-    alps_protocols: NotRequired[List[AlpsProtocol]]
+    alps_protocols: NotRequired[Sequence[AlpsProtocol]]
     """
     Application-Layer Protocol Settings (ALPS).
 
@@ -369,13 +369,13 @@ class Params(TypedDict):
     """
 
     certificate_compression_algorithms: NotRequired[
-        List[CertificateCompressionAlgorithm]
+        Sequence[CertificateCompressionAlgorithm]
     ]
     """
     Supported certificate compression algorithms (RFC 8879).
     """
 
-    extension_permutation: NotRequired[List[ExtensionType]]
+    extension_permutation: NotRequired[Sequence[ExtensionType]]
     """
     Supported TLS extensions, used for extension ordering/permutation.
     """