DOC: revert gbq doc-strings to be in-line rather than wrapped

Author: jreback

pandas/core/frame.py

@@ -78,7 +78,7 @@
 from pandas import compat
 from pandas.compat.numpy import function as nv
 from pandas.util.decorators import (deprecate_kwarg, Appender,
-                                    Substitution, docstring_wrapper)
+                                    Substitution)
 from pandas.util.validators import validate_bool_kwarg
 
 from pandas.tseries.period import PeriodIndex
@@ -908,7 +908,26 @@ def to_gbq(self, destination_table, project_id, chunksize=10000,
                verbose=True, reauth=False, if_exists='fail', private_key=None):
         """Write a DataFrame to a Google BigQuery table.
 
-        THIS IS AN EXPERIMENTAL LIBRARY
+        The main method a user calls to export pandas DataFrame contents to
+        Google BigQuery table.
+
+        Google BigQuery API Client Library v2 for Python is used.
+        Documentation is available `here
+        <https://developers.google.com/api-client-library/python/apis/bigquery/v2>`__
+
+        Authentication to the Google BigQuery service is via OAuth 2.0.
+
+        - If "private_key" is not provided:
+
+          By default "application default credentials" are used.
+
+          If default application credentials are not found or are restrictive,
+          user account credentials are used. In this case, you will be asked to
+          grant permissions for product name 'pandas GBQ'.
+
+        - If "private_key" is provided:
+
+          Service account credentials will be used to authenticate.
 
         Parameters
         ----------
@@ -933,8 +952,6 @@ def to_gbq(self, destination_table, project_id, chunksize=10000,
             Service account private key in JSON format. Can be file path
             or string contents. This is useful for remote server
             authentication (eg. jupyter iPython notebook on remote host)
-
-            .. versionadded:: 0.17.0
         """
 
         from pandas.io import gbq
@@ -5402,16 +5419,6 @@ def combineMult(self, other):
 _EMPTY_SERIES = Series([])
 
 
-# patch in the doc-string for to_gbq
-# and bind this method
-def _f():
-    from pandas.io.gbq import _try_import
-    return _try_import().to_gbq.__doc__
-
-
-DataFrame.to_gbq = docstring_wrapper(DataFrame.to_gbq, _f)
-
-
 def _arrays_to_mgr(arrays, arr_names, index, columns, dtype=None):
     """
     Segregate Series based on type and coerce into matrices.

pandas/io/gbq.py

@@ -1,7 +1,5 @@
 """ Google BigQuery support """
 
-from pandas.util.decorators import docstring_wrapper
-
 
 def _try_import():
     # since pandas is a dependency of pandas-gbq
@@ -25,6 +23,72 @@ def _try_import():
 def read_gbq(query, project_id=None, index_col=None, col_order=None,
              reauth=False, verbose=True, private_key=None, dialect='legacy',
              **kwargs):
+    r"""Load data from Google BigQuery.
+
+    The main method a user calls to execute a Query in Google BigQuery
+    and read results into a pandas DataFrame.
+
+    Google BigQuery API Client Library v2 for Python is used.
+    Documentation is available `here
+    <https://developers.google.com/api-client-library/python/apis/bigquery/v2>`__
+
+    Authentication to the Google BigQuery service is via OAuth 2.0.
+
+    - If "private_key" is not provided:
+
+      By default "application default credentials" are used.
+
+      If default application credentials are not found or are restrictive,
+      user account credentials are used. In this case, you will be asked to
+      grant permissions for product name 'pandas GBQ'.
+
+    - If "private_key" is provided:
+
+      Service account credentials will be used to authenticate.
+
+    Parameters
+    ----------
+    query : str
+        SQL-Like Query to return data values
+    project_id : str
+        Google BigQuery Account project ID.
+    index_col : str (optional)
+        Name of result column to use for index in results DataFrame
+    col_order : list(str) (optional)
+        List of BigQuery column names in the desired order for results
+        DataFrame
+    reauth : boolean (default False)
+        Force Google BigQuery to reauthenticate the user. This is useful
+        if multiple accounts are used.
+    verbose : boolean (default True)
+        Verbose output
+    private_key : str (optional)
+        Service account private key in JSON format. Can be file path
+        or string contents. This is useful for remote server
+        authentication (eg. jupyter iPython notebook on remote host)
+
+    dialect : {'legacy', 'standard'}, default 'legacy'
+        'legacy' : Use BigQuery's legacy SQL dialect.
+        'standard' : Use BigQuery's standard SQL (beta), which is
+        compliant with the SQL 2011 standard. For more information
+        see `BigQuery SQL Reference
+        <https://cloud.google.com/bigquery/sql-reference/>`__
+
+    **kwargs : Arbitrary keyword arguments
+        configuration (dict): query config parameters for job processing.
+        For example:
+
+            configuration = {'query': {'useQueryCache': False}}
+
+        For more information see `BigQuery SQL Reference
+        <https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query>`__
+
+    Returns
+    -------
+    df: DataFrame
+        DataFrame representing results of query
+
+    """
     pandas_gbq = _try_import()
     return pandas_gbq.read_gbq(
         query, project_id=project_id,
@@ -35,18 +99,10 @@ def read_gbq(query, project_id=None, index_col=None, col_order=None,
         **kwargs)
 
 
-read_gbq = docstring_wrapper(read_gbq,
-                             lambda: _try_import().read_gbq.__doc__)
-
-
 def to_gbq(dataframe, destination_table, project_id, chunksize=10000,
            verbose=True, reauth=False, if_exists='fail', private_key=None):
     pandas_gbq = _try_import()
     pandas_gbq.to_gbq(dataframe, destination_table, project_id,
                       chunksize=chunksize,
                       verbose=verbose, reauth=reauth,
                       if_exists=if_exists, private_key=private_key)
-
-
-to_gbq = docstring_wrapper(to_gbq,
-                           lambda: _try_import().to_gbq.__doc__)