Skip to content

Commit ecc695f

Browse files
tswasttswast
authored
CLN: use pydata-google-auth for auth flow (#241)
* CLN: use pydata-google-auth for auth flow Only private_key logic and customized path for credentials cache remain. At some point in the future private_key logic will be removed, as that parameter is deprecated in favor of the credentials argument. Also removes the _try_credentials logic, as that slows down the authentication process and is largely unnecessary now that credentials can be explicitly created and supplied via the credentials argument. * Add user auth detail to authentication guide. * Add comment explaining client_id and client_secret.
1 parent 08590bd commit ecc695f

File tree

10 files changed

+223
-341
lines changed

10 files changed

+223
-341
lines changed

‎docs/source/changelog.rst

+11
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
11
Changelog
22
=========
33

4+
.. _changelog-0.9.0:
5+
6+
0.9.0 / TBD
7+
-----------
8+
9+
Internal changes
10+
~~~~~~~~~~~~~~~~
11+
12+
- **New dependency** Use the ``pydata-google-auth`` package for
13+
authentication. (:issue:`241`)
14+
415
.. _changelog-0.8.0:
516

617
0.8.0 / 2018-11-12

‎docs/source/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,7 @@
372372
intersphinx_mapping = {
373373
"https://docs.python.org/": None,
374374
"https://pandas.pydata.org/pandas-docs/stable/": None,
375+
"https://pydata-google-auth.readthedocs.io/en/latest/": None,
375376
"https://google-auth.readthedocs.io/en/latest/": None,
376377
}
377378

‎docs/source/howto/authentication.rst

+92-7
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ pandas-gbq `authenticates with the Google BigQuery service
77
.. _authentication:
88

99

10-
Authentication with a Service Account
10+
Authenticating with a Service Account
1111
--------------------------------------
1212

1313
Using service account credentials is particularly useful when working on
@@ -57,10 +57,81 @@ To use service account credentials, set the ``credentials`` parameter to the res
5757
)
5858
df = pandas_gbq.read_gbq(sql, project_id="YOUR-PROJECT-ID", credentials=credentials)
5959
60+
Use the :func:`~google.oauth2.service_account.Credentials.with_scopes` method
61+
to use authorize with specific OAuth2 scopes, which may be required in
62+
queries to federated data sources such as Google Sheets.
63+
64+
.. code:: python
65+
66+
credentials = ...
67+
credentials = credentials.with_scopes(
68+
[
69+
'https://www.googleapis.com/auth/drive',
70+
'https://www.googleapis.com/auth/cloud-platform',
71+
],
72+
)
73+
df = pandas_gbq.read_gbq(..., credentials=credentials)
74+
6075
See the `Getting started with authentication on Google Cloud Platform
6176
<https://cloud.google.com/docs/authentication/getting-started>`_ guide for
6277
more information on service accounts.
6378

79+
80+
Authenticating with a User Account
81+
----------------------------------
82+
83+
Use the `pydata-google-auth <https://pydata-google-auth.readthedocs.io/>`__
84+
library to authenticate with a user account (i.e. a G Suite or Gmail
85+
account). The :func:`pydata_google_auth.get_user_credentials` function loads
86+
credentials from a cache on disk or initiates an OAuth 2.0 flow if cached
87+
credentials are not found.
88+
89+
.. code:: python
90+
91+
import pandas_gbq
92+
import pydata_google_auth
93+
94+
SCOPES = [
95+
'https://www.googleapis.com/auth/cloud-platform',
96+
'https://www.googleapis.com/auth/drive',
97+
]
98+
99+
credentials = pydata_google_auth.get_user_credentials(
100+
SCOPES,
101+
# Set auth_local_webserver to True to have a slightly more convienient
102+
# authorization flow. Note, this doesn't work if you're running from a
103+
# notebook on a remote sever, such as over SSH or with Google Colab.
104+
auth_local_webserver=True,
105+
106+
107+
df = pandas_gbq.read_gbq(
108+
"SELECT my_col FROM `my_dataset.my_table`",
109+
project_id='YOUR-PROJECT-ID',
110+
credentials=credentials,
111+
)
112+
113+
.. warning::
114+
115+
Do not store credentials on disk when using shared computing resources
116+
such as a GCE VM or Colab notebook. Use the
117+
:data:`pydata_google_auth.cache.NOOP` cache to avoid writing credentials
118+
to disk.
119+
120+
.. code:: python
121+
122+
import pydata_google_auth.cache
123+
124+
credentials = pydata_google_auth.get_user_credentials(
125+
SCOPES,
126+
# Use the NOOP cache to avoid writing credentials to disk.
127+
cache=pydata_google_auth.cache.NOOP,
128+
)
129+
130+
Additional information on the user credentials authentication mechanism
131+
can be found in the `Google Cloud authentication guide
132+
<https://cloud.google.com/docs/authentication/end-user>`__.
133+
134+
64135
Default Authentication Methods
65136
------------------------------
66137
@@ -71,6 +142,19 @@ methods:
71142
1. In-memory, cached credentials at ``pandas_gbq.context.credentials``. See
72143
:attr:`pandas_gbq.Context.credentials` for details.
73144
145+
.. code:: python
146+
147+
import pandas_gbq
148+
149+
credentials = ... # From google-auth or pydata-google-auth library.
150+
151+
# Update the in-memory credentials cache (added in pandas-gbq 0.7.0).
152+
pandas_gbq.context.credentials = credentials
153+
pandas_gbq.context.project = "your-project-id"
154+
155+
# The credentials and project_id arguments can be omitted.
156+
df = pandas_gbq.read_gbq("SELECT my_col FROM `my_dataset.my_table`")
157+
74158
2. Application Default Credentials via the :func:`google.auth.default`
75159
function.
76160
@@ -87,13 +171,14 @@ methods:
87171
3. User account credentials.
88172
89173
pandas-gbq loads cached credentials from a hidden user folder on the
90-
operating system. Override the location of the cached user credentials
91-
by setting the ``PANDAS_GBQ_CREDENTIALS_FILE`` environment variable.
174+
operating system.
175+
176+
Windows
177+
``%APPDATA%\pandas_gbq\bigquery_credentials.dat``
178+
179+
Linux/Mac/Unix
180+
``~/.config/pandas_gbq/bigquery_credentials.dat``
92181
93182
If pandas-gbq does not find cached credentials, it opens a browser window
94183
asking for you to authenticate to your BigQuery account using the product
95184
name ``pandas GBQ``.
96-
97-
Additional information on the user credentails authentication mechanism
98-
can be found `here
99-
<https://developers.google.com/identity/protocols/OAuth2#clientside/>`__.

‎docs/source/install.rst

+1
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ Dependencies
3737

3838
This module requires following additional dependencies:
3939

40+
- `pydata-google-auth <https://github.com/pydata/pydata-google-auth>`__: Helpers for authentication to Google's API
4041
- `google-auth <https://github.com/GoogleCloudPlatform/google-auth-library-python>`__: authentication and authorization for Google's API
4142
- `google-auth-oauthlib <https://github.com/GoogleCloudPlatform/google-auth-library-python-oauthlib>`__: integration with `oauthlib <https://github.com/idan/oauthlib>`__ for end-user authentication
4243
- `google-cloud-bigquery <http://github.com/GoogleCloudPlatform/google-cloud-python>`__: Google Cloud client library for BigQuery

0 commit comments

Comments
 (0)