Django typehinting

Question

I created an empty migration, which now looks like this:

def forwards(apps, schema_editor):
    Foo = apps.get_model('app', 'Foo')
    FixedResponse.objects.create(name='Bar')


def backwards(apps, schema_editor):
    Foo = apps.get_model('app', 'Foo')
    Foo.objects.filter(name='Bar').delete()


class Migration(migrations.Migration):

    dependencies = [
        ('app', '0035_fixedresponse'),
    ]

    operations = [
        migrations.RunPython(forwards, backwards)
    ]

Since there is no Django documentation anywhere on this topic (migrations specific) or best practice,

I want to know how do I type hint the code above?

Answer 1

There is no universal answer to that question, and the only reputable source you will find about it is Django's reference and documentation, which don't make any mention about annotations for migrations.

The "correct way to handle type hinting in Django" strictly depends on your company's policy. Prior to asking how, you must ask why. Once you know why, figuring out how will likely be straightforward. However, if instead of asking "why?", you (or your boss) ask "why not?", that's taking the issue upside down. You need a reason to do something, but you don't need a reason not to do something. (1)

If the reason is "to pass CI", this is no valid reason. CI is meant to work for you, not the opposite.

If the reason is "to document the code", this is no valid reason either. Type hints are documentation, the purpose of writing documentation is not "to document the code". Why is any documentation needed? Who is going to read this documentation? What information do they need that is not already clear in the code?

I see 3 valid reasons to use type hints:

1. Provide help for developers using the functions. In the case of migrations, forwards and backwards functions are only used internally by Django. Developers reading your code are expected to have knowledge about migrations. If they don't know what apps and schema_editor are, it seems fair to expect them to refer to migrations.RunPython documentation, rather than re-explaining it for every single backwards and forwards callbacks of every single RunPython operation of every single migration.
2. QA type checking. But type checking is only useful for your own code. You'll never import the functions from migrations to use them in your code, so there is nothing to check.
3. Provide meta information for some smart tools (internal or third party) using introspection to do magic stuff. An excellent example of this use case is FastAPI, their use of annotations is highly advanced and a powerful part of their API.

Unless your case fits in one of these three, or you have any other reason to use type hints, don't try to fit to "policies" blindly. Don't write annotations just because you can. Keep calm and (re)read the Zen of Python. :) (2)

TLDR: Ask your boss to tell you why he wants type hints for migrations. If the answer is a well-defined purpose, write hints to serve that purpose. If the answer is anyhow stupid, write stupid type hints. ¯\(ツ)/¯ (3)

---

Footnotes

(1) The double negation might be confusing. What I mean here is that if someone can't explain the purpose of doing something, you don't need to find the purpose of not doing it. Or at least, there is a very straightforward purpose: saving the time and resources required to do it and maintain it.

(2) Don't try to find any principle specific to this situation in the Zen of Python. I only meant this reference as a general reminder of Python's philosophy: keep things simple, clear explicit code is worth more than poor paraphrasing documentation, that kind of stuff.

(3) If the purpose is "to pass CI" or such, I'd personally recommend something silly like def forwards(apps: ..., schema_editor: ...) -> ... (I mean, literally annotate with the Ellipsis object). Either nobody notice and it was indeed pointless, either your boss or your colleagues throw it back at you and hopefully come with a better defined purpose.

Answer 2

The documentation:

code (and reverse_code if supplied) should be callable objects that accept two arguments; the first is an instance of django.apps.registry.Apps containing historical models that match the operation’s place in the project history, and the second is an instance of SchemaEditor.

https://docs.djangoproject.com/en/stable/ref/migration-operations/#django.db.migrations.operations.RunPython

So, if you want to annotate your data migrations with types, these are the appropriate annotations:

from django.apps.registry import Apps
from django.db.backends.base.schema import BaseDatabaseSchemaEditor

def forwards(apps: Apps, schema_editor: BaseDatabaseSchemaEditor):
    ...