PageRenderTime 39ms CodeModel.GetById 35ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 1ms

/docs/releases/1.0.txt

https://code.google.com/p/mango-py/
Plain Text | 246 lines | 180 code | 66 blank | 0 comment | 0 complexity | 5e4f513764317c5dcfcf2b52d31fc0ce MD5 | raw file
  1========================
  2Django 1.0 release notes
  3========================
  4
  5Welcome to Django 1.0!
  6
  7We've been looking forward to this moment for over three years, and it's finally
  8here. Django 1.0 represents a the largest milestone in Django's development to
  9date: a Web framework that a group of perfectionists can truly be proud of.
 10
 11Django 1.0 represents over three years of community development as an Open
 12Source project. Django's received contributions from hundreds of developers,
 13been translated into fifty languages, and today is used by developers on every
 14continent and in every kind of job.
 15
 16An interesting historical note: when Django was first released in July 2005, the
 17initial released version of Django came from an internal repository at revision
 18number 8825. Django 1.0 represents revision 8961 of our public repository. It
 19seems fitting that our 1.0 release comes at the moment where community
 20contributions overtake those made privately.
 21
 22Stability and forwards-compatibility
 23====================================
 24
 25:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
 26stability and forwards-compatibility. In a nutshell, this means that code you
 27develop against Django 1.0 will continue to work against 1.1 unchanged, and you
 28should need to make only minor changes for any 1.X release.
 29
 30See the :doc:`API stability guide </misc/api-stability>` for full details.
 31
 32Backwards-incompatible changes
 33==============================
 34
 35Django 1.0 has a number of backwards-incompatible changes from Django 0.96. If
 36you have apps written against Django 0.96 that you need to port, see our
 37detailed porting guide:
 38
 39.. toctree::
 40   :maxdepth: 1
 41
 42   1.0-porting-guide
 43
 44A complete list of backwards-incompatible changes can be found at
 45http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges.
 46
 47What's new in Django 1.0
 48========================
 49
 50A *lot*!
 51
 52Since Django 0.96, we've made over 4,000 code commits, fixed more than 2,000
 53bugs, and edited, added, or removed around 350,000 lines of code. We've also
 54added 40,000 lines of new documentation, and greatly improved what was already
 55there.
 56
 57In fact, new documentation is one of our favorite features of Django 1.0, so we
 58might as well start there. First, there's a new documentation site:
 59
 60    http://docs.djangoproject.com/
 61
 62The documentation has been greatly improved, cleaned up, and generally made
 63awesome. There's now dedicated search, indexes, and more.
 64
 65We can't possibly document everything that's new in 1.0, but the documentation
 66will be your definitive guide. Anywhere you see something like:
 67
 68.. versionadded:: 1.0
 69   This feature is new in Django 1.0
 70
 71You'll know that you're looking at something new or changed.
 72
 73The other major highlights of Django 1.0 are:
 74
 75Re-factored admin application
 76-----------------------------
 77
 78The Django administrative interface (``django.contrib.admin``) has been
 79completely refactored; admin definitions are now completely decoupled from model
 80definitions (no more ``class Admin`` declaration in models!), rewritten to use
 81Django's new form-handling library (introduced in the 0.96 release as
 82``django.newforms``, and now available as simply ``django.forms``) and
 83redesigned with extensibility and customization in mind. Full documentation for
 84the admin application is available online in the official Django documentation:
 85
 86See the :doc:`admin reference </ref/contrib/admin/index>` for details
 87
 88Improved Unicode handling
 89-------------------------
 90
 91Django's internals have been refactored to use Unicode throughout; this
 92drastically simplifies the task of dealing with non-Western-European content and
 93data in Django. Additionally, utility functions have been provided to ease
 94interoperability with third-party libraries and systems which may or may not
 95handle Unicode gracefully. Details are available in Django's Unicode-handling
 96documentation.
 97
 98See :doc:`/ref/unicode`.
 99
