forked from s3lph/matemat
325 lines
12 KiB
Python
325 lines
12 KiB
Python
|
|
from __future__ import annotations
|
|
from typing import Dict, Iterator, List, Tuple, Union
|
|
|
|
|
|
class RequestArguments(object):
|
|
"""
|
|
Container for HTTP Request arguments.
|
|
|
|
Usage:
|
|
|
|
# Create empty instance
|
|
ra = RequestArguments()
|
|
# Add an entry for the key 'foo' with the value 'bar' and Content-Type 'text/plain'
|
|
ra['foo'].append('text/plain', 'bar')
|
|
# Retrieve the value for the key 'foo', as a string...
|
|
foo = str(ra.foo)
|
|
# ... or as raw bytes
|
|
foo = bytes(ra.foo)
|
|
"""
|
|
|
|
def __init__(self) -> None:
|
|
"""
|
|
Create an empty container instance.
|
|
"""
|
|
self.__container: Dict[str, RequestArgument] = dict()
|
|
|
|
def __getitem__(self, key: str) -> RequestArgument:
|
|
"""
|
|
Retrieve the argument for the given name, creating it on the fly, if it doesn't exist.
|
|
|
|
:param key: Name of the argument to retrieve.
|
|
:return: A RequestArgument instance.
|
|
:raises TypeError: If key is not a string.
|
|
"""
|
|
if not isinstance(key, str):
|
|
raise TypeError('key must be a str')
|
|
# Create empty argument, if it doesn't exist
|
|
if key not in self.__container:
|
|
self.__container[key] = RequestArgument(key)
|
|
# Return the argument for the name
|
|
return self.__container[key]
|
|
|
|
def __getattr__(self, key: str) -> RequestArgument:
|
|
"""
|
|
Syntactic sugar for accessing values with a name that can be used in Python attributes. The value will be
|
|
returned as an immutable view.
|
|
|
|
:param key: Name of the argument to retrieve.
|
|
:return: An immutable view of the RequestArgument instance.
|
|
"""
|
|
return _View.of(self.__container[key])
|
|
|
|
def __iter__(self) -> Iterator['RequestArgument']:
|
|
"""
|
|
Returns an iterator over the values in this instance. Values are represented as immutable views.
|
|
|
|
:return: An iterator that yields immutable views of the values.
|
|
"""
|
|
for ra in self.__container.values():
|
|
# Yield an immutable scalar view for each value
|
|
yield _View.of(ra)
|
|
|
|
def __contains__(self, key: str) -> bool:
|
|
"""
|
|
Checks whether an argument with a given name exists in the RequestArguments instance.
|
|
|
|
:param key: The name to check whether it exists.
|
|
:return: True, if present, False otherwise.
|
|
"""
|
|
return key in self.__container
|
|
|
|
def __len__(self) -> int:
|
|
"""
|
|
:return: The number of arguments in this instance.
|
|
"""
|
|
return len(self.__container)
|
|
|
|
|
|
class RequestArgument(object):
|
|
"""
|
|
Container class for HTTP request arguments that simplifies dealing with
|
|
- scalar and array arguments:
|
|
Automatically converts between single values and arrays where necessary: Arrays with one element can be
|
|
accessed as scalars, and scalars can be iterated, yielding themselves as a single item.
|
|
- UTF-8 strings and binary data (e.g. file uploads):
|
|
All data can be retrieved both as a str (if utf-8 decoding is possible) and a bytes object.
|
|
|
|
The objects returned from iteration or indexing are immutable views of (parts of) this object.
|
|
|
|
Usage example:
|
|
|
|
qsargs = urllib.parse.parse_qs(qs, strict_parsing=True, keep_blank_values=True, errors='strict')
|
|
args: RequestArguments
|
|
for k, vs in qsargs:
|
|
args[k].clear()
|
|
for v in vs:
|
|
# text/plain usually is a sensible choice for values decoded from urlencoded strings
|
|
# IF ALREADY IN STRING FORM (which parse_qs does)!
|
|
args[k].append('text/plain', v)
|
|
|
|
if 'username' in args and args.username.is_scalar:
|
|
username = str(args.username)
|
|
|
|
"""
|
|
|
|
def __init__(self,
|
|
name: str,
|
|
value: Union[Tuple[str, Union[bytes, str]], List[Tuple[str, Union[bytes, str]]]] = None) -> None:
|
|
"""
|
|
Create a new RequestArgument with a name and optionally an initial value.
|
|
|
|
:param name: The name for this argument, as provided via GET or POST.
|
|
:param value: The initial value, if any. Optional, initializes with empty array if omitted.
|
|
"""
|
|
# Assign name
|
|
self.__name: str = name
|
|
# Initialize value
|
|
self.__value: List[Tuple[str, Union[bytes, str]]] = []
|
|
# Default to empty array
|
|
if value is None:
|
|
self.__value = []
|
|
else:
|
|
if isinstance(value, list):
|
|
# Store the array
|
|
self.__value = value
|
|
else:
|
|
# Turn scalar into an array before storing
|
|
self.__value = [value]
|
|
|
|
@property
|
|
def is_array(self) -> bool:
|
|
"""
|
|
:return: True, if the value is a (possibly empty) array, False otherwise.
|
|
"""
|
|
return len(self.__value) != 1
|
|
|
|
@property
|
|
def is_scalar(self) -> bool:
|
|
"""
|
|
:return: True, if the value is a single scalar value, False otherwise.
|
|
"""
|
|
return len(self.__value) == 1
|
|
|
|
@property
|
|
def is_view(self) -> bool:
|
|
"""
|
|
:return: True, if this instance is an immutable view, False otherwise.
|
|
"""
|
|
return False
|
|
|
|
@property
|
|
def name(self) -> str:
|
|
"""
|
|
:return: The name of this argument.
|
|
"""
|
|
return self.__name
|
|
|
|
def get_str(self, index: int = 0) -> str:
|
|
"""
|
|
Attempts to return a value as a string. The index defaults to 0.
|
|
|
|
:param index: The index of the value to retrieve. Default: 0.
|
|
:return: An UTF-8 string representation of the requested value.
|
|
:raises UnicodeDecodeError: If the value cannot be decoded into an UTF-8 string.
|
|
:raises IndexError: If the index is out of bounds.
|
|
:raises TypeError: If the index is not an int.
|
|
:raises TypeError: If the requested value is neither a str nor a bytes object.
|
|
"""
|
|
if not isinstance(index, int):
|
|
# Index must be an int
|
|
raise TypeError('index must be an int')
|
|
# Type hint; access array element
|
|
v: Tuple[str, Union[bytes, str]] = self.__value[index]
|
|
if isinstance(v[1], str):
|
|
# The value already is a string, return
|
|
return v[1]
|
|
elif isinstance(v[1], bytes):
|
|
# The value is a bytes object, attempt to decode
|
|
return v[1].decode('utf-8')
|
|
raise TypeError('Value is neither a str nor bytes')
|
|
|
|
def __str__(self) -> str:
|
|
"""
|
|
Attempts to return the first value as a string.
|
|
:return: An UTF-8 string representation of the first value.
|
|
:raises UnicodeDecodeError: If the value cannot be decoded into an UTF-8 string.
|
|
"""
|
|
return self.get_str()
|
|
|
|
def get_bytes(self, index: int = 0) -> bytes:
|
|
"""
|
|
Attempts to return a value as a bytes object. The index defaults to 0.
|
|
|
|
:param index: The index of the value to retrieve. Default: 0.
|
|
:return: A bytes object representation of the requested value. Strings will be encoded as UTF-8.
|
|
:raises IndexError: If the index is out of bounds.
|
|
:raises TypeError: If the index is not an int.
|
|
:raises TypeError: If the requested value is neither a str nor a bytes object.
|
|
"""
|
|
if not isinstance(index, int):
|
|
# Index must be a int
|
|
raise TypeError('index must be an int')
|
|
# Type hint; access array element
|
|
v: Tuple[str, Union[bytes, str]] = self.__value[index]
|
|
if isinstance(v[1], bytes):
|
|
# The value already is a bytes object, return
|
|
return v[1]
|
|
elif isinstance(v[1], str):
|
|
# The value is a string, encode first
|
|
return v[1].encode('utf-8')
|
|
raise TypeError('Value is neither a str nor bytes')
|
|
|
|
def __bytes__(self) -> bytes:
|
|
"""
|
|
Attempts to return the first value as a bytes object.
|
|
:return: A bytes string representation of the first value.
|
|
"""
|
|
return self.get_bytes()
|
|
|
|
def get_content_type(self, index: int = 0) -> str:
|
|
"""
|
|
Attempts to retrieve a value's Content-Type. The index defaults to 0.
|
|
|
|
:param index: The index of the value to retrieve. Default: 0.
|
|
:return: The Content-Type of the requested value, as sent by the client. Not necessarily trustworthy.
|
|
:raises IndexError: If the index is out of bounds.
|
|
:raises TypeError: If the index is not an int.
|
|
"""
|
|
# instance is an array value
|
|
if not isinstance(index, int):
|
|
# Needs an index for array values
|
|
raise TypeError('index must be an int')
|
|
# Type hint; access array element
|
|
va: Tuple[str, Union[bytes, str]] = self.__value[index]
|
|
# Return the content type of the requested value
|
|
if not isinstance(va[0], str):
|
|
raise TypeError('Content-Type is not a str')
|
|
return va[0]
|
|
|
|
def append(self, ctype: str, value: Union[str, bytes]) -> None:
|
|
"""
|
|
Append a value to this instance. Turns an empty argument into a scalar and a scalar into an array.
|
|
|
|
:param ctype: The Content-Type, as provided in the request.
|
|
:param value: The scalar value to append, either a string or bytes object.
|
|
:raises TypeError: If called on an immutable view.
|
|
"""
|
|
if self.is_view:
|
|
# This is an immutable view, raise exception
|
|
raise TypeError('A RequestArgument view is immutable!')
|
|
self.__value.append((ctype, value))
|
|
|
|
def clear(self) -> None:
|
|
"""
|
|
Remove all values from this instance.
|
|
|
|
:raises TypeError: If called on an immutable view.
|
|
"""
|
|
if self.is_view:
|
|
# This is an immutable view, raise exception
|
|
raise TypeError('A RequestArgument view is immutable!')
|
|
self.__value.clear()
|
|
|
|
def __len__(self) -> int:
|
|
"""
|
|
:return: Number of values for this argument.
|
|
"""
|
|
return len(self.__value)
|
|
|
|
def __iter__(self) -> Iterator['RequestArgument']:
|
|
"""
|
|
Iterate the values of this argument. Each value is accessible as if it were a scalar RequestArgument in turn,
|
|
although they are immutable.
|
|
|
|
:return: An iterator that yields immutable views of the values.
|
|
"""
|
|
for v in self.__value:
|
|
# Yield an immutable scalar view for each (ctype, value) element in the array
|
|
yield _View(self.__name, v)
|
|
|
|
def __getitem__(self, index: Union[int, slice]) -> RequestArgument:
|
|
"""
|
|
Index the argument with either an int or a slice. The returned values are represented as immutable
|
|
RequestArgument views.
|
|
|
|
:param index: The index or slice.
|
|
:return: An immutable view of the indexed elements of this argument.
|
|
"""
|
|
# Pass the index or slice through to the array, packing the result in an immutable view
|
|
return _View(self.__name, self.__value[index])
|
|
|
|
|
|
class _View(RequestArgument):
|
|
"""
|
|
This class represents an immutable view of a (subset of a) RequestArgument object. Should not be instantiated
|
|
directly.
|
|
"""
|
|
|
|
def __init__(self, name: str, value: Union[Tuple[str, Union[bytes, str]], List[Tuple[str, Union[bytes, str]]]])\
|
|
-> None:
|
|
"""
|
|
Create a new immutable view of a (subset of a) RequestArgument.
|
|
|
|
:param name: The name for this argument, same as in the original RequestArgument.
|
|
:param value: The values to represent in this view, obtained by e.g. indexing or slicing.
|
|
"""
|
|
super().__init__(name, value)
|
|
|
|
@staticmethod
|
|
def of(argument: 'RequestArgument') ->'RequestArgument':
|
|
"""
|
|
Create an immutable, unsliced view of an RequestArgument instance.
|
|
|
|
:param argument: The RequestArgument instance to create a view of.
|
|
:return: An immutable view of the provided RequestArgument instance.
|
|
"""
|
|
return argument[:]
|
|
|
|
@property
|
|
def is_view(self) -> bool:
|
|
"""
|
|
:return: True, if this instance is an immutable view, False otherwise.
|
|
"""
|
|
return True
|