You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
121 lines
3.5 KiB
Python
121 lines
3.5 KiB
Python
"""
|
|
This type stub file was generated by pyright.
|
|
"""
|
|
|
|
"""Helper functions for commonly used utilities."""
|
|
logger = ...
|
|
POSITIONAL_WARNING = ...
|
|
POSITIONAL_EXCEPTION = ...
|
|
POSITIONAL_IGNORE = ...
|
|
POSITIONAL_SET = ...
|
|
positional_parameters_enforcement = ...
|
|
_SYM_LINK_MESSAGE = ...
|
|
_IS_DIR_MESSAGE = ...
|
|
_MISSING_FILE_MESSAGE = ...
|
|
def positional(max_positional_args): # -> Callable[..., _Wrapped[Callable[..., Any], Any, Callable[..., Any], Any]]:
|
|
"""A decorator to declare that only the first N arguments may be positional.
|
|
|
|
This decorator makes it easy to support Python 3 style keyword-only
|
|
parameters. For example, in Python 3 it is possible to write::
|
|
|
|
def fn(pos1, *, kwonly1=None, kwonly2=None):
|
|
...
|
|
|
|
All named parameters after ``*`` must be a keyword::
|
|
|
|
fn(10, 'kw1', 'kw2') # Raises exception.
|
|
fn(10, kwonly1='kw1') # Ok.
|
|
|
|
Example
|
|
^^^^^^^
|
|
|
|
To define a function like above, do::
|
|
|
|
@positional(1)
|
|
def fn(pos1, kwonly1=None, kwonly2=None):
|
|
...
|
|
|
|
If no default value is provided to a keyword argument, it becomes a
|
|
required keyword argument::
|
|
|
|
@positional(0)
|
|
def fn(required_kw):
|
|
...
|
|
|
|
This must be called with the keyword parameter::
|
|
|
|
fn() # Raises exception.
|
|
fn(10) # Raises exception.
|
|
fn(required_kw=10) # Ok.
|
|
|
|
When defining instance or class methods always remember to account for
|
|
``self`` and ``cls``::
|
|
|
|
class MyClass(object):
|
|
|
|
@positional(2)
|
|
def my_method(self, pos1, kwonly1=None):
|
|
...
|
|
|
|
@classmethod
|
|
@positional(2)
|
|
def my_method(cls, pos1, kwonly1=None):
|
|
...
|
|
|
|
The positional decorator behavior is controlled by
|
|
``_helpers.positional_parameters_enforcement``, which may be set to
|
|
``POSITIONAL_EXCEPTION``, ``POSITIONAL_WARNING`` or
|
|
``POSITIONAL_IGNORE`` to raise an exception, log a warning, or do
|
|
nothing, respectively, if a declaration is violated.
|
|
|
|
Args:
|
|
max_positional_arguments: Maximum number of positional arguments. All
|
|
parameters after this index must be
|
|
keyword only.
|
|
|
|
Returns:
|
|
A decorator that prevents using arguments after max_positional_args
|
|
from being used as positional parameters.
|
|
|
|
Raises:
|
|
TypeError: if a keyword-only argument is provided as a positional
|
|
parameter, but only if
|
|
_helpers.positional_parameters_enforcement is set to
|
|
POSITIONAL_EXCEPTION.
|
|
"""
|
|
...
|
|
|
|
def parse_unique_urlencoded(content): # -> dict[Any, Any]:
|
|
"""Parses unique key-value parameters from urlencoded content.
|
|
|
|
Args:
|
|
content: string, URL-encoded key-value pairs.
|
|
|
|
Returns:
|
|
dict, The key-value pairs from ``content``.
|
|
|
|
Raises:
|
|
ValueError: if one of the keys is repeated.
|
|
"""
|
|
...
|
|
|
|
def update_query_params(uri, params):
|
|
"""Updates a URI with new query parameters.
|
|
|
|
If a given key from ``params`` is repeated in the ``uri``, then
|
|
the URI will be considered invalid and an error will occur.
|
|
|
|
If the URI is valid, then each value from ``params`` will
|
|
replace the corresponding value in the query parameters (if
|
|
it exists).
|
|
|
|
Args:
|
|
uri: string, A valid URI, with potential existing query parameters.
|
|
params: dict, A dictionary of query parameters.
|
|
|
|
Returns:
|
|
The same URI but with the new query parameters added.
|
|
"""
|
|
...
|
|
|