Worksheet.update change in arguments and deprecation

[ksj20]

Important: Please do not post usage questions here.
To get a quick response, please ask a question on Stack Overflow using gspread tag.
See existing questions: https://stackoverflow.com/questions/tagged/gspread

-> Always appreciate your work for the community

---

Describe the bug
A clear and concise description of what the bug is.

-> I got the below warning

.env\lib\site-packages\gspread\worksheet.py:1069: UserWarning: [Deprecated][in version 6.0.0]: method signature will change to: 'Worksheet.update(value = [[]], range_name=)' arguments 'range_name' and 'values' will swap, values will be mandatory of type: 'list(list(...))'
  warnings.warn(

I somewhat think that the warning message is vague, in that the part after change to has an errata of Worksheet.update(value*s*... and overall I think the change is not clear; why not rewrite the warning into something like below?

.env\lib\site-packages\gspread\worksheet.py:1069: UserWarning: [Deprecated][in version 6.0.0]: method signature's arguments 'range_name' and 'values' will change their order. We recommend using named arguments. In addition, the argument 'values' will be mandatory of type: 'List[List]'. 
  warnings.warn(

To Reproduce
Steps to reproduce the behavior:

1. I got this warning just reproducing the first example code as shown in below.

Code example*

import gspread

gc = gspread.service_account()

# Open a sheet from a spreadsheet in one go
wks = gc.open("gspread_test").sheet1

# Update a range of cells using the top left corner address
wks.update('A1', [[1, 2], [3, 4]])

# Or update a single cell
wks.update('B3', "it's down there somewhere, let me take another look.")

# Format the header
wks.format('A1:B1', {'textFormat': {'bold': True}})

Environment info:

• Operating System [e.g. Linux, Windows, macOS]: Windows
• Python version: Python 3.10.4
• gspread version: gspread==5.11.3

Additional
I get confused, does this warning appear for every .update method? Not even when I change the type of values into a list of list?
Might be better to update your README for the best practices of using the update method.

Thanks alot

[alifeee]

Hi, thanks for the issue. It is a good point. I think we should still include an example like 'Worksheet.update(value = [[]], range_name=)'.

Here is where the warning is emitted

gspread/gspread/worksheet.py

Lines 1187 to 1193 in d91310c

	warnings.warn(
	DEPRECATION_WARNING_TEMPLATE.format(
	v_deprecated="6.0.0",
	msg_deprecated="method signature will change to: 'Worksheet.update(value = [[]], range_name=)'"
	" arguments 'range_name' and 'values' will swap, values will be mandatory of type: 'list(list(...))'",
	)
	)

Feel free to change this and submit a Pull Request. I can help with whatever you need.