Add type hints to additional servlet functions (#10437)

Improves type hints for:

* parse_{boolean,integer}
* parse_{boolean,integer}_from_args
* parse_json_{value,object}_from_request

And fixes any incorrect calls that resulted from unknown types.
This commit is contained in:
Patrick Cloke 2021-07-21 14:12:22 -04:00 committed by GitHub
parent 5b68816de9
commit 590cc4e888
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 177 additions and 67 deletions

1
changelog.d/10437.misc Normal file
View File

@ -0,0 +1 @@
Improve servlet type hints.

View File

@ -984,7 +984,7 @@ class PublicRoomList(BaseFederationServlet):
limit = parse_integer_from_args(query, "limit", 0) limit = parse_integer_from_args(query, "limit", 0)
since_token = parse_string_from_args(query, "since", None) since_token = parse_string_from_args(query, "since", None)
include_all_networks = parse_boolean_from_args( include_all_networks = parse_boolean_from_args(
query, "include_all_networks", False query, "include_all_networks", default=False
) )
third_party_instance_id = parse_string_from_args( third_party_instance_id = parse_string_from_args(
query, "third_party_instance_id", None query, "third_party_instance_id", None
@ -1908,16 +1908,7 @@ class FederationSpaceSummaryServlet(BaseFederationServlet):
suggested_only = parse_boolean_from_args(query, "suggested_only", default=False) suggested_only = parse_boolean_from_args(query, "suggested_only", default=False)
max_rooms_per_space = parse_integer_from_args(query, "max_rooms_per_space") max_rooms_per_space = parse_integer_from_args(query, "max_rooms_per_space")
exclude_rooms = [] exclude_rooms = parse_strings_from_args(query, "exclude_rooms", default=[])
if b"exclude_rooms" in query:
try:
exclude_rooms = [
room_id.decode("ascii") for room_id in query[b"exclude_rooms"]
]
except Exception:
raise SynapseError(
400, "Bad query parameter for exclude_rooms", Codes.INVALID_PARAM
)
return 200, await self.handler.federation_space_summary( return 200, await self.handler.federation_space_summary(
origin, room_id, suggested_only, max_rooms_per_space, exclude_rooms origin, room_id, suggested_only, max_rooms_per_space, exclude_rooms

View File

@ -14,47 +14,86 @@
""" This module contains base REST classes for constructing REST servlets. """ """ This module contains base REST classes for constructing REST servlets. """
import logging import logging
from typing import Dict, Iterable, List, Optional, overload from typing import Iterable, List, Mapping, Optional, Sequence, overload
from typing_extensions import Literal from typing_extensions import Literal
from twisted.web.server import Request from twisted.web.server import Request
from synapse.api.errors import Codes, SynapseError from synapse.api.errors import Codes, SynapseError
from synapse.types import JsonDict
from synapse.util import json_decoder from synapse.util import json_decoder
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
def parse_integer(request, name, default=None, required=False): @overload
def parse_integer(request: Request, name: str, default: int) -> int:
...
@overload
def parse_integer(request: Request, name: str, *, required: Literal[True]) -> int:
...
@overload
def parse_integer(
request: Request, name: str, default: Optional[int] = None, required: bool = False
) -> Optional[int]:
...
def parse_integer(
request: Request, name: str, default: Optional[int] = None, required: bool = False
) -> Optional[int]:
"""Parse an integer parameter from the request string """Parse an integer parameter from the request string
Args: Args:
request: the twisted HTTP request. request: the twisted HTTP request.
name (bytes/unicode): the name of the query parameter. name: the name of the query parameter.
default (int|None): value to use if the parameter is absent, defaults default: value to use if the parameter is absent, defaults to None.
to None. required: whether to raise a 400 SynapseError if the parameter is absent,
required (bool): whether to raise a 400 SynapseError if the defaults to False.
parameter is absent, defaults to False.
Returns: Returns:
int|None: An int value or the default. An int value or the default.
Raises: Raises:
SynapseError: if the parameter is absent and required, or if the SynapseError: if the parameter is absent and required, or if the
parameter is present and not an integer. parameter is present and not an integer.
""" """
return parse_integer_from_args(request.args, name, default, required) args: Mapping[bytes, Sequence[bytes]] = request.args # type: ignore
return parse_integer_from_args(args, name, default, required)
def parse_integer_from_args(args, name, default=None, required=False): def parse_integer_from_args(
args: Mapping[bytes, Sequence[bytes]],
name: str,
default: Optional[int] = None,
required: bool = False,
) -> Optional[int]:
"""Parse an integer parameter from the request string
if not isinstance(name, bytes): Args:
name = name.encode("ascii") args: A mapping of request args as bytes to a list of bytes (e.g. request.args).
name: the name of the query parameter.
default: value to use if the parameter is absent, defaults to None.
required: whether to raise a 400 SynapseError if the parameter is absent,
defaults to False.
if name in args: Returns:
An int value or the default.
Raises:
SynapseError: if the parameter is absent and required, or if the
parameter is present and not an integer.
"""
name_bytes = name.encode("ascii")
if name_bytes in args:
try: try:
return int(args[name][0]) return int(args[name_bytes][0])
except Exception: except Exception:
message = "Query parameter %r must be an integer" % (name,) message = "Query parameter %r must be an integer" % (name,)
raise SynapseError(400, message, errcode=Codes.INVALID_PARAM) raise SynapseError(400, message, errcode=Codes.INVALID_PARAM)
@ -66,36 +105,102 @@ def parse_integer_from_args(args, name, default=None, required=False):
return default return default
def parse_boolean(request, name, default=None, required=False): @overload
def parse_boolean(request: Request, name: str, default: bool) -> bool:
...
@overload
def parse_boolean(request: Request, name: str, *, required: Literal[True]) -> bool:
...
@overload
def parse_boolean(
request: Request, name: str, default: Optional[bool] = None, required: bool = False
) -> Optional[bool]:
...
def parse_boolean(
request: Request, name: str, default: Optional[bool] = None, required: bool = False
) -> Optional[bool]:
"""Parse a boolean parameter from the request query string """Parse a boolean parameter from the request query string
Args: Args:
request: the twisted HTTP request. request: the twisted HTTP request.
name (bytes/unicode): the name of the query parameter. name: the name of the query parameter.
default (bool|None): value to use if the parameter is absent, defaults default: value to use if the parameter is absent, defaults to None.
to None. required: whether to raise a 400 SynapseError if the parameter is absent,
required (bool): whether to raise a 400 SynapseError if the defaults to False.
parameter is absent, defaults to False.
Returns: Returns:
bool|None: A bool value or the default. A bool value or the default.
Raises: Raises:
SynapseError: if the parameter is absent and required, or if the SynapseError: if the parameter is absent and required, or if the
parameter is present and not one of "true" or "false". parameter is present and not one of "true" or "false".
""" """
args: Mapping[bytes, Sequence[bytes]] = request.args # type: ignore
return parse_boolean_from_args(request.args, name, default, required) return parse_boolean_from_args(args, name, default, required)
def parse_boolean_from_args(args, name, default=None, required=False): @overload
def parse_boolean_from_args(
args: Mapping[bytes, Sequence[bytes]],
name: str,
default: bool,
) -> bool:
...
if not isinstance(name, bytes):
name = name.encode("ascii")
if name in args: @overload
def parse_boolean_from_args(
args: Mapping[bytes, Sequence[bytes]],
name: str,
*,
required: Literal[True],
) -> bool:
...
@overload
def parse_boolean_from_args(
args: Mapping[bytes, Sequence[bytes]],
name: str,
default: Optional[bool] = None,
required: bool = False,
) -> Optional[bool]:
...
def parse_boolean_from_args(
args: Mapping[bytes, Sequence[bytes]],
name: str,
default: Optional[bool] = None,
required: bool = False,
) -> Optional[bool]:
"""Parse a boolean parameter from the request query string
Args:
args: A mapping of request args as bytes to a list of bytes (e.g. request.args).
name: the name of the query parameter.
default: value to use if the parameter is absent, defaults to None.
required: whether to raise a 400 SynapseError if the parameter is absent,
defaults to False.
Returns:
A bool value or the default.
Raises:
SynapseError: if the parameter is absent and required, or if the
parameter is present and not one of "true" or "false".
"""
name_bytes = name.encode("ascii")
if name_bytes in args:
try: try:
return {b"true": True, b"false": False}[args[name][0]] return {b"true": True, b"false": False}[args[name_bytes][0]]
except Exception: except Exception:
message = ( message = (
"Boolean query parameter %r must be one of ['true', 'false']" "Boolean query parameter %r must be one of ['true', 'false']"
@ -111,7 +216,7 @@ def parse_boolean_from_args(args, name, default=None, required=False):
@overload @overload
def parse_bytes_from_args( def parse_bytes_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[bytes] = None, default: Optional[bytes] = None,
) -> Optional[bytes]: ) -> Optional[bytes]:
@ -120,7 +225,7 @@ def parse_bytes_from_args(
@overload @overload
def parse_bytes_from_args( def parse_bytes_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Literal[None] = None, default: Literal[None] = None,
*, *,
@ -131,7 +236,7 @@ def parse_bytes_from_args(
@overload @overload
def parse_bytes_from_args( def parse_bytes_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[bytes] = None, default: Optional[bytes] = None,
required: bool = False, required: bool = False,
@ -140,7 +245,7 @@ def parse_bytes_from_args(
def parse_bytes_from_args( def parse_bytes_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[bytes] = None, default: Optional[bytes] = None,
required: bool = False, required: bool = False,
@ -241,7 +346,7 @@ def parse_string(
parameter is present, must be one of a list of allowed values and parameter is present, must be one of a list of allowed values and
is not one of those allowed values. is not one of those allowed values.
""" """
args: Dict[bytes, List[bytes]] = request.args # type: ignore args: Mapping[bytes, Sequence[bytes]] = request.args # type: ignore
return parse_string_from_args( return parse_string_from_args(
args, args,
name, name,
@ -275,9 +380,8 @@ def _parse_string_value(
@overload @overload
def parse_strings_from_args( def parse_strings_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[List[str]] = None,
*, *,
allowed_values: Optional[Iterable[str]] = None, allowed_values: Optional[Iterable[str]] = None,
encoding: str = "ascii", encoding: str = "ascii",
@ -287,9 +391,20 @@ def parse_strings_from_args(
@overload @overload
def parse_strings_from_args( def parse_strings_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str,
default: List[str],
*,
allowed_values: Optional[Iterable[str]] = None,
encoding: str = "ascii",
) -> List[str]:
...
@overload
def parse_strings_from_args(
args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[List[str]] = None,
*, *,
required: Literal[True], required: Literal[True],
allowed_values: Optional[Iterable[str]] = None, allowed_values: Optional[Iterable[str]] = None,
@ -300,7 +415,7 @@ def parse_strings_from_args(
@overload @overload
def parse_strings_from_args( def parse_strings_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[List[str]] = None, default: Optional[List[str]] = None,
*, *,
@ -312,7 +427,7 @@ def parse_strings_from_args(
def parse_strings_from_args( def parse_strings_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[List[str]] = None, default: Optional[List[str]] = None,
required: bool = False, required: bool = False,
@ -361,7 +476,7 @@ def parse_strings_from_args(
@overload @overload
def parse_string_from_args( def parse_string_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[str] = None, default: Optional[str] = None,
*, *,
@ -373,7 +488,7 @@ def parse_string_from_args(
@overload @overload
def parse_string_from_args( def parse_string_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[str] = None, default: Optional[str] = None,
*, *,
@ -386,7 +501,7 @@ def parse_string_from_args(
@overload @overload
def parse_string_from_args( def parse_string_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[str] = None, default: Optional[str] = None,
required: bool = False, required: bool = False,
@ -397,7 +512,7 @@ def parse_string_from_args(
def parse_string_from_args( def parse_string_from_args(
args: Dict[bytes, List[bytes]], args: Mapping[bytes, Sequence[bytes]],
name: str, name: str,
default: Optional[str] = None, default: Optional[str] = None,
required: bool = False, required: bool = False,
@ -445,13 +560,14 @@ def parse_string_from_args(
return strings[0] return strings[0]
def parse_json_value_from_request(request, allow_empty_body=False): def parse_json_value_from_request(
request: Request, allow_empty_body: bool = False
) -> Optional[JsonDict]:
"""Parse a JSON value from the body of a twisted HTTP request. """Parse a JSON value from the body of a twisted HTTP request.
Args: Args:
request: the twisted HTTP request. request: the twisted HTTP request.
allow_empty_body (bool): if True, an empty body will be accepted and allow_empty_body: if True, an empty body will be accepted and turned into None
turned into None
Returns: Returns:
The JSON value. The JSON value.
@ -460,7 +576,7 @@ def parse_json_value_from_request(request, allow_empty_body=False):
SynapseError if the request body couldn't be decoded as JSON. SynapseError if the request body couldn't be decoded as JSON.
""" """
try: try:
content_bytes = request.content.read() content_bytes = request.content.read() # type: ignore
except Exception: except Exception:
raise SynapseError(400, "Error reading JSON content.") raise SynapseError(400, "Error reading JSON content.")
@ -476,13 +592,15 @@ def parse_json_value_from_request(request, allow_empty_body=False):
return content return content
def parse_json_object_from_request(request, allow_empty_body=False): def parse_json_object_from_request(
request: Request, allow_empty_body: bool = False
) -> JsonDict:
"""Parse a JSON object from the body of a twisted HTTP request. """Parse a JSON object from the body of a twisted HTTP request.
Args: Args:
request: the twisted HTTP request. request: the twisted HTTP request.
allow_empty_body (bool): if True, an empty body will be accepted and allow_empty_body: if True, an empty body will be accepted and turned into
turned into an empty dict. an empty dict.
Raises: Raises:
SynapseError if the request body couldn't be decoded as JSON or SynapseError if the request body couldn't be decoded as JSON or
@ -493,14 +611,14 @@ def parse_json_object_from_request(request, allow_empty_body=False):
if allow_empty_body and content is None: if allow_empty_body and content is None:
return {} return {}
if type(content) != dict: if not isinstance(content, dict):
message = "Content must be a JSON object." message = "Content must be a JSON object."
raise SynapseError(400, message, errcode=Codes.BAD_JSON) raise SynapseError(400, message, errcode=Codes.BAD_JSON)
return content return content
def assert_params_in_dict(body, required): def assert_params_in_dict(body: JsonDict, required: Iterable[str]) -> None:
absent = [] absent = []
for k in required: for k in required:
if k not in body: if k not in body:

View File

@ -754,7 +754,7 @@ class PublicRoomListRestServlet(TransactionRestServlet):
if server: if server:
raise e raise e
limit = parse_integer(request, "limit", 0) limit: Optional[int] = parse_integer(request, "limit", 0)
since_token = parse_string(request, "since") since_token = parse_string(request, "since")
if limit == 0: if limit == 0:

View File

@ -650,7 +650,7 @@ class StatsStore(StateDeltasStore):
order_by: Optional[str] = UserSortOrder.USER_ID.value, order_by: Optional[str] = UserSortOrder.USER_ID.value,
direction: Optional[str] = "f", direction: Optional[str] = "f",
search_term: Optional[str] = None, search_term: Optional[str] = None,
) -> Tuple[List[JsonDict], Dict[str, int]]: ) -> Tuple[List[JsonDict], int]:
"""Function to retrieve a paginated list of users and their uploaded local media """Function to retrieve a paginated list of users and their uploaded local media
(size and number). This will return a json list of users and the (size and number). This will return a json list of users and the
total number of users matching the filter criteria. total number of users matching the filter criteria.

View File

@ -261,7 +261,7 @@ class DeleteMediaByDateSizeTestCase(unittest.HomeserverTestCase):
self.assertEqual(400, int(channel.result["code"]), msg=channel.result["body"]) self.assertEqual(400, int(channel.result["code"]), msg=channel.result["body"])
self.assertEqual(Codes.MISSING_PARAM, channel.json_body["errcode"]) self.assertEqual(Codes.MISSING_PARAM, channel.json_body["errcode"])
self.assertEqual( self.assertEqual(
"Missing integer query parameter b'before_ts'", channel.json_body["error"] "Missing integer query parameter 'before_ts'", channel.json_body["error"]
) )
def test_invalid_parameter(self): def test_invalid_parameter(self):
@ -303,7 +303,7 @@ class DeleteMediaByDateSizeTestCase(unittest.HomeserverTestCase):
self.assertEqual(400, int(channel.result["code"]), msg=channel.result["body"]) self.assertEqual(400, int(channel.result["code"]), msg=channel.result["body"])
self.assertEqual(Codes.UNKNOWN, channel.json_body["errcode"]) self.assertEqual(Codes.UNKNOWN, channel.json_body["errcode"])
self.assertEqual( self.assertEqual(
"Boolean query parameter b'keep_profiles' must be one of ['true', 'false']", "Boolean query parameter 'keep_profiles' must be one of ['true', 'false']",
channel.json_body["error"], channel.json_body["error"],
) )