100An improved ORM
101---------------
102
103Django's object-relational mapper -- the component which provides the mapping
104between Django model classes and your database, and which mediates your database
105queries -- has been dramatically improved by a massive refactoring. For most
106users of Django this is backwards-compatible; the public-facing API for database
107querying underwent a few minor changes, but most of the updates took place in
108the ORM's internals. A guide to the changes, including backwards-incompatible
109modifications and mentions of new features opened up by this refactoring, is
110`available on the Django wiki`__.
111
112__ http://code.djangoproject.com/wiki/QuerysetRefactorBranch
113
114Automatic escaping of template variables
115----------------------------------------
116
117To provide improved security against cross-site scripting (XSS) vulnerabilities,
118Django's template system now automatically escapes the output of variables. This
119behavior is configurable, and allows both variables and larger template
120constructs to be marked as safe (requiring no escaping) or unsafe (requiring
121escaping). A full guide to this feature is in the documentation for the
122:ttag:`autoescape` tag.
123
124``django.contrib.gis`` (GeoDjango)
125----------------------------------
126
127A project over a year in the making, this adds world-class GIS (`Geographic
128Information Systems`_) support to Django, in the form of a ``contrib``
129application. Its documentation is currently being maintained externally, and
130will be merged into the main Django documentation shortly. Huge thanks go to
131Justin Bronn, Jeremy Dunck, Brett Hoerner and Travis Pinney for their efforts in
132creating and completing this feature.
133
134See http://geodjango.org/ for details.
135
136.. _Geographic Information Systems: http://en.wikipedia.org/wiki/Geographic_information_system
137
138Pluggable file storage
139----------------------
140
141Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
142pluggable file-storage backends, allowing extensive customization of where and
143how uploaded files get stored by Django. For details, see :doc:`the files
144documentation </topics/files>`; big thanks go to Marty Alchin for putting in the
145hard work to get this completed.
146
147Jython compatibility
148--------------------
149
150Thanks to a lot of work from Leo Soto during a Google Summer of Code project,
151Django's codebase has been refactored to remove incompatibilities with
152`Jython`_, an implementation of Python written in Java, which runs Python code
153on the Java Virtual Machine. Django is now compatible with the forthcoming
154Jython 2.5 release.
155
156See :doc:`/howto/jython`.
157
158.. _Jython: http://www.jython.org/
159
160Generic relations in forms and admin
161------------------------------------
162
163Classes are now included in ``django.contrib.contenttypes`` which can be used to
164support generic relations in both the admin interface and in end-user forms. See
165:ref:`the documentation for generic relations <generic-relations>` for details.
166
167``INSERT``/``UPDATE`` distinction
168---------------------------------
169
170Although Django's default behavior of having a model's ``save()`` method
171automatically determine whether to perform an ``INSERT`` or an ``UPDATE`` at the
172SQL level is suitable for the majority of cases, there are occasional situations
173where forcing one or the other is useful. As a result, models can now support an
174additional parameter to ``save()`` which can force a specific operation.
175
176See :ref:`ref-models-force-insert` for details.
177
178Split ``CacheMiddleware``
179-------------------------
180
181Django's ``CacheMiddleware`` has been split into three classes:
182``CacheMiddleware`` itself still exists and retains all of its previous
183functionality, but it is now built from two separate middleware classes which
184handle the two parts of caching (inserting into and reading from the cache)
185separately, offering additional flexibility for situations where combining these
186functions into a single middleware posed problems.
187
188Full details, including updated notes on appropriate use, are in :doc:`the
189caching documentation </topics/cache>`.
190
191Refactored ``django.contrib.comments``
192--------------------------------------
193
194As part of a Google Summer of Code project, Thejaswi Puthraya carried out a
195major rewrite and refactoring of Django's bundled comment system, greatly
196increasing its flexibility and customizability. :doc:`Full documentation
197</ref/contrib/comments/index>` is available, as well as :doc:`an upgrade guide
198</ref/contrib/comments/upgrade>` if you were using the previous incarnation of
199the comments application.
200
201Removal of deprecated features
202------------------------------
203
204A number of features and methods which had previously been marked as deprecated,
205and which were scheduled for removal prior to the 1.0 release, are no longer
206present in Django. These include imports of the form library from
207``django.newforms`` (now located simply at ``django.forms``), the
208``form_for_model`` and ``form_for_instance`` helper functions (which have been
209replaced by ``ModelForm``) and a number of deprecated features which were
210replaced by the dispatcher, file-uploading and file-storage refactorings
211introduced in the Django 1.0 alpha releases.
212
213Known issues
214============
215
216We've done our best to make Django 1.0 as solid as possible, but unfortunately
217there are a couple of issues that we know about in the release.
218
219Multi-table model inheritance with ``to_field``
220-----------------------------------------------
221
222If you're using :ref:`multiple table model inheritance
223<multi-table-inheritance>`, be aware of this caveat: child models using a custom
224``parent_link`` and ``to_field`` will cause database integrity errors. A set of
225models like the following are **not valid**::
226
227    class Parent(models.Model):
228        name = models.CharField(max_length=10)
229        other_value = models.IntegerField(unique=True)
230
231    class Child(Parent):
232        father = models.OneToOneField(Parent, primary_key=True, to_field="other_value", parent_link=True)
233        value = models.IntegerField()
234
235This bug will be fixed in the next release of Django.
236
237Caveats with support of certain databases
238-----------------------------------------
239
240Django attempts to support as many features as possible on all database
241backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :doc:`notes on supported database </ref/databases>`:
242
243    - :ref:`mysql-notes`
244    - :ref:`sqlite-notes`
245    - :ref:`oracle-notes`
246