March 23, 2012
\nWelcome to Django 1.4!
\nThese release notes cover the new features, as well as\nsome backwards incompatible changes you’ll\nwant to be aware of when upgrading from Django 1.3 or older versions. We’ve\nalso dropped some features, which are detailed in our deprecation plan, and we’ve begun the deprecation process\nfor some features.
\nThe biggest new feature in Django 1.4 is support for time zones when\nhandling date/times. When enabled, this Django will store date/times in UTC,\nuse timezone-aware objects internally, and translate them to users’ local\ntimezones for display.
\nIf you’re upgrading an existing project to Django 1.4, switching to the\ntimezone aware mode may take some care: the new mode disallows some rather\nsloppy behavior that used to be accepted. We encourage anyone who’s upgrading\nto check out the timezone migration guide\nand the\ntimezone FAQ for useful pointers.
\nOther notable new features in Django 1.4 include:
\nA number of ORM improvements, including SELECT FOR UPDATE support,\nthe ability to bulk insert\nlarge datasets for improved performance, and\nQuerySet.prefetch_related, a method to batch-load related objects\nin areas where select_related()\ndoesn’t work.
Some nice security additions, including improved password hashing\n(featuring PBKDF2 and bcrypt support), new tools for cryptographic\nsigning, several CSRF improvements, and simple clickjacking\nprotection.
An updated default project layout and manage.py that removes the “magic”\nfrom prior versions. And for those who don’t like the new layout, you can\nuse custom project and app templates instead!
… and a whole lot more; see below!
Wherever possible we try to introduce new features in a backwards-compatible\nmanner per our API stability policy policy.\nHowever, as with previous releases, Django 1.4 ships with some minor\nbackwards incompatible changes; people\nupgrading from previous versions of Django should read that list carefully.
\nDjango 1.4 has dropped support for Python 2.4. Python 2.5 is now the minimum\nrequired Python version. Django is tested and supported on Python 2.5, 2.6 and\n2.7.
\nThis change should affect only a small number of Django users, as most\noperating-system vendors today are shipping Python 2.5 or newer as their\ndefault version. If you’re still using Python 2.4, however, you’ll need to\nstick to Django 1.3 until you can upgrade. Per our support policy, Django 1.3 will continue to receive security\nsupport until the release of Django 1.5.
\nDjango does not support Python 3.x at this time. At some point before the\nrelease of Django 1.4, we plan to publish a document outlining our full\ntimeline for deprecating Python 2.x and moving to Python 3.x.
\nIn previous versions, Django used “naive” date/times (that is, date/times\nwithout an associated time zone), leaving it up to each developer to interpret\nwhat a given date/time “really means”. This can cause all sorts of subtle\ntimezone-related bugs.
\nIn Django 1.4, you can now switch Django into a more correct, time-zone aware\nmode. In this mode, Django stores date and time information in UTC in the\ndatabase, uses time-zone-aware datetime objects internally and translates them\nto the end user’s time zone in templates and forms. Reasons for using this\nfeature include:
\nCustomizing date and time display for users around the world.
Storing datetimes in UTC for database portability and interoperability.\n(This argument doesn’t apply to PostgreSQL, because it already stores\ntimestamps with time zone information in Django 1.3.)
Avoiding data corruption problems around DST transitions.
Time zone support is enabled by default in new projects created with\nstartproject. If you want to use this feature in an existing\nproject, read the migration guide. If you\nencounter problems, there’s a helpful FAQ.
Django 1.4 supports integration with in-browser testing frameworks like\nSelenium. The new django.test.LiveServerTestCase base class lets you\ntest the interactions between your site’s front and back ends more\ncomprehensively. See the\ndocumentation for more details and\nconcrete examples.
manage.pyLink to this heading#Django 1.4 ships with an updated default project layout and manage.py file\nfor the startproject management command. These fix some issues with\nthe previous manage.py handling of Python import paths that caused double\nimports, trouble moving from development to deployment, and other\ndifficult-to-debug path issues.
The previous manage.py called functions that are now deprecated, and thus\nprojects upgrading to Django 1.4 should update their manage.py. (The\nold-style manage.py will continue to work as before until Django 1.6. In\n1.5 it will raise DeprecationWarning).
The new recommended manage.py file should look like this:
#!/usr/bin/env python\nimport os, sys\n\nif __name__ == "__main__":\n os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings")\n\n from django.core.management import execute_from_command_line\n\n execute_from_command_line(sys.argv)\n{{ project_name }} should be replaced with the Python package name of the\nactual project.
If settings, URLconfs and apps within the project are imported or referenced\nusing the project name prefix (e.g. myproject.settings, ROOT_URLCONF =\n"myproject.urls", etc.), the new manage.py will need to be moved one\ndirectory up, so it is outside the project package rather than adjacent to\nsettings.py and urls.py.
For instance, with the following layout:
\nmanage.py\nmysite/\n __init__.py\n settings.py\n urls.py\n myapp/\n __init__.py\n models.py\nYou could import mysite.settings, mysite.urls, and mysite.myapp,\nbut not settings, urls, or myapp as top-level modules.
Anything imported as a top-level module can be placed adjacent to the new\nmanage.py. For instance, to decouple myapp from the project module and\nimport it as just myapp, place it outside the mysite/ directory:
manage.py\nmyapp/\n __init__.py\n models.py\nmysite/\n __init__.py\n settings.py\n urls.py\nIf the same code is imported inconsistently (some places with the project\nprefix, some places without it), the imports will need to be cleaned up when\nswitching to the new manage.py.
The startapp and startproject management commands\nnow have a --template option for specifying a path or URL to a custom app\nor project template.
For example, Django will use the /path/to/my_project_template directory\nwhen you run the following command:
django-admin.py startproject --template=/path/to/my_project_template myproject\nYou can also now provide a destination directory as the second\nargument to both startapp and startproject:
django-admin.py startapp myapp /path/to/new/app\ndjango-admin.py startproject myproject /path/to/new/project\nFor more information, see the startapp and startproject\ndocumentation.
The startproject management command now adds a wsgi.py\nmodule to the initial project layout, containing a simple WSGI application that\ncan be used for deploying with WSGI app\nservers.
The built-in development server now supports using an\nexternally-defined WSGI callable, which makes it possible to run runserver\nwith the same WSGI configuration that is used for deployment. The new\nWSGI_APPLICATION setting lets you configure which WSGI callable\nrunserver uses.
(The runfcgi management command also internally wraps the WSGI\ncallable configured via WSGI_APPLICATION.)
SELECT FOR UPDATE supportLink to this heading#Django 1.4 includes a QuerySet.select_for_update() method, which generates a\nSELECT ... FOR UPDATE SQL query. This will lock rows until the end of the\ntransaction, meaning other transactions cannot modify or delete rows matched by\na FOR UPDATE query.
For more details, see the documentation for\nselect_for_update().
Model.objects.bulk_create in the ORMLink to this heading#This method lets you create multiple objects more efficiently. It can result in\nsignificant performance increases if you have many objects.
\nDjango makes use of this internally, meaning some operations (such as database\nsetup for test suites) have seen a performance benefit as a result.
\nSee the bulk_create() docs for more\ninformation.
Django’s auth system (django.contrib.auth) stores passwords using a one-way\nalgorithm. Django 1.3 uses the SHA1 algorithm, but increasing processor speeds\nand theoretical attacks have revealed that SHA1 isn’t as secure as we’d like.\nThus, Django 1.4 introduces a new password storage system: by default Django\nnow uses the PBKDF2 algorithm (as recommended by NIST). You can also easily\nchoose a different algorithm (including the popular bcrypt algorithm). For\nmore details, see How Django stores passwords.
We’ve switched the admin and other bundled templates to use the HTML5\ndoctype. While Django will be careful to maintain compatibility with older\nbrowsers, this change means that you can use any HTML5 features you need in\nadmin pages without having to lose HTML validity or override the provided\ntemplates to change the doctype.
\nPrior to Django 1.4, the admin app let you specify\nchange list filters by specifying a field lookup, but it didn’t allow you to\ncreate custom filters. This has been rectified with a simple API (previously\nused internally and known as “FilterSpec”). For more details, see the\ndocumentation for list_filter.
The admin change list now supports sorting on multiple columns. It respects all\nelements of the ordering attribute,\nand sorting on multiple columns by clicking on headers is designed to mimic the\nbehavior of desktop GUIs. We also added a\nget_ordering() method for specifying the\nordering dynamically (i.e., depending on the request).
ModelAdmin methodsLink to this heading#We added a save_related() method to\nModelAdmin to ease customization of how\nrelated objects are saved in the admin.
Two other new ModelAdmin methods,\nget_list_display() and\nget_list_display_links()\nenable dynamic customization of fields and links displayed on the admin\nchange list.
Admin inlines now only allow those actions for which the user has\npermission. For ManyToMany relationships with an auto-created intermediate\nmodel (which does not have its own permissions), the change permission for the\nrelated model determines if the user has the permission to add, change or\ndelete relationships.
Django 1.4 adds both a low-level API for signing values and a high-level API\nfor setting and reading signed cookies, one of the most common uses of\nsigning in web applications.
\nSee the cryptographic signing docs for more\ninformation.
\nThe previous FormWizard from django.contrib.formtools has been\nreplaced with a new implementation based on the class-based views\nintroduced in Django 1.3. It features a pluggable storage API and doesn’t\nrequire the wizard to pass around hidden fields for every previous step.
Django 1.4 ships with a session-based storage backend and a cookie-based\nstorage backend. The latter uses the tools for\ncryptographic signing also introduced in\nDjango 1.4 to store the wizard’s state in the user’s cookies.
\nreverse_lazyLink to this heading#A lazily evaluated version of reverse() was added to allow using URL\nreversals before the project’s URLconf gets loaded.
Django can now look for a language prefix in the URLpattern when using the new\ni18n_patterns() helper function.\nIt’s also now possible to define translatable URL patterns using\ndjango.utils.translation.ugettext_lazy(). See\nInternationalization: in URL patterns for more information about the language prefix\nand how to internationalize URL patterns.
{% trans %} and {% blocktrans %}Link to this heading#The contextual translation support introduced in\nDjango 1.3 via the pgettext function has been extended to the\ntrans and blocktrans template tags using the new context\nkeyword.
SingleObjectMixin URLConf kwargsLink to this heading#Two new attributes,\npk_url_kwarg\nand\nslug_url_kwarg,\nhave been added to SingleObjectMixin to\nenable the customization of URLconf keyword arguments used for single\nobject generic views.
*args and **kwargs support for template tag helper functionsLink to this heading#The simple_tag,\ninclusion_tag and newly\nintroduced assignment_tag template helper functions may now accept any\nnumber of positional or keyword arguments. For example:
@register.simple_tag\ndef my_tag(a, b, *args, **kwargs):\n warning = kwargs["warning"]\n profile = kwargs["profile"]\n ...\n return ...\nThen, in the template, any number of arguments may be passed to the template\ntag. For example:
\n{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\nTEMPLATE_DEBUG modeLink to this heading#In previous versions of Django, whenever the TEMPLATE_DEBUG setting\nwas True, any exception raised during template rendering (even exceptions\nunrelated to template syntax) were wrapped in TemplateSyntaxError and\nre-raised. This was done in order to provide detailed template source location\ninformation in the debug 500 page.
In Django 1.4, exceptions are no longer wrapped. Instead, the original\nexception is annotated with the source information. This means that catching\nexceptions from template rendering is now consistent regardless of the value of\nTEMPLATE_DEBUG, and there’s no need to catch and unwrap\nTemplateSyntaxError in order to catch other errors.
truncatechars template filterLink to this heading#This new filter truncates a string to be no longer than the specified\nnumber of characters. Truncated strings end with a translatable ellipsis\nsequence (”…”). See the documentation for truncatechars for\nmore details.
static template tagLink to this heading#The staticfiles contrib app has a new\nstatic template tag to refer to files saved with the\nSTATICFILES_STORAGE storage backend. It uses the storage backend’s\nurl method and therefore supports advanced features such as serving\nfiles from a cloud service.
CachedStaticFilesStorage storage backendLink to this heading#The staticfiles contrib app now has a\ndjango.contrib.staticfiles.storage.CachedStaticFilesStorage backend\nthat caches the files it saves (when running the collectstatic\nmanagement command) by appending the MD5 hash of the file’s content to the\nfilename. For example, the file css/styles.css would also be saved as\ncss/styles.55e7cbb9ba48.css
We’ve added a middleware to provide easy protection against clickjacking using the X-Frame-Options\nheader. It’s not enabled by default for backwards compatibility reasons, but\nyou’ll almost certainly want to enable it to help\nplug that security hole for browsers that support the header.
We’ve made various improvements to our CSRF features, including the\nensure_csrf_cookie() decorator, which can\nhelp with AJAX-heavy sites; protection for PUT and DELETE requests; and the\nCSRF_COOKIE_SECURE and CSRF_COOKIE_PATH settings, which\ncan improve the security and usefulness of CSRF protection. See the CSRF\ndocs for more information.
We added two function decorators,\nsensitive_variables() and\nsensitive_post_parameters(), to allow\ndesignating the local variables and POST parameters that may contain sensitive\ninformation and should be filtered out of error reports.
All POST parameters are now systematically filtered out of error reports for\ncertain views (login, password_reset_confirm, password_change and\nadd_view in django.contrib.auth.views, as well as\nuser_change_password in the admin app) to prevent the leaking of sensitive\ninformation such as user passwords.
You can override or customize the default filtering by writing a custom\nfilter. For more information see the docs on\nFiltering error reports.
\nDjango 1.4 can now better handle IPv6 addresses with the new\nGenericIPAddressField model field,\nGenericIPAddressField form field and\nthe validators validate_ipv46_address and\nvalidate_ipv6_address.
The base classes in django.test now have some helpers to\ncompare HTML without tripping over irrelevant differences in whitespace,\nargument quoting/ordering and closing of self-closing tags. You can either\ncompare HTML directly with the new\nassertHTMLEqual() and\nassertHTMLNotEqual() assertions, or use\nthe html=True flag with\nassertContains() and\nassertNotContains() to test whether the\nclient’s response contains a given HTML fragment. See the assertions\ndocumentation for more.
Two new date formats were added for use in template filters,\ntemplate tags and Format localization:
e – the name of the timezone of the given datetime object
o – the ISO 8601 year number
Please make sure to update your custom format files if they contain either e or o in a format\nstring. For example a Spanish localization format previously only escaped the\nd format character:
DATE_FORMAT = r"j \\de F \\de Y"\nBut now it needs to also escape e and o:
DATE_FORMAT = r"j \\d\\e F \\d\\e Y"\nFor more information, see the date documentation.
Django 1.4 also includes several smaller improvements worth noting:
\nA more usable stacktrace in the technical 500 page. Frames in the\nstack trace that reference Django’s framework code are dimmed out,\nwhile frames in application code are slightly emphasized. This change\nmakes it easier to scan a stacktrace for issues in application code.
Tablespace support in PostgreSQL.
Customizable names for simple_tag().
In the documentation, a helpful security overview\npage.
The django.contrib.auth.models.check_password function has been moved\nto the django.contrib.auth.hashers module. Importing it from the old\nlocation will still work, but you should update your imports.
The collectstatic management command now has a --clear option\nto delete all files at the destination before copying or linking the static\nfiles.
It’s now possible to load fixtures containing forward references when using\nMySQL with the InnoDB database engine.
A new 403 response handler has been added as\n'django.views.defaults.permission_denied'. You can set your own handler\nby setting the value of django.conf.urls.handler403. See the\ndocumentation about the 403 (HTTP Forbidden) view\nfor more information.
The makemessages command uses a new and more accurate lexer,\nJsLex, for extracting translatable strings from JavaScript\nfiles.
The trans template tag now takes an optional as argument to\nbe able to retrieve a translation string without displaying it but setting\na template context variable instead.
The if template tag now supports {% elif %} clauses.
If your Django app is behind a proxy, you might find the new\nSECURE_PROXY_SSL_HEADER setting useful. It solves the problem of\nyour proxy “eating” the fact that a request came in via HTTPS. But only use\nthis setting if you know what you’re doing.
A new, plain-text, version of the HTTP 500 status code internal error page\nserved when DEBUG is True is now sent to the client when\nDjango detects that the request has originated in JavaScript code.\n(is_ajax() is used for this.)
Like its HTML counterpart, it contains a collection of different\npieces of information about the state of the application.
\nThis should make it easier to read when debugging interaction with\nclient-side JavaScript.
\nAdded the makemessages --no-location option.
Changed the locmem cache backend to use\npickle.HIGHEST_PROTOCOL for better compatibility with the other\ncache backends.
Added support in the ORM for generating SELECT queries containing\nDISTINCT ON.
The distinct() QuerySet method now accepts an optional list of model\nfield names. If specified, then the DISTINCT statement is limited to\nthese fields. This is only supported in PostgreSQL.
For more details, see the documentation for\ndistinct().
The admin login page will add a password reset link if you include a URL with\nthe name 'admin_password_reset' in your urls.py, so plugging in the\nbuilt-in password reset mechanism and making it available is now much easier.\nFor details, see Adding a password reset feature.
The MySQL database backend can now make use of the savepoint feature\nimplemented by MySQL version 5.0.3 or newer with the InnoDB storage engine.
It’s now possible to pass initial values to the model forms that are part of\nboth model formsets and inline model formsets as returned from factory\nfunctions modelformset_factory and inlineformset_factory respectively\njust like with regular formsets. However, initial values only apply to extra\nforms, i.e. those which are not bound to an existing model instance.
The sitemaps framework can now handle HTTPS links using the new\nSitemap.protocol class\nattribute.
A new django.test.SimpleTestCase subclass of\nunittest.TestCase\nthat’s lighter than django.test.TestCase and company. It can be\nuseful in tests that don’t need to hit a database. See\nHierarchy of Django unit testing classes.
Running Django with an empty or known SECRET_KEY disables many of\nDjango’s security protections and can lead to remote-code-execution\nvulnerabilities. No Django site should ever be run without a\nSECRET_KEY.
In Django 1.4, starting Django with an empty SECRET_KEY will raise a\nDeprecationWarning. In Django 1.5, it will raise an exception and Django\nwill refuse to start. This is slightly accelerated from the usual deprecation\npath due to the severity of the consequences of running Django with no\nSECRET_KEY.
django.contrib.adminLink to this heading#The included administration app django.contrib.admin has for a long time\nshipped with a default set of static files such as JavaScript, images and\nstylesheets. Django 1.3 added a new contrib app django.contrib.staticfiles\nto handle such files in a generic way and defined conventions for static\nfiles included in apps.
Starting in Django 1.4, the admin’s static files also follow this\nconvention, to make the files easier to deploy. In previous versions of Django,\nit was also common to define an ADMIN_MEDIA_PREFIX setting to point to the\nURL where the admin’s static files live on a web server. This setting has now\nbeen deprecated and replaced by the more general setting STATIC_URL.\nDjango will now expect to find the admin static files under the URL\n<STATIC_URL>/admin/.
If you’ve previously used a URL path for ADMIN_MEDIA_PREFIX (e.g.\n/media/) simply make sure STATIC_URL and STATIC_ROOT\nare configured and your web server serves those files correctly. The\ndevelopment server continues to serve the admin files just like before. Read\nthe static files howto for more details.
If your ADMIN_MEDIA_PREFIX is set to a specific domain (e.g.\nhttp://media.example.com/admin/), make sure to also set your\nSTATIC_URL setting to the correct URL – for example,\nhttp://media.example.com/.
Django hasn’t had a clear policy on which browsers are supported by the\nadmin app. Our new policy formalizes existing practices: YUI’s A-grade\nbrowsers should provide a fully-functional admin experience, with the notable\nexception of Internet Explorer 6, which is no longer supported.
\nReleased over 10 years ago, IE6 imposes many limitations on modern web\ndevelopment. The practical implications of this policy are that contributors\nare free to improve the admin without consideration for these limitations.
\nThis new policy has no impact on sites you develop using Django. It only\napplies to the Django admin. Feel free to develop apps compatible with any\nrange of browsers.
\nAs part of an effort to improve the performance and usability of the admin’s\nchange-list sorting interface and horizontal and vertical “filter” widgets, some icon\nfiles were removed and grouped into two sprite files.
Specifically: selector-add.gif, selector-addall.gif,\nselector-remove.gif, selector-removeall.gif,\nselector_stacked-add.gif and selector_stacked-remove.gif were\ncombined into selector-icons.gif; and arrow-up.gif and\narrow-down.gif were combined into sorting-icons.gif.
If you used those icons to customize the admin, then you’ll need to replace\nthem with your own icons or get the files from a previous release.
\nTo avoid conflicts with other common CSS class names (e.g. “button”), we added\na prefix (“field-”) to all CSS class names automatically generated from the\nform field names in the main admin forms, stacked inline forms and tabular\ninline cells. You’ll need to take that prefix into account in your custom\nstyle sheets or JavaScript files if you previously used plain field names as\nselectors for custom styles or JavaScript transformations.
\nDjango 1.3 changed the cryptographic signing mechanisms used in a number of\nplaces in Django. While Django 1.3 kept fallbacks that would accept hashes\nproduced by the previous methods, these fallbacks are removed in Django 1.4.
\nSo, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may\nlose/invalidate certain pieces of data that have been cryptographically signed\nusing an old method. To avoid this, use Django 1.3 first for a period of time\nto allow the signed data to expire naturally. The affected parts are detailed\nbelow, with 1) the consequences of ignoring this advice and 2) the amount of\ntime you need to run Django 1.3 for the data to expire or become irrelevant.
\ncontrib.sessions data integrity check
Consequences: The user will be logged out, and session data will be lost.
Time period: Defined by SESSION_COOKIE_AGE.
contrib.auth password reset hash
Consequences: Password reset links from before the upgrade will not work.
Time period: Defined by PASSWORD_RESET_TIMEOUT_DAYS.
Form-related hashes: these have a much shorter lifetime and are relevant\nonly for the short window where a user might fill in a form generated by the\npre-upgrade Django instance and try to submit it to the upgraded Django\ninstance:
\ncontrib.comments form security hash
Consequences: The user will see the validation error “Security hash\nfailed.”
Time period: The amount of time you expect users to take filling out\ncomment forms.
FormWizard security hash
Consequences: The user will see an error about the form having expired\nand will be sent back to the first page of the wizard, losing the data\nentered so far.
Time period: The amount of time you expect users to take filling out the\naffected forms.
CSRF check
\nNote: This is actually a Django 1.1 fallback, not Django 1.2,\nand it applies only if you’re upgrading from 1.1.
Consequences: The user will see a 403 error with any CSRF-protected POST\nform.
Time period: The amount of time you expect user to take filling out\nsuch forms.
contrib.auth user password hash-upgrade sequence
Consequences: Each user’s password will be updated to a stronger password\nhash when it’s written to the database in 1.4. This means that if you\nupgrade to 1.4 and then need to downgrade to 1.3, version 1.3 won’t be able\nto read the updated passwords.
Remedy: Set PASSWORD_HASHERS to use your original password\nhashing when you initially upgrade to 1.4. After you confirm your app works\nwell with Django 1.4 and you won’t have to roll back to 1.3, enable the new\npassword hashes.
django.contrib.flatpagesLink to this heading#Starting in 1.4, the\nFlatpageFallbackMiddleware only\nadds a trailing slash and redirects if the resulting URL refers to an existing\nflatpage. For example, requesting /notaflatpageoravalidurl in a previous\nversion would redirect to /notaflatpageoravalidurl/, which would\nsubsequently raise a 404. Requesting /notaflatpageoravalidurl now will\nimmediately raise a 404.
Also, redirects returned by flatpages are now permanent (with 301 status code),\nto match the behavior of CommonMiddleware.
datetime and timeLink to this heading#As a consequence of time-zone support, and according to the ECMA-262\nspecification, we made changes to the JSON serializer:
\nIt includes the time zone for aware datetime objects. It raises an exception\nfor aware time objects.
It includes milliseconds for datetime and time objects. There is still\nsome precision loss, because Python stores microseconds (6 digits) and JSON\nonly supports milliseconds (3 digits). However, it’s better than discarding\nmicroseconds entirely.
We changed the XML serializer to use the ISO8601 format for datetimes.\nThe letter T is used to separate the date part from the time part, instead\nof a space. Time zone information is included in the [+-]HH:MM format.
Though the serializers now use these new formats when creating fixtures, they\ncan still load fixtures that use the old format.
\nsupports_timezone changed to False for SQLiteLink to this heading#The database feature supports_timezone used to be True for SQLite.\nIndeed, if you saved an aware datetime object, SQLite stored a string that\nincluded an UTC offset. However, this offset was ignored when loading the value\nback from the database, which could corrupt the data.
In the context of time-zone support, this flag was changed to False, and\ndatetimes are now stored without time-zone information in SQLite. When\nUSE_TZ is False, if you attempt to save an aware datetime\nobject, Django raises an exception.
MySQLdb-specific exceptionsLink to this heading#The MySQL backend historically has raised MySQLdb.OperationalError\nwhen a query triggered an exception. We’ve fixed this bug, and we now raise\ndjango.db.DatabaseError instead. If you were testing for\nMySQLdb.OperationalError, you’ll need to update your except\nclauses.
DatabaseWrapper objects (i.e. the connection objects referenced by\ndjango.db.connection and django.db.connections["some_alias"]) used to\nbe thread-local. They are now global objects in order to be potentially shared\nbetween multiple threads. While the individual connection objects are now\nglobal, the django.db.connections dictionary referencing those objects is\nstill thread-local. Therefore if you just use the ORM or\nDatabaseWrapper.cursor() then the behavior is still the same as before.\nNote, however, that django.db.connection does not directly reference the\ndefault DatabaseWrapper object anymore and is now a proxy to access that\nobject’s attributes. If you need to access the actual DatabaseWrapper\nobject, use django.db.connections[DEFAULT_DB_ALIAS] instead.
As part of this change, all underlying SQLite connections are now enabled for\npotential thread-sharing (by passing the check_same_thread=False attribute\nto pysqlite). DatabaseWrapper however preserves the previous behavior\nby disabling thread-sharing by default, so this does not affect any existing\ncode that purely relies on the ORM or on DatabaseWrapper.cursor().
Finally, while it’s now possible to pass connections between threads, Django\ndoesn’t make any effort to synchronize access to the underlying backend.\nConcurrency behavior is defined by the underlying backend implementation.\nCheck their documentation for details.
\nCOMMENTS_BANNED_USERS_GROUP settingLink to this heading#Django’s comments has historically\nsupported excluding the comments of a special user group, but we’ve never\ndocumented the feature properly and didn’t enforce the exclusion in other parts\nof the app such as the template tags. To fix this problem, we removed the code\nfrom the feed class.
\nIf you rely on the feature and want to restore the old behavior, use a custom\ncomment model manager to exclude the user group, like this:
\nfrom django.conf import settings\nfrom django.contrib.comments.managers import CommentManager\n\n\nclass BanningCommentManager(CommentManager):\n def get_query_set(self):\n qs = super().get_query_set()\n if getattr(settings, "COMMENTS_BANNED_USERS_GROUP", None):\n where = [\n "user_id NOT IN (SELECT user_id FROM auth_user_groups WHERE group_id = %s)"\n ]\n params = [settings.COMMENTS_BANNED_USERS_GROUP]\n qs = qs.extra(where=where, params=params)\n return qs\nSave this model manager in your custom comment app (e.g., in\nmy_comments_app/managers.py) and add it your custom comment app model:
from django.db import models\nfrom django.contrib.comments.models import Comment\n\nfrom my_comments_app.managers import BanningCommentManager\n\n\nclass CommentWithTitle(Comment):\n title = models.CharField(max_length=300)\n\n objects = BanningCommentManager()\nIGNORABLE_404_STARTS and IGNORABLE_404_ENDS settingsLink to this heading#Until Django 1.3, it was possible to exclude some URLs from Django’s\n404 error reporting by adding prefixes to\nIGNORABLE_404_STARTS and suffixes to IGNORABLE_404_ENDS.
In Django 1.4, these two settings are superseded by\nIGNORABLE_404_URLS, which is a list of compiled regular\nexpressions. Django won’t send an email for 404 errors on URLs that match any\nof them.
Furthermore, the previous settings had some rather arbitrary default values:
\nIGNORABLE_404_STARTS = ("/cgi-bin/", "/_vti_bin", "/_vti_inf")\nIGNORABLE_404_ENDS = (\n "mail.pl",\n "mailform.pl",\n "mail.cgi",\n "mailform.cgi",\n "favicon.ico",\n ".php",\n)\nIt’s not Django’s role to decide if your website has a legacy /cgi-bin/\nsection or a favicon.ico. As a consequence, the default values of\nIGNORABLE_404_URLS, IGNORABLE_404_STARTS, and\nIGNORABLE_404_ENDS are all now empty.
If you have customized IGNORABLE_404_STARTS or IGNORABLE_404_ENDS, or\nif you want to keep the old default value, you should add the following lines\nin your settings file:
import re\n\nIGNORABLE_404_URLS = (\n # for each <prefix> in IGNORABLE_404_STARTS\n re.compile(r"^<prefix>"),\n # for each <suffix> in IGNORABLE_404_ENDS\n re.compile(r"<suffix>$"),\n)\nDon’t forget to escape characters that have a special meaning in a regular\nexpression, such as periods.
\nPreviously, Django’s CSRF protection provided\nprotection only against POST requests. Since use of PUT and DELETE methods in\nAJAX applications is becoming more common, we now protect all methods not\ndefined as safe by RFC 2616 – i.e., we exempt GET, HEAD, OPTIONS and TRACE,\nand we enforce protection on everything else.
\nIf you’re using PUT or DELETE methods in AJAX applications, please see the\ninstructions about using AJAX and CSRF.
\nsubject_template_nameLink to this heading#The password_reset view in django.contrib.auth now accepts a\nsubject_template_name parameter, which is passed to the password save form\nas a keyword argument. If you are using this view with a custom password reset\nform, then you will need to ensure your form’s save() method accepts this\nkeyword argument.
django.core.template_loadersLink to this heading#This was an alias to django.template.loader since 2005, and we’ve removed\nit without emitting a warning due to the length of the deprecation. If your\ncode still referenced this, please use django.template.loader instead.
django.db.models.fields.URLField.verify_existsLink to this heading#This functionality has been removed due to intractable performance and\nsecurity issues. Any existing usage of verify_exists should be\nremoved.
django.core.files.storage.Storage.openLink to this heading#The open method of the base Storage class used to take an obscure parameter\nmixin that allowed you to dynamically change the base classes of the\nreturned file object. This has been removed. In the rare case you relied on the\nmixin parameter, you can easily achieve the same by overriding the open\nmethod, like this:
from django.core.files import File\nfrom django.core.files.storage import FileSystemStorage\n\n\nclass Spam(File):\n """\n Spam, spam, spam, spam and spam.\n """\n\n def ham(self):\n return "eggs"\n\n\nclass SpamStorage(FileSystemStorage):\n """\n A custom file storage backend.\n """\n\n def open(self, name, mode="rb"):\n return Spam(open(self.path(name), mode))\nyaml.safe_loadLink to this heading#yaml.load is able to construct any Python object, which may trigger\narbitrary code execution if you process a YAML document that comes from an\nuntrusted source. This feature isn’t necessary for Django’s YAML deserializer,\nwhose primary use is to load fixtures consisting of simple objects. Even though\nfixtures are trusted data, the YAML deserializer now uses yaml.safe_load\nfor additional security.
urlize filter no longer escapes every URLLink to this heading#When a URL contains a %xx sequence, where xx are two hexadecimal\ndigits, urlize now assumes that the URL is already escaped and\ndoesn’t apply URL escaping again. This is wrong for URLs whose unquoted form\ncontains a %xx sequence, but such URLs are very unlikely to happen in the\nwild, because they would confuse browsers too.
assertTemplateUsed and assertTemplateNotUsed as context managerLink to this heading#It’s now possible to check whether a template was used within a block of\ncode with assertTemplateUsed() and\nassertTemplateNotUsed(). And they\ncan be used as a context manager:
with self.assertTemplateUsed("index.html"):\n render_to_string("index.html")\nwith self.assertTemplateNotUsed("base.html"):\n render_to_string("index.html")\nSee the assertion documentation for more.
\nThe default test runner no longer restores the database connections after\ntests’ execution. This prevents the production database from being exposed to\npotential threads that would still be running and attempting to create new\nconnections.
\nIf your code relied on connections to the production database being created\nafter tests’ execution, then you can restore the previous behavior by\nsubclassing DjangoTestRunner and overriding its teardown_databases()\nmethod.
manage.py helpLink to this heading#manage.py help now groups available commands by application.\nIf you depended on the output of this command – if you parsed it, for example\n– then you’ll need to update your code. To get a list of all available\nmanagement commands in a script, use\nmanage.py help --commands instead.
extends template tagLink to this heading#Previously, the extends tag used a buggy method of parsing arguments,\nwhich could lead to it erroneously considering an argument as a string literal\nwhen it wasn’t. It now uses parser.compile_filter, like other tags.
The internals of the tag aren’t part of the official stable API, but in the\ninterests of full disclosure, the ExtendsNode.__init__ definition has\nchanged, which may break any custom tags that use this class.
Prior to 1.4, a default value was inserted for fixture objects that were\nmissing a specific date or datetime value when auto_now or auto_now_add was set\nfor the field. This was something that should not have worked, and in 1.4\nloading such incomplete fixtures will fail. Because fixtures are a raw import,\nthey should explicitly specify all field values, regardless of field options on\nthe model.
\nThe development server is now is multithreaded by default. Use the\nrunserver --nothreading option to disable the use of threading in the\ndevelopment server:
django-admin.py runserver --nothreading\nPrior to Django 1.4, attributes were included in any markdown output regardless\nof safe mode setting of the filter. With version > 2.1 of the Python-Markdown\nlibrary, an enable_attributes option was added. When the safe argument is\npassed to the markdown filter, both the safe_mode=True and\nenable_attributes=False options are set. If using a version of the\nPython-Markdown library less than 2.1, a warning is issued that the output is\ninsecure.
In Django 1.3, the get_initial method of the\ndjango.views.generic.edit.FormMixin class was returning the\nclass initial dictionary. This has been fixed to return a copy of this\ndictionary, so form instances can modify their initial data without messing\nwith the class variable.
cache_page decoratorLink to this heading#Some legacy ways of calling cache_page()\nhave been deprecated. Please see the documentation for the correct way to use\nthis decorator.
Django 1.3 dropped support for PostgreSQL versions older than 8.0, and we\nsuggested using a more recent version because of performance improvements\nand, more importantly, the end of upstream support periods for 8.0 and 8.1\nwas near (November 2010).
\nDjango 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL\nversion it officially supports.
\nWhen we added logging support in Django in 1.3, the\nadmin error email support was moved into the\ndjango.utils.log.AdminEmailHandler, attached to the\n'django.request' logger. In order to maintain the established behavior of\nerror emails, the 'django.request' logger was called only when\nDEBUG was False.
To increase the flexibility of error logging for requests, the\n'django.request' logger is now called regardless of the value of\nDEBUG, and the default settings file for new projects now includes a\nseparate filter attached to django.utils.log.AdminEmailHandler to\nprevent admin error emails in DEBUG mode:
LOGGING = {\n # ...\n "filters": {\n "require_debug_false": {\n "()": "django.utils.log.RequireDebugFalse",\n }\n },\n "handlers": {\n "mail_admins": {\n "level": "ERROR",\n "filters": ["require_debug_false"],\n "class": "django.utils.log.AdminEmailHandler",\n }\n },\n}\nIf your project was created prior to this change, your LOGGING\nsetting will not include this new filter. In order to maintain\nbackwards-compatibility, Django will detect that your 'mail_admins' handler\nconfiguration includes no 'filters' section and will automatically add\nthis filter for you and issue a pending-deprecation warning. This will become a\ndeprecation warning in Django 1.5, and in Django 1.6 the\nbackwards-compatibility shim will be removed entirely.
The existence of any 'filters' key under the 'mail_admins' handler will\ndisable this backward-compatibility shim and deprecation warning.
django.conf.urls.defaultsLink to this heading#Until Django 1.3, the include(), patterns(), and url() functions,\nplus handler404 and\nhandler500 were located in a\ndjango.conf.urls.defaults module.
In Django 1.4, they live in django.conf.urls.
django.contrib.databrowseLink to this heading#Databrowse has not seen active development for some time, and this does not\nshow any sign of changing. There had been a suggestion for a GSOC project to\nintegrate the functionality of databrowse into the admin, but no progress was\nmade. While Databrowse has been deprecated, an enhancement of\ndjango.contrib.admin providing a similar feature set is still possible.
The code that powers Databrowse is licensed under the same terms as Django\nitself, so it’s available to be adopted by an individual or group as\na third-party project.
\ndjango.core.management.setup_environLink to this heading#This function temporarily modified sys.path in order to make the parent\n“project” directory importable under the old flat startproject\nlayout. This function is now deprecated, as its path workarounds are no longer\nneeded with the new manage.py and default project layout.
This function was never documented or part of the public API, but it was widely\nrecommended for use in setting up a “Django environment” for a user script.\nThese uses should be replaced by setting the DJANGO_SETTINGS_MODULE\nenvironment variable or using django.conf.settings.configure().
django.core.management.execute_managerLink to this heading#This function was previously used by manage.py to execute a management\ncommand. It is identical to\ndjango.core.management.execute_from_command_line, except that it first\ncalls setup_environ, which is now deprecated. As such, execute_manager\nis also deprecated; execute_from_command_line can be used instead. Neither\nof these functions is documented as part of the public API, but a deprecation\npath is needed due to use in existing manage.py files.
is_safe and needs_autoescape attributes of template filtersLink to this heading#Two flags, is_safe and needs_autoescape, define how each template\nfilter interacts with Django’s auto-escaping behavior. They used to be\nattributes of the filter function:
@register.filter\ndef noop(value):\n return value\n\n\nnoop.is_safe = True\nHowever, this technique caused some problems in combination with decorators,\nespecially @stringfilter.\nNow, the flags are keyword arguments of @register.filter:
@register.filter(is_safe=True)\ndef noop(value):\n return value\nSee filters and auto-escaping for more\ninformation.
\nINSTALLED_APPSLink to this heading#Until Django 1.3, INSTALLED_APPS accepted wildcards in application\nnames, like django.contrib.*. The expansion was performed by a\nfilesystem-based implementation of from <package> import *. Unfortunately,\nthis can’t be done reliably.
This behavior was never documented. Since it is unpythonic, it was removed in\nDjango 1.4. If you relied on it, you must edit your settings file to list all\nyour applications explicitly.
\nHttpRequest.raw_post_data renamed to HttpRequest.bodyLink to this heading#This attribute was confusingly named HttpRequest.raw_post_data, but it\nactually provided the body of the HTTP request. It’s been renamed to\nHttpRequest.body, and HttpRequest.raw_post_data has been deprecated.
django.contrib.sitemaps bug fix with potential performance implicationsLink to this heading#In previous versions, Paginator objects used in sitemap classes were\ncached, which could result in stale site maps. We’ve removed the caching, so\neach request to a site map now creates a new Paginator object and calls the\nitems method of the\nSitemap subclass. Depending on what your\nitems() method is doing, this may have a negative performance impact.\nTo mitigate the performance impact, consider using the caching\nframework within your Sitemap subclass.
Versions of Python-Markdown earlier than 2.1 do not support the option to\ndisable attributes. As a security issue, earlier versions of this library will\nnot be supported by the markup contrib app in 1.5 under an accelerated\ndeprecation timeline.
\n