Fixed #35060 -- Deprecated passing positional arguments to Model.save()/asave().

4 files changed, 31 insertions, 27 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index a1b00c364a..07e0f46856 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -68,6 +68,9 @@ details on these changes.
 
 * The ``django.contrib.gis.geoip2.GeoIP2.open()`` method will be removed.
 
+* Support for passing positional arguments to ``Model.save()`` and
+  ``Model.asave()`` will be removed.
+
 .. _deprecation-removed-in-5.1:
 
 5.1
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 81f9bfb433..45af7f244f 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -116,7 +116,7 @@ are loaded from the database::
         return instance
 
 
-    def save(self, *args, **kwargs):
+    def save(self, **kwargs):
         # Check how the current values differ from ._loaded_values. For example,
         # prevent changing the creator_id of the model. (This example doesn't
         # support cases where 'creator_id' is deferred).
@@ -124,7 +124,7 @@ are loaded from the database::
             self.creator_id != self._loaded_values["creator_id"]
         ):
             raise ValueError("Updating the value of creator isn't allowed")
-        super().save(*args, **kwargs)
+        super().save(**kwargs)
 
 The example above shows a full ``from_db()`` implementation to clarify how that
 is done. In this case it would be possible to use a ``super()`` call in the
@@ -410,8 +410,8 @@ Saving objects
 
 To save an object back to the database, call ``save()``:
 
-.. method:: Model.save(force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)
-.. method:: Model.asave(force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)
+.. method:: Model.save(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)
+.. method:: Model.asave(*, force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS, update_fields=None)
 
 *Asynchronous version*: ``asave()``
 
@@ -424,6 +424,10 @@ method. See :ref:`overriding-model-methods` for more details.
 
 The model save process also has some subtleties; see the sections below.
 
+.. deprecated:: 5.1
+
+    Support for positional arguments is deprecated.
+
 Auto-incrementing primary keys
 ------------------------------
 
diff --git a/docs/releases/5.1.txt b/docs/releases/5.1.txt
index b825e9be4f..539ff566a3 100644
--- a/docs/releases/5.1.txt
+++ b/docs/releases/5.1.txt
@@ -331,6 +331,9 @@ Miscellaneous
 * The ``django.contrib.gis.geoip2.GeoIP2.open()`` method is deprecated. Use the
   :class:`~django.contrib.gis.geoip2.GeoIP2` constructor instead.
 
+* Passing positional arguments to :meth:`.Model.save` and :meth:`.Model.asave`
+  is deprecated in favor of keyword-only arguments.
+
 Features removed in 5.1
 =======================
 
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index b419185bbc..244e9bbb16 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -868,9 +868,9 @@ to happen whenever you save an object. For example (see
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
-        def save(self, *args, **kwargs):
+        def save(self, **kwargs):
             do_something()
-            super().save(*args, **kwargs)  # Call the "real" save() method.
+            super().save(**kwargs)  # Call the "real" save() method.
             do_something_else()
 
 You can also prevent saving::
@@ -882,24 +882,23 @@ You can also prevent saving::
         name = models.CharField(max_length=100)
         tagline = models.TextField()
 
-        def save(self, *args, **kwargs):
+        def save(self, **kwargs):
             if self.name == "Yoko Ono's blog":
                 return  # Yoko shall never have her own blog!
             else:
-                super().save(*args, **kwargs)  # Call the "real" save() method.
+                super().save(**kwargs)  # Call the "real" save() method.
 
 It's important to remember to call the superclass method -- that's
-that ``super().save(*args, **kwargs)`` business -- to ensure
-that the object still gets saved into the database. If you forget to
-call the superclass method, the default behavior won't happen and the
-database won't get touched.
+that ``super().save(**kwargs)`` business -- to ensure that the object still
+gets saved into the database. If you forget to call the superclass method, the
+default behavior won't happen and the database won't get touched.
 
 It's also important that you pass through the arguments that can be
-passed to the model method -- that's what the ``*args, **kwargs`` bit
-does. Django will, from time to time, extend the capabilities of
-built-in model methods, adding new arguments. If you use ``*args,
-**kwargs`` in your method definitions, you are guaranteed that your
-code will automatically support those arguments when they are added.
+passed to the model method -- that's what the ``**kwargs`` bit does. Django
+will, from time to time, extend the capabilities of built-in model methods,
+adding new keyword arguments. If you use ``**kwargs`` in your method
+definitions, you are guaranteed that your code will automatically support those
+arguments when they are added.
 
 If you wish to update a field value in the :meth:`~Model.save` method, you may
 also want to have this field added to the ``update_fields`` keyword argument.
@@ -914,18 +913,13 @@ example::
         name = models.CharField(max_length=100)
         slug = models.TextField()
 
-        def save(
-            self, force_insert=False, force_update=False, using=None, update_fields=None
-        ):
+        def save(self, **kwargs):
             self.slug = slugify(self.name)
-            if update_fields is not None and "name" in update_fields:
+            if (
+                update_fields := kwargs.get("update_fields")
+            ) is not None and "name" in update_fields:
                 update_fields = {"slug"}.union(update_fields)
-            super().save(
-                force_insert=force_insert,
-                force_update=force_update,
-                using=using,
-                update_fields=update_fields,
-            )
+            super().save(**kwargs)
 
 See :ref:`ref-models-update-fields` for more details.