Add new auth method API key

Add a new auth method that allows users to open public
spreadsheet files with a simple API key.

closes #1096

Signed-off-by: Alexandre Lavigne <lavigne958@gmail.com>

docs/oauth2.rst

@@ -5,6 +5,7 @@ To access spreadsheets via Google Sheets API you need to authenticate and author
 
 * If you plan to access spreadsheets on behalf of a bot account use :ref:`Service Account <service-account>`.
 * If you'd like to access spreadsheets on behalf of end users (including yourself) use :ref:`OAuth Client ID <oauth-client-id>`.
+* If you'd like to **only** open public spreadsheets use :ref:`API key <api-key>`
 
 .. _enable-api-access:
 
@@ -247,3 +248,50 @@ as second argument in your next `oauth` request to be directly authenticated and
 .. NOTE::
     The user interface of Google Developers Console may be different when you're reading this. If you find that this document is out of sync with the actual UI, please update it. Improvements to the documentation are always welcome.
     Click **Edit on GitHub** in the top right corner of the page, make it better and submit a PR.
+
+
+.. _api-key:
+
+For public spreadsheets only
+----------------------------
+
+An API key is a token that allows an application to open public spreadsheet files.
+
+Here's how to get one:
+
+1. :ref:`enable-api-access` if you haven't done it yet.
+
+2. Go to "APIs & Services > Credentials" and choose "Create credentials > API key"
+
+3. A pop-up should display your newly created key.
+
+4. Copy the key.
+
+5. That's it your key is created.
+
+.. note::
+
+   You can access your key any time later, come back to the "APIs & Services > Credentials" page,
+   you'll be able to see your key again.
+
+6. Create a new Python file with this code:
+
+::
+
+    import gspread
+
+    gc = gspread.api_key("<your newly create key>"")
+
+    sh = gc.open_by_key("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms")
+
+    print(sh.sheet1.get('A1'))
+
+Ta-da !
+
+.. note::
+
+   You can only open public keys, this means you can only open spreadsheet files
+   using the methods: ``gc.open_by_key`` and ``gc.open_by_url``.
+
+   The method ``gc.open()`` searches your private files to find the one with a matching
+   name so it will never work.

gspread/__init__.py

@@ -5,6 +5,7 @@
 
 
 from .auth import (
+    api_key,
     authorize,
     oauth,
     oauth_from_dict,

gspread/auth.py

@@ -11,6 +11,7 @@
 from pathlib import Path
 from typing import Any, Dict, Iterable, Mapping, Optional, Protocol, Tuple, Union
 
+from google.auth.api_key import Credentials as APIKeyCredentials
 from google.auth.credentials import Credentials
 from google.oauth2.credentials import Credentials as OAuthCredentials
 from google.oauth2.service_account import Credentials as SACredentials
@@ -187,7 +188,7 @@ def oauth(
 
             * `%APPDATA%\gspread\authorized_user.json` on Windows
             * `~/.config/gspread/authorized_user.json` everywhere else
-    :type http_client: :class:`gspread.HTTPClient`
+    :type http_client: :class:`gspread.http_client.HTTPClient`
     :param http_client: A factory function that returns a client class.
         Defaults to :class:`gspread.http_client.HTTPClient` (but could also use
         :class:`gspread.http_client.BackOffHTTPClient` to avoid rate limiting)
@@ -268,7 +269,7 @@ def oauth_from_dict(
     :param list scopes: The scopes used to obtain authorization.
     :param function flow: OAuth flow to use for authentication.
         Defaults to :meth:`~gspread.auth.local_server_flow`
-    :type http_client: :class:`gspread.HTTPClientType`
+    :type http_client: :class:`gspread.http_client.HTTPClient`
     :param http_client: A factory function that returns a client class.
         Defaults to :class:`gspread.http_client.HTTPClient` (but could also use
         :class:`gspread.http_client.BackOffHTTPClient` to avoid rate limiting)
@@ -313,7 +314,7 @@ def service_account(
 
     :param str filename: The path to the service account json file.
     :param list scopes: The scopes used to obtain authorization.
-    :type http_client: :class:`gspread.HTTPClientType`
+    :type http_client: :class:`gspread.http_client.HTTPClient`
     :param http_client: A factory function that returns a client class.
         Defaults to :class:`gspread.HTTPClient` (but could also use
         :class:`gspread.BackOffHTTPClient` to avoid rate limiting)
@@ -346,7 +347,7 @@ def service_account_from_dict(
 
     :param info (Mapping[str, str]): The service account info in Google format
     :param list scopes: The scopes used to obtain authorization.
-    :type http_client: :class:`gspread.HTTPClientType`
+    :type http_client: :class:`gspread.http_client.HTTPClient`
     :param http_client: A factory function that returns a client class.
         Defaults to :class:`gspread.http_client.HTTPClient` (but could also use
         :class:`gspread.http_client.BackOffHTTPClient` to avoid rate limiting)
@@ -358,3 +359,26 @@ def service_account_from_dict(
         scopes=scopes,
     )
     return Client(auth=creds, http_client=http_client)
+
+
+def api_key(token: str, http_client: HTTPClientType = HTTPClient) -> Client:
+    """Authenticate using an API key.
+
+    Allows you to open public spreadsheet files.
+
+    .. warning::
+
+       This method only allows you to open public spreadsheet files.
+       It does not work for private spreadsheet files.
+
+    :param token str: The actual API key to use
+    :type http_client: :class:`gspread.http_client.HTTPClient`
+    :param http_client: A factory function that returns a client class.
+        Defaults to :class:`gspread.http_client.HTTPClient` (but could also use
+        :class:`gspread.http_client.BackOffHTTPClient` to avoid rate limiting)
+
+    :rtype: :class:`gspread.client.Client`
+
+    """
+    creds = APIKeyCredentials(token)
+    return Client(auth=creds, http_client=http_client)