= Removing the magic: the cheat sheet =

This document assumes a basic familiarity with [wiki:RemovingTheMagic 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 [wiki:RemovingTheMagic 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 [wiki:RemovingTheMagic#Databasechangesyoullneedtomake 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}}}.
 1. [wiki:RemovingTheMagic#Modellocationchanged Relocate models] by moving content of files in your {{{yourapp/models/}}} directory to {{{yourapp/models.py}}} file.
 1. If your models use {{{datetime}}} or {{{db}}} modules without exporting them directly, [wiki:RemovingTheMagic#Modelmethodsnolongerautomaticallyhaveaccesstodatetimeanddbmodules add import statements].
 1. [wiki:RemovingTheMagic#ModelclassandFieldclassesrenamed/relocated Relocate Model and Field classes]: use {{{django.db.models}}} instead of {{{django.core.meta}}}.
 1. [wiki:RemovingTheMagic#MovedadminoptionstoclassAdmin 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.
 1. [wiki:RemovingTheMagic#Changestomodelsyntax 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}}}.
 1. [wiki:RemovingTheMagic#a__repr__modelmethodisreplacedby__str__ Replace __repr__ with __str__].
 1. If you use {{{_pre_save()}}}, {{{_post_save()}}}, {{{_pre_delete()}}}, and/or {{{_post_delete()}}} hooks, [wiki:RemovingTheMagic#Addedamorepowerfulwayofoverridingmodelmethodsremovedhardcoded_pre_save_post_saveetc. replace them] by overriding {{{save()}}} and {{{delete()}}} methods.
 1. If your model has {{{objects}}} attribute, [wiki:RemovingTheMagic#Overridedefaultmanagernameobjects rename it].

== Views ==

 1. [wiki:RemovingTheMagic#Interactdirectlywithmodelclassesnotwithmagicmodules Import your models directly] the Python way. For example, if your model {{{Person}}} is in {{{yourproject/yourapp/models.py}}} file, use:
{{{
#!python
from yourproject.yourapp.models import Person
}}}
 1. [wiki:RemovingTheMagic#Namespacesimplification 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}}}
 1. A former module {{{settings}}} is an instance now. [wiki:RemovingTheMagic#Movedsettingsintoaninstance Import it] using:
{{{
#!python
from django.conf import settings
}}}
 1. Update your code to reflect model changes you did in the [wiki:MagicRemovalCheatSheet#Models Models section] above.
 1. [wiki:RemovingTheMagic#Includetemplateextensionexplicitly Include template extensions explicitly].
 1. [wiki:RemovingTheMagic#Descriptorfields Convert to new Database API]. ''Warning: usually this is the most time-consuming step. Be careful!''
 1. [wiki:RemovingTheMagic#RenamedDoesNotExistexception Rename DoesNotExist exception]: {{{people.PersonDoesNotExist}}} becomes {{{Person.DoesNotExist}}}.
 1. If you use {{{get_object_or_404()}}} and {{{get_list_or_404()}}}, [wiki:RemovingTheMagic#get_object_or_404andget_list_or_404nowtakemodelclassesnotmodules change their parameters]. Note: you cannot use ''field''{{{__ne}}} and {{{order_by}}} keywords. Use {{{exclude()}}} and {{{order_by()}}} methods of [wiki:RemovingTheMagic#Descriptorfields new Database API].
 1. If you call generic views from your views:
   * [wiki:RemovingTheMagic#Changedtheparametersyoupasstogenericviews Update their parameters]: remove {{{app_label}}} and {{{model_name}}}, add {{{queryset}}}.
   * If you pass a {{{template_name}}} argument, [wiki:RemovingTheMagic#Includetemplateextensionexplicitly add the explicit template extension].
 1. If you use Django's authentication, [wiki:RemovingTheMagic#Authenticationhasbeenconsolidated update your code to reflect the consolidation].
 1. If you use manipulators, [wiki:RemovingTheMagic#Changedinterfacetomanipulators update your code]: {{{django.core.formfields}}} is {{{django.forms}}} now.
 1. If you use the syndication framework, [wiki:RemovingTheMagic#Includetemplateextensionexplicitly specify .html extension for slug templates explicitly].
 1. If you use raw database connections, [wiki:RemovingTheMagic#Databaseconnectionrelocated/renamed update your code].
 1. The {{{packages}}} module [wiki:RemovingTheMagic#Thepackagesmoduleisnomore has been removed].

== Templates ==

 1. ''Optional (file consolidation):'' you can relocate your templates from {{{yourproject/templates/yourapp/}}} directory to {{{yourproject/yourapp/templates/}}} directory.
 1. Template tags {{{extends}}} and {{{include}}} [wiki:RemovingTheMagic#Includetemplateextensionexplicitly should include template extensions explicitly].
 1. [wiki:RemovingTheMagic#Changedtemplatenamesingenericviews Change template names for generic views]: remove pluralization of model names.
 1. 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 [wiki:MagicRemovalCheatSheet#Views Views section] above.

== Template tags ==

 1. [wiki:RemovingTheMagic#Namespacesimplification 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}}}
 1. If your template tag uses external templates, [wiki:RemovingTheMagic#Includetemplateextensionexplicitly include template extensions explicitly].
 1. [wiki:RemovingTheMagic#RemovedSilentVariableFailureexception SilentVariableFailure exception was removed]: use {{{silent_variable_failure}}} attribute instead.
 1. Update your code to reflect model changes you did in the [wiki:MagicRemovalCheatSheet#Models Models section] above, if applicable.
 1. If you create a template tag via {{{inclusion_tag()}}}, [wiki:RemovingTheMagic#Includetemplateextensionexplicitly specify its extension explicitly].
 1. If your template tag implements a high-level view-like functionality, apply changes outlined in the [wiki:MagicRemovalCheatSheet#Views Views section] above.

== URLs and settings ==

 1. Update {{{urls.py}}}:
   1. Admin URLConf was [wiki:RemovingTheMagic#MovedadminURLconftoshortenitspath relocated]:
     * {{{django.contrib.admin.urls.admin}}} => {{{django.contrib.admin.urls}}}
   1. [wiki:RemovingTheMagic#Changedtheparametersyoupasstogenericviews Change the parameters you pass to generic views]: remove {{{app_label}}} and {{{model_name}}}, add {{{queryset}}}.
   1. If you pass a {{{template_name}}} argument to generic views, [wiki:RemovingTheMagic#Includetemplateextensionexplicitly add the explicit template extension].
 1. Update {{{settings.py}}}:
   1. Update {{{TEMPLATE_LOADERS}}} to reflect [wiki:RemovingTheMagic#Namespacesimplification Namespace simplification]: remove {{{core}}} from their names.
   1. If you moved templates to {{{yourapp}}} directory (see the [wiki:MagicRemovalCheatSheet#Templates Templates section]), make sure your {{{TEMPLATE_LOADERS}}} variable includes {{{django.template.loaders.app_directories.load_template_source}}}.
   1. Update {{{INSTALLED_APPS}}} to reflect [wiki:RemovingTheMagic#Namespacesimplification 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}}}
   1. Update {{{INSTALLED_APPS}}} to reflect changes you made in the Models section:
     * {{{yourproject.apps.yourapp}}} => {{{yourproject.yourapp}}}
   1. 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}}}.
   1. The {{{packages}}} module [wiki:RemovingTheMagic#Thepackagesmoduleisnomore has been removed].
   1. Update {{{MIDDLEWARE_CLASSES}}} to reflect [wiki:RemovingTheMagic#Namespacesimplification Namespace simplification]:
     * {{{django.middleware.sessions.SessionMiddleware}}} => {{{django.contrib.sessions.middleware.SessionMiddleware}}}
   1. If you rely on {{{request.user}}} [wiki:RemovingTheMagic#request.userisnowsetviamiddleware anywhere in your code], modify {{{MIDDLEWARE_CLASSES}}}:
     * Add {{{django.contrib.auth.middleware.AuthenticationMiddleware}}} anywhere after {{{django.contrib.sessions.middleware.SessionMiddleware}}}.
   1. Remove {{{TEMPLATE_FILE_EXTENSION}}} --- [wiki:RemovingTheMagic#Includetemplateextensionexplicitly 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 [wiki:RemovingTheMagic 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.