diff --git a/README.md b/README.md index 94ef8db36..229c706ae 100644 --- a/README.md +++ b/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 diff --git a/gspread/auth.py b/gspread/auth.py index 3779b8a47..9dc8376da 100644 --- a/gspread/auth.py +++ b/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( diff --git a/gspread/client.py b/gspread/client.py index ade2b8b30..bc97c65ee 100644 --- a/gspread/client.py +++ b/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) diff --git a/gspread/utils.py b/gspread/utils.py index 326dce5fa..753937016 100644 --- a/gspread/utils.py +++ b/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]:->[4]: + ) + + if __name__ == "__main__": import doctest diff --git a/gspread/worksheet.py b/gspread/worksheet.py index 9898a53e1..0e8d87cea 100644 --- a/gspread/worksheet.py +++ b/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"]