Removing the magic: the cheat sheet

This document assumes a basic familiarity with Removing the magic changes. It is designed to be used as a simple cheat sheet during a conversion process providing links to relevant parts of Removing the magic document. It is organized by functional areas: databases, models, views, templates, template tags, and settings. This document doesn't cover new functionality.

Pre-conversion

Optional (saves time): if your project doesn't have manage.py file in the project's directory, copy it from django/conf/project_template/.

Databases

Database changes are covered extensively in Database changes you'll need to make. Just execute appropriate SQL scripts.

Optional (saves space): package column of auth_permission table is not used anymore. You can drop it by executing following SQL statement (works for MySQL):

ALTER TABLE `auth_permission` DROP COLUMN `package`;

Eugene's note: after conversion I found that my permissions are screwed up. I regenerated them this way:

• Delete a content of following tables (you can do it now):
  • auth_group_permissions
  • auth_permissions
  • auth_user_user_permissions
  • django_content_type
• After you finished with code changes, run manage.py syncdb. Don't do it now'''

It repopulates the content of said tables properly, but an administrator has to reassign group and user permissions again in Admin. Obviously it can be a problem, if you have hundreds of users with arcane permissions.

Models

1. If your application still lives in yourproject/apps/ directory, you can move it up one level: move yourproject/apps/yourapp/ to yourproject/yourapp.
2. Relocate models by moving content of files in your yourapp/models/ directory to yourapp/models.py file.
3. If your models use datetime or db modules without exporting them directly, add import statements.
4. Relocate Model and Field classes: use django.db.models instead of django.core.meta.
5. Convert the META.admin member to new inner class Admin of the model. Don't forget to remove all pesky commas at the end of lines.
6. Remove from META following parameters: admin (see the previous step), module_name, exceptions, module_constants, and where_constraints. If now your class META is empty, delete it. Otherwise rename it to class Meta.
7. Replace __repr__ with __str__.
8. If you use _pre_save(), _post_save(), _pre_delete(), and/or _post_delete() hooks, replace them by overriding save() and delete() methods.
9. If your model has objects attribute, rename it.

Views

1. Import your models directly the Python way. For example, if your model Person is in yourproject/yourapp/models.py file, use:

   from yourproject.yourapp.models import Person
   

2. Change import statements to reflect the namespace simplification:
   • django.utils.httpwrappers => django.http
   • django.core.exceptions.Http404 => django.http.Http404
   • django.core.template => django.template
   • django.core.formfields => django.forms
   • django.core.extensions => django.shortcuts
   • renamed: django.core.extensions.DjangoContext => django.template.RequestContext
   • moved: django.models.core.Session => django.contrib.sessions.models.Session
3. A former module settings is an instance now. Import it using:

   from django.conf import settings
   

4. Update your code to reflect model changes you did in the Models section above.
5. Include template extensions explicitly.
6. Convert to new Database API. Warning: usually this is the most time-consuming step. Be careful!
7. Rename DoesNotExist exception: people.PersonDoesNotExist becomes Person.DoesNotExist.
8. If you use get_object_or_404() and get_list_or_404(), change their parameters. Note: you cannot use field__ne and order_by keywords. Use exclude() and order_by() methods of new Database API.
9. If you call generic views from your views:
   • Update their parameters: remove app_label and model_name, add queryset.
   • If you pass a template_name argument, add the explicit template extension.
10. If you use Django's authentication, update your code to reflect the consolidation.
11. If you use manipulators, update your code: django.core.formfields is django.forms now.
12. If you use the syndication framework, specify .html extension for slug templates explicitly.
13. If you use raw database connections, update your code.
14. The packages module has been removed.

Templates

1. Optional (file consolidation): you can relocate your templates from yourproject/templates/yourapp/ directory to yourproject/yourapp/templates/ directory.
2. Template tags extends and include should include template extensions explicitly.
3. Change template names for generic views: remove pluralization of model names.
4. If your template uses Django's methods defined on its parameters, try to move this code to corresponding views, if possible. Otherwise apply changes outlined in the Views section above.

Template tags

1. Change import statements to reflect the namespace simplification:
   • django.core.template => django.template
   • django.core.extensions => django.shortcuts
   • renamed: django.core.extensions.DjangoContext => django.template.RequestContext
2. If your template tag uses external templates, include template extensions explicitly.
3. SilentVariableFailure exception was removed: use silent_variable_failure attribute instead.
4. Update your code to reflect model changes you did in the Models section above, if applicable.
5. If you create a template tag via inclusion_tag(), specify its extension explicitly.
6. If your template tag implements a high-level view-like functionality, apply changes outlined in the Views section above.

URLs and settings

1. Update urls.py:
   1. Admin URLConf was relocated:
      • django.contrib.admin.urls.admin => django.contrib.admin.urls
   2. Change the parameters you pass to generic views: remove app_label and model_name, add queryset.
   3. If you pass a template_name argument to generic views, add the explicit template extension.
2. Update settings.py:
   1. Update TEMPLATE_LOADERS to reflect Namespace simplification: remove core from their names.
   2. If you moved templates to yourapp directory (see the Templates section), make sure your TEMPLATE_LOADERS variable includes django.template.loaders.app_directories.load_template_source.
   3. Update INSTALLED_APPS to reflect Namespace simplification:
      • django.models.auth => django.contrib.auth.models
      • django.models.core.sites => django.contrib.sites.models
      • django.models.core.contenttypes => django.contrib.contenttypes.models
   4. Update INSTALLED_APPS to reflect changes you made in the Models section:
      • yourproject.apps.yourapp => yourproject.yourapp
   5. Add additional applications to your INSTALLED_APPS to satisfy dependencies:
      • Before django.contrib.admin add django.contrib.auth and django.contrib.contenttypes.
      • Before django.contrib.flatpages and/or django.contrib.redirects add django.contrib.sites.
   6. The packages module has been removed.
   7. Update MIDDLEWARE_CLASSES to reflect Namespace simplification:
      • django.middleware.sessions.SessionMiddleware => django.contrib.sessions.middleware.SessionMiddleware
   8. If you rely on request.user anywhere in your code, modify MIDDLEWARE_CLASSES:
      • Add django.contrib.auth.middleware.AuthenticationMiddleware anywhere after django.contrib.sessions.middleware.SessionMiddleware.
   9. Remove TEMPLATE_FILE_EXTENSION --- it's not used anymore.

Post-conversion

Debug your changes using manage.py validate and manage.py runserver. If there are any problems, please refer to the appropriate section of this document to verify your changes, and consult Removing the magic.

If you decided to regenerate permissions (see the Pre-conversion section above), now is the good time to execute manage.py syncdb. Remember that an administrator should reassign permissions to all users using Admin.