Merge branch 'master' into cgkoutzigiannis-change-tab-color

Author: lavigne958

HISTORY.rst

@@ -1,6 +1,8 @@
 Release History
 ===============
 
+* Add `client_factory` param to `auth` methods by @jlumbroso in https://github.com/burnash/gspread/pull/1075
+
 5.4.0 (2022-06-01)
 ------------------
 * fix typo by @joswlv in https://github.com/burnash/gspread/pull/1031

docs/api/exceptions.rst

@@ -6,6 +6,7 @@ Exceptions
 .. autoexception:: gspread.exceptions.CellNotFound
 .. autoexception:: gspread.exceptions.GSpreadException
 .. autoexception:: gspread.exceptions.IncorrectCellLabel
+.. autoexception:: gspread.exceptions.InvalidInputValue
 .. autoexception:: gspread.exceptions.NoValidUrlKeyFound
 .. autoexception:: gspread.exceptions.SpreadsheetNotFound
 .. autoexception:: gspread.exceptions.UnSupportedExportFormat

docs/oauth2.rst

@@ -188,14 +188,12 @@ manager.
     import gspread
 
     credentials = {
-        {
-            "installed": {
-                "client_id": "12345678901234567890abcdefghijklmn.apps.googleusercontent.com",
-                "project_id": "my-project1234",
-                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
-                "token_uri": "https://oauth2.googleapis.com/token",
-                ...
-            }
+        "installed": {
+            "client_id": "12345678901234567890abcdefghijklmn.apps.googleusercontent.com",
+            "project_id": "my-project1234",
+            "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+            "token_uri": "https://oauth2.googleapis.com/token",
+            ...
         }
     }
     gc, authorized_user = gspread.oauth_from_dict(credentials)

gspread/__init__.py

@@ -13,9 +13,15 @@
 __author__ = "Anton Burnashev"
 
 
-from .auth import oauth, oauth_from_dict, service_account, service_account_from_dict
+from .auth import (
+    authorize,
+    oauth,
+    oauth_from_dict,
+    service_account,
+    service_account_from_dict,
+)
 from .cell import Cell
-from .client import Client
+from .client import BackoffClient, Client, ClientFactory
 from .exceptions import (
     CellNotFound,
     GSpreadException,
@@ -26,16 +32,3 @@
 )
 from .spreadsheet import Spreadsheet
 from .worksheet import Worksheet
-
-
-def authorize(credentials, client_class=Client):
-    """Login to Google API using OAuth2 credentials.
-    This is a shortcut function which
-    instantiates `client_class`.
-    By default :class:`gspread.Client` is used.
-
-    :returns: `client_class` instance.
-    """
-
-    client = client_class(auth=credentials)
-    return client

gspread/auth.py

@@ -49,6 +49,20 @@ def get_config_dir(config_dir_name="gspread", os_is_windows=os.name == "nt"):
 DEFAULT_SERVICE_ACCOUNT_FILENAME = DEFAULT_CONFIG_DIR / "service_account.json"
 
 
+def authorize(credentials, client_factory=Client):
+    """Login to Google API using OAuth2 credentials.
+    This is a shortcut/helper function which
+    instantiates a client using `client_factory`.
+    By default :class:`gspread.Client` is used (but could also use
+    :class:`gspread.BackoffClient` to avoid rate limiting).
+
+    :returns: An instance of the class produced by `client_factory`.
+    :rtype: :class:`gspread.client.Client`
+    """
+
+    return client_factory(auth=credentials)
+
+
 def local_server_flow(client_config, scopes, port=0):
     """Run an OAuth flow using a local server strategy.
 
@@ -105,6 +119,7 @@ def oauth(
     flow=local_server_flow,
     credentials_filename=DEFAULT_CREDENTIALS_FILENAME,
     authorized_user_filename=DEFAULT_AUTHORIZED_USER_FILENAME,
+    client_factory=Client,
 ):
     r"""Authenticate with OAuth Client ID.
 
@@ -162,8 +177,12 @@ def oauth(
 
             * `%APPDATA%\gspread\authorized_user.json` on Windows
             * `~/.config/gspread/authorized_user.json` everywhere else
+    :type client_factory: :class:`gspread.ClientFactory`
+    :param client_factory: A factory function that returns a client class.
+        Defaults to :class:`gspread.Client` (but could also use
+        :class:`gspread.BackoffClient` to avoid rate limiting)
 
-    :rtype: :class:`gspread.Client`
+    :rtype: :class:`gspread.client.Client`
     """
     authorized_user_filename = Path(authorized_user_filename)
     creds = load_credentials(filename=authorized_user_filename)
@@ -174,14 +193,15 @@ def oauth(
         creds = flow(client_config=client_config, scopes=scopes)
         store_credentials(creds, filename=authorized_user_filename)
 
-    return Client(auth=creds)
+    return client_factory(auth=creds)
 
 
 def oauth_from_dict(
     credentials=None,
     authorized_user_info=None,
     scopes=DEFAULT_SCOPES,
     flow=local_server_flow,
+    client_factory=Client,
 ):
     r"""Authenticate with OAuth Client ID.
 
@@ -237,8 +257,12 @@ 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 client_factory: :class:`gspread.ClientFactory`
+    :param client_factory: A factory function that returns a client class.
+        Defaults to :class:`gspread.Client` (but could also use
+        :class:`gspread.BackoffClient` to avoid rate limiting)
 
-    :rtype: tuple(:class:`gspread.Client` , str)
+    :rtype: (`gspread.client.Client`, str)
     """
 
     creds = None
@@ -248,15 +272,19 @@ def oauth_from_dict(
     if not creds:
         creds = flow(client_config=credentials, scopes=scopes)
 
-    client = Client(auth=creds)
+    client = client_factory(auth=creds)
 
     # must return the creds to the user
     # must strip the token an use the dedicated method from Credentials
     # to return a dict "safe to store".
     return (client, creds.to_json("token"))
 
 
-def service_account(filename=DEFAULT_SERVICE_ACCOUNT_FILENAME, scopes=DEFAULT_SCOPES):
+def service_account(
+    filename=DEFAULT_SERVICE_ACCOUNT_FILENAME,
+    scopes=DEFAULT_SCOPES,
+    client_factory=Client,
+):
     """Authenticate using a service account.
 
     ``scopes`` parameter defaults to read/write scope available in
@@ -274,14 +302,18 @@ def service_account(filename=DEFAULT_SERVICE_ACCOUNT_FILENAME, scopes=DEFAULT_SC
 
     :param str filename: The path to the service account json file.
     :param list scopes: The scopes used to obtain authorization.
+    :type client_factory: :class:`gspread.ClientFactory`
+    :param client_factory: A factory function that returns a client class.
+        Defaults to :class:`gspread.Client` (but could also use
+        :class:`gspread.BackoffClient` to avoid rate limiting)
 
-    :rtype: :class:`gspread.Client`
+    :rtype: :class:`gspread.client.Client`
     """
     creds = ServiceAccountCredentials.from_service_account_file(filename, scopes=scopes)
-    return Client(auth=creds)
+    return client_factory(auth=creds)
 
 
-def service_account_from_dict(info, scopes=DEFAULT_SCOPES):
+def service_account_from_dict(info, scopes=DEFAULT_SCOPES, client_factory=Client):
     """Authenticate using a service account (json).
 
     ``scopes`` parameter defaults to read/write scope available in
@@ -299,11 +331,15 @@ def service_account_from_dict(info, scopes=DEFAULT_SCOPES):
 
     :param info (Mapping[str, str]): The service account info in Google format
     :param list scopes: The scopes used to obtain authorization.
+    :type client_factory: :class:`gspread.ClientFactory`
+    :param client_factory: A factory function that returns a client class.
+        Defaults to :class:`gspread.Client` (but could also use
+        :class:`gspread.BackoffClient` to avoid rate limiting)
 
-    :rtype: :class:`gspread.Client`
+    :rtype: :class:`gspread.client.Client`
     """
     creds = ServiceAccountCredentials.from_service_account_info(
         info=info,
         scopes=scopes,
     )
-    return Client(auth=creds)
+    return client_factory(auth=creds)

gspread/client.py

@@ -8,6 +8,7 @@
 """
 
 from http import HTTPStatus
+from typing import Type
 
 from google.auth.transport.requests import AuthorizedSession
 
@@ -57,6 +58,12 @@ def login(self):
         self.session.headers.update({"Authorization": "Bearer %s" % self.auth.token})
 
     def set_timeout(self, timeout):
+        """How long to wait for the server to send
+        data before giving up, as a float, or a ``(connect timeout,
+        read timeout)`` tuple.
+
+        Value for ``timeout`` is in seconds (s).
+        """
         self.timeout = timeout
 
     def request(
@@ -223,9 +230,9 @@ def create(self, title, folder_id=None):
         return self.open_by_key(spreadsheet_id)
 
     def export(self, file_id, format=ExportFormat.PDF):
-        """Export the spreadsheet in the format.
+        """Export the spreadsheet in the given format.
 
-        :param str file_id: A key of a spreadsheet to export
+        :param str file_id: The key of the spreadsheet to export
 
         :param str format: The format of the resulting file.
             Possible values are:
@@ -239,7 +246,7 @@ def export(self, file_id, format=ExportFormat.PDF):
 
             See `ExportFormat`_ in the Drive API.
 
-        :returns bytes: A content of the exported file.
+        :returns bytes: The content of the exported file.
 
         .. _ExportFormat: https://developers.google.com/drive/api/guides/ref-export-formats
         """
@@ -459,6 +466,8 @@ def insert_permission(
         :param bool with_link: (optional) Whether the link is required for this
             permission to be active.
 
+        :returns dict: the newly created permission
+
         Examples::
 
             # Give write permissions to [email protected]
@@ -496,7 +505,7 @@ def insert_permission(
             "supportsAllDrives": "true",
         }
 
-        self.request("post", url, json=payload, params=params)
+        return self.request("post", url, json=payload, params=params)
 
     def remove_permission(self, file_id, permission_id):
         """Deletes a permission from a file.
@@ -526,6 +535,11 @@ class BackoffClient(Client):
         This Client is not production ready yet.
         Use it at your own risk !
 
+    .. note::
+        To use with the `auth` module, make sure to pass this backoff
+        client factory using the ``client_factory`` parameter of the
+        method used.
+
     .. note::
         Currently known issues are:
 
@@ -573,3 +587,6 @@ def request(self, *args, **kwargs):
 
             # failed too many times, raise APIEerror
             raise err
+
+
+ClientFactory = Type[Client]

gspread/exceptions.py

@@ -35,6 +35,10 @@ class IncorrectCellLabel(GSpreadException):
     """The cell label is incorrect."""
 
 
+class InvalidInputValue(GSpreadException):
+    """The provided values is incorrect."""
+
+
 class APIError(GSpreadException):
     def __init__(self, response):