PageRenderTime 280ms CodeModel.GetById 256ms RepoModel.GetById 0ms app.codeStats 1ms

Plain Text | 578 lines | 429 code | 149 blank | 0 comment | 0 complexity | c7441bc9e06cfe957858dfee8237cc5b MD5 | raw file
Possible License(s): BSD-3-Clause
  1. ================================
  2. Django 1.2 alpha 1 release notes
  3. ================================
  4. January 5, 2010
  5. Welcome to Django 1.2 alpha 1!
  6. This is the first in a series of preview/development releases leading up to the
  7. eventual release of Django 1.2, currently scheduled to take place in March 2010.
  8. This release is primarily targeted at developers who are interested in trying
  9. out new features and testing the Django codebase to help identify and resolve
  10. bugs prior to the final 1.2 release.
  11. As such, this release is *not* intended for production use, and any such use is
  12. discouraged.
  13. Backwards-incompatible changes in 1.2
  14. =====================================
  15. CSRF Protection
  16. ---------------
  17. There have been large changes to the way that CSRF protection works, detailed in
  18. :doc:`the CSRF documentaton </ref/contrib/csrf>`. The following are the major
  19. changes that developers must be aware of:
  20. * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated, and
  21. **will be removed completely in Django 1.4**, in favor of a template tag that
  22. should be inserted into forms.
  23. * All contrib apps use a ``csrf_protect`` decorator to protect the view. This
  24. requires the use of the ``csrf_token`` template tag in the template, so if you
  25. have used custom templates for contrib views, you MUST READ THE :ref:`UPGRADE
  26. INSTRUCTIONS <ref-csrf-upgrading-notes>` to fix those templates.
  27. * ``CsrfViewMiddleware`` is included in :setting:`MIDDLEWARE_CLASSES` by
  28. default. This turns on CSRF protection by default, so that views that accept
  29. POST requests need to be written to work with the middleware. Instructions
  30. on how to do this are found in the CSRF docs.
  31. * CSRF-related code has moved from ``contrib`` to ``core`` (with
  32. backwards compatible imports in the old locations, which are
  33. deprecated).
  34. :ttag:`if` tag changes
  35. ----------------------
  36. Due to new features in the :ttag:`if` template tag, it no longer accepts 'and',
  37. 'or' and 'not' as valid **variable** names. Previously that worked in some
  38. cases even though these strings were normally treated as keywords. Now, the
  39. keyword status is always enforced, and template code like ``{% if not %}`` or
  40. ``{% if and %}`` will throw a TemplateSyntaxError.
  41. ``LazyObject``
  42. --------------
  43. ``LazyObject`` is an undocumented utility class used for lazily wrapping other
  44. objects of unknown type. In Django 1.1 and earlier, it handled introspection in
  45. a non-standard way, depending on wrapped objects implementing a public method
  46. ``get_all_members()``. Since this could easily lead to name clashes, it has been
  47. changed to use the standard method, involving ``__members__`` and ``__dir__()``.
  48. If you used ``LazyObject`` in your own code, and implemented the
  49. ``get_all_members()`` method for wrapped objects, you need to make the following
  50. changes:
  51. * If your class does not have special requirements for introspection (i.e. you
  52. have not implemented ``__getattr__()`` or other methods that allow for
  53. attributes not discoverable by normal mechanisms), you can simply remove the
  54. ``get_all_members()`` method. The default implementation on ``LazyObject``
  55. will do the right thing.
  56. * If you have more complex requirements for introspection, first rename the
  57. ``get_all_members()`` method to ``__dir__()``. This is the standard method,
  58. from Python 2.6 onwards, for supporting introspection. If you are require
  59. support for Python < 2.6, add the following code to the class::
  60. __members__ = property(lambda self: self.__dir__())
  61. ``__dict__`` on Model instances
  62. -------------------------------
  63. Historically, the ``__dict__`` attribute of a model instance has only contained
  64. attributes corresponding to the fields on a model.
  65. In order to support multiple database configurations, Django 1.2 has
  66. added a ``_state`` attribute to object instances. This attribute will
  67. appear in ``__dict__`` for a model instance. If your code relies on
  68. iterating over __dict__ to obtain a list of fields, you must now
  69. filter the ``_state`` attribute of out ``__dict__``.
  70. ``get_db_prep_*()`` methods on Field
  71. ------------------------------------
  72. Prior to v1.2, a custom field had the option of defining several
  73. functions to support conversion of Python values into
  74. database-compatible values. A custom field might look something like::
  75. class CustomModelField(models.Field):
  76. # ...
  77. def get_db_prep_save(self, value):
  78. # ...
  79. def get_db_prep_value(self, value):
  80. # ...
  81. def get_db_prep_lookup(self, lookup_type, value):
  82. # ...
  83. In 1.2, these three methods have undergone a change in prototype, and
  84. two extra methods have been introduced::
  85. class CustomModelField(models.Field):
  86. # ...
  87. def get_prep_value(self, value):
  88. # ...
  89. def get_prep_lookup(self, lookup_type, value):
  90. # ...
  91. def get_db_prep_save(self, value, connection):
  92. # ...
  93. def get_db_prep_value(self, value, connection, prepared=False):
  94. # ...
  95. def get_db_prep_lookup(self, lookup_type, value, connection, prepared=False):
  96. # ...
  97. These changes are required to support multiple databases:
  98. ``get_db_prep_*`` can no longer make any assumptions regarding the
  99. database for which it is preparing. The ``connection`` argument now
  100. provides the preparation methods with the specific connection for
  101. which the value is being prepared.
  102. The two new methods exist to differentiate general data preparation
  103. requirements, and requirements that are database-specific. The
  104. ``prepared`` argument is used to indicate to the database preparation
  105. methods whether generic value preparation has been performed. If
  106. an unprepared (i.e., ``prepared=False``) value is provided to the
  107. ``get_db_prep_*()`` calls, they should invoke the corresponding
  108. ``get_prep_*()`` calls to perform generic data preparation.
  109. Conversion functions has been provided which will transparently
  110. convert functions adhering to the old prototype into functions
  111. compatible with the new prototype. However, this conversion function
  112. will be removed in Django 1.4, so you should upgrade your Field
  113. definitions to use the new prototype.
  114. If your ``get_db_prep_*()`` methods made no use of the database
  115. connection, you should be able to upgrade by renaming
  116. ``get_db_prep_value()`` to ``get_prep_value()`` and
  117. ``get_db_prep_lookup()`` to ``get_prep_lookup()`. If you require
  118. database specific conversions, then you will need to provide an
  119. implementation ``get_db_prep_*`` that uses the ``connection``
  120. argument to resolve database-specific values.
  121. Stateful template tags
  122. ----------------------
  123. Template tags that store rendering state on the node itself may experience
  124. problems if they are used with the new :ref:`cached
  125. template loader<template-loaders>`.
  126. All of the built-in Django template tags are safe to use with the cached
  127. loader, but if you're using custom template tags that come from third
  128. party packages, or that you wrote yourself, you should ensure that the
  129. ``Node`` implementation for each tag is thread-safe. For more
  130. information, see
  131. :ref:`template tag thread safety considerations<template_tag_thread_safety>`.
  132. Test runner exit status code
  133. ----------------------------
  134. The exit status code of the test runners (``tests/`` and ``python
  135. test``) no longer represents the number of failed tests, since a
  136. failure of 256 or more tests resulted in a wrong exit status code. The exit
  137. status code for the test runner is now 0 for success (no failing tests) and 1
  138. for any number of test failures. If needed, the number of test failures can be
  139. found at the end of the test runner's output.
  140. Features deprecated in 1.2
  141. ==========================
  142. CSRF response rewriting middleware
  143. ----------------------------------
  144. ``CsrfResponseMiddleware``, the middleware that automatically inserted CSRF
  145. tokens into POST forms in outgoing pages, has been deprecated in favor of a
  146. template tag method (see above), and will be removed completely in Django
  147. 1.4. ``CsrfMiddleware``, which includes the functionality of
  148. ``CsrfResponseMiddleware`` and ``CsrfViewMiddleware`` has likewise been
  149. deprecated.
  150. Also, the CSRF module has moved from contrib to core, and the old imports are
  151. deprecated, as described in the :ref:`upgrading notes <ref-csrf-upgrading-notes>`.
  152. ``SMTPConnection``
  153. ------------------
  154. The ``SMTPConnection`` class has been deprecated in favor of a generic
  155. E-mail backend API. Old code that explicitly instantiated an instance
  156. of an SMTPConnection::
  157. from django.core.mail import SMTPConnection
  158. connection = SMTPConnection()
  159. messages = get_notification_email()
  160. connection.send_messages(messages)
  161. should now call :meth:`~django.core.mail.get_connection()` to
  162. instantiate a generic e-mail connection::
  163. from django.core.mail import get_connection
  164. connection = get_connection()
  165. messages = get_notification_email()
  166. connection.send_messages(messages)
  167. Depending on the value of the :setting:`EMAIL_BACKEND` setting, this
  168. may not return an SMTP connection. If you explicitly require an SMTP
  169. connection with which to send e-mail, you can explicitly request an
  170. SMTP connection::
  171. from django.core.mail import get_connection
  172. connection = get_connection('django.core.mail.backends.smtp.EmailBackend')
  173. messages = get_notification_email()
  174. connection.send_messages(messages)
  175. If your call to construct an instance of ``SMTPConnection`` required
  176. additional arguments, those arguments can be passed to the
  177. :meth:`~django.core.mail.get_connection()` call::
  178. connection = get_connection('django.core.mail.backends.smtp.EmailBackend', hostname='localhost', port=1234)
  179. Specifying databases
  180. --------------------
  181. Prior to Django 1.1, Django used a number of settings to control access to a
  182. single database. Django 1.2 introduces support for multiple databases, and as
  183. a result, the way you define database settings has changed.
  184. **Any existing Django settings file will continue to work as expected
  185. until Django 1.4.** Old-style database settings will be automatically
  186. translated to the new-style format.
  187. In the old-style (pre 1.2) format, there were a number of
  188. ``DATABASE_`` settings at the top level of your settings file. For
  189. example::
  190. DATABASE_NAME = 'test_db'
  191. DATABASE_ENGINE = 'postgresql_psycopg2'
  192. DATABASE_USER = 'myusername'
  193. DATABASE_PASSWORD = 's3krit'
  194. These settings are now contained inside a dictionary named
  195. :setting:`DATABASES`. Each item in the dictionary corresponds to a
  196. single database connection, with the name ``'default'`` describing the
  197. default database connection. The setting names have also been
  198. shortened to reflect the fact that they are stored in a dictionary.
  199. The sample settings given previously would now be stored using::
  200. DATABASES = {
  201. 'default': {
  202. 'NAME': 'test_db',
  203. 'ENGINE': 'django.db.backends.postgresql_psycopg2',
  204. 'USER': 'myusername',
  205. 'PASSWORD': 's3krit',
  206. }
  207. }
  208. This affects the following settings:
  209. ========================================= ==========================
  210. Old setting New Setting
  211. ========================================= ==========================
  212. :setting:`DATABASE_ENGINE` :setting:`ENGINE`
  213. :setting:`DATABASE_HOST` :setting:`HOST`
  214. :setting:`DATABASE_NAME` :setting:`NAME`
  215. :setting:`DATABASE_OPTIONS` :setting:`OPTIONS`
  216. :setting:`DATABASE_PASSWORD` :setting:`PASSWORD`
  217. :setting:`DATABASE_PORT` :setting:`PORT`
  218. :setting:`DATABASE_USER` :setting:`USER`
  219. :setting:`TEST_DATABASE_CHARSET` :setting:`TEST_CHARSET`
  221. :setting:`TEST_DATABASE_NAME` :setting:`TEST_NAME`
  222. ========================================= ==========================
  223. These changes are also required if you have manually created a database
  224. connection using ``DatabaseWrapper()`` from your database backend of choice.
  225. In addition to the change in structure, Django 1.2 removes the special
  226. handling for the built-in database backends. All database backends
  227. must now be specified by a fully qualified module name (i.e.,
  228. ``django.db.backends.postgresql_psycopg2``, rather than just
  229. ``postgresql_psycopg2``).
  230. User Messages API
  231. -----------------
  232. The API for storing messages in the user ``Message`` model (via
  233. ``user.message_set.create``) is now deprecated and will be removed in Django
  234. 1.4 according to the standard :doc:`release process </internals/release-process>`.
  235. To upgrade your code, you need to replace any instances of::
  236. user.message_set.create('a message')
  237. with the following::
  238. from django.contrib import messages
  239. messages.add_message(request, messages.INFO, 'a message')
  240. Additionally, if you make use of the method, you need to replace the
  241. following::
  242. for message in user.get_and_delete_messages():
  243. ...
  244. with::
  245. from django.contrib import messages
  246. for message in messages.get_messages(request):
  247. ...
  248. For more information, see the full
  249. :doc:`messages documentation </ref/contrib/messages>`. You should begin to
  250. update your code to use the new API immediately.
  251. Date format helper functions
  252. ----------------------------
  253. ``django.utils.translation.get_date_formats()`` and
  254. ``django.utils.translation.get_partial_date_formats()`` have been deprecated
  255. in favor of the appropriate calls to ``django.utils.formats.get_format()``
  256. which is locale aware when :setting:`USE_L10N` is set to ``True``, and falls
  257. back to default settings if set to ``False``.
  258. To get the different date formats, instead of writing::
  259. from django.utils.translation import get_date_formats
  260. date_format, datetime_format, time_format = get_date_formats()
  261. use::
  262. from django.utils import formats
  263. date_format = formats.get_format('DATE_FORMAT')
  264. datetime_format = formats.get_format('DATETIME_FORMAT')
  265. time_format = formats.get_format('TIME_FORMAT')
  266. or, when directly formatting a date value::
  267. from django.utils import formats
  268. value_formatted = formats.date_format(value, 'DATETIME_FORMAT')
  269. The same applies to the globals found in ``django.forms.fields``:
  273. Use ``django.utils.formats.get_format()`` to get the appropriate formats.
  274. What's new in Django 1.2 alpha 1
  275. ================================
  276. The following new features are present as of this alpha release; this
  277. release also marks the end of major feature development for the 1.2
  278. release cycle. Some minor features will continue development until the
  279. 1.2 beta release, however.
  280. CSRF support
  281. ------------
  282. Django now has much improved protection against :doc:`Cross-Site
  283. Request Forgery (CSRF) attacks</ref/contrib/csrf>`. This type of attack
  284. occurs when a malicious Web site contains a link, a form button or
  285. some javascript that is intended to perform some action on your Web
  286. site, using the credentials of a logged-in user who visits the
  287. malicious site in their browser. A related type of attack, 'login
  288. CSRF', where an attacking site tricks a user's browser into logging
  289. into a site with someone else's credentials, is also covered.
  290. E-mail Backends
  291. ---------------
  292. You can now :ref:`configure the way that Django sends e-mail
  293. <topic-email-backends>`. Instead of using SMTP to send all e-mail, you
  294. can now choose a configurable e-mail backend to send messages. If your
  295. hosting provider uses a sandbox or some other non-SMTP technique for
  296. sending mail, you can now construct an e-mail backend that will allow
  297. Django's standard :doc:`mail sending methods</topics/email>` to use
  298. those facilities.
  299. This also makes it easier to debug mail sending - Django ships with
  300. backend implementations that allow you to send e-mail to a
  301. :ref:`file<topic-email-file-backend>`, to the
  302. :ref:`console<topic-email-console-backend>`, or to
  303. :ref:`memory<topic-email-memory-backend>` - you can even configure all
  304. e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.
  305. Messages Framework
  306. ------------------
  307. Django now includes a robust and configurable :doc:`messages framework
  308. </ref/contrib/messages>` with built-in support for cookie- and session-based
  309. messaging, for both anonymous and authenticated clients. The messages framework
  310. replaces the deprecated user message API and allows you to temporarily store
  311. messages in one request and retrieve them for display in a subsequent request
  312. (usually the next one).
  313. Support for multiple databases
  314. ------------------------------
  315. Django 1.2 adds the ability to use :doc:`more than one database
  316. </topics/db/multi-db>` in your Django project. Queries can be
  317. issued at a specific database with the `using()` method on
  318. querysets; individual objects can be saved to a specific database
  319. by providing a ``using`` argument when you save the instance.
  320. 'Smart' if tag
  321. --------------
  322. The :ttag:`if` tag has been upgraded to be much more powerful. First, support
  323. for comparison operators has been added. No longer will you have to type:
  324. .. code-block:: html+django
  325. {% ifnotequal a b %}
  326. ...
  327. {% endifnotequal %}
  328. you can now do:
  329. .. code-block:: html+django
  330. {% if a != b %}
  331. ...
  332. {% endif %}
  333. The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=`` and
  334. ``in``, all of which work like the Python operators, in addition to ``and``,
  335. ``or`` and ``not`` which were already supported.
  336. Also, filters may now be used in the ``if`` expression. For example:
  337. .. code-block:: html+django
  338. <div
  339. {% if|lower == message.recipient|lower %}
  340. class="highlight"
  341. {% endif %}
  342. >{{ message }}</div>
  343. Template caching
  344. ----------------
  345. In previous versions of Django, every time you rendered a template it
  346. would be reloaded from disk. In Django 1.2, you can use a :ref:`cached
  347. template loader <template-loaders>` to load templates once, then use
  348. the cached result for every subsequent render. This can lead to a
  349. significant performance improvement if your templates are broken into
  350. lots of smaller subtemplates (using the ``{% extends %}`` or ``{%
  351. include %}`` tags).
  352. As a side effect, it is now much easier to support non-Django template
  353. languages. For more details, see the :ref:`notes on supporting
  354. non-Django template languages<topic-template-alternate-language>`.
  355. Natural keys in fixtures
  356. ------------------------
  357. Fixtures can refer to remote objects using
  358. :ref:`topics-serialization-natural-keys`. This lookup scheme is an
  359. alternative to the normal primary-key based object references in a
  360. fixture, improving readability, and resolving problems referring to
  361. objects whose primary key value may not be predictable or known.
  362. ``BigIntegerField``
  363. -------------------
  364. Models can now use a 64 bit :class:`~django.db.models.BigIntegerField` type.
  365. Fast Failure for Tests
  366. ----------------------
  367. The :djadmin:`test` subcommand of ````, and the ````
  368. script used to run Django's own test suite, support a new ``--failfast`` option.
  369. When specified, this option causes the test runner to exit after encountering
  370. a failure instead of continuing with the test run. In addition, the handling
  371. of ``Ctrl-C`` during a test run has been improved to trigger a graceful exit
  372. from the test run that reports details of the tests run before the interruption.
  373. Improved localization
  374. ---------------------
  375. Django's :doc:`internationalization framework </topics/i18n/index>` has been
  376. expanded by locale aware formatting and form processing. That means, if
  377. enabled, dates and numbers on templates will be displayed using the format
  378. specified for the current locale. Django will also use localized formats
  379. when parsing data in forms.
  380. See :ref:`Format localization <format-localization>` for more details.
  381. Added ``readonly_fields`` to ``ModelAdmin``
  382. -------------------------------------------
  383. :attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to
  384. enable non-editable fields in add/change pages for models and inlines. Field
  385. and calculated values can be displayed along side editable fields.
  386. Customizable syntax highlighting
  387. --------------------------------
  388. You can now use the ``DJANGO_COLORS`` environment variable to modify
  389. or disable the colors used by ```` to provide
  390. :ref:`syntax highlighting <syntax-coloring>`.
  391. The Django 1.2 roadmap
  392. ======================
  393. Before the final Django 1.2 release, several other preview/development
  394. releases will be made available. The current schedule consists of at
  395. least the following:
  396. * Week of **January 26, 2010**: First Django 1.2 beta release. Final
  397. feature freeze for Django 1.2.
  398. * Week of **March 2, 2010**: First Django 1.2 release
  399. candidate. String freeze for translations.
  400. * Week of **March 9, 2010**: Django 1.2 final release.
  401. If necessary, additional alpha, beta or release-candidate packages
  402. will be issued prior to the final 1.2 release. Django 1.2 will be
  403. released approximately one week after the final release candidate.
  404. What you can do to help
  405. =======================
  406. In order to provide a high-quality 1.2 release, we need your help. Although this
  407. alpha release is, again, *not* intended for production use, you can help the
  408. Django team by trying out the alpha codebase in a safe test environment and
  409. reporting any bugs or issues you encounter. The Django ticket tracker is the
  410. central place to search for open issues:
  411. *
  412. Please open new tickets if no existing ticket corresponds to a problem you're
  413. running into.
  414. Additionally, discussion of Django development, including progress toward the
  415. 1.2 release, takes place daily on the django-developers mailing list:
  416. *
  417. ... and in the ``#django-dev`` IRC channel on ````. If you're
  418. interested in helping out with Django's development, feel free to join the
  419. discussions there.
  420. Django's online documentation also includes pointers on how to contribute to
  421. Django:
  422. * :doc:`How to contribute to Django </internals/contributing>`
  423. Contributions on any level -- developing code, writing documentation or simply
  424. triaging tickets and helping to test proposed bugfixes -- are always welcome and
  425. appreciated.
  426. Development sprints for Django 1.2 will also be taking place at PyCon
  427. US 2010, on the dedicated sprint days (February 22 through 25), and
  428. anyone who wants to help out is welcome to join in, either in person
  429. at PyCon or virtually in the IRC channel or on the mailing list.