Package googleapiclient :: Module _helpers
[hide private]
[frames] | no frames]

Module _helpers

source code

Helper functions for commonly used utilities.

Functions [hide private]
 
positional(max_positional_args)
A decorator to declare that only the first N arguments may be positional.
source code
 
parse_unique_urlencoded(content)
Parses unique key-value parameters from urlencoded content.
source code
 
update_query_params(uri, params)
Updates a URI with new query parameters.
source code
 
_add_query_parameter(url, name, value)
Adds a query parameter to a url.
source code
Variables [hide private]
  logger = logging.getLogger(__name__)
  POSITIONAL_WARNING = 'WARNING'
  POSITIONAL_EXCEPTION = 'EXCEPTION'
  POSITIONAL_IGNORE = 'IGNORE'
  POSITIONAL_SET = frozenset(['EXCEPTION', 'IGNORE', 'WARNING'])
  positional_parameters_enforcement = 'WARNING'
  _SYM_LINK_MESSAGE = 'File: {0}: Is a symbolic link.'
  _IS_DIR_MESSAGE = '{0}: Is a directory'
  _MISSING_FILE_MESSAGE = 'Cannot access {0}: No such file or di...
  __package__ = 'googleapiclient'
Function Details [hide private]

positional(max_positional_args)

source code 
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.

parse_unique_urlencoded(content)

source code 
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.

update_query_params(uri, params)

source code 
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.

_add_query_parameter(url, name, value)

source code 
Adds a query parameter to a url.

Replaces the current value if it already exists in the URL.

Args:
    url: string, url to add the query parameter to.
    name: string, query parameter name.
    value: string, query parameter value.

Returns:
    Updated query parameter. Does not update the url if value is None.


Variables Details [hide private]

_MISSING_FILE_MESSAGE

Value:
'Cannot access {0}: No such file or directory'