[Authlib] Improve utility functions

Author: donbarbos

stubs/Authlib/authlib/common/encoding.pyi

@@ -16,10 +16,10 @@ def to_unicode(x: None, charset: str = "utf-8", errors: str = "strict") -> None:
 @overload
 def to_unicode(x: object, charset: str = "utf-8", errors: str = "strict") -> str: ...
 
-def to_native(x: str | bytes, encoding: str = "ascii") -> str: ...
+def to_native(x: str | bytes | bytearray, encoding: str = "ascii") -> str: ...
 def json_loads(s: str | bytes | bytearray) -> Any: ...  # returns json.loads()
 def json_dumps(data: Any, ensure_ascii: bool = False) -> str: ...  # data pass to json.dumps()
-def urlsafe_b64decode(s: bytes) -> bytes: ...
+def urlsafe_b64decode(s: bytes | bytearray) -> bytes: ...
 def urlsafe_b64encode(s: ReadableBuffer) -> bytes: ...
 def base64_to_int(s: str | bytes | float | Iterable[SupportsIndex] | SupportsIndex | SupportsBytes | ReadableBuffer) -> int: ...
 def int_to_base64(num: int) -> str: ...

stubs/Authlib/authlib/common/urls.pyi

@@ -1,25 +1,24 @@
+from collections.abc import Iterable
 from re import Pattern
-from typing import Final, TypeAlias, overload
+from typing import Final, overload
 
 always_safe: Final[str]
 urlencoded: Final[set[str]]
 INVALID_HEX_PATTERN: Final[Pattern[str]]
 
-_ExplodedQueryString: TypeAlias = list[tuple[str, str]]
-
-def url_encode(params: _ExplodedQueryString) -> str: ...
-def url_decode(query: str) -> _ExplodedQueryString: ...
-def add_params_to_qs(query: str, params: _ExplodedQueryString | dict[str, str]) -> str: ...
-def add_params_to_uri(uri: str, params: _ExplodedQueryString, fragment: bool = False) -> str: ...
-def quote(s: str, safe: bytes = b"/") -> str: ...
+def url_encode(params: Iterable[tuple[str, str]]) -> str: ...
+def url_decode(query: str) -> list[tuple[str, str]]: ...
+def add_params_to_qs(query: str, params: Iterable[tuple[str, str]] | dict[str, str]) -> str: ...
+def add_params_to_uri(uri: str, params: Iterable[tuple[str, str]] | dict[str, str], fragment: bool = False) -> str: ...
+def quote(s: str | bytes | float, safe: bytes = b"/") -> str: ...
 def unquote(s: str | bytes) -> str: ...
-def quote_url(s: str) -> str: ...
+def quote_url(s: str | bytes | float) -> str: ...
 
 @overload
 def extract_params(raw: None) -> None: ...
 @overload
-def extract_params(raw: dict[str, str]) -> _ExplodedQueryString: ...
+def extract_params(raw: dict[str, str]) -> list[tuple[str, str]]: ...
 @overload
-def extract_params(raw: _ExplodedQueryString | tuple[tuple[str, str], ...] | str) -> _ExplodedQueryString | None: ...
+def extract_params(raw: list[tuple[str, str]] | tuple[tuple[str, str], ...] | str) -> list[tuple[str, str]] | None: ...
 
 def is_valid_url(url: str, fragments_allowed: bool = True) -> bool: ...

stubs/Authlib/authlib/integrations/httpx_client/utils.pyi

@@ -1,7 +1,18 @@
 from _typeshed import Incomplete
-from typing import Final
+from collections.abc import AsyncIterable, Iterable, Mapping, MutableMapping, Sequence
+from typing import Final, TypeAlias
 
 HTTPX_CLIENT_KWARGS: Final[list[str]]
 
-def extract_client_kwargs(kwargs) -> dict[str, Incomplete]: ...
-def build_request(url, headers, body, initial_request): ...
+_Request: TypeAlias = Incomplete  # actual type is httpx.Request
+_URL: TypeAlias = Incomplete  # actual type is httpx.URL
+_Headers: TypeAlias = MutableMapping[str, str]  # actual type is httpx.Headers
+_HeaderTypes: TypeAlias = (  # actual type is httpx._types.HeaderTypes
+    _Headers | Mapping[str, str] | Mapping[bytes, bytes] | Sequence[tuple[str, str]] | Sequence[tuple[bytes, bytes]]
+)
+_RequestContent: TypeAlias = str | bytes | Iterable[bytes] | AsyncIterable[bytes]  # actual type is httpx._types.RequestContent
+
+def extract_client_kwargs(kwargs: dict[str, Incomplete]) -> dict[str, Incomplete]: ...
+def build_request(
+    url: _URL | str, headers: _HeaderTypes | None, body: _RequestContent, initial_request: _Request
+) -> _Request: ...

stubs/Authlib/authlib/oauth1/rfc5849/parameters.pyi

@@ -1,3 +1,10 @@
-def prepare_headers(oauth_params, headers=None, realm=None): ...
-def prepare_form_encoded_body(oauth_params, body) -> str: ...
-def prepare_request_uri_query(oauth_params, uri): ...
+from collections.abc import Iterable
+from typing import TypeVar
+
+_K = TypeVar("_K")
+
+def prepare_headers(
+    oauth_params: Iterable[tuple[str, str]], headers: dict[str, _K] | None = None, realm=None
+) -> dict[str, _K | str]: ...
+def prepare_form_encoded_body(oauth_params: Iterable[tuple[str, str]], body: Iterable[tuple[str, str]]) -> str: ...
+def prepare_request_uri_query(oauth_params: Iterable[tuple[str, str]], uri: str) -> str: ...

stubs/Authlib/authlib/oauth1/rfc5849/util.pyi

