From 551feef89b1dc0efdb68bb2731f52b98e4d0a00e Mon Sep 17 00:00:00 2001
From: Alexandre Lavigne <lavigne958@gmail.com>
Date: Sun, 13 Aug 2023 16:38:01 +0200
Subject: [PATCH] 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     |  5 ++++-
 gspread/worksheet.py |  6 ++++++
 tests/utils_test.py  | 25 +++++++++++++++++++++++++
 3 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/gspread/utils.py b/gspread/utils.py
index 6886a315f..1ff79b938 100644
--- a/gspread/utils.py
+++ b/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)
 
diff --git a/gspread/worksheet.py b/gspread/worksheet.py
index 606b71a31..68a398cb4 100644
--- a/gspread/worksheet.py
+++ b/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,
diff --git a/tests/utils_test.py b/tests/utils_test.py
index 727ed8f40..02656d790 100644
--- a/tests/utils_test.py
+++ b/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)