pytask.new: comparison parts/django/docs/releases/1.1.txt

equal deleted inserted replaced

-:5ff1fc726848
+:c6bca38c1cbf
+========================
+Django 1.1 release notes
+========================
+July 29, 2009
+Welcome to Django 1.1!
+Django 1.1 includes a number of nifty `new features`_, lots of bug
+fixes, and an easy upgrade path from Django 1.0.
+.. _new features: `What's new in Django 1.1`_
+.. _backwards-incompatible-changes-1.1:
+Backwards-incompatible changes in 1.1
+=====================================
+Django has a policy of :doc:`API stability </misc/api-stability>`. This means
+that, in general, code you develop against Django 1.0 should continue to work
+against 1.1 unchanged. However, we do sometimes make backwards-incompatible
+changes if they're necessary to resolve bugs, and there are a handful of such
+(minor) changes between Django 1.0 and Django 1.1.
+Before upgrading to Django 1.1 you should double-check that the following
+changes don't impact you, and upgrade your code if they do.
+Changes to constraint names
+---------------------------
+Django 1.1 modifies the method used to generate database constraint names so
+that names are consistent regardless of machine word size. This change is
+backwards incompatible for some users.
+If you are using a 32-bit platform, you're off the hook; you'll observe no
+differences as a result of this change.
+However, **users on 64-bit platforms may experience some problems** using the
+:djadmin:`reset` management command. Prior to this change, 64-bit platforms
+would generate a 64-bit, 16 character digest in the constraint name; for
+example::
+ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_5e8f10c132091d1e FOREIGN KEY ...
+Following this change, all platforms, regardless of word size, will generate a
+32-bit, 8 character digest in the constraint name; for example::
+ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_32091d1e FOREIGN KEY ...
+As a result of this change, you will not be able to use the :djadmin:`reset`
+management command on any table made by a 64-bit machine. This is because the
+the new generated name will not match the historically generated name; as a
+result, the SQL constructed by the reset command will be invalid.
+If you need to reset an application that was created with 64-bit constraints,
+you will need to manually drop the old constraint prior to invoking
+:djadmin:`reset`.
+Test cases are now run in a transaction
+---------------------------------------
+Django 1.1 runs tests inside a transaction, allowing better test performance
+(see `test performance improvements`_ for details).
+This change is slightly backwards incompatible if existing tests need to test
+transactional behavior, if they rely on invalid assumptions about the test
+environment, or if they require a specific test case ordering.
+For these cases, :class:`~django.test.TransactionTestCase` can be used instead.
+This is a just a quick fix to get around test case errors revealed by the new
+rollback approach; in the long-term tests should be rewritten to correct the
+test case.
+.. _removed-setremoteaddrfromforwardedfor-middleware:
+Removed ``SetRemoteAddrFromForwardedFor`` middleware
+----------------------------------------------------
+For convenience, Django 1.0 included an optional middleware class --
+``django.middleware.http.SetRemoteAddrFromForwardedFor`` -- which updated the
+value of ``REMOTE_ADDR`` based on the HTTP ``X-Forwarded-For`` header commonly
+set by some proxy configurations.
+It has been demonstrated that this mechanism cannot be made reliable enough for
+general-purpose use, and that (despite documentation to the contrary) its
+inclusion in Django may lead application developers to assume that the value of
+``REMOTE_ADDR`` is "safe" or in some way reliable as a source of authentication.
+While not directly a security issue, we've decided to remove this middleware
+with the Django 1.1 release. It has been replaced with a class that does nothing
+other than raise a ``DeprecationWarning``.
+If you've been relying on this middleware, the easiest upgrade path is:
+* Examine `the code as it existed before it was removed`__.
+* Verify that it works correctly with your upstream proxy, modifying
+it to support your particular proxy (if necessary).
+* Introduce your modified version of ``SetRemoteAddrFromForwardedFor`` as a
+piece of middleware in your own project.
+__ http://code.djangoproject.com/browser/django/trunk/django/middleware/http.py?rev=11000#L33
+Names of uploaded files are available later
+-------------------------------------------
+.. currentmodule:: django.db.models
+In Django 1.0, files uploaded and stored in a model's :class:`FileField` were
+saved to disk before the model was saved to the database. This meant that the
+actual file name assigned to the file was available before saving. For example,
+it was available in a model's pre-save signal handler.
+In Django 1.1 the file is saved as part of saving the model in the database, so
+the actual file name used on disk cannot be relied on until *after* the model
+has been saved.
+Changes to how model formsets are saved
+---------------------------------------
+.. currentmodule:: django.forms.models
+In Django 1.1, :class:`BaseModelFormSet` now calls :meth:`ModelForm.save()`.
+This is backwards-incompatible if you were modifying ``self.initial`` in a model
+formset's ``__init__``, or if you relied on the internal ``_total_form_count``
+or ``_initial_form_count`` attributes of BaseFormSet. Those attributes are now
+public methods.
+Fixed the ``join`` filter's escaping behavior
+---------------------------------------------
+The :ttag:`join` filter no longer escapes the literal value that is
+passed in for the connector.
+This is backwards incompatible for the special situation of the literal string
+containing one of the five special HTML characters. Thus, if you were writing
+``{{ foo|join:"&" }}``, you now have to write ``{{ foo|join:"&amp;" }}``.
+The previous behavior was a bug and contrary to what was documented
+and expected.
+Permanent redirects and the ``redirect_to()`` generic view
+----------------------------------------------------------
+Django 1.1 adds a ``permanent`` argument to the
+:func:`django.views.generic.simple.redirect_to()` view. This is technically
+backwards-incompatible if you were using the ``redirect_to`` view with a
+format-string key called 'permanent', which is highly unlikely.
+.. _deprecated-features-1.1:
+Features deprecated in 1.1
+==========================
+One feature has been marked as deprecated in Django 1.1:
+* You should no longer use ``AdminSite.root()`` to register that admin
+views. That is, if your URLconf contains the line::
+(r'^admin/(.*)', admin.site.root),
+You should change it to read::
+(r'^admin/', include(admin.site.urls)),
+You should begin to remove use of this feature from your code immediately.
+``AdminSite.root`` will raise a ``PendingDeprecationWarning`` if used in
+Django 1.1. This warning is hidden by default. In Django 1.2, this warning will
+be upgraded to a ``DeprecationWarning``, which will be displayed loudly. Django
+1.3 will remove ``AdminSite.root()`` entirely.
+For more details on our deprecation policies and strategy, see
+:doc:`/internals/release-process`.
+What's new in Django 1.1
+========================
+Quite a bit: since Django 1.0, we've made 1,290 code commits, fixed 1,206 bugs,
+and added roughly 10,000 lines of documentation.
+The major new features in Django 1.1 are:
+ORM improvements
+----------------
+.. currentmodule:: django.db.models
+Two major enhancements have been added to Django's object-relational mapper
+(ORM): aggregate support, and query expressions.
+Aggregate support
+~~~~~~~~~~~~~~~~~
+It's now possible to run SQL aggregate queries (i.e. ``COUNT()``, ``MAX()``,
+``MIN()``, etc.) from within Django's ORM. You can choose to either return the
+results of the aggregate directly, or else annotate the objects in a
+:class:`QuerySet` with the results of the aggregate query.
+This feature is available as new :meth:`QuerySet.aggregate()`` and
+:meth:`QuerySet.annotate()`` methods, and is covered in detail in :doc:`the ORM
+aggregation documentation </topics/db/aggregation>`.
+Query expressions
+~~~~~~~~~~~~~~~~~
+Queries can now refer to a another field on the query and can traverse
+relationships to refer to fields on related models. This is implemented in the
+new :class:`F` object; for full details, including examples, consult the
+:ref:`documentation for F expressions <query-expressions>`.
+Model improvements
+------------------
+A number of features have been added to Django's model layer:
+"Unmanaged" models
+~~~~~~~~~~~~~~~~~~
+You can now control whether or not Django manages the life-cycle of the database
+tables for a model using the :attr:`~Options.managed` model option. This
+defaults to ``True``, meaning that Django will create the appropriate database
+tables in :djadmin:`syncdb` and remove them as part of the :djadmin:`reset`
+command. That is, Django *manages* the database table's lifecycle.
+If you set this to ``False``, however, no database table creating or deletion
+will be automatically performed for this model. This is useful if the model
+represents an existing table or a database view that has been created by some
+other means.
+For more details, see the documentation for the :attr:`~Options.managed`
+option.
+Proxy models
+~~~~~~~~~~~~
+You can now create :ref:`proxy models <proxy-models>`: subclasses of existing
+models that only add Python-level (rather than database-level) behavior and
+aren't represented by a new table. That is, the new model is a *proxy* for some
+underlying model, which stores all the real data.
+All the details can be found in the :ref:`proxy models documentation
+<proxy-models>`. This feature is similar on the surface to unmanaged models,
+so the documentation has an explanation of :ref:`how proxy models differ from
+unmanaged models <proxy-vs-unmanaged-models>`.
+Deferred fields
+~~~~~~~~~~~~~~~
+In some complex situations, your models might contain fields which could
+contain a lot of data (for example, large text fields), or require expensive
+processing to convert them to Python objects. If you know you don't need those
+particular fields, you can now tell Django not to retrieve them from the
+database.
+You'll do this with the new queryset methods
+:meth:`~django.db.models.QuerySet.defer` and
+:meth:`~django.db.models.QuerySet.only`.
+Testing improvements
+--------------------
+A few notable improvements have been made to the :doc:`testing framework
+</topics/testing>`.
+Test performance improvements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. currentmodule:: django.test
+Tests written using Django's :doc:`testing framework </topics/testing>` now run
+dramatically faster (as much as 10 times faster in many cases).
+This was accomplished through the introduction of transaction-based tests: when
+using :class:`django.test.TestCase`, your tests will now be run in a transaction
+which is rolled back when finished, instead of by flushing and re-populating the
+database. This results in an immense speedup for most types of unit tests. See
+the documentation for :class:`TestCase` and :class:`TransactionTestCase` for a
+full description, and some important notes on database support.
+Test client improvements
+------------------------
+.. currentmodule:: django.test.client
+A couple of small -- but highly useful -- improvements have been made to the
+test client:
+* The test :class:`Client` now can automatically follow redirects with the
+``follow`` argument to :meth:`Client.get` and :meth:`Client.post`. This
+makes testing views that issue redirects simpler.
+* It's now easier to get at the template context in the response returned
+the test client: you'll simply access the context as
+``request.context[key]``. The old way, which treats ``request.context`` as
+a list of contexts, one for each rendered template in the inheritance
+chain, is still available if you need it.
+New admin features
+------------------
+Django 1.1 adds a couple of nifty new features to Django's admin interface:
+Editable fields on the change list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can now make fields editable on the admin list views via the new
+:ref:`list_editable <admin-list-editable>` admin option. These fields will show
+up as form widgets on the list pages, and can be edited and saved in bulk.
+Admin "actions"
+~~~~~~~~~~~~~~~
+You can now define :doc:`admin actions </ref/contrib/admin/actions>` that can
+perform some action to a group of models in bulk. Users will be able to select
+objects on the change list page and then apply these bulk actions to all
+selected objects.
+Django ships with one pre-defined admin action to delete a group of objects in
+one fell swoop.
+Conditional view processing
+---------------------------
+Django now has much better support for :doc:`conditional view processing
+</topics/conditional-view-processing>` using the standard ``ETag`` and
+``Last-Modified`` HTTP headers. This means you can now easily short-circuit
+view processing by testing less-expensive conditions. For many views this can
+lead to a serious improvement in speed and reduction in bandwidth.
+URL namespaces
+--------------
+Django 1.1 improves :ref:`named URL patterns <naming-url-patterns>` with the
+introduction of URL "namespaces."
+In short, this feature allows the same group of URLs, from the same application,
+to be included in a Django URLConf multiple times, with varying (and potentially
+nested) named prefixes which will be used when performing reverse resolution. In
+other words, reusable applications like Django's admin interface may be
+registered multiple times without URL conflicts.
+For full details, see :ref:`the documentation on defining URL namespaces
+<topics-http-defining-url-namespaces>`.
+GeoDjango
+---------
+In Django 1.1, GeoDjango_ (i.e. ``django.contrib.gis``) has several new
+features:
+* Support for SpatiaLite_ -- a spatial database for SQLite -- as a spatial
+backend.
+* Geographic aggregates (``Collect``, ``Extent``, ``MakeLine``, ``Union``)
+and ``F`` expressions.
+* New ``GeoQuerySet`` methods: ``collect``, ``geojson``, and
+``snap_to_grid``.
+* A new list interface methods for ``GEOSGeometry`` objects.
+For more details, see the `GeoDjango documentation`_.
+.. _geodjango: http://geodjango.org/
+.. _spatialite: http://www.gaia-gis.it/spatialite/
+.. _geodjango documentation: http://geodjango.org/docs/
+Other improvements
+------------------
+Other new features and changes introduced since Django 1.0 include:
+* The :doc:`CSRF protection middleware </ref/contrib/csrf>` has been split into
+two classes -- ``CsrfViewMiddleware`` checks incoming requests, and
+``CsrfResponseMiddleware`` processes outgoing responses. The combined
+``CsrfMiddleware`` class (which does both) remains for
+backwards-compatibility, but using the split classes is now recommended in
+order to allow fine-grained control of when and where the CSRF processing
+takes place.
+* :func:`~django.core.urlresolvers.reverse` and code which uses it (e.g., the
+``{% url %}`` template tag) now works with URLs in Django's administrative
+site, provided that the admin URLs are set up via ``include(admin.site.urls)``
+(sending admin requests to the ``admin.site.root`` view still works, but URLs
+in the admin will not be "reversible" when configured this way).
+* The ``include()`` function in Django URLconf modules can now accept sequences
+of URL patterns (generated by ``patterns()``) in addition to module names.
+* Instances of Django forms (see :doc:`the forms overview </topics/forms/index>`)
+now have two additional methods, ``hidden_fields()`` and ``visible_fields()``,
+which return the list of hidden -- i.e., ``<input type="hidden">`` -- and
+visible fields on the form, respectively.
+* The ``redirect_to`` generic view (see :doc:`the generic views documentation
+</ref/generic-views>`) now accepts an additional keyword argument
+``permanent``. If ``permanent`` is ``True``, the view will emit an HTTP
+permanent redirect (status code 301). If ``False``, the view will emit an HTTP
+temporary redirect (status code 302).
+* A new database lookup type -- ``week_day`` -- has been added for ``DateField``
+and ``DateTimeField``. This type of lookup accepts a number between 1 (Sunday)
+and 7 (Saturday), and returns objects where the field value matches that day
+of the week. See :ref:`the full list of lookup types <field-lookups>` for
+details.
+* The ``{% for %}`` tag in Django's template language now accepts an optional
+``{% empty %}`` clause, to be displayed when ``{% for %}`` is asked to loop
+over an empty sequence. See :doc:`the list of built-in template tags
+</ref/templates/builtins>` for examples of this.
+* The :djadmin:`dumpdata` management command now accepts individual
+model names as arguments, allowing you to export the data just from
+particular models.
+* There's a new :tfilter:`safeseq` template filter which works just like
+:tfilter:`safe` for lists, marking each item in the list as safe.
+* :doc:`Cache backends </topics/cache>` now support ``incr()`` and
+``decr()`` commands to increment and decrement the value of a cache key.
+On cache backends that support atomic increment/decrement -- most
+notably, the memcached backend -- these operations will be atomic, and
+quite fast.
+* Django now can :doc:`easily delegate authentication to the Web server
+</howto/auth-remote-user>` via a new authentication backend that supports
+the standard ``REMOTE_USER`` environment variable used for this purpose.
+* There's a new :func:`django.shortcuts.redirect` function that makes it
+easier to issue redirects given an object, a view name, or a URL.
+* The ``postgresql_psycopg2`` backend now supports :ref:`native PostgreSQL
+autocommit <postgresql-notes>`. This is an advanced, PostgreSQL-specific
+feature, that can make certain read-heavy applications a good deal
+faster.
+What's next?
+============
+We'll take a short break, and then work on Django 1.2 will begin -- no rest for
+the weary! If you'd like to help, 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``. Feel free to
+join the discussions!
+Django's online documentation also includes pointers on how to contribute to
+Django:
+* :doc:`How to contribute to Django </internals/contributing>`
+Contributions on any level -- developing code, writing documentation or simply
+triaging tickets and helping to test proposed bugfixes -- are always welcome and
+appreciated.
+And that's the way it is.