[change] Allow passing specific migration number to dependency #43

Closes #43

CHANGES.rst

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+Verson 1.3.0 [unreleased]
+-------------------------
+
+- [change] Allow possibility to point swappable dependency to specific migration number
+  (instead of only to ``__latest__``)
+
 Version 1.2.0 [2021-11-12]
 --------------------------
 

README.md

@@ -200,7 +200,7 @@ function | purpose
 `get_model_name(app_label, model)` | Gets the name of the model the swappable model has been swapped for (or the name of the original model if not swapped.)
 `get_model_names(app_label, models)` | Match a list of model names to their swapped versions.  All of the models should be from the same app (though their swapped versions need not be).
 `load_model(app_label, model, required=True)` | Load the swapped model class for a swappable model (or the original model if it hasn't been swapped).  If your code can function without the specified model, set `required = False`.
-`dependency(app_label, model, latest=False)` | Generate a dependency tuple for use in migrations. Use `latest=True` only when depending on the first migration of the target dependency doesn't work (eg: when all migrations of the target module should be run), please keep in mind that using `latest=True` can have [drawbacks].
+`dependency(app_label, model, version=None)` | Generate a dependency tuple for use in migrations. Use `version` only when depending on the first migration of the target dependency doesn't work (eg: when a specific migration needs to be depended upon), we recommend avoid using `version='__latest__'` because it can have serious [drawbacks] when new migrations are added to the module which is being depended upon.
 `set_app_prefix(app_label, prefix)` | Set a custom prefix for swappable settings (the default is the upper case `app_label`).  This can be useful if the app has a long name or is part of a larger framework.  This should be set at the top of your models.py.
 `join(app_label, model)`, `split(model)` | Utilities for splitting and joining `"app.Model"` strings and `("app", "Model")` tuples.
 

swapper/__init__.py

@@ -44,15 +44,15 @@ def get_model_name(app_label, model):
     return is_swapped(app_label, model) or join(app_label, model)
 
 
-def dependency(app_label, model, latest=False):
+def dependency(app_label, model, version=None):
     """
     Returns a Django 1.7+ style dependency tuple for inclusion in
     migration.dependencies[]
     """
     dependencies = swappable_dependency(get_model_name(app_label, model))
-    if not latest:
+    if not version:
         return dependencies
-    return dependencies[0], '__latest__'
+    return dependencies[0], version
 
 
 def get_model_names(app_label, models):

tests/test_swapper.py

@@ -86,7 +86,12 @@ def test_swap_dependency(self):
             swapper.dependency("default_app", "Type"), ("alt_app", "__first__")
         )
         self.assertEqual(
-            swapper.dependency("default_app", "Type", True), ("alt_app", "__latest__")
+            swapper.dependency("default_app", "Type", "__latest__"),
+            ("alt_app", "__latest__"),
+        )
+        self.assertEqual(
+            swapper.dependency("default_app", "Type", "0001_custom_migration"),
+            ("alt_app", "0001_custom_migration"),
         )
 
     # Tests that only work if default_app.Type is *not* swapped