{"id":5611,"library":"django-deprecation","title":"Django Deprecation (Field Management)","description":"django-deprecation is a Python library designed to facilitate the deprecation and renaming of Django model fields without introducing breaking changes to existing code or requiring immediate, complex database migrations. It helps maintain backward compatibility during phased rollouts, especially in environments with rolling deployments. The current version is 0.1.1, and its release cadence appears to be feature-driven rather than time-based.","status":"active","version":"0.1.1","language":"en","source_language":"en","source_url":"https://github.com/openbox/django-deprecation","tags":["django","deprecation","migrations","model fields","backward compatibility"],"install":[{"cmd":"pip install django-deprecation","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality; the library operates within Django's ORM and migration system.","package":"Django","optional":false}],"imports":[{"symbol":"DeprecatedField","correct":"from django_deprecation import DeprecatedField"}],"quickstart":{"code":"import os\nimport django\nfrom django.db import models\nfrom django_deprecation import DeprecatedField\n\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings') # Replace with your project settings\ndjango.setup()\n\nclass Musician(models.Model):\n    name = models.CharField(max_length=50)\n\n    def __str__(self):\n        return self.name\n\nclass Album(models.Model):\n    artist = models.ForeignKey(Musician, on_delete=models.CASCADE)\n    # Deprecate 'musician' field, pointing to 'artist'\n    musician = DeprecatedField('artist')\n    name = models.CharField(max_length=100)\n\n    def __str__(self):\n        return self.name\n\n# Example usage (assuming models are migrated and data exists)\n# No runnable example for DB operations without full Django setup\n# print('Demonstrating DeprecatedField behavior:')\n# band = Musician.objects.create(name='The Beatles')\n# album = Album.objects.create(artist=band, name='Abbey Road')\n# assert album.musician == album.artist\n# print(f\"Album name: {album.name}, Musician (deprecated): {album.musician.name}, Artist (new): {album.artist.name}\")","lang":"python","description":"This example demonstrates how to use `DeprecatedField` to rename a model field (`musician` to `artist`) while maintaining backward compatibility for existing code that still references the old field name. The `DeprecatedField` ensures that lookups and access via the old name are correctly redirected to the new field. This typically involves a multi-step migration process."},"warnings":[{"fix":"Implement a phased rollout: 1. Add `DeprecatedField` pointing to the new field, deploy, run `makemigrations` and `migrate`. 2. After all instances are updated, refactor code to use the new field. 3. Finally, remove the `DeprecatedField` entirely, deploy, run `makemigrations` and `migrate` again. This ensures database schema compatibility at each stage.","message":"When deprecating and removing model fields, it is crucial to follow a multi-step deployment process, especially in rolling deployment environments. Failure to do so can lead to application crashes due to database schema mismatches. The recommended steps involve adding the `DeprecatedField`, deploying, running migrations, then later removing the deprecated field entirely and running migrations again.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Understand the distinct use cases. Use `django-deprecation.DeprecatedField` for seamless runtime field aliasing and query redirection. Use Django's `system_check_deprecated_details` on custom fields for static code analysis warnings to guide developers away from deprecated usage during development.","message":"This `django-deprecation` library (by openbox) focuses on runtime aliasing and query handling for deprecated fields. Django also has built-in mechanisms like `system_check_deprecated_details` for raising developer warnings during system checks. These serve different purposes: `DeprecatedField` maintains runtime compatibility, while `system_check_deprecated_details` primarily informs developers of impending changes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the `pypi-slug` and `source_url` for the library you intend to use. This entry specifically refers to `openbox/django-deprecation` (version 0.1.1) imported as `django_deprecation`. Check your `requirements.txt` and `setup.py` for clarity.","message":"Be aware of potential confusion with similarly named libraries like 'django-deprecate-fields' (by 3YOURMIND, version 0.2.3), which serves a similar purpose but might have different import paths or implementations. Ensure you are using the correct library based on your project's chosen dependency.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}