From d3c88d9a252de376ad8a2bef133d97e11b71970d Mon Sep 17 00:00:00 2001 From: Heath Raftery Date: Sun, 16 Mar 2025 16:08:53 +1100 Subject: [PATCH 1/3] Clarify the first step: authentication As discussed in #145, help newbies by clarifying the step between import and opening a spreadsheet. Make it clearer what your options are and how to choose. This is motivated by the confusion about how to use the library when your spreadsheet is shared with "anyone with the URL". --- README.md | 2 ++ docs/oauth2.rst | 14 ++++++++++---- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a7f6e8b01..9e4198594 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ Requirements: Python 3.8+. ```python import gspread +# First you need access to the Google API. Based on the route you +# chose in Step 1, call either service_account(), oauth() or api_key(). gc = gspread.service_account() # Open a sheet from a spreadsheet in one go diff --git a/docs/oauth2.rst b/docs/oauth2.rst index 773369c36..7cb0752a8 100644 --- a/docs/oauth2.rst +++ b/docs/oauth2.rst @@ -1,11 +1,17 @@ Authentication ============== -To access spreadsheets via Google Sheets API you need to authenticate and authorize your application. +To access spreadsheets your application needs to authenticate itself with the Google Sheets API. Choose from the following options. + +1. Create an :ref:`API key ` if you’d like to only open public spreadsheets. +1. Create a :ref:`OAuth Client ID ` if you’d like to access spreadsheets on behalf of end users (including yourself). + - When your application runs, it will prompt the user to authorize it. +1. Create a :ref:`Service Account ` to access spreadsheets as a standalone bot. + - Service accounts get their own email address, so can be authorized by sharing the Sheet with the account in the same way it is shared with a person. + - Service accounts don't need any explicit permissions to access Sheets that are shared to "anyone with the URL". + +An API Key is the easiest option, but to access private Sheets you need authorization. To provide that interactively, use an OAuth Client ID. To pre-configure authorization, use a Service Account. -* If you plan to access spreadsheets on behalf of a bot account use :ref:`Service Account `. -* If you'd like to access spreadsheets on behalf of end users (including yourself) use :ref:`OAuth Client ID `. -* If you'd like to **only** open public spreadsheets use :ref:`API key ` .. _enable-api-access: From f86f540c63553ca7a0f7b59d0db7bf56bd8070eb Mon Sep 17 00:00:00 2001 From: Heath Raftery Date: Tue, 18 Mar 2025 10:29:09 +1100 Subject: [PATCH 2/3] Correct rst dot point formatting --- docs/oauth2.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/oauth2.rst b/docs/oauth2.rst index 7cb0752a8..18627fbd0 100644 --- a/docs/oauth2.rst +++ b/docs/oauth2.rst @@ -3,12 +3,15 @@ Authentication To access spreadsheets your application needs to authenticate itself with the Google Sheets API. Choose from the following options. -1. Create an :ref:`API key ` if you’d like to only open public spreadsheets. -1. Create a :ref:`OAuth Client ID ` if you’d like to access spreadsheets on behalf of end users (including yourself). - - When your application runs, it will prompt the user to authorize it. -1. Create a :ref:`Service Account ` to access spreadsheets as a standalone bot. - - Service accounts get their own email address, so can be authorized by sharing the Sheet with the account in the same way it is shared with a person. - - Service accounts don't need any explicit permissions to access Sheets that are shared to "anyone with the URL". +#. Create an :ref:`API key ` if you’d like to only open public spreadsheets. +#. Create a :ref:`OAuth Client ID ` if you’d like to access spreadsheets on behalf of end users (including yourself). + + - When your application runs, it will prompt the user to authorize it. + +#. Create a :ref:`Service Account ` to access spreadsheets as a standalone bot. + + - Service accounts get their own email address, so can be authorized by sharing the Sheet with the account in the same way it is shared with a person. + - Service accounts don't need any explicit permissions to access Sheets that are shared to "anyone with the URL". An API Key is the easiest option, but to access private Sheets you need authorization. To provide that interactively, use an OAuth Client ID. To pre-configure authorization, use a Service Account. From 72eb89b78752cf82427c8d508474a0e6c236ca6f Mon Sep 17 00:00:00 2001 From: alifeee Date: Wed, 26 Mar 2025 00:35:39 +0000 Subject: [PATCH 3/3] add `(or)` to make it extra clear that it's a choice --- docs/oauth2.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/oauth2.rst b/docs/oauth2.rst index 18627fbd0..9d3244520 100644 --- a/docs/oauth2.rst +++ b/docs/oauth2.rst @@ -4,11 +4,11 @@ Authentication To access spreadsheets your application needs to authenticate itself with the Google Sheets API. Choose from the following options. #. Create an :ref:`API key ` if you’d like to only open public spreadsheets. -#. Create a :ref:`OAuth Client ID ` if you’d like to access spreadsheets on behalf of end users (including yourself). +#. (or) Create a :ref:`OAuth Client ID ` if you’d like to access spreadsheets on behalf of end users (including yourself). - When your application runs, it will prompt the user to authorize it. -#. Create a :ref:`Service Account ` to access spreadsheets as a standalone bot. +#. (or) Create a :ref:`Service Account ` to access spreadsheets as a standalone bot. - Service accounts get their own email address, so can be authorized by sharing the Sheet with the account in the same way it is shared with a person. - Service accounts don't need any explicit permissions to access Sheets that are shared to "anyone with the URL".