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

Module util

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.
Variables [hide private]
  FLAGS = gflags.FLAGS
  __package__ = 'oauth2client'
  logger = <logging.Logger instance at 0x40e8d88>
Function Details [hide private]

positional(max_positional_args)

 
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 the
--positional_parameters_enforcement flag. The flag may be set to 'EXCEPTION',
'WARNING' or '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 the --positional_parameters_enforcement flag is set to
  'EXCEPTION'.