diff --git a/docs/releases/1.2-alpha-1.txt b/docs/releases/1.2-alpha-1.txt new file mode 100644 index 0000000000..60c33e56f5 --- /dev/null +++ b/docs/releases/1.2-alpha-1.txt @@ -0,0 +1,582 @@ +.. _releases-1.2-alpha-1: + +================================ +Django 1.2 alpha 1 release notes +================================ + +January 5, 2010 + +Welcome to Django 1.2 alpha 1! + +This is the first in a series of preview/development releases leading up to the +eventual release of Django 1.2, currently scheduled to take place in March 2010. +This release is primarily targeted at developers who are interested in trying +out new features and testing the Django codebase to help identify and resolve +bugs prior to the final 1.2 release. + +As such, this release is *not* intended for production use, and any such use is +discouraged. + + +Backwards-incompatible changes in 1.2 +===================================== + +CSRF Protection +--------------- + +There have been large changes to the way that CSRF protection works, detailed in +:ref:`the CSRF documentaton `. The following are the major +changes that developers must be aware of: + + * ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` have been deprecated, and + **will be removed completely in Django 1.4**, in favor of a template tag that + should be inserted into forms. + + * All contrib apps use a ``csrf_protect`` decorator to protect the view. This + requires the use of the ``csrf_token`` template tag in the template, so if you + have used custom templates for contrib views, you MUST READ THE :ref:`UPGRADE + INSTRUCTIONS ` to fix those templates. + + * ``CsrfViewMiddleware`` is included in :setting:`MIDDLEWARE_CLASSES` by + default. This turns on CSRF protection by default, so that views that accept + POST requests need to be written to work with the middleware. Instructions + on how to do this are found in the CSRF docs. + + * CSRF-related code has moved from ``contrib`` to ``core`` (with + backwards compatible imports in the old locations, which are + deprecated). + +:ttag:`if` tag changes +---------------------- + +Due to new features in the :ttag:`if` template tag, it no longer accepts 'and', +'or' and 'not' as valid **variable** names. Previously that worked in some +cases even though these strings were normally treated as keywords. Now, the +keyword status is always enforced, and template code like ``{% if not %}`` or +``{% if and %}`` will throw a TemplateSyntaxError. + +``LazyObject`` +-------------- + +``LazyObject`` is an undocumented utility class used for lazily wrapping other +objects of unknown type. In Django 1.1 and earlier, it handled introspection in +a non-standard way, depending on wrapped objects implementing a public method +``get_all_members()``. Since this could easily lead to name clashes, it has been +changed to use the standard method, involving ``__members__`` and ``__dir__()``. +If you used ``LazyObject`` in your own code, and implemented the +``get_all_members()`` method for wrapped objects, you need to make the following +changes: + + * If your class does not have special requirements for introspection (i.e. you + have not implemented ``__getattr__()`` or other methods that allow for + attributes not discoverable by normal mechanisms), you can simply remove the + ``get_all_members()`` method. The default implementation on ``LazyObject`` + will do the right thing. + + * If you have more complex requirements for introspection, first rename the + ``get_all_members()`` method to ``__dir__()``. This is the standard method, + from Python 2.6 onwards, for supporting introspection. If you are require + support for Python < 2.6, add the following code to the class:: + + __members__ = property(lambda self: self.__dir__()) + +Specifying databases +-------------------- + +Prior to Django 1.1, Django used a number of settings to control access to a +single database. Django 1.2 introduces support for multiple databases, and as +a result, the way you define database settings has changed. + +**Any existing Django settings file will continue to work as expected +until Django 1.4.** Old-style database settings will be automatically +translated to the new-style format. + +In the old-style (pre 1.2) format, there were a number of +``DATABASE_`` settings at the top level of your settings file. For +example:: + + DATABASE_NAME = 'test_db' + DATABASE_BACKEND = 'postgresl_psycopg2' + DATABASE_USER = 'myusername' + DATABASE_PASSWORD = 's3krit' + +These settings are now contained inside a dictionary named +:setting:`DATABASES`. Each item in the dictionary corresponds to a +single database connection, with the name ``'default'`` describing the +default database connection. The setting names have also been +shortened to reflect the fact that they are stored in a dictionary. +The sample settings given previously would now be stored using:: + + DATABASES = { + 'default': { + 'NAME': 'test_db', + 'BACKEND': 'django.db.backends.postgresl_psycopg2', + 'USER': 'myusername', + 'PASSWORD': 's3krit', + } + } + +This affects the following settings: + + ========================================= ========================== + Old setting New Setting + ========================================= ========================== + :setting:`DATABASE_ENGINE` :setting:`ENGINE` + :setting:`DATABASE_HOST` :setting:`HOST` + :setting:`DATABASE_NAME` :setting:`NAME` + :setting:`DATABASE_OPTIONS` :setting:`OPTIONS` + :setting:`DATABASE_PASSWORD` :setting:`PASSWORD` + :setting:`DATABASE_PORT` :setting:`PORT` + :setting:`DATABASE_USER` :setting:`USER` + :setting:`TEST_DATABASE_CHARSET` :setting:`TEST_CHARSET` + :setting:`TEST_DATABASE_COLLATION` :setting:`TEST_COLLATION` + :setting:`TEST_DATABASE_NAME` :setting:`TEST_NAME` + ========================================= ========================== + +These changes are also required if you have manually created a database +connection using ``DatabaseWrapper()`` from your database backend of choice. + +In addition to the change in structure, Django 1.2 removes the special +handling for the built-in database backends. All database backends +must now be specified by a fully qualified module name (i.e., +``django.db.backends.postgresql_psycopg2``, rather than just +``postgresql_psycopg2``). + +``__dict__`` on Model instances +------------------------------- + +Historically, the ``__dict__`` attribute of a model instance has only contained +attributes corresponding to the fields on a model. + +In order to support multiple database configurations, Django 1.2 has +added a ``_state`` attribute to object instances. This attribute will +appear in ``__dict__`` for a model instance. If your code relies on +iterating over __dict__ to obtain a list of fields, you must now +filter the ``_state`` attribute of out ``__dict__``. + +``get_db_prep_*()`` methods on Field +------------------------------------ + +Prior to v1.2, a custom field had the option of defining several +functions to support conversion of Python values into +database-compatible values. A custom field might look something like:: + + class CustomModelField(models.Field): + # ... + + def get_db_prep_save(self, value): + # ... + + def get_db_prep_value(self, value): + # ... + + def get_db_prep_lookup(self, lookup_type, value): + # ... + +In 1.2, these three methods have undergone a change in prototype, and +two extra methods have been introduced:: + + class CustomModelField(models.Field): + # ... + + def get_prep_value(self, value): + # ... + + def get_prep_lookup(self, lookup_type, value): + # ... + + def get_db_prep_save(self, value, connection): + # ... + + def get_db_prep_value(self, value, connection, prepared=False): + # ... + + def get_db_prep_lookup(self, lookup_type, value, connection, prepared=False): + # ... + +These changes are required to support multiple databases: +``get_db_prep_*`` can no longer make any assumptions regarding the +database for which it is preparing. The ``connection`` argument now +provides the preparation methods with the specific connection for +which the value is being prepared. + +The two new methods exist to differentiate general data preparation +requirements, and requirements that are database-specific. The +``prepared`` argument is used to indicate to the database preparation +methods whether generic value preparation has been performed. If +an unprepared (i.e., ``prepared=False``) value is provided to the +``get_db_prep_*()`` calls, they should invoke the corresponding +``get_prep_*()`` calls to perform generic data preparation. + +Conversion functions has been provided which will transparently +convert functions adhering to the old prototype into functions +compatible with the new prototype. However, this conversion function +will be removed in Django 1.4, so you should upgrade your Field +definitions to use the new prototype. + +If your ``get_db_prep_*()`` methods made no use of the database +connection, you should be able to upgrade by renaming +``get_db_prep_value()`` to ``get_prep_value()`` and +``get_db_prep_lookup()`` to ``get_prep_lookup()`. If you require +database specific conversions, then you will need to provide an +implementation ``get_db_prep_*`` that uses the ``connection`` +argument to resolve database-specific values. + +Stateful template tags +---------------------- + +Template tags that store rendering state on the node itself may experience +problems if they are used with the new :ref:`cached +template loader`. + +All of the built-in Django template tags are safe to use with the cached +loader, but if you're using custom template tags that come from third +party packages, or that you wrote yourself, you should ensure that the +``Node`` implementation for each tag is thread-safe. For more +information, see +:ref:`template tag thread safety considerations`. + +Test runner exit status code +---------------------------- + +The exit status code of the test runners (``tests/runtests.py`` and ``python +manage.py test``) no longer represents the number of failed tests, since a +failure of 256 or more tests resulted in a wrong exit status code. The exit +status code for the test runner is now 0 for success (no failing tests) and 1 +for any number of test failures. If needed, the number of test failures can be +found at the end of the test runner's output. + +.. _deprecated-features-1.2: + +Features deprecated in 1.2 +========================== + +CSRF response rewriting middleware +---------------------------------- + +``CsrfResponseMiddleware``, the middleware that automatically inserted CSRF +tokens into POST forms in outgoing pages, has been deprecated in favor of a +template tag method (see above), and will be removed completely in Django +1.4. ``CsrfMiddleware``, which includes the functionality of +``CsrfResponseMiddleware`` and ``CsrfViewMiddleware`` has likewise been +deprecated. + +Also, the CSRF module has moved from contrib to core, and the old imports are +deprecated, as described in the :ref:`upgrading notes `. + +``SMTPConnection`` +------------------ + +The ``SMTPConnection`` class has been deprecated in favor of a generic +E-mail backend API. Old code that explicitly instantiated an instance +of an SMTPConnection:: + + from django.core.mail import SMTPConnection + connection = SMTPConnection() + messages = get_notification_email() + connection.send_messages(messages) + +should now call :meth:`~django.core.mail.get_connection()` to +instantiate a generic e-mail connection:: + + from django.core.mail import get_connection + connection = get_connection() + messages = get_notification_email() + connection.send_messages(messages) + +Depending on the value of the :setting:`EMAIL_BACKEND` setting, this +may not return an SMTP connection. If you explicitly require an SMTP +connection with which to send e-mail, you can explicitly request an +SMTP connection:: + + from django.core.mail import get_connection + connection = get_connection('django.core.mail.backends.smtp.EmailBackend') + messages = get_notification_email() + connection.send_messages(messages) + +If your call to construct an instance of ``SMTPConnection`` required +additional arguments, those arguments can be passed to the +:meth:`~django.core.mail.get_connection()` call:: + + connection = get_connection('django.core.mail.backends.smtp.EmailBackend', hostname='localhost', port=1234) + +User Messages API +----------------- + +The API for storing messages in the user ``Message`` model (via +``user.message_set.create``) is now deprecated and will be removed in Django +1.4 according to the standard :ref:`release process `. + +To upgrade your code, you need to replace any instances of:: + + user.message_set.create('a message') + +with the following:: + + from django.contrib import messages + messages.add_message(request, messages.INFO, 'a message') + +Additionally, if you make use of the method, you need to replace the +following:: + + for message in user.get_and_delete_messages(): + ... + +with:: + + from django.contrib import messages + for message in messages.get_messages(request): + ... + +For more information, see the full +:ref:`messages documentation `. You should begin to +update your code to use the new API immediately. + +Date format helper functions +---------------------------- + +``django.utils.translation.get_date_formats()`` and +``django.utils.translation.get_partial_date_formats()`` have been deprecated +in favor of the appropriate calls to ``django.utils.formats.get_format()`` +which is locale aware when :setting:`USE_L10N` is set to ``True``, and falls +back to default settings if set to ``False``. + +To get the different date formats, instead of writing:: + + from django.utils.translation import get_date_formats + date_format, datetime_format, time_format = get_date_formats() + +use:: + + from django.utils import formats + + date_format = formats.get_format('DATE_FORMAT') + datetime_format = formats.get_format('DATETIME_FORMAT') + time_format = formats.get_format('TIME_FORMAT') + +or, when directly formatting a date value:: + + from django.utils import formats + value_formatted = formats.date_format(value, 'DATETIME_FORMAT') + +The same applies to the globals found in ``django.forms.fields``: + + * ``DEFAULT_DATE_INPUT_FORMATS`` + * ``DEFAULT_TIME_INPUT_FORMATS`` + * ``DEFAULT_DATETIME_INPUT_FORMATS`` + +Use ``django.utils.formats.get_format()`` to get the appropriate formats. + + +What's new in Django 1.2 alpha 1 +================================ + +The following new features are present as of this alpha release; this +release also marks the end of major feature development for the 1.2 +release cycle. Some minor features will continue development until the +1.2 beta release, however. + + +CSRF support +------------ + +Django now has much improved protection against :ref:`Cross-Site +Request Forgery (CSRF) attacks`. This type of attack +occurs when a malicious Web site contains a link, a form button or +some javascript that is intended to perform some action on your Web +site, using the credentials of a logged-in user who visits the +malicious site in their browser. A related type of attack, 'login +CSRF', where an attacking site tricks a user's browser into logging +into a site with someone else's credentials, is also covered. + +E-mail Backends +--------------- + +You can now :ref:`configure the way that Django sends e-mail +`. Instead of using SMTP to send all e-mail, you +can now choose a configurable e-mail backend to send messages. If your +hosting provider uses a sandbox or some other non-SMTP technique for +sending mail, you can now construct an e-mail backend that will allow +Django's standard :ref:`mail sending methods` to use +those facilities. + +This also makes it easier to debug mail sending - Django ships with +backend implementations that allow you to send e-mail to a +:ref:`file`, to the +:ref:`console`, or to +:ref:`memory` - you can even configure all +e-mail to be :ref:`thrown away`. + +Messages Framework +------------------ + +Django now includes a robust and configurable :ref:`messages framework +` with built-in support for cookie- and session-based +messaging, for both anonymous and authenticated clients. The messages framework +replaces the deprecated user message API and allows you to temporarily store +messages in one request and retrieve them for display in a subsequent request +(usually the next one). + +Support for multiple databases +------------------------------ + +Django 1.2 adds the ability to use :ref:`more than one database +` in your Django project. Queries can be +issued at a specific database with the `using()` method on +querysets; individual objects can be saved to a specific database +by providing a ``using`` argument when you save the instance. + +'Smart' if tag +-------------- + +The :ttag:`if` tag has been upgraded to be much more powerful. First, support +for comparison operators has been added. No longer will you have to type: + +.. code-block:: html+django + + {% ifnotequal a b %} + ... + {% endifnotequal %} + +...as you can now do: + +.. code-block:: html+django + + {% if a != b %} + ... + {% endif %} + +The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=`` and +``in``, all of which work like the Python operators, in addition to ``and``, +``or`` and ``not`` which were already supported. + +Also, filters may now be used in the ``if`` expression. For example: + +.. code-block:: html+django + +
{{ message }}
+ +Template caching +---------------- + +In previous versions of Django, every time you rendered a template it +would be reloaded from disk. In Django 1.2, you can use a :ref:`cached +template loader ` to load templates once, then use a +cached the result for every subsequent render. This can lead to a +significant performance improvement if your templates are broken into +lots of smaller subtemplates (using the ``{% extends %}`` or ``{% +include %}`` tags). + +As a side effect, it is now much easier to support non-Django template +languages. For more details, see the :ref:`notes on supporting +non-Django template languages`. + +Natural keys in fixtures +------------------------ + +Fixtures can refer to remote objects using +:ref:`topics-serialization-natural-keys`. This lookup scheme is an +alternative to the normal primary-key based object references in a +fixture, improving readability, and resolving problems referring to +objects whose primary key value may not be predictable or known. + +``BigIntegerField`` +------------------- + +Models can now use a 64 bit :class:`~django.db.models.BigIntegerField` type. + +Fast Failure for Tests +---------------------- + +The :djadmin:`test` subcommand of ``django-admin.py``, and the ``runtests.py`` +script used to run Django's own test suite, support a new ``--failfast`` option. +When specified, this option causes the test runner to exit after encountering +a failure instead of continuing with the test run. In addition, the handling +of ``Ctrl-C`` during a test run has been improved to trigger a graceful exit +from the test run that reports details of the tests run before the interruption. + +Improved localization +--------------------- + +Django's :ref:`internationalization framework ` has been +expanded by locale aware formatting and form processing. That means, if +enabled, dates and numbers on templates will be displayed using the format +specified for the current locale. Django will also use localized formats +when parsing data in forms. +See :ref:`Format localization ` for more details. + +Added ``readonly_fields`` to ``ModelAdmin`` +------------------------------------------- + +:attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to +enable non-editable fields in add/change pages for models and inlines. Field +and calculated values can be displayed along side editable fields. + +Customizable syntax highlighting +-------------------------------- + +You can now use the ``DJANGO_COLORS`` environment variable to modify +or disable the colors used by ``django-admin.py`` to provide +:ref:`syntax highlighting `. + + +The Django 1.2 roadmap +====================== + +Before the final Django 1.2 release, several other preview/development +releases will be made available. The current schedule consists of at +least the following: + +* Week of **January 26, 2010**: First Django 1.2 beta release. Final + feature freeze for Django 1.2. + +* Week of **March 2, 2010**: First Django 1.2 release + candidate. String freeze for translations. + +* Week of **March 9, 2010**: Django 1.2 final release. + +If necessary, additional alpha, beta or release-candidate packages +will be issued prior to the final 1.2 release. Django 1.2 will be +released approximately one week after the final release candidate. + + +What you can do to help +======================= + +In order to provide a high-quality 1.2 release, we need your help. Although this +alpha release is, again, *not* intended for production use, you can help the +Django team by trying out the alpha codebase in a safe test environment and +reporting any bugs or issues you encounter. The Django ticket tracker is the +central place to search for open issues: + + * http://code.djangoproject.com/timeline + +Please open new tickets if no existing ticket corresponds to a problem you're +running into. + +Additionally, discussion of Django development, including progress toward the +1.2 release, takes place daily on the django-developers mailing list: + + * http://groups.google.com/group/django-developers + +... and in the ``#django-dev`` IRC channel on ``irc.freenode.net``. If you're +interested in helping out with Django's development, feel free to join the +discussions there. + +Django's online documentation also includes pointers on how to contribute to +Django: + + * :ref:`How to contribute to Django ` + +Contributions on any level -- developing code, writing documentation or simply +triaging tickets and helping to test proposed bugfixes -- are always welcome and +appreciated. + +Development sprints for Django 1.2 will also be taking place at PyCon +US 2010, on the dedicated sprint days (February 22 through 25), and +anyone who wants to help out is welcome to join in, either in person +at PyCon or virtually in the IRC channel or on the mailing list.