Package oauth2client :: Module util |
[hide private]
[frames] | no frames]

# Module util

source code

    Common utility library.

Authors:
  rafek@google.com (Rafe Kaplan), guido@google.com (Guido van Rossum)

Functions | [hide private]
positional(max_positional_args) A decorator to declare that only the first N arguments my be positional. | source code
scopes_to_string(scopes) Converts scope value to a string. | source code
dict_to_tuple_key(dictionary) Converts a dictionary to a tuple that can be used as an immutable key. | 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([POSITIONAL_WARNING, POSITIONAL_EXC`...``
| positional_parameters_enforcement = `'WARNING'`

Function Details | [hide private]

### positional(max_positional_args) | source code
    A decorator to declare that only the first N arguments my be positional.

    This decorator makes it easy to support Python 3 style key-word 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
    util.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 util.positional_parameters_enforcement is set to
      POSITIONAL_EXCEPTION.

### scopes_to_string(scopes) | source code
    Converts scope value to a string.

    If scopes is a string then it is simply passed through. If scopes is an
    iterable then a string is returned that is all the individual scopes
    concatenated with spaces.

    Args:
      scopes: string or iterable of strings, the scopes.

    Returns:
      The scopes formatted as a single string.

### dict_to_tuple_key(dictionary) | source code
    Converts a dictionary to a tuple that can be used as an immutable key.

    The resulting key is always sorted so that logically equivalent dictionaries
    always produce an identical tuple for a key.

    Args:
      dictionary: the dictionary to use as the key.

    Returns:
      A tuple representing the dictionary in it's naturally sorted ordering.

### _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]

  ### POSITIONAL_SET Value:
      frozenset([POSITIONAL_WARNING, POSITIONAL_EXCEPTION, POSITIONAL_IGNORE
      ])