Update to_gbq and read_gbq to pandas-gbq 0.5.0
State: closed

Closes https://github.com/pydata/pandas-gbq/issues/177

Closes #21627

- [x] closes #xxxx
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] whatsnew entry

I've also verified that the docs build and render well with
```
python doc/make.py --single read_gbq
python doc/make.py --single DataFrame.to_gbq
```

Output from `scripts/validate_docstrings.py pandas.read_gbq`:

<details>

```

################################################################################
######################### Docstring (pandas.read_gbq)  #########################
################################################################################

Load data from Google BigQuery.

This function requires the `pandas-gbq package
<https://pandas-gbq.readthedocs.io>`__.

See the `How to authenticate with Google BigQuery
<https://pandas-gbq.readthedocs.io/en/latest/howto/authentication.html>`__
guide for authentication instructions.

Parameters
----------
query : str
    SQL-Like Query to return data values.
project_id : str, optional
    Google BigQuery Account project ID. Optional when available from
    the environment.
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 re-authenticate the user. This is useful
    if multiple accounts are used.
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).
auth_local_webserver : boolean, default False
    Use the `local webserver flow`_ instead of the `console flow`_
    when getting user credentials.

    .. _local webserver flow:
        http://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
    .. _console flow:
        http://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_console

    *New in version 0.2.0 of pandas-gbq*.
dialect : str, default 'legacy'
    SQL syntax dialect to use. Value can be one of:

    ``'legacy'``
        Use BigQuery's legacy SQL dialect. For more information see
        `BigQuery Legacy SQL Reference
        <https://cloud.google.com/bigquery/docs/reference/legacy-sql>`__.
    ``'standard'``
        Use BigQuery's standard SQL, which is
        compliant with the SQL 2011 standard. For more information
        see `BigQuery Standard SQL Reference
        <https://cloud.google.com/bigquery/docs/reference/standard-sql/>`__.
location : str, optional
    Location where the query job should run. See the `BigQuery locations
    documentation
    <https://cloud.google.com/bigquery/docs/dataset-locations>`__ for a
    list of available locations. The location must match that of any
    datasets used in the query.

    *New in version 0.5.0 of pandas-gbq*.
configuration : dict, optional
    Query config parameters for job processing.
    For example:

        configuration = {'query': {'useQueryCache': False}}

    For more information see `BigQuery REST API Reference
    <https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query>`__.
verbose : None, deprecated
    Deprecated in Pandas-GBQ 0.4.0. Use the `logging module
    to adjust verbosity instead
    <https://pandas-gbq.readthedocs.io/en/latest/intro.html#logging>`__.

Returns
-------
df: DataFrame
    DataFrame representing results of query.

See Also
--------
pandas_gbq.read_gbq : This function in the pandas-gbq library.
pandas.DataFrame.to_gbq : Write a DataFrame to Google BigQuery.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No examples section found
```

</details>

Output from `scripts/validate_docstrings.py pandas.DataFrame.to_gbq`:

<details>

```
################################################################################
##################### Docstring (pandas.DataFrame.to_gbq)  #####################
################################################################################

Write a DataFrame to a Google BigQuery table.

This function requires the `pandas-gbq package
<https://pandas-gbq.readthedocs.io>`__.

See the `How to authenticate with Google BigQuery
<https://pandas-gbq.readthedocs.io/en/latest/howto/authentication.html>`__
guide for authentication instructions.

Parameters
----------
destination_table : str
    Name of table to be written, in the form ``dataset.tablename``.
project_id : str, optional
    Google BigQuery Account project ID. Optional when available from
    the environment.
chunksize : int, optional
    Number of rows to be inserted in each chunk from the dataframe.
    Use ``None`` to load the dataframe in a single chunk.
reauth : bool, default False
    Force Google BigQuery to re-authenticate the user. This is useful
    if multiple accounts are used.
if_exists : str, default 'fail'
    Behavior when the destination table exists. Value can be one of:

    ``'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).
auth_local_webserver : bool, default False
    Use the `local webserver flow`_ instead of the `console flow`_
    when getting user credentials.

    .. _local webserver flow:
        http://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
    .. _console flow:
        http://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_console

    *New in version 0.2.0 of pandas-gbq*.
table_schema : list of dicts, optional
    List of BigQuery table fields to which according DataFrame
    columns conform to, e.g. ``[{'name': 'col1', 'type':
    'STRING'},...]``. If schema is not provided, it will be
    generated according to dtypes of DataFrame columns. See
    BigQuery API documentation on available names of a field.

    *New in version 0.3.1 of pandas-gbq*.
location : str, optional
    Location where the load job should run. See the `BigQuery locations
    documentation
    <https://cloud.google.com/bigquery/docs/dataset-locations>`__ for a
    list of available locations. The location must match that of the
    target dataset.

    *New in version 0.5.0 of pandas-gbq*.
progress_bar : bool, default True
    Use the library `tqdm` to show the progress bar for the upload,
    chunk by chunk.

    *New in version 0.5.0 of pandas-gbq*.
verbose : bool, deprecated
    Deprecated in Pandas-GBQ 0.4.0. Use the `logging module
    to adjust verbosity instead
    <https://pandas-gbq.readthedocs.io/en/latest/intro.html#logging>`__.

See Also
--------
pandas_gbq.to_gbq : This function in the pandas-gbq library.
pandas.read_gbq : Read a DataFrame from Google BigQuery.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	No returns section found
	No examples section found
```

</details>


Labels:
name: Enhancement

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=h1) Report
> Merging [#21628](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/36422a88474396148bd7d5d38aa238ea844d9555?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/21628/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #21628   +/-   ##
=======================================
  Coverage    91.9%    91.9%           
=======================================
  Files         154      154           
  Lines       49562    49562           
=======================================
  Hits        45549    45549           
  Misses       4013     4013
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.3% <100%> (ø)` | :arrow_up: |
| #single | `41.85% <100%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/21628/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <100%> (ø)` | :arrow_up: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/21628/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.19% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=footer). Last update [36422a8...7330463](https://codecov.io/gh/pandas-dev/pandas/pull/21628?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Travis failure appears to be unrelated to this change.
Looks like Travis and Circle are both happy now that I rebased.
I am not really familiar with the gbq code, but, did we consider making this just a passthrough of `*args, **kwargs` ? Then it would automatically work with the installed pandas_gbq
@jorisvandenbossche I considered (and even coded) that in https://github.com/pandas-dev/pandas/pull/20564

The development experience is nicer (IDEs understand them better) without using `**kwargs`. It is somewhat rare to add new arguments to Pandas-GBQ, though I do have a couple changes in mind to streamline auth https://github.com/pydata/pandas-gbq/issues/161.

The `location` field is special because it's a new field on the BigQuery API as opposed to a new field in the BigQuery API resources.
i think writing out the kwargs is nice from a usability pov - we do this for other apis as well
Yep, no problem, was just wondering!
thanks @tswast !