@@ -1,2 +1,2 @@
-def escape(s) -> str: ...
+def escape(s: str | bytes | float) -> str: ...
 def unescape(s: str | bytes) -> str: ...

stubs/Authlib/authlib/oauth2/rfc6749/parameters.pyi

@@ -1,6 +1,22 @@
-from _typeshed import Incomplete
+from collections.abc import Collection, Sequence
 
-def prepare_grant_uri(uri, client_id, response_type, redirect_uri=None, scope=None, state=None, **kwargs): ...
-def prepare_token_request(grant_type, body: str = "", redirect_uri=None, **kwargs) -> str: ...
-def parse_authorization_code_response(uri, state=None) -> dict[Incomplete, Incomplete]: ...
-def parse_implicit_response(uri, state=None) -> dict[Incomplete, Incomplete]: ...
+def prepare_grant_uri(
+    uri: str,
+    client_id: str,
+    response_type: str,
+    redirect_uri: str | None = None,
+    scope: Collection[str] | str | None = None,
+    state: str | None = None,
+    **kwargs: str | Sequence[str | None] | None,
+): ...
+def prepare_token_request(
+    grant_type: str,
+    body: str = "",
+    redirect_uri: str | None = None,
+    *,
+    scope: Collection[str] | str | None = None,
+    code: str | None = None,
+    **kwargs: str | None,
+) -> str: ...
+def parse_authorization_code_response(uri: str, state: str | None = None) -> dict[str, str]: ...
+def parse_implicit_response(uri: str, state: str | None = None) -> dict[str, str]: ...

stubs/Authlib/authlib/oauth2/rfc6749/util.pyi

@@ -1,5 +1,14 @@
 from collections.abc import Collection
+from typing import overload
 
-def list_to_scope(scope: Collection[str] | str | None) -> str: ...
-def scope_to_list(scope: Collection[str] | str | None) -> list[str]: ...
-def extract_basic_authorization(headers: dict[str, str]) -> tuple[str, str]: ...
+@overload
+def list_to_scope(scope: str | Collection[str]) -> str: ...
+@overload
+def list_to_scope(scope: None) -> None: ...
+
+@overload
+def scope_to_list(scope: str | Collection[str]) -> list[str]: ...
+@overload
+def scope_to_list(scope: None) -> None: ...
+
+def extract_basic_authorization(headers: dict[str, str]) -> tuple[str, str] | tuple[str, None] | tuple[None, None]: ...

stubs/Authlib/authlib/oauth2/rfc6750/parameters.pyi

@@ -1,6 +1,14 @@
-from _typeshed import Incomplete
+from typing import Literal, TypeVar
 
-def add_to_uri(token, uri) -> str: ...
-def add_to_headers(token, headers=None): ...
-def add_to_body(token, body=None) -> str: ...
-def add_bearer_token(token, uri, headers, body, placement: str = "header") -> tuple[Incomplete, Incomplete, Incomplete]: ...
+_K = TypeVar("_K")
+
+def add_to_uri(token: str, uri: str) -> str: ...
+def add_to_headers(token: str, headers: dict[str, _K] | None = None) -> dict[str, _K | str]: ...
+def add_to_body(token: str, body: str | None = None) -> str: ...
+def add_bearer_token(
+    token: str,
+    uri: str,
+    headers: dict[str, _K],
+    body: str,
+    placement: Literal["uri", "url", "query", "header", "headers", "body"] = "header",
+) -> tuple[str, dict[str, _K | str], str]: ...

stubs/Authlib/authlib/oauth2/rfc7009/parameters.pyi

@@ -1 +1,7 @@
-def prepare_revoke_token_request(token, token_type_hint=None, body=None, headers=None): ...
+from typing import TypeVar
+
+_K = TypeVar("_K")
+
+def prepare_revoke_token_request(
+    token: str, token_type_hint: str | None = None, body: str | None = None, headers: dict[str, _K] | None = None
+) -> tuple[str, dict[str, _K | str]]: ...

stubs/Authlib/authlib/oidc/core/grants/util.pyi

@@ -1,7 +1,11 @@
+from _typeshed import ReadableBuffer
+from collections.abc import Collection, Iterable
+from typing import Literal, SupportsBytes, SupportsIndex, overload
+
 from authlib.oidc.core import UserInfo
 
-def is_openid_scope(scope: str | None) -> bool: ...
-def validate_request_prompt(grant, redirect_uri, redirect_fragment: bool = False): ...
+def is_openid_scope(scope: Collection[str] | str | None) -> bool: ...
+def validate_request_prompt(grant, redirect_uri: str, redirect_fragment: bool = False): ...
 def validate_nonce(request, exists_nonce, required: bool = False): ...
 def generate_id_token(
     token: dict[str, str | int],
@@ -15,7 +19,15 @@ def generate_id_token(
     auth_time: int | None = None,
     acr: str | None = None,
     amr: list[str] | None = None,
-    code: str | None = None,
+    code: str | bytes | float | Iterable[SupportsIndex] | SupportsIndex | SupportsBytes | ReadableBuffer | None = None,
     kid: str | None = None,
 ) -> str: ...
-def create_response_mode_response(redirect_uri, params, response_mode): ...
+
+@overload
+def create_response_mode_response(
+    redirect_uri: str, params: Iterable[tuple[str, str]], response_mode: Literal["form_post"]
+) -> tuple[Literal[200], str, list[tuple[str, str]]]: ...
+@overload  # `params` can accept dict in another mode
+def create_response_mode_response(
+    redirect_uri: str, params: Iterable[tuple[str, str]] | dict[str, str], response_mode: Literal["query", "fragment"]
+) -> tuple[Literal[302], str, list[tuple[str, str]]]: ...