Django Deprecate Fields

Warnings

• gotcha When a field is deprecated, it automatically becomes nullable. You must generate a new migration (`python manage.py makemigrations`) to apply this change to your database schema.
  Fix: Run `python manage.py makemigrations` after wrapping a field with `deprecate_field`, and then apply the migration.
• gotcha By default, accessing a deprecated field will log an `ERROR` message. To make it raise an exception (e.g., in development or CI environments) set `DEPRECATED_FIELD_STRICT = True` in your Django settings.
  Fix: Add `DEPRECATED_FIELD_STRICT = True` to your Django `settings.py` file to convert access warnings into exceptions.
• breaking The complete removal of a field should be a two-step deployment process, especially in a rolling deploy scenario. First, mark the field as deprecated and deploy. Second, once the deprecated version is stable, remove the field definition entirely from the model and deploy again with a new migration.
  Fix: Follow the two-step removal process: 1. Deprecate field, `makemigrations`, deploy. 2. Remove field from model, `makemigrations`, deploy.
• gotcha If you use custom Django migration commands (e.g., `pgmakemigrations`), the `deprecate_field` wrapper might not return the actual field during these commands. You must specify these commands in your settings using `DEPRECATE_FIELD_CUSTOM_MIGRATION_COMMAND` to ensure correct behavior.
  Fix: Add `DEPRECATE_FIELD_CUSTOM_MIGRATION_COMMAND = {"your_custom_command"}` to your Django `settings.py`.

Install

• pip install django-deprecate-fields Pip

Imports

• deprecate_field

  from django_deprecate_fields import deprecate_field

Quickstart

To deprecate a model field, import `deprecate_field` and wrap the existing field definition with it. After this, run `makemigrations`. The package automatically handles making the field nullable. The `return_instead` argument can be used to specify a value or callable to return when the deprecated field is accessed.

from django.db import models
from django_deprecate_fields import deprecate_field

class MyModel(models.Model):
    # Original field
    old_field = models.CharField(max_length=255)

    # To deprecate old_field, wrap it with deprecate_field
    # Run './manage.py makemigrations' after this change.
    deprecated_field = deprecate_field(models.CharField(max_length=255, null=True, blank=True), return_instead='default_value_or_none')
    # After deprecation and deployment, old_field can be safely removed.
    # deprecated_field = models.CharField(max_length=255) # This is how it would look after the first step
    # Then, after successful deployment, it can be entirely removed and a new migration created.