Deprecation plan

This change is sure to cause disruption for users. Smooth the transition
with an option.

docs/changelog.rst

@@ -35,6 +35,22 @@ retain the previous behavior.
 
  :func:`~factory.use_strategy()` will be removed in the next major version.
 
+ - :class:`factory.django.DjangoModelFactory._after_postgeneration` raises a :class:`DeprecationWarning` when
+ calling :meth:`~django.db.models.Model.save`. :meth:`~django.db.models.Model.save` will no longer be called in
+ the next major version of Factory Boy.
+
+ Inspect your :class:`~factory.django.DjangoModelFactory` subclasses:
+
+ - If the :meth:`~django.db.models.Model.save` call is not needed after :class:`~factory.PostGeneration`, set
+ :attr:`~factory.django.DjangoOptions.skip_postgeneration_save` to ``True``.
+ - Otherwise, the instance has been modified by :class:`~factory.PostGeneration` hooks and needs to be
+ :meth:`~django.db.models.Model.save`\ d. Either:
+
+ - call :meth:`django.db.models.Model.save` in the :class:`~factory.PostGeneration` hook that modifies the
+ instance, or
+ - override :class:`~factory.django.DjangoModelFactory._after_postgeneration` to
+ :meth:`~django.db.models.Model.save` the instance.
+
 
 3.1.1 (unreleased)
 ------------------

docs/orms.rst

@@ -109,6 +109,14 @@ All factories for a Django :class:`~django.db.models.Model` should use the
  >>> john.email # The email value was not updated
  "john@example.com"
 
+ .. attribute:: skip_postgeneration_save
+
+ Transitional option to prevent
+ :meth:`~factory.django.DjangoModelFactory._after_postgeneration` from
+ issuing a duplicate call to :meth:`~django.db.models.Model.save` on the
+ created instance when :class:`factory.PostGeneration` hooks return a
+ value.
+
 
 Extra fields
 """"""""""""

factory/django.py

@@ -8,6 +8,7 @@
 import io
 import logging
 import os
+import warnings
 
 from django.contrib.auth.hashers import make_password
 from django.core import files as django_files
@@ -48,6 +49,7 @@ def _build_default_options(self):
  return super()._build_default_options() + [
  base.OptionDefault('django_get_or_create', (), inherit=True),
  base.OptionDefault('database', DEFAULT_DB_ALIAS, inherit=True),
+ base.OptionDefault('skip_postgeneration_save', False, inherit=True),
  ]
 
  def _get_counter_reference(self):
@@ -166,6 +168,23 @@ def _create(cls, model_class, *args, **kwargs):
  manager = cls._get_manager(model_class)
  return manager.create(*args, **kwargs)
 
+ # DEPRECATED. Remove this override with the next major release.
+ @classmethod
+ def _after_postgeneration(cls, instance, create, results=None):
+ """Save again the instance if creating and at least one hook ran."""
+ if create and results and not cls._meta.skip_postgeneration_save:
+ warnings.warn(
+ f"{cls.__name__}._after_postgeneration will stop saving the instance "
+ "after postgeneration hooks in the next major release.\n"
+ "If the save call is extraneous, set skip_postgeneration_save=True "
+ f"in the {cls.__name__}.Meta.\n"
+ "To keep saving the instance, move the save call to your "
+ "postgeneration hooks or override _after_postgeneration.",
+ DeprecationWarning,
+ )
+ # Some post-generation hooks ran, and may have modified us.
+ instance.save()
+
 
 class Password(declarations.Transformer):
  def __init__(self, password, *args, **kwargs):

tests/test_django.py

@@ -425,6 +425,9 @@ class PointedRelatedFactory(PointedFactory):
  factory_related_name='pointed',
  )
 
+ class Meta:
+ skip_postgeneration_save = True
+
  class PointerExtraFactory(PointerFactory):
  pointed__foo = 'extra_new_foo'
 
@@ -441,6 +444,9 @@ class Params:
  )
  )
 
+ class Meta:
+ skip_postgeneration_save = True
+
  cls.PointedFactory = PointedFactory
  cls.PointerFactory = PointerFactory
  cls.PointedRelatedFactory = PointedRelatedFactory
@@ -935,6 +941,7 @@ def test_class_decorator_with_subfactory(self):
  class WithSignalsDecoratedFactory(factory.django.DjangoModelFactory):
  class Meta:
  model = models.WithSignals
+ skip_postgeneration_save = True
 
  @factory.post_generation
  def post(obj, create, extracted, **kwargs):
@@ -1021,6 +1028,7 @@ def test_class_decorator_with_muted_related_factory(self):
  class UndecoratedFactory(factory.django.DjangoModelFactory):
  class Meta:
  model = models.PointerModel
+ skip_postgeneration_save = True
  pointed = factory.RelatedFactory(self.WithSignalsDecoratedFactory)
 
  UndecoratedFactory()
@@ -1041,3 +1049,28 @@ class Meta:
  # Our CustomManager will remove the 'arg=' argument,
  # invalid for the actual model.
  ObjFactory.create(arg='invalid')
+
+
+class DjangoModelFactoryDuplicateSaveDeprecationTest(django_test.TestCase):
+ class StandardFactoryWithPost(StandardFactory):
+ @factory.post_generation
+ def post_action(obj, create, extracted, **kwargs):
+ return 3
+
+ def test_create_warning(self):
+ with self.assertWarns(DeprecationWarning) as cm:
+ self.StandardFactoryWithPost.create()
+
+ [msg] = cm.warning.args
+ self.assertEqual(
+ msg,
+ "StandardFactoryWithPost._after_postgeneration will stop saving the "
+ "instance after postgeneration hooks in the next major release.\n"
+ "If the save call is extraneous, set skip_postgeneration_save=True in the "
+ "StandardFactoryWithPost.Meta.\n"
+ "To keep saving the instance, move the save call to your postgeneration "
+ "hooks or override _after_postgeneration.",
+ )
+
+ def test_build_no_warning(self):
+ self.StandardFactoryWithPost.build()