Module _helpers

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, kwonly1=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 the 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 key-word only argument is provided as a positional
               parameter, but only if
               _helpers.positional_parameters_enforcement is set to
               POSITIONAL_EXCEPTION.

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.

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.