Removing the magic: the cheat sheet

Work in progress.

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 Removing the magic document. It is organized by functional areas: databases, settings, models, views, templates, and template tags. 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 django-admin.py syncdb or 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 applications still live in yourproject/apps/ directory, you can move them 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
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.
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 raw database connections, update your code.
13. 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 your template tag implements a high-level view-like functionality, apply changes outlined in the Views section above.

URLs and settings

Post-conversion

If you decided to regenerate permissions, now is the good time to execute django-admin.py syncdb or manage.py syncdb. Remember that an administrator should reassign permissions to all users using Admin.