Add required kwargs with no default value

In the next major release we will update some method signature.
In order to help users in the transition, add this new special value
which allows a user to specify an argument as a regular arg and
as a kwarg.

In the case of the breaking change of the method `Worksheet.update()`
it will allow users to speficy the argument names and keep their code
running when the update arrives with no changes.

closes #1264

gspread/utils.py

@@ -89,6 +89,8 @@
     "[Deprecated][in version {v_deprecated}]: {msg_deprecated}"
 )
 
+REQUIRED_KWARGS = "required"
+
 
 def convert_credentials(credentials):
     module = credentials.__module__
@@ -723,7 +725,8 @@ def wrapper(*args, **kwargs):
                 raise TypeError(err % (f.__name__, list(unexpected_kwargs)))
 
             for k, v in default_kwargs.items():
-                kwargs.setdefault(k, v)
+                if v != REQUIRED_KWARGS:
+                    kwargs.setdefault(k, v)
 
             return f(*args, **kwargs)
 

gspread/worksheet.py

@@ -13,6 +13,7 @@
 from .urls import SPREADSHEET_URL, WORKSHEET_DRIVE_URL
 from .utils import (
     DEPRECATION_WARNING_TEMPLATE,
+    REQUIRED_KWARGS,
     Dimension,
     PasteOrientation,
     PasteType,
@@ -933,7 +934,12 @@ def batch_get(self, ranges, **kwargs):
 
         return [ValueRange.from_json(x) for x in response["valueRanges"]]
 
+    # required kwargs is a special value just to allow users to use kwargs
+    # and regular args mixed in order to transit to version 6.0.0
+    # This will be be entirely removed in version 6.0.0
     @accepted_kwargs(
+        range_name=REQUIRED_KWARGS,
+        values=REQUIRED_KWARGS,
         raw=True,
         major_dimension=None,
         value_input_option=None,

tests/utils_test.py

@@ -274,3 +274,28 @@ def test_fill_gaps(self):
         actual = utils.fill_gaps(matrix, 3, 6)
 
         self.assertEqual(actual, expected)
+
+    def test_accepted_kwargs(self):
+        """test accepted_kwargs function.
+        Test the temporary special value: REQUIRED_KWARGS
+        """
+
+        expected_arg0 = 0
+        expected_arg1 = 1
+
+        @utils.accepted_kwargs(arg1=1)
+        def sample_arg1(arg0, **kwargs):
+            self.assertEqual(arg0, expected_arg0)
+            self.assertEqual(kwargs["arg1"], expected_arg1)
+
+        sample_arg1(0)
+
+        expected_arg2 = 2
+
+        @utils.accepted_kwargs(arg1=utils.REQUIRED_KWARGS, arg2=2)
+        def sample_arg2(arg0, arg1=None, **kwargs):
+            self.assertEqual(arg0, expected_arg0)
+            self.assertEqual(arg1, expected_arg1)
+            self.assertEqual(kwargs["arg2"], expected_arg2)
+
+        sample_arg2(0, arg1=1, arg2=2)