PageRenderTime 147ms CodeModel.GetById 101ms app.highlight 4ms RepoModel.GetById 36ms app.codeStats 0ms

/docs/releases/1.2-alpha-1.txt

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