DOC: dynamically create the gbq doc-strings

Author: jreback

pandas/core/frame.py

@@ -77,7 +77,8 @@
                            OrderedDict, raise_with_traceback)
 from pandas import compat
 from pandas.compat.numpy import function as nv
-from pandas.util.decorators import deprecate_kwarg, Appender, Substitution
+from pandas.util.decorators import (deprecate_kwarg, Appender,
+                                    Substitution, generate_dynamic_docstring)
 from pandas.util.validators import validate_bool_kwarg
 
 from pandas.tseries.period import PeriodIndex
@@ -941,6 +942,11 @@ def to_gbq(self, destination_table, project_id, chunksize=10000,
                           chunksize=chunksize, verbose=verbose, reauth=reauth,
                           if_exists=if_exists, private_key=private_key)
 
+    def _f():
+        from pandas.io import gbq
+        return gbq.to_gbq.__doc__
+    to_gbq.__doc__ = generate_dynamic_docstring(_f)
+
     @classmethod
     def from_records(cls, data, index=None, exclude=None, columns=None,
                      coerce_float=False, nrows=None):

pandas/io/gbq.py

@@ -1,10 +1,11 @@
 """ Google BigQuery support """
 
+from pandas.util.decorators import generate_dynamic_docstring
+
 
 def _try_import():
     # since pandas is a dependency of pandas-gbq
     # we need to import on first use
-
     try:
         import pandas_gbq
     except ImportError:
@@ -20,82 +21,6 @@ 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.
-
-    THIS IS AN EXPERIMENTAL LIBRARY
-
-    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 at
-    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.
-
-      .. versionadded:: 0.19.0
-
-      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)
-
-        .. versionadded:: 0.18.1
-
-    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/>`__
-
-        .. versionadded:: 0.19.0
-
-    **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>`
-
-        .. versionadded:: 0.20.0
-
-    Returns
-    -------
-    df: DataFrame
-        DataFrame representing results of query
-
-    """
     pandas_gbq = _try_import()
     return pandas_gbq.read_gbq(
         query, project_id=project_id,
@@ -106,61 +31,18 @@ def read_gbq(query, project_id=None, index_col=None, col_order=None,
         **kwargs)
 
 
-def to_gbq(dataframe, 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 at
-    https://developers.google.com/api-client-library/python/apis/bigquery/v2
-
-    Authentication to the Google BigQuery service is via OAuth 2.0.
+read_gbq.__doc__ = generate_dynamic_docstring(
+    lambda: _try_import().read_gbq.__doc__)
 
-    - If "private_key" is not provided:
 
-      By default "application default credentials" are used.
-
-      .. versionadded:: 0.19.0
-
-      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
-    ----------
-    dataframe : DataFrame
-        DataFrame to be written
-    destination_table : string
-        Name of table to be written, in the form 'dataset.tablename'
-    project_id : str
-        Google BigQuery Account project ID.
-    chunksize : int (default 10000)
-        Number of rows to be inserted in each chunk from the dataframe.
-    verbose : boolean (default True)
-        Show percentage complete
-    reauth : boolean (default False)
-        Force Google BigQuery to reauthenticate the user. This is useful
-        if multiple accounts are used.
-    if_exists : {'fail', 'replace', 'append'}, default 'fail'
-        'fail': If table exists, do nothing.
-        'replace': If table exists, drop it, recreate it, and insert data.
-        'append': If table exists, insert data. Create if does not exist.
-    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)
-    """
+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.__doc__ = generate_dynamic_docstring(
+    lambda: _try_import().to_gbq.__doc__)

pandas/util/decorators.py

@@ -233,3 +233,24 @@ def make_signature(func):
     if spec.keywords:
         args.append('**' + spec.keywords)
     return args, spec.args
+
+
+def generate_dynamic_docstring(creator):
+    """
+    this function returns a dynamically generated doc-string
+    that will call the creator callable to actually
+    create the docstring.
+
+    The point of this is that we want to get a docstring
+    from another module, but don't want to actually
+    import that module until we look up the docstring
+    rather than at function definition time
+    """
+
+    class Docstring(str):
+
+        @staticmethod
+        def expandtabs(*args):
+            return creator().expandtabs(*args)
+
+    return Docstring()