From cb9d1bf1a9f1a1525cf0ec287bb45cae8ca28493 Mon Sep 17 00:00:00 2001 From: Craig Citro Date: Thu, 12 Feb 2015 11:36:30 -0800 Subject: [PATCH] Add functools.wraps() to util.positional(). This forces `util.positional` to correctly wrap the function it produces, in particular to fix an issue with generation of docstrings. This also cleans up the docstrings for `tools.run_flow` and `old_run.run` to be valid restructured text. Fixes #124. --- oauth2client/old_run.py | 45 ++++++++++++++--------------- oauth2client/tools.py | 64 +++++++++++++++++++++-------------------- oauth2client/util.py | 2 ++ 3 files changed, 57 insertions(+), 54 deletions(-) diff --git a/oauth2client/old_run.py b/oauth2client/old_run.py index f433b84..51db69b 100644 --- a/oauth2client/old_run.py +++ b/oauth2client/old_run.py @@ -50,39 +50,38 @@ gflags.DEFINE_multi_int('auth_host_port', [8080, 8090], def run(flow, storage, http=None): """Core code for a command-line application. - The run() function is called from your application and runs through all - the steps to obtain credentials. It takes a Flow argument and attempts to - open an authorization server page in the user's default web browser. The - server asks the user to grant your application access to the user's data. - If the user grants access, the run() function returns new credentials. The - new credentials are also stored in the Storage argument, which updates the - file associated with the Storage object. + The ``run()`` function is called from your application and runs + through all the steps to obtain credentials. It takes a ``Flow`` + argument and attempts to open an authorization server page in the + user's default web browser. The server asks the user to grant your + application access to the user's data. If the user grants access, + the ``run()`` function returns new credentials. The new credentials + are also stored in the ``storage`` argument, which updates the file + associated with the ``Storage`` object. It presumes it is run from a command-line application and supports the following flags: - --auth_host_name: Host name to use when running a local web server - to handle redirects during OAuth authorization. - (default: 'localhost') + ``--auth_host_name`` (string, default: ``localhost``) + Host name to use when running a local web server to handle + redirects during OAuth authorization. - --auth_host_port: Port to use when running a local web server to handle - redirects during OAuth authorization.; - repeat this option to specify a list of values - (default: '[8080, 8090]') - (an integer) + ``--auth_host_port`` (integer, default: ``[8080, 8090]``) + Port to use when running a local web server to handle redirects + during OAuth authorization. Repeat this option to specify a list + of values. - --[no]auth_local_webserver: Run a local web server to handle redirects - during OAuth authorization. - (default: 'true') + ``--[no]auth_local_webserver`` (boolean, default: ``True``) + Run a local web server to handle redirects during OAuth authorization. - Since it uses flags make sure to initialize the gflags module before - calling run(). + Since it uses flags make sure to initialize the ``gflags`` module before + calling ``run()``. Args: flow: Flow, an OAuth 2.0 Flow to step through. - storage: Storage, a Storage to store the credential in. - http: An instance of httplib2.Http.request - or something that acts like it. + storage: Storage, a ``Storage`` to store the credential in. + http: An instance of ``httplib2.Http.request`` or something that acts + like it. Returns: Credentials, the obtained credential. diff --git a/oauth2client/tools.py b/oauth2client/tools.py index 20faa43..2caa134 100644 --- a/oauth2client/tools.py +++ b/oauth2client/tools.py @@ -111,48 +111,50 @@ class ClientRedirectHandler(BaseHTTPServer.BaseHTTPRequestHandler): def run_flow(flow, storage, flags, http=None): """Core code for a command-line application. - The run() function is called from your application and runs through all the - steps to obtain credentials. It takes a Flow argument and attempts to open an - authorization server page in the user's default web browser. The server asks - the user to grant your application access to the user's data. If the user - grants access, the run() function returns new credentials. The new credentials - are also stored in the Storage argument, which updates the file associated - with the Storage object. + The ``run()`` function is called from your application and runs + through all the steps to obtain credentials. It takes a ``Flow`` + argument and attempts to open an authorization server page in the + user's default web browser. The server asks the user to grant your + application access to the user's data. If the user grants access, + the ``run()`` function returns new credentials. The new credentials + are also stored in the ``storage`` argument, which updates the file + associated with the ``Storage`` object. It presumes it is run from a command-line application and supports the following flags: - --auth_host_name: Host name to use when running a local web server - to handle redirects during OAuth authorization. - (default: 'localhost') + ``--auth_host_name`` (string, default: ``localhost``) + Host name to use when running a local web server to handle + redirects during OAuth authorization. - --auth_host_port: Port to use when running a local web server to handle - redirects during OAuth authorization.; - repeat this option to specify a list of values - (default: '[8080, 8090]') - (an integer) + ``--auth_host_port`` (integer, default: ``[8080, 8090]``) + Port to use when running a local web server to handle redirects + during OAuth authorization. Repeat this option to specify a list + of values. - --[no]auth_local_webserver: Run a local web server to handle redirects - during OAuth authorization. - (default: 'true') + ``--[no]auth_local_webserver`` (boolean, default: ``True``) + Run a local web server to handle redirects during OAuth authorization. - The tools module defines an ArgumentParser the already contains the flag - definitions that run() requires. You can pass that ArgumentParser to your - ArgumentParser constructor: - parser = argparse.ArgumentParser(description=__doc__, - formatter_class=argparse.RawDescriptionHelpFormatter, - parents=[tools.argparser]) - flags = parser.parse_args(argv) + + + The tools module defines an ``ArgumentParser`` the already contains the flag + definitions that ``run()`` requires. You can pass that ``ArgumentParser`` to your + ``ArgumentParser`` constructor:: + + parser = argparse.ArgumentParser(description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter, + parents=[tools.argparser]) + flags = parser.parse_args(argv) Args: flow: Flow, an OAuth 2.0 Flow to step through. - storage: Storage, a Storage to store the credential in. - flags: argparse.Namespace, The command-line flags. This is the object - returned from calling parse_args() on - argparse.ArgumentParser as described above. - http: An instance of httplib2.Http.request - or something that acts like it. + storage: Storage, a ``Storage`` to store the credential in. + flags: ``argparse.Namespace``, The command-line flags. This is the + object returned from calling ``parse_args()`` on + ``argparse.ArgumentParser`` as described above. + http: An instance of ``httplib2.Http.request`` or something that + acts like it. Returns: Credentials, the obtained credential. diff --git a/oauth2client/util.py b/oauth2client/util.py index 72cd871..a706f02 100644 --- a/oauth2client/util.py +++ b/oauth2client/util.py @@ -29,6 +29,7 @@ __all__ = [ 'POSITIONAL_IGNORE', ] +import functools import inspect import logging import sys @@ -119,6 +120,7 @@ def positional(max_positional_args): """ def positional_decorator(wrapped): + @functools.wraps(wrapped) def positional_wrapper(*args, **kwargs): if len(args) > max_positional_args: plural_s = ''