Improve oauthlib.common (#13744)

stubs/oauthlib/oauthlib/__init__.pyi

@@ -1,2 +1,7 @@
-def set_debug(debug_val) -> None: ...
-def get_debug(): ...
+from typing import Final
+
+__author__: Final[str]
+__version__: Final[str]
+
+def set_debug(debug_val: bool) -> None: ...
+def get_debug() -> bool: ...

stubs/oauthlib/oauthlib/common.pyi

@@ -1,64 +1,81 @@
-from _typeshed import Incomplete
-from typing import Any
+import re
+from _typeshed import Incomplete, SupportsLenAndGetItem
+from collections.abc import Iterable, Mapping
+from logging import Logger
+from typing import Any, Final, Literal, TypeVar, overload
+from typing_extensions import TypeAlias
 
-UNICODE_ASCII_CHARACTER_SET: str
-CLIENT_ID_CHARACTER_SET: str
-SANITIZE_PATTERN: Any
-INVALID_HEX_PATTERN: Any
-always_safe: str
-log: Any
+_T = TypeVar("_T")
+_V = TypeVar("_V")
 
-def quote(s, safe: bytes = b"/"): ...
-def unquote(s): ...
-def urlencode(params): ...
-def encode_params_utf8(params): ...
-def decode_params_utf8(params): ...
+_HTTPMethod: TypeAlias = Literal["CONNECT", "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT", "TRACE"]
 
-urlencoded: Any
+UNICODE_ASCII_CHARACTER_SET: Final[str]
+CLIENT_ID_CHARACTER_SET: Final[str]
+SANITIZE_PATTERN: Final[re.Pattern[str]]
+INVALID_HEX_PATTERN: Final[re.Pattern[str]]
+always_safe: Final[str]
+log: Logger
 
-def urldecode(query): ...
-def extract_params(raw): ...
-def generate_nonce(): ...
-def generate_timestamp(): ...
-def generate_token(length: int = 30, chars=...): ...
-def generate_signed_token(private_pem, request): ...
+def quote(s: str | bytes, safe: bytes = b"/") -> str: ...
+def unquote(s: str | bytes) -> str: ...
+def urlencode(params: Iterable[tuple[str | bytes, str | bytes]]) -> str: ...
+def encode_params_utf8(params: Iterable[tuple[str | bytes, str | bytes]]) -> list[tuple[bytes, bytes]]: ...
+def decode_params_utf8(params: Iterable[tuple[str | bytes, str | bytes]]) -> list[tuple[str, str]]: ...
+
+urlencoded: Final[set[str]]
+
+def urldecode(query: str | bytes) -> list[tuple[str, str]]: ...
+def extract_params(raw: str | bytes | dict[str, str] | Iterable[tuple[str, str]]) -> list[tuple[str, str]] | None: ...
+def generate_nonce() -> str: ...
+def generate_timestamp() -> str: ...
+def generate_token(length: int = 30, chars: SupportsLenAndGetItem[str] = ...) -> str: ...
+def generate_signed_token(private_pem: str, request: Request) -> str: ...
 def verify_signed_token(public_pem, token): ...
-def generate_client_id(length: int = 30, chars=...): ...
-def add_params_to_qs(query, params): ...
-def add_params_to_uri(uri, params, fragment: bool = False): ...
-def safe_string_equals(a, b): ...
-def to_unicode(data, encoding: str = "UTF-8"): ...
+def generate_client_id(length: int = 30, chars: SupportsLenAndGetItem[str] = ...) -> str: ...
+def add_params_to_qs(query: str, params: dict[str, str] | Iterable[tuple[str, str]]) -> str: ...
+def add_params_to_uri(uri: str, params: dict[str, str] | Iterable[tuple[str, str]], fragment: bool = False) -> str: ...
+def safe_string_equals(a: str, b: str) -> bool: ...
+@overload
+def to_unicode(data: str | bytes, encoding: str = "UTF-8") -> str: ...
+@overload
+def to_unicode(data: Mapping[str, _V] | Mapping[bytes, _V], encoding: str = "UTF-8") -> dict[str, _V]: ...
+@overload
+def to_unicode(data: _T, encoding: str = "UTF-8") -> _T: ...
 
-class CaseInsensitiveDict(dict[Any, Any]):
-    proxy: Any
-    def __init__(self, data) -> None: ...
-    def __contains__(self, k): ...
-    def __delitem__(self, k) -> None: ...
-    def __getitem__(self, k): ...
-    def get(self, k, default: Incomplete | None = None): ...
-    def __setitem__(self, k, v) -> None: ...
+class CaseInsensitiveDict(dict[str, Incomplete]):
+    proxy: dict[str, str]
+    def __init__(self, data: dict[str, Incomplete]) -> None: ...
+    @overload
+    def __contains__(self, k: str) -> bool: ...
+    @overload
+    def __contains__(self, k: object) -> bool: ...
+    def __delitem__(self, k: str) -> None: ...
+    def __getitem__(self, k: str): ...
+    def get(self, k: str, default: Incomplete | None = None) -> Incomplete | None: ...
+    def __setitem__(self, k: str, v) -> None: ...
     def update(self, *args, **kwargs) -> None: ...
 
 class Request:
-    uri: Any
-    http_method: Any
-    headers: Any
-    body: Any
-    decoded_body: Any
-    oauth_params: Any
-    validator_log: Any
+    uri: str
+    http_method: _HTTPMethod
+    headers: CaseInsensitiveDict
+    body: str | dict[str, str] | list[tuple[str, str]] | None
+    decoded_body: list[tuple[str, str]] | None
+    oauth_params: list[str]
+    validator_log: dict[str, Any]  # value type depends on the key
     def __init__(
         self,
-        uri,
-        http_method: str = "GET",
-        body: Incomplete | None = None,
-        headers: Incomplete | None = None,
+        uri: str,
+        http_method: _HTTPMethod = "GET",
+        body: str | dict[str, str] | list[tuple[str, str]] | None = None,
+        headers: Mapping[str, str] | None = None,
         encoding: str = "utf-8",
     ): ...
-    def __getattr__(self, name: str): ...
+    def __getattr__(self, name: str) -> str | None: ...  # or raises AttributeError if attribute is not found
     @property
-    def uri_query(self): ...
+    def uri_query(self) -> str: ...
     @property
-    def uri_query_params(self): ...
+    def uri_query_params(self) -> list[tuple[str, str]]: ...
     @property
-    def duplicate_params(self): ...
+    def duplicate_params(self) -> list[str]: ...

stubs/oauthlib/oauthlib/signals.pyi

@@ -1,15 +1,14 @@
-from _typeshed import Incomplete
 from typing import Any
 
 signals_available: bool
 
 class Namespace:
-    def signal(self, name, doc: Incomplete | None = None): ...
+    def signal(self, name: str, doc: str | None = None) -> _FakeSignal: ...
 
 class _FakeSignal:
-    name: Any
+    name: str
     __doc__: Any
-    def __init__(self, name, doc: Incomplete | None = None) -> None: ...
+    def __init__(self, name: str, doc: str | None = None) -> None: ...
     send: Any
     connect: Any
     disconnect: Any
@@ -18,4 +17,4 @@ class _FakeSignal:
     temporarily_connected_to: Any
     connected_to: Any
 
-scope_changed: Any
+scope_changed: _FakeSignal

stubs/oauthlib/oauthlib/uri_validate.pyi

@@ -1,43 +1,44 @@
-from typing import Any
+import re
+from typing import Final
 
-DIGIT: str
-ALPHA: str
-HEXDIG: str
-pct_encoded: Any
-unreserved: Any
-gen_delims: str
-sub_delims: str
-pchar: Any
-reserved: Any
-scheme: Any
-dec_octet: Any
-IPv4address: Any
-IPv6address: str
-IPvFuture: Any
-IP_literal: Any
-reg_name: Any
-userinfo: Any
-host: Any
-port: Any
-authority: Any
-segment: Any
-segment_nz: Any
-segment_nz_nc: Any
-path_abempty: Any
-path_absolute: Any
-path_noscheme: Any
-path_rootless: Any
-path_empty: str
-path: Any
-query: Any
-fragment: Any
-hier_part: Any
-relative_part: Any
-relative_ref: Any
-URI: Any
-URI_reference: Any
-absolute_URI: Any
+DIGIT: Final[str]
+ALPHA: Final[str]
+HEXDIG: Final[str]
+pct_encoded: Final[str]
+unreserved: Final[str]
+gen_delims: Final[str]
+sub_delims: Final[str]
+pchar: Final[str]
+reserved: Final[str]
+scheme: Final[str]
+dec_octet: Final[str]
+IPv4address: Final[str]
+IPv6address: Final[str]
+IPvFuture: Final[str]
+IP_literal: Final[str]
+reg_name: Final[str]
+userinfo: Final[str]
+host: Final[str]
+port: Final[str]
+authority: Final[str]
+segment: Final[str]
+segment_nz: Final[str]
+segment_nz_nc: Final[str]
+path_abempty: Final[str]
+path_absolute: Final[str]
+path_noscheme: Final[str]
+path_rootless: Final[str]
+path_empty: Final[str]
+path: Final[str]
+query: Final[str]
+fragment: Final[str]
+hier_part: Final[str]
+relative_part: Final[str]
+relative_ref: Final[str]
+URI: Final[str]
+URI_reference: Final[str]
+absolute_URI: Final[str]
 
-def is_uri(uri): ...
-def is_uri_reference(uri): ...
-def is_absolute_uri(uri): ...
+def is_uri(uri: str) -> re.Match[str] | None: ...
+def is_uri_reference(uri: str) -> re.Match[str] | None: ...
+def is_absolute_uri(uri: str) -> re.Match[str] | None: ...