allows users to silence deprecation warnings

README.md

@@ -17,6 +17,12 @@ Features:
 - Sharing and access control.
 - Batching updates.
 
+## v6.0.0 migration
+
+### Silence the warnings
+In version 5 there are many warnings to mark deprecated feature/functions/methods.
+They can be silenced by setting the `GSPREAD_SILENCE_WARNINGS` environment variable to `1`
+
 ## Installation
 
 ```sh

gspread/auth.py

@@ -16,7 +16,7 @@
 from google_auth_oauthlib.flow import InstalledAppFlow
 
 from .client import Client
-from .utils import DEPRECATION_WARNING_TEMPLATE
+from .utils import deprecation_warning
 
 DEFAULT_SCOPES = [
     "https://www.googleapis.com/auth/spreadsheets",
@@ -60,12 +60,9 @@ def authorize(credentials, client_factory=Client):
     :returns: An instance of the class produced by `client_factory`.
     :rtype: :class:`gspread.client.Client`
     """
-    warnings.warn(
-        DEPRECATION_WARNING_TEMPLATE.format(
-            v_deprecated="6.0.0",
-            msg_deprecated="client_factory will be replaced by gspread.http_client types",
-        ),
-        DeprecationWarning,
+    deprecation_warning(
+        version="6.0.0",
+        msg="client_factory will be replaced by gspread.http_client types",
     )
 
     return client_factory(auth=credentials)
@@ -192,12 +189,9 @@ def oauth(
 
     :rtype: :class:`gspread.client.Client`
     """
-    warnings.warn(
-        DEPRECATION_WARNING_TEMPLATE.format(
-            v_deprecated="6.0.0",
-            msg_deprecated="client_factory will be replaced by gspread.http_client types",
-        ),
-        DeprecationWarning,
+    deprecation_warning(
+        version="6.0.0",
+        msg="client_factory will be replaced by gspread.http_client types",
     )
 
     authorized_user_filename = Path(authorized_user_filename)
@@ -280,12 +274,9 @@ def oauth_from_dict(
 
     :rtype: (`gspread.client.Client`, str)
     """
-    warnings.warn(
-        DEPRECATION_WARNING_TEMPLATE.format(
-            v_deprecated="6.0.0",
-            msg_deprecated="client_factory will be replaced by gspread.http_client types",
-        ),
-        DeprecationWarning,
+    deprecation_warning(
+        version="6.0.0",
+        msg="client_factory will be replaced by gspread.http_client types",
     )
 
     creds = None
@@ -332,14 +323,10 @@ def service_account(
 
     :rtype: :class:`gspread.client.Client`
     """
-    warnings.warn(
-        DEPRECATION_WARNING_TEMPLATE.format(
-            v_deprecated="6.0.0",
-            msg_deprecated="client_factory will be replaced by gspread.http_client types",
-        ),
-        DeprecationWarning,
+    deprecation_warning(
+        version="6.0.0",
+        msg="client_factory will be replaced by gspread.http_client types",
     )
-
     creds = ServiceAccountCredentials.from_service_account_file(filename, scopes=scopes)
     return client_factory(auth=creds)
 
@@ -369,12 +356,9 @@ def service_account_from_dict(info, scopes=DEFAULT_SCOPES, client_factory=Client
 
     :rtype: :class:`gspread.client.Client`
     """
-    warnings.warn(
-        DEPRECATION_WARNING_TEMPLATE.format(
-            v_deprecated="6.0.0",
-            msg_deprecated="client_factory will be replaced by gspread.http_client types",
-        ),
-        DeprecationWarning,
+    deprecation_warning(
+        version="6.0.0",
+        msg="client_factory will be replaced by gspread.http_client types",
     )
 
     creds = ServiceAccountCredentials.from_service_account_info(

gspread/client.py

@@ -6,7 +6,6 @@
 Google API.
 
 """
-import warnings
 from http import HTTPStatus
 from typing import Any, Dict, List, Tuple, Type
 
@@ -21,10 +20,10 @@
     DRIVE_FILES_UPLOAD_API_V2_URL,
 )
 from .utils import (
-    DEPRECATION_WARNING_TEMPLATE,
     ExportFormat,
     MimeType,
     convert_credentials,
+    deprecation_warning,
     extract_id_from_url,
     finditem,
 )
@@ -610,12 +609,9 @@ class BackoffClient(Client):
     _MAX_BACKOFF_REACHED = False  # Stop after reaching _MAX_BACKOFF
 
     def __init__(self, auth):
-        warnings.warn(
-            DEPRECATION_WARNING_TEMPLATE.format(
-                v_deprecated="6.0.0",
-                msg_deprecated="this class will be deprecated and moved to gspread.http_client package",
-            ),
-            DeprecationWarning,
+        deprecation_warning(
+            version="6.0.0",
+            msg="this class will be deprecated and moved to gspread.http_client package",
         )
         super().__init__(auth)
 

gspread/utils.py

@@ -6,7 +6,9 @@
 
 """
 
+import os
 import re
+import warnings
 from collections import defaultdict, namedtuple
 from collections.abc import Sequence
 from functools import wraps
@@ -92,6 +94,8 @@
 
 REQUIRED_KWARGS = "required"
 
+SILENCE_WARNINGS_ENV_KEY = "GSPREAD_SILENCE_WARNINGS"
+
 
 def convert_credentials(credentials):
     module = credentials.__module__
@@ -867,6 +871,26 @@ def to_hex(value: float) -> str:
     return f"#{to_hex(red)}{to_hex(green)}{to_hex(blue)}"
 
 
+def deprecation_warning(version: str, msg: str) -> None:
+    """Emit a deprecation warning.
+
+    ..note::
+
+        This warning can be silenced by setting the environment variable:
+        GSPREAD_SILENCE_WARNINGS=1
+    """
+
+    # do not emit warning if env variable is set specifically to 1
+    if os.getenv(SILENCE_WARNINGS_ENV_KEY, "0") == "1":
+        return
+
+    warnings.warn(
+        DEPRECATION_WARNING_TEMPLATE.format(v_deprecated=version, msg_deprecated=msg),
+        DeprecationWarning,
+        4,  # showd the 4th stack: [1]:current->[2]:deprecation_warning->[3]:<gspread method/function>->[4]:<user's code>
+    )
+
+
 if __name__ == "__main__":
     import doctest
 

gspread/worksheet.py

@@ -6,14 +6,12 @@
 
 """
 
-import warnings
 from typing import Union
 
 from .cell import Cell
 from .exceptions import GSpreadException
 from .urls import SPREADSHEET_URL, WORKSHEET_DRIVE_URL
 from .utils import (
-    DEPRECATION_WARNING_TEMPLATE,
     REQUIRED_KWARGS,
     Dimension,
     PasteOrientation,
@@ -29,6 +27,7 @@
     combined_merge_values,
     convert_colors_to_hex_value,
     convert_hex_to_colors_dict,
+    deprecation_warning,
     fill_gaps,
     filter_dict_values,
     finditem,
@@ -207,14 +206,13 @@ def tab_color(self):
         """Tab color style. Dict with RGB color values.
         If any of R, G, B are 0, they will not be present in the dict.
         """
-        warnings.warn(
-            DEPRECATION_WARNING_TEMPLATE.format(
-                v_deprecated="6.0.0",
-                msg_deprecated="""color format will change to hex format "#RRGGBB".
+        deprecation_warning(
+            version="6.0.0",
+            msg="""color format will change to hex format "#RRGGBB".
                 To suppress warning, use "get_tab_color()" and convert back to dict format, use gspread.utils.convert_hex_to_colors_dict.
                 However, we recommend changing your code to use hex format.""",
-            )
         )
+
         return self._properties.get("tabColorStyle", {}).get("rgbColor", None)
 
     def get_tab_color(self) -> Union[str, None]:
@@ -1184,14 +1182,13 @@ def update(self, range_name, values=None, **kwargs):
 
         .. versionadded:: 3.3
         """
-        warnings.warn(
-            DEPRECATION_WARNING_TEMPLATE.format(
-                v_deprecated="6.0.0",
-                msg_deprecated="Method signature's arguments 'range_name' and 'values' will change their order."
-                " We recommend using named arguments for minimal impact. In addition, the argument 'values' will be mandatory of type: 'List[List]'."
-                " (ex) Worksheet.update(values = [[]], range_name=) ",
-            )
+        deprecation_warning(
+            version="6.0.0",
+            msg="Method signature's arguments 'range_name' and 'values' will change their order."
+            " We recommend using named arguments for minimal impact. In addition, the argument 'values' will be mandatory of type: 'List[List]'."
+            " (ex) Worksheet.update(values = [[]], range_name=) ",
         )
+
         if is_scalar(range_name):
             range_name = absolute_range_name(self.title, range_name)
         else:
@@ -1525,12 +1522,9 @@ def sort(self, *specs, **kwargs):
 
         .. versionadded:: 3.4
         """
-        warnings.warn(
-            DEPRECATION_WARNING_TEMPLATE.format(
-                v_deprecated="6.0.0",
-                msg_deprecated="This function signature will change, arguments will swap places:  sort(range, specs)",
-            ),
-            DeprecationWarning,
+        deprecation_warning(
+            version="6.0.0",
+            msg="This function signature will change, arguments will swap places:  sort(range, specs)",
         )
         range_name = kwargs.pop("range", None)
 
@@ -1612,12 +1606,10 @@ def update_tab_color(self, color: Union[dict, str]):
         if isinstance(color, str):
             color = convert_hex_to_colors_dict(color)
         else:
-            warnings.warn(
-                message=DEPRECATION_WARNING_TEMPLATE.format(
-                    v_deprecated="6.0.0",
-                    msg_deprecated="""color format will change to hex format "#RRGGBB".
+            deprecation_warning(
+                version="6.0.0",
+                msg="""color format will change to hex format "#RRGGBB".
                     To suppress this warning, first convert color to hex with "gspread.utils.convert_colors_to_hex_value(color)""",
-                )
             )
 
         red, green, blue = color["red"], color["green"], color["blue"]