From ab5adfe2aca27ace008d9b27ebaf7e2303986f54 Mon Sep 17 00:00:00 2001 From: Alexandre Lavigne Date: Thu, 19 Oct 2023 16:17:23 +0200 Subject: [PATCH 1/2] allows users to silence deprecation warnings Anyone can silence all the deprecation warnings using the env variable GSPREAD_SILENCE_WARNINGS=1 closes #1323 Signed-off-by: Alexandre Lavigne --- README.md | 15 ++++++++++++++ gspread/auth.py | 48 +++++++++++++++----------------------------- gspread/client.py | 12 ++++------- gspread/utils.py | 24 ++++++++++++++++++++++ gspread/worksheet.py | 42 ++++++++++++++++---------------------- 5 files changed, 76 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 94ef8db36..514a26a0a 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,21 @@ Features: - Sharing and access control. - Batching updates. +# v6.0.0 migration + +## Silence the warnings +We have many warnings to mark deprecated feature/functions/methods. +They can be silenced by setting the following environment variable: + +- name: `GSPREAD_SILENCE_WARNING` +- value: `1` + +Example: +```sh +export GSPREAD_SILENCE_WARNING=1 +python get_sheet.py +``` + ## 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..3e1ebb164 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_WARNING_ENV_KEY = "GSPREAD_SILENCE_WARNING" + 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_WARNING=1 + """ + + # do not emit warning if env variable is set specifically to 1 + if os.getenv(SILENCE_WARNING_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"] From e65109de93acaca5b7e0e0e7f64a741d19412dbb Mon Sep 17 00:00:00 2001 From: Alexandre Lavigne Date: Thu, 19 Oct 2023 17:57:02 +0200 Subject: [PATCH 2/2] improve variable names Signed-off-by: Alexandre Lavigne --- README.md | 17 ++++------------- gspread/utils.py | 6 +++--- 2 files changed, 7 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 514a26a0a..229c706ae 100644 --- a/README.md +++ b/README.md @@ -17,20 +17,11 @@ Features: - Sharing and access control. - Batching updates. -# v6.0.0 migration +## v6.0.0 migration -## Silence the warnings -We have many warnings to mark deprecated feature/functions/methods. -They can be silenced by setting the following environment variable: - -- name: `GSPREAD_SILENCE_WARNING` -- value: `1` - -Example: -```sh -export GSPREAD_SILENCE_WARNING=1 -python get_sheet.py -``` +### 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 diff --git a/gspread/utils.py b/gspread/utils.py index 3e1ebb164..753937016 100644 --- a/gspread/utils.py +++ b/gspread/utils.py @@ -94,7 +94,7 @@ REQUIRED_KWARGS = "required" -SILENCE_WARNING_ENV_KEY = "GSPREAD_SILENCE_WARNING" +SILENCE_WARNINGS_ENV_KEY = "GSPREAD_SILENCE_WARNINGS" def convert_credentials(credentials): @@ -877,11 +877,11 @@ def deprecation_warning(version: str, msg: str) -> None: ..note:: This warning can be silenced by setting the environment variable: - GSPREAD_SILENCE_WARNING=1 + GSPREAD_SILENCE_WARNINGS=1 """ # do not emit warning if env variable is set specifically to 1 - if os.getenv(SILENCE_WARNING_ENV_KEY, "0") == "1": + if os.getenv(SILENCE_WARNINGS_ENV_KEY, "0") == "1": return warnings.warn(