diff options
Diffstat (limited to 'docs')
73 files changed, 641 insertions, 406 deletions
diff --git a/docs/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 572bcd2e29..3ae770da20 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -5,9 +5,7 @@ import json import os import re -from docutils import nodes, transforms - -from sphinx import addnodes, roles, __version__ as sphinx_ver +from sphinx import addnodes, __version__ as sphinx_ver from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.writers.html import SmartyPantsHTMLTranslator from sphinx.util.console import bold @@ -64,21 +62,25 @@ class VersionDirective(Directive): option_spec = {} def run(self): + if len(self.arguments) > 1: + msg = """Only one argument accepted for directive '{directive_name}::'. + Comments should be provided as content, + not as an extra argument.""".format(directive_name=self.name) + raise self.error(msg) + env = self.state.document.settings.env ret = [] node = addnodes.versionmodified() ret.append(node) + if self.arguments[0] == env.config.django_next_version: node['version'] = "Development version" else: node['version'] = self.arguments[0] + node['type'] = self.name - if len(self.arguments) == 2: - inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1) - node.extend(inodes) - if self.content: - self.state.nested_parse(self.content, self.content_offset, node) - ret = ret + messages + if self.content: + self.state.nested_parse(self.content, self.content_offset, node) env.note_versionchange(node['type'], node['version'], node, self.lineno) return ret diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index 7a31fc44e3..34e68d3700 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -256,7 +256,7 @@ All attributes can be set in your derived class and can be used in .. versionadded:: 1.6 -The ``leave_locale_alone`` option was added in Django 1.6. + The ``leave_locale_alone`` option was added in Django 1.6. Methods ------- diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt index b092048870..b72be75497 100644 --- a/docs/howto/deployment/checklist.txt +++ b/docs/howto/deployment/checklist.txt @@ -157,6 +157,15 @@ Performance optimizations Setting :setting:`DEBUG = False <DEBUG>` disables several features that are only useful in development. In addition, you can tune the following settings. +:setting:`CONN_MAX_AGE` +----------------------- + +Enabling `persistent database connections <persistent-database-connections>`_ +can result in a nice speed-up when connecting to the database accounts for a +significant part of the request processing time. + +This helps a lot on virtualized hosts with limited network performance. + :setting:`TEMPLATE_LOADERS` --------------------------- diff --git a/docs/howto/deployment/fastcgi.txt b/docs/howto/deployment/fastcgi.txt index 6a5acfb7cc..507e50d1a2 100644 --- a/docs/howto/deployment/fastcgi.txt +++ b/docs/howto/deployment/fastcgi.txt @@ -112,7 +112,7 @@ Running a preforked server on a Unix domain socket:: .. admonition:: Socket security - Django's default umask requires that the webserver and the Django fastcgi + Django's default umask requires that the web server and the Django fastcgi process be run with the same group **and** user. For increased security, you can run them under the same group but as different users. If you do this, you will need to set the umask to 0002 using the ``umask`` argument diff --git a/docs/howto/legacy-databases.txt b/docs/howto/legacy-databases.txt index 6846e4b2df..0bea8b41c4 100644 --- a/docs/howto/legacy-databases.txt +++ b/docs/howto/legacy-databases.txt @@ -61,7 +61,7 @@ this generated model definition: class Person(models.Model): id = models.IntegerField(primary_key=True) - first_name = models.ChaField(max_length=70) + first_name = models.CharField(max_length=70) class Meta: **managed = False** db_table = 'CENSUS_PERSONS' @@ -75,8 +75,8 @@ access to your precious data on a model by model basis. .. versionchanged:: 1.6 -The behavior by which introspected models are created as unmanaged ones is new -in Django 1.6. + The behavior by which introspected models are created as unmanaged ones is new + in Django 1.6. Install the core Django tables ============================== diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt index 2c98566e88..1fdad94143 100644 --- a/docs/howto/static-files/index.txt +++ b/docs/howto/static-files/index.txt @@ -32,7 +32,7 @@ Configuring static files {% load staticfiles %} <img src="{% static "my_app/myexample.jpg" %}" alt="My image"/> -3. Store your static files in a folder called ``static`` in your app. For +4. Store your static files in a folder called ``static`` in your app. For example ``my_app/static/my_app/myimage.jpg``. Now, if you use ``./manage.py runserver``, all static files should be served @@ -106,7 +106,7 @@ for gathering static files in a single directory so you can serve them easily. This will copy all files from your static folders into the :setting:`STATIC_ROOT` directory. -3. Use a webserver of your choice to serve the +3. Use a web server of your choice to serve the files. :doc:`/howto/static-files/deployment` covers some common deployment strategies for static files. diff --git a/docs/internals/committers.txt b/docs/internals/committers.txt index a0649f38a2..f891bc4eb7 100644 --- a/docs/internals/committers.txt +++ b/docs/internals/committers.txt @@ -15,7 +15,7 @@ Journal-World`_ of Lawrence, Kansas, USA. He was lead developer at World Online for 2.5 years, during which time Django was developed and implemented on World Online's sites. He was the - leader and founder of EveryBlock_, a "news feed for your block." He now + leader and founder of EveryBlock_, a "news feed for your block." He now develops for Soundslice_. Adrian lives in Chicago, USA. @@ -41,7 +41,7 @@ Journal-World`_ of Lawrence, Kansas, USA. `Wilson Miner`_ Wilson's design-fu is what makes Django look so nice. He designed the Web site you're looking at right now, as well as Django's acclaimed admin - interface. Wilson was the designer for EveryBlock and Rdio_. He now + interface. Wilson was the designer for EveryBlock and Rdio_. He now designs for Facebook. Wilson lives in San Francisco, USA. @@ -105,8 +105,8 @@ Malcolm Tredinnick .. _russell keith-magee: http://cecinestpasun.com/ Joseph Kocherhans - Joseph was the director of lead development at EveryBlock and previously - developed at the Lawrence Journal-World. He is treasurer of the `Django + Joseph was the director of lead development at EveryBlock and previously + developed at the Lawrence Journal-World. He is treasurer of the `Django Software Foundation`_. He often disappears for several days into the woods, attempts to teach himself computational linguistics, and annoys his neighbors with his Charango_ playing. @@ -386,17 +386,17 @@ Florian Apolloner .. _Ubuntuusers webteam: http://wiki.ubuntuusers.de/ubuntuusers/Webteam Jeremy Dunck - Jeremy was rescued from corporate IT drudgery by Free Software and, in part, + Jeremy was rescued from corporate IT drudgery by Free Software and, in part, Django. Many of Jeremy's interests center around access to information. - Jeremy was the lead developer of Pegasus News, one of the first uses of - Django outside World Online, and has since joined Votizen, a startup intent + Jeremy was the lead developer of Pegasus News, one of the first uses of + Django outside World Online, and has since joined Votizen, a startup intent on reducing the influence of money in politics. - He serves as DSF Secretary, organizes and helps organize sprints, cares - about the health and equity of the Django community. He has gone an + He serves as DSF Secretary, organizes and helps organize sprints, cares + about the health and equity of the Django community. He has gone an embarrassingly long time without a working blog. - + Jeremy lives in Mountain View, CA, USA. `Bryan Veloso`_ @@ -441,6 +441,20 @@ Jeremy Dunck .. _Ultimate Frisbee: http://www.montrealultimate.ca .. _Reptiletech: http://www.reptiletech.com +`Daniel Lindsley`_ + Pythonista since 2003, Djangonaut since 2006. Daniel started with Django + just after the v0.90 release (back when ``Manipulators`` looked good) & fell + in love. Since then, he wrote third-party apps like Haystack & Tastypie + & has run the annual Django Dash since 2007. One of the testing faithful, + Daniel's contributions include rewriting the ``Forms`` test suite & the + addition of ``request.is_ajax``. Daniel currently works as a Python + developer at `Amazon Web Services`_ on the ``boto`` library. + + Daniel lives in Seattle, WA, USA. + +.. _`Daniel Lindsley`: http://toastdriven.com/ +.. _`Amazon Web Services`: https://aws.amazon.com/ + Specialists ----------- diff --git a/docs/internals/contributing/localizing.txt b/docs/internals/contributing/localizing.txt index 0cde77882c..01b88d8d9a 100644 --- a/docs/internals/contributing/localizing.txt +++ b/docs/internals/contributing/localizing.txt @@ -62,5 +62,5 @@ Django source tree, as for any code change: .. _Transifex: https://www.transifex.com/ .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ -.. _Django project page: https://www.transifex.com/projects/p/django/ +.. _Django project page: https://www.transifex.com/projects/p/django-core/ .. _Transifex User Guide: http://help.transifex.com/ diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 469f8614b9..2944dea504 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -188,8 +188,8 @@ Our policy for new features is: release, not the development version. Our preferred way for marking new features is by prefacing the features' -documentation with: "``.. versionadded:: X.Y``", followed by an optional one -line comment and a mandatory blank line. +documentation with: "``.. versionadded:: X.Y``", followed by a a mandatory +blank line and an optional content (indented). General improvements, or other changes to the APIs that should be emphasized should use the "``.. versionchanged:: X.Y``" directive (with the same format diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt index a49251da76..fd985ddafc 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -175,13 +175,13 @@ OK, this is the fun part, where we actually push out a release! #. Make sure you have an absolutely clean tree by running ``git clean -dfx``. -#. Run ``python setup.py sdist`` to generate the release package. This will - create the release package in a ``dist/`` directory. +#. Run ``make -f extras/Makefile`` to generate the release packages. This will + create the release packages in a ``dist/`` directory. -#. Generate the hashes of the release package:: +#. Generate the hashes of the release packages:: - $ md5sum dist/Django-<version>.tar.gz - $ sha1sum dist/Django-<version>.tar.gz + $ md5sum dist/Django-* + $ sha1sum dist/Django-* *FIXME: perhaps we should switch to sha256?* @@ -221,6 +221,9 @@ Now you're ready to actually put the release out there. To do this: $ mktmpenv $ pip install https://www.djangoproject.com/m/releases/1.5/Django-1.5.1.tar.gz $ deactivate + $ mktmpenv + $ pip install https://www.djangoproject.com/m/releases/1.5/Django-1.5.1-py2.py3-none-any.whl + $ deactivate This just tests that the tarballs are available (i.e. redirects are up) and that they install correctly, but it'll catch silly mistakes. diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index 8747375b0a..dd7136c877 100644 --- a/docs/intro/contributing.txt +++ b/docs/intro/contributing.txt @@ -389,8 +389,8 @@ This is a new feature, so it should be documented. Add the following on line .. versionadded:: 1.5 - The current value of the field will be displayed as a clickable link above the - input widget. + The current value of the field will be displayed as a clickable link above the + input widget. For more information on writing documentation, including an explanation of what the ``versionadded`` bit is all about, see diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index 1e0f1da0c5..4247b45238 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -66,16 +66,17 @@ After the previous tutorials, our project should look like this:: __init__.py admin.py models.py - tests.py static/ - style.css - images/ - background.gif + polls + images/ + background.gif + style.css templates/ polls/ detail.html index.html results.html + tests.py urls.py views.py templates/ @@ -129,7 +130,7 @@ this. For a small app like polls, this process isn't too difficult. 2. Move the ``polls`` directory into the ``django-polls`` directory. -3. Create a file ``django-polls/README.txt`` with the following contents:: +3. Create a file ``django-polls/README.rst`` with the following contents:: ===== Polls @@ -157,7 +158,7 @@ this. For a small app like polls, this process isn't too difficult. 3. Run `python manage.py syncdb` to create the polls models. 4. Start the development server and visit http://127.0.0.1:8000/admin/ - to create a poll (you'll need the Admin app enabled). + to create a poll (you'll need the Admin app enabled). 5. Visit http://127.0.0.1:8000/polls/ to participate in the poll. @@ -177,23 +178,23 @@ Create a file ``django-polls/setup.py`` with the following contents:: import os from setuptools import setup - README = open(os.path.join(os.path.dirname(__file__), 'README.txt')).read() + README = open(os.path.join(os.path.dirname(__file__), 'README.rst')).read() # allow setup.py to be run from any path os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir))) setup( - name = 'django-polls', - version = '0.1', - packages = ['polls'], - include_package_data = True, - license = 'BSD License', # example license - description = 'A simple Django app to conduct Web-based polls.', - long_description = README, - url = 'http://www.example.com/', - author = 'Your Name', - author_email = 'yourname@example.com', - classifiers = [ + name='django-polls', + version='0.1', + packages=['polls'], + include_package_data=True, + license='BSD License', # example license + description='A simple Django app to conduct Web-based polls.', + long_description=README, + url='http://www.example.com/', + author='Your Name', + author_email='yourname@example.com', + classifiers=[ 'Environment :: Web Environment', 'Framework :: Django', 'Intended Audience :: Developers', @@ -216,10 +217,13 @@ Create a file ``django-polls/setup.py`` with the following contents:: 6. Only Python modules and packages are included in the package by default. To include additional files, we'll need to create a ``MANIFEST.in`` file. The distribute docs referred to in the previous step discuss this file in more - details. To include the templates and our LICENSE file, create a file - ``django-polls/MANIFEST.in`` with the following contents:: + details. To include the templates, the ``README.rst`` and our ``LICENSE`` + file, create a file ``django-polls/MANIFEST.in`` with the following + contents:: include LICENSE + include README.rst + recursive-include polls/static * recursive-include polls/templates * 7. It's optional, but recommended, to include detailed documentation with your diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 7f69945300..d623bd8451 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -23,7 +23,8 @@ If Django is installed, you should see the version of your installation. If it isn't, you'll get an error telling "No module named django". This tutorial is written for Django |version| and Python 2.x. If the Django -version doesn't match, you can refer to the tutorial for your version of Django +version doesn't match, you can refer to the tutorial for your version of +Django by using the version switcher at the bottom right corner of this page, or update Django to the newest version. If you are using Python 3.x, be aware that your code may need to differ from what is in the tutorial and you should continue using the tutorial only if you know what you are doing with Python @@ -122,7 +123,7 @@ These files are: "table of contents" of your Django-powered site. You can read more about URLs in :doc:`/topics/http/urls`. -* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible webservers to +* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible web servers to serve your project. See :doc:`/howto/deployment/wsgi/index` for more details. .. _more about packages: http://docs.python.org/tutorial/modules.html#packages @@ -242,9 +243,6 @@ come with Django: * :mod:`django.contrib.sessions` -- A session framework. -* :mod:`django.contrib.sites` -- A framework for managing multiple sites - with one Django installation. - * :mod:`django.contrib.messages` -- A messaging framework. * :mod:`django.contrib.staticfiles` -- A framework for managing @@ -252,7 +250,7 @@ come with Django: These applications are included by default as a convenience for the common case. -Each of these applications makes use of at least one database table, though, +Some of these applications makes use of at least one database table, though, so we need to create the tables in the database before we can use them. To do that, run the following command: @@ -581,27 +579,32 @@ Wait a minute. ``<Poll: Poll object>`` is, utterly, an unhelpful representation of this object. Let's fix that by editing the polls model (in the ``polls/models.py`` file) and adding a :meth:`~django.db.models.Model.__unicode__` method to both ``Poll`` and -``Choice``:: +``Choice``. On Python 3, simply replace ``__unicode__`` by ``__str__`` in the +following example:: class Poll(models.Model): # ... - def __unicode__(self): + def __unicode__(self): # Python 3: def __str__(self): return self.question class Choice(models.Model): # ... - def __unicode__(self): + def __unicode__(self): # Python 3: def __str__(self): return self.choice_text -It's important to add :meth:`~django.db.models.Model.__unicode__` methods to -your models, not only for your own sanity when dealing with the interactive -prompt, but also because objects' representations are used throughout Django's -automatically-generated admin. +It's important to add :meth:`~django.db.models.Model.__unicode__` methods (or +:meth:`~django.db.models.Model.__str__` on Python 3) to your models, not only +for your own sanity when dealing with the interactive prompt, but also because +objects' representations are used throughout Django's automatically-generated +admin. + +.. admonition:: `__unicode__` or `__str__`? -.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not - :meth:`~django.db.models.Model.__str__`? + On Python 3, things are simpler, just use + :meth:`~django.db.models.Model.__str__` and forget about + :meth:`~django.db.models.Model.__unicode__`. - If you're familiar with Python, you might be in the habit of adding + If you're familiar with Python 2, you might be in the habit of adding :meth:`~django.db.models.Model.__str__` methods to your classes, not :meth:`~django.db.models.Model.__unicode__` methods. We use :meth:`~django.db.models.Model.__unicode__` here because Django models deal diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt index 3b0a95f253..97d1d96ad7 100644 --- a/docs/intro/tutorial05.txt +++ b/docs/intro/tutorial05.txt @@ -15,9 +15,9 @@ What are automated tests? Tests are simple routines that check the operation of your code. Testing operates at different levels. Some tests might apply to a tiny detail -- *does a particular model method return values as expected?*, while others -examine the overall operation of the software - *does a sequence of user inputs -on the site produce the desired result?* That's no different from the kind of +(*does a particular model method return values as expected?*) while others +examine the overall operation of the software (*does a sequence of user inputs +on the site produce the desired result?*). That's no different from the kind of testing you did earlier in :doc:`Tutorial 1 </intro/tutorial01>`, using the shell to examine the behavior of a method, or running the application and entering data to check how it behaves. @@ -326,6 +326,13 @@ in the shell:: >>> from django.test.utils import setup_test_environment >>> setup_test_environment() +:meth:`~django.test.utils.setup_test_environment` installs a template renderer +which will allow us to examine some additional attributes on responses such as +``response.context`` that otherwise wouldn't be available. Note that this +method *does not* setup a test database, so the following will be run against +the existing database and the output may differ slightly depending on what +polls you already created. + Next we need to import the test client class (later in ``tests.py`` we will use the :class:`django.test.TestCase` class, which comes with its own client, so this won't be required):: diff --git a/docs/intro/tutorial06.txt b/docs/intro/tutorial06.txt index 6b3d0f35e2..d5db3ae232 100644 --- a/docs/intro/tutorial06.txt +++ b/docs/intro/tutorial06.txt @@ -108,7 +108,7 @@ loaded in the bottom right of the screen. These are the **basics**. For more details on settings and other bits included with the framework see -:doc:`the static files howto </howto/static-files/index>` and the +:doc:`the static files howto </howto/static-files/index>` and :doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying static files </howto/static-files/deployment>` discusses how to use static files on a real server. diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index 2073458314..3ba7c38c43 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -105,6 +105,7 @@ TemplateView in the URL. .. versionchanged:: 1.5 + The context used to be populated with a ``{{ params }}`` dictionary of the parameters captured in the URL. Now those parameters are first-level context variables. diff --git a/docs/ref/class-based-views/generic-date-based.txt b/docs/ref/class-based-views/generic-date-based.txt index 4144c382f8..4dcb788779 100644 --- a/docs/ref/class-based-views/generic-date-based.txt +++ b/docs/ref/class-based-views/generic-date-based.txt @@ -142,7 +142,7 @@ YearArchiveView .. versionchanged:: 1.5 - Previously, this returned a string. + Previously, this returned a string. * ``next_year``: A :class:`~datetime.date` object representing the first day of the next year, according to diff --git a/docs/ref/class-based-views/generic-editing.txt b/docs/ref/class-based-views/generic-editing.txt index 1dbb427036..555ba40cfb 100644 --- a/docs/ref/class-based-views/generic-editing.txt +++ b/docs/ref/class-based-views/generic-editing.txt @@ -110,6 +110,7 @@ CreateView class AuthorCreate(CreateView): model = Author + fields = ['name'] UpdateView ---------- @@ -152,6 +153,7 @@ UpdateView class AuthorUpdate(UpdateView): model = Author + fields = ['name'] DeleteView ---------- diff --git a/docs/ref/class-based-views/mixins-date-based.txt b/docs/ref/class-based-views/mixins-date-based.txt index 75f2a77615..1a1a4d531b 100644 --- a/docs/ref/class-based-views/mixins-date-based.txt +++ b/docs/ref/class-based-views/mixins-date-based.txt @@ -330,5 +330,6 @@ BaseDateListView :meth:`QuerySet.dates()<django.db.models.query.QuerySet.dates>`. .. versionchanged:: 1.5 + The ``ordering`` parameter was added, and the default order was changed to ascending. diff --git a/docs/ref/class-based-views/mixins-editing.txt b/docs/ref/class-based-views/mixins-editing.txt index a4175369aa..51d8628818 100644 --- a/docs/ref/class-based-views/mixins-editing.txt +++ b/docs/ref/class-based-views/mixins-editing.txt @@ -116,6 +116,18 @@ ModelFormMixin by examining ``self.object`` or :attr:`~django.views.generic.detail.SingleObjectMixin.queryset`. + .. attribute:: fields + + .. versionadded:: 1.6 + + A list of names of fields. This is interpreted the same way as the + ``Meta.fields`` attribute of :class:`~django.forms.ModelForm`. + + This is a required attribute if you are generating the form class + automatically (e.g. using ``model``). Omitting this attribute will + result in all fields being used, but this behaviour is deprecated + and will be removed in Django 1.8. + .. attribute:: success_url The URL to redirect to when the form is successfully processed. @@ -206,10 +218,10 @@ ProcessFormView .. versionadded:: 1.6 - ``success_url`` may contain dictionary string formatting, which - will be interpolated against the object's field attributes. For - example, you could use ``success_url="/parent/%(parent_id)s/"`` to - redirect to a URL composed out of the ``parent_id`` field on a model. + ``success_url`` may contain dictionary string formatting, which + will be interpolated against the object's field attributes. For + example, you could use ``success_url="/parent/%(parent_id)s/"`` to + redirect to a URL composed out of the ``parent_id`` field on a model. .. method:: get_success_url() diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index 51b0386654..6796675529 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -67,7 +67,6 @@ TemplateResponseMixin .. attribute:: content_type .. versionadded:: 1.5 - The ``content_type`` attribute was added. The content type to use for the response. ``content_type`` is passed as a keyword argument to ``response_class``. Default is ``None`` -- diff --git a/docs/ref/clickjacking.txt b/docs/ref/clickjacking.txt index ce27148ad3..0b81243b92 100644 --- a/docs/ref/clickjacking.txt +++ b/docs/ref/clickjacking.txt @@ -62,6 +62,7 @@ To set the same ``X-Frame-Options`` value for all responses in your site, put ) .. versionchanged:: 1.6 + This middleware is enabled in the settings file generated by :djadmin:`startproject`. diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index c567bc1db4..67e498ee91 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -18,6 +18,7 @@ The admin is enabled in the default project template used by :djadmin:`startproject`. .. versionchanged:: 1.6 + In previous versions, the admin wasn't enabled by default. For reference, here are the requirements: @@ -336,6 +337,22 @@ subclass:: .. admonition:: Note + .. versionchanged:: 1.6 + + If you define the ``Meta.model`` attribute on a + :class:`~django.forms.ModelForm`, you must also define the + ``Meta.fields`` attribute (or the ``Meta.exclude`` attribute). However, + since the admin has its own way of defining fields, the ``Meta.fields`` + attribute will be ignored. + + If the ``ModelForm`` is only going to be used for the admin, the easiest + solution is to omit the ``Meta.model`` attribute, since ``ModelAdmin`` + will provide the correct model to use. Alternatively, you can set + ``fields = []`` in the ``Meta`` class to satisfy the validation on the + ``ModelForm``. + + .. admonition:: Note + If your ``ModelForm`` and ``ModelAdmin`` both define an ``exclude`` option then ``ModelAdmin`` takes precedence:: @@ -1282,13 +1299,24 @@ templates used by the :class:`ModelAdmin` views: on the changelist page. To use a custom form, for example:: class MyForm(forms.ModelForm): - class Meta: - model = MyModel + pass class MyModelAdmin(admin.ModelAdmin): def get_changelist_form(self, request, **kwargs): return MyForm + .. admonition:: Note + + .. versionchanged:: 1.6 + + If you define the ``Meta.model`` attribute on a + :class:`~django.forms.ModelForm`, you must also define the + ``Meta.fields`` attribute (or the ``Meta.exclude`` attribute). However, + ``ModelAdmin`` ignores this value, overriding it with the + :attr:`ModelAdmin.list_editable` attribute. The easiest solution is to + omit the ``Meta.model`` attribute, since ``ModelAdmin`` will provide the + correct model to use. + .. method:: ModelAdmin.get_changelist_formset(self, request, **kwargs) Returns a :ref:`ModelFormSet <model-formsets>` class for use on the @@ -1341,6 +1369,7 @@ templates used by the :class:`ModelAdmin` views: return qs.filter(author=request.user) .. versionchanged:: 1.6 + The ``get_queryset`` method was previously named ``queryset``. .. method:: ModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False) @@ -1348,7 +1377,9 @@ templates used by the :class:`ModelAdmin` views: Sends a message to the user using the :mod:`django.contrib.messages` backend. See the :ref:`custom ModelAdmin example <custom-admin-action>`. - .. versionadded:: 1.5 + .. versionchanged:: 1.5 + + Keyword arguments were added in Django 1.5. Keyword arguments allow you to change the message level, add extra CSS tags, or fail silently if the ``contrib.messages`` framework is not @@ -1451,6 +1482,7 @@ in your own admin JavaScript without including a second copy, you can use the ``django.jQuery`` object on changelist and add/edit views. .. versionchanged:: 1.6 + The embedded jQuery has been upgraded from 1.4.2 to 1.9.1. The :class:`ModelAdmin` class requires jQuery by default, so there is no need @@ -1485,9 +1517,6 @@ needed. Now within your form you can add your own custom validation for any field:: class MyArticleAdminForm(forms.ModelForm): - class Meta: - model = Article - def clean_name(self): # do something that validates your data return self.cleaned_data["name"] diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 388172c43e..4fa119bc70 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -234,18 +234,18 @@ lookup:: .. versionadded:: 1.5 -Prior to Django 1.5, -:meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_model` and -:meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_models` -always returned the :class:`~django.contrib.contenttypes.models.ContentType` -associated with the concrete model of the specified one(s). That means there -was no way to retrieve the -:class:`~django.contrib.contenttypes.models.ContentType` of a proxy model -using those methods. As of Django 1.5 you can now pass a boolean flag – -``for_concrete_model`` and ``for_concrete_models`` respectively – to specify -wether or not you want to retrieve the -:class:`~django.contrib.contenttypes.models.ContentType` for the concrete or -direct model. + Prior to Django 1.5, + :meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_model` and + :meth:`~django.contrib.contenttypes.models.ContentTypeManager.get_for_models` + always returned the :class:`~django.contrib.contenttypes.models.ContentType` + associated with the concrete model of the specified one(s). That means there + was no way to retrieve the + :class:`~django.contrib.contenttypes.models.ContentType` of a proxy model + using those methods. As of Django 1.5 you can now pass a boolean flag – + ``for_concrete_model`` and ``for_concrete_models`` respectively – to specify + wether or not you want to retrieve the + :class:`~django.contrib.contenttypes.models.ContentType` for the concrete or + direct model. Generic relations ================= diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt index 97217e3c38..5e51e4cbf3 100644 --- a/docs/ref/contrib/gis/geoquerysets.txt +++ b/docs/ref/contrib/gis/geoquerysets.txt @@ -950,6 +950,7 @@ __ http://geohash.org/ *Availability*: PostGIS, SpatiaLite .. versionchanged:: 1.5 + ``geojson`` support for Spatialite > 3.0 has been added. Attaches a ``geojson`` attribute to every model in the queryset that contains the diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index 4d44638488..12e4e55165 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -845,7 +845,7 @@ include the SRID value (in other words, EWKB). .. class:: WKBWriter ``WKBWriter`` provides the most control over its output. By default it -returns OGC-compliant WKB when it's ``write`` method is called. However, +returns OGC-compliant WKB when its ``write`` method is called. However, it has properties that allow for the creation of EWKB, a superset of the WKB standard that includes additional information. diff --git a/docs/ref/contrib/gis/install/geolibs.txt b/docs/ref/contrib/gis/install/geolibs.txt index 74ebf6a35f..c9a1b405a3 100644 --- a/docs/ref/contrib/gis/install/geolibs.txt +++ b/docs/ref/contrib/gis/install/geolibs.txt @@ -194,7 +194,7 @@ Configure, make and install:: .. note:: - Because GeoDjango has it's own Python interface, the preceding instructions + Because GeoDjango has its own Python interface, the preceding instructions do not build GDAL's own Python bindings. The bindings may be built by adding the ``--with-python`` flag when running ``configure``. See `GDAL/OGR In Python`__ for more information on GDAL's bindings. diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index 139a9b377f..65838dfa3e 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -252,6 +252,7 @@ Enabling the sites framework ============================ .. versionchanged:: 1.6 + In previous versions, the sites framework was enabled by default. To enable the sites framework, follow these steps: diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 395abd90dd..7555acaaba 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -22,14 +22,14 @@ Persistent connections .. versionadded:: 1.6 Persistent connections avoid the overhead of re-establishing a connection to -the database in each request. By default, connections are kept open for up 10 -minutes — if not specified, :setting:`CONN_MAX_AGE` defaults to 600 seconds. +the database in each request. They're controlled by the +:setting:`CONN_MAX_AGE` parameter which defines the maximum lifetime of a +connection. It can be set independently for each database. -Django 1.5 and earlier didn't have persistent connections. To restore the -legacy behavior of closing the connection at the end of every request, set -:setting:`CONN_MAX_AGE` to ``0``. - -For unlimited persistent connections, set :setting:`CONN_MAX_AGE` to ``None``. +The default value is ``0``, preserving the historical behavior of closing the +database connection at the end of each request. To enable persistent +connections, set :setting:`CONN_MAX_AGE` to a positive number of seconds. For +unlimited persistent connections, set it to ``None``. Connection management ~~~~~~~~~~~~~~~~~~~~~ @@ -64,13 +64,22 @@ least as many simultaneous connections as you have worker threads. Sometimes a database won't be accessed by the majority of your views, for example because it's the database of an external system, or thanks to caching. -In such cases, you should set :setting:`CONN_MAX_AGE` to a lower value, or -even ``0``, because it doesn't make sense to maintain a connection that's -unlikely to be reused. This will help keep the number of simultaneous -connections to this database small. +In such cases, you should set :setting:`CONN_MAX_AGE` to a low value or even +``0``, because it doesn't make sense to maintain a connection that's unlikely +to be reused. This will help keep the number of simultaneous connections to +this database small. The development server creates a new thread for each request it handles, -negating the effect of persistent connections. +negating the effect of persistent connections. Don't enable them during +development. + +When Django establishes a connection to the database, it sets up appropriate +parameters, depending on the backend being used. If you enable persistent +connections, this setup is no longer repeated every request. If you modify +parameters such as the connection's isolation level or time zone, you should +either restore Django's defaults at the end of each request, force an +appropriate value at the beginning of each request, or disable persistent +connections. .. _postgresql-notes: @@ -182,6 +191,7 @@ Django supports MySQL 5.0.3 and higher. data on all database schema. Django's ``inspectdb`` feature uses it. .. versionchanged:: 1.5 + The minimum version requirement of MySQL 5.0.3 was set in Django 1.5. Django expects the database to support Unicode (UTF-8 encoding) and delegates to @@ -251,6 +261,18 @@ required for full MySQL support in Django. .. _MySQLdb: http://sourceforge.net/projects/mysql-python +Python 3 +-------- + +At the time of writing, the latest release of MySQLdb (1.2.4) doesn't support +Python 3. In order to use MySQL under Python 3, you'll have to install an +unofficial fork, such as `MySQL-for-Python-3`_. + +This port is still in alpha. In particular, it doesn't support binary data, +making it impossible to use :class:`django.db.models.BinaryField`. + +.. _MySQL-for-Python-3: https://github.com/clelland/MySQL-for-Python-3 + Creating your database ---------------------- @@ -360,8 +382,8 @@ Here's a sample configuration which uses a MySQL option file:: default-character-set = utf8 Several other MySQLdb connection options may be useful, such as ``ssl``, -``use_unicode``, ``init_command``, and ``sql_mode``. Consult the -`MySQLdb documentation`_ for more details. +``init_command``, and ``sql_mode``. Consult the `MySQLdb documentation`_ for +more details. .. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html .. _MySQLdb documentation: http://mysql-python.sourceforge.net/ diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 1d3f1b8d1d..ec49705add 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -98,6 +98,7 @@ Can be run as a cronjob or directly to clean out old data from the database (only expired sessions at the moment). .. versionchanged:: 1.5 + :djadmin:`cleanup` is deprecated. Use :djadmin:`clearsessions` instead. compilemessages @@ -122,7 +123,7 @@ Example usage:: .. versionchanged:: 1.6 -Added the ability to specify multiple locales. + Added the ability to specify multiple locales. createcachetable ---------------- @@ -173,6 +174,7 @@ The :djadminopt:`--all` option may be provided to display all settings, even if they have Django's default value. Such settings are prefixed by ``"###"``. .. versionadded:: 1.6 + The :djadminopt:`--all` option was added. dumpdata <appname appname appname.Model ...> @@ -307,8 +309,8 @@ database to introspect. .. versionchanged:: 1.6 -The behavior by which introspected models are created as unmanaged ones is new -in Django 1.6. + The behavior by which introspected models are created as unmanaged ones is new + in Django 1.6. loaddata <fixture fixture ...> ------------------------------ @@ -467,7 +469,7 @@ You can also use commas to separate multiple locales:: .. versionchanged:: 1.6 -Added the ability to specify multiple locales. + Added the ability to specify multiple locales. .. django-admin-option:: --domain @@ -778,8 +780,6 @@ use the ``--plain`` option, like so:: django-admin.py shell --plain -.. versionchanged:: 1.5 - If you would like to specify either IPython or bpython as your interpreter if you have both installed you can specify an alternative interpreter interface with the ``-i`` or ``--interface`` options like so: @@ -807,9 +807,13 @@ behavior you can use the ``--no-startup`` option. e.g.:: django-admin.py shell --plain --no-startup +.. versionadded:: 1.5 + + The ``--interface`` option was added in Django 1.5. + .. versionadded:: 1.6 -The ``--no-startup`` option was added in Django 1.6. + The ``--no-startup`` option was added in Django 1.6. sql <appname appname ...> ------------------------- @@ -1353,6 +1357,7 @@ for any other exception. If you specify ``--traceback``, ``django-admin.py`` will also output a full stack trace when a ``CommandError`` is raised. .. versionchanged:: 1.6 + Previously, Django didn't show a full stack trace by default for exceptions other than ``CommandError``. diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index 93bb9ed251..f9a1715180 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -138,6 +138,7 @@ the underlying database exceptions. See :pep:`249`, the Python Database API Specification v2.0, for further information. .. versionchanged:: 1.6 + Previous version of Django only wrapped ``DatabaseError`` and ``IntegrityError``. diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index c8b8044d26..29f889445d 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -467,6 +467,11 @@ For each field, we describe the default widget used if you don't specify The ``max_value`` and ``min_value`` error messages may contain ``%(limit_value)s``, which will be substituted by the appropriate limit. + .. versionchanged:: 1.6 + + Similarly, the ``max_digits``, ``max_decimal_places`` and + ``max_whole_digits`` error messages may contain ``%(max)s``. + Takes four optional arguments: .. attribute:: max_value @@ -1010,9 +1015,16 @@ objects (in the case of ``ModelMultipleChoiceField``) into the ``invalid_pk_value`` .. versionchanged:: 1.5 + The empty and normalized values were changed to be consistently ``QuerySets`` instead of ``[]`` and ``QuerySet`` respectively. + .. versionchanged:: 1.6 + + The ``invalid_choice`` message may contain ``%(value)s`` and the + ``invalid_pk_value`` message may contain ``%(pk)s``, which will be + substituted by the appropriate values. + Allows the selection of one or more model objects, suitable for representing a many-to-many relation. As with :class:`ModelChoiceField`, you can use ``label_from_instance`` to customize the object diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt index dd0a422fd0..9b3480758a 100644 --- a/docs/ref/forms/models.txt +++ b/docs/ref/forms/models.txt @@ -25,6 +25,14 @@ Model Form Functions See :ref:`modelforms-factory` for example usage. + .. versionchanged:: 1.6 + + You must provide the list of fields explicitly, either via keyword arguments + ``fields`` or ``exclude``, or the corresponding attributes on the form's + inner ``Meta`` class. See :ref:`modelforms-selecting-fields` for more + information. Omitting any definition of the fields to use will result in all + fields being used, but this behaviour is deprecated. + .. function:: modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False) Returns a ``FormSet`` class for the given ``model`` class. @@ -42,7 +50,7 @@ Model Form Functions .. versionchanged:: 1.6 - The ``widgets`` and the ``validate_max`` parameters were added. + The ``widgets`` and the ``validate_max`` parameters were added. .. function:: inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False) @@ -57,4 +65,4 @@ Model Form Functions .. versionchanged:: 1.6 - The ``widgets`` and the ``validate_max`` parameters were added. + The ``widgets`` and the ``validate_max`` parameters were added. diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 978c985b55..3aaa69b6ea 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -359,7 +359,7 @@ considering aren't valid, we must remember to remove them from the .. versionchanged:: 1.5 -Django used to remove the ``cleaned_data`` attribute entirely if there were -any errors in the form. Since version 1.5, ``cleaned_data`` is present even if -the form doesn't validate, but it contains only field values that did -validate. + Django used to remove the ``cleaned_data`` attribute entirely if there were + any errors in the form. Since version 1.5, ``cleaned_data`` is present even if + the form doesn't validate, but it contains only field values that did + validate. diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 514e8b3dc0..678f2e6949 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -522,6 +522,7 @@ Selector and checkbox widgets ``True`` if the checkbox should be checked for that value. .. versionchanged:: 1.5 + Exceptions from ``check_test`` used to be silenced by its caller, this is no longer the case, they will propagate upwards. diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index 20bb2fb751..03885a2215 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -206,6 +206,7 @@ Transaction middleware .. class:: TransactionMiddleware .. versionchanged:: 1.6 + ``TransactionMiddleware`` is deprecated. The documentation of transactions contains :ref:`upgrade instructions <transactions-upgrading-from-1.5>`. diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 7ef251c907..d322904ec9 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -378,6 +378,7 @@ If you need to accept :attr:`~Field.null` values then use :class:`NullBooleanField` instead. .. versionchanged:: 1.6 + The default value of ``BooleanField`` was changed from ``False`` to ``None`` when :attr:`Field.default` isn't defined. @@ -956,8 +957,8 @@ Like all :class:`CharField` subclasses, :class:`URLField` takes the optional .. versionadded:: 1.5 -The current value of the field will be displayed as a clickable link above the -input widget. + The current value of the field will be displayed as a clickable link above the + input widget. Relationship fields diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 9f583c42ac..b4b162a9ea 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -297,8 +297,9 @@ follows this algorithm: didn't update anything, Django executes an ``INSERT``. .. versionchanged:: 1.6 - Previously Django used ``SELECT`` - if not found ``INSERT`` else ``UPDATE`` - algorithm. The old algorithm resulted in one more query in ``UPDATE`` case. + + Previously Django used ``SELECT`` - if not found ``INSERT`` else ``UPDATE`` + algorithm. The old algorithm resulted in one more query in ``UPDATE`` case. The one gotcha here is that you should be careful not to specify a primary-key value explicitly when saving new objects, if you cannot guarantee the diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 9c1337d59f..d27214a66c 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -554,11 +554,13 @@ Returns a ``DateQuerySet`` — a ``QuerySet`` that evaluates to a list of particular kind within the contents of the ``QuerySet``. .. versionchanged:: 1.6 + ``dates`` used to return a list of :class:`datetime.datetime` objects. ``field`` should be the name of a ``DateField`` of your model. .. versionchanged:: 1.6 + ``dates`` used to accept operating on a ``DateTimeField``. ``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each @@ -625,7 +627,8 @@ object. If it's ``None``, Django uses the :ref:`current time zone - SQLite: install pytz_ — conversions are actually performed in Python. - PostgreSQL: no requirements (see `Time Zones`_). - Oracle: no requirements (see `Choosing a Time Zone File`_). - - MySQL: load the time zone tables with `mysql_tzinfo_to_sql`_. + - MySQL: install pytz_ and load the time zone tables with + `mysql_tzinfo_to_sql`_. .. _pytz: http://pytz.sourceforge.net/ .. _Time Zones: http://www.postgresql.org/docs/current/static/datatype-datetime.html#DATATYPE-TIMEZONES @@ -1121,11 +1124,11 @@ to ``defer()``:: .. versionchanged:: 1.5 -Some fields in a model won't be deferred, even if you ask for them. You can -never defer the loading of the primary key. If you are using -:meth:`select_related()` to retrieve related models, you shouldn't defer the -loading of the field that connects from the primary model to the related -one, doing so will result in an error. + Some fields in a model won't be deferred, even if you ask for them. You can + never defer the loading of the primary key. If you are using + :meth:`select_related()` to retrieve related models, you shouldn't defer the + loading of the field that connects from the primary model to the related + one, doing so will result in an error. .. note:: @@ -1193,20 +1196,20 @@ logically:: # existing set of fields). Entry.objects.defer("body").only("headline", "body") -.. versionchanged:: 1.5 - All of the cautions in the note for the :meth:`defer` documentation apply to ``only()`` as well. Use it cautiously and only after exhausting your other -options. Also note that using :meth:`only` and omitting a field requested -using :meth:`select_related` is an error as well. +options. .. versionchanged:: 1.5 -.. note:: + Using :meth:`only` and omitting a field requested using + :meth:`select_related` is an error as well. - When calling :meth:`~django.db.models.Model.save()` for instances with - deferred fields, only the loaded fields will be saved. See - :meth:`~django.db.models.Model.save()` for more details. + .. note:: + + When calling :meth:`~django.db.models.Model.save()` for instances with + deferred fields, only the loaded fields will be saved. See + :meth:`~django.db.models.Model.save()` for more details. using ~~~~~ @@ -1424,6 +1427,7 @@ query. The default is to create all objects in one batch, except for SQLite where the default is such that at maximum 999 variables per query is used. .. versionadded:: 1.5 + The ``batch_size`` parameter was added in version 1.5. count @@ -1725,7 +1729,8 @@ methods on your models. It does, however, emit the (including cascaded deletions). .. versionadded:: 1.5 - Allow fast-path deletion of objects + + Allow fast-path deletion of objects. Django needs to fetch objects into memory to send signals and handle cascades. However, if there are no cascades and no signals, then Django may take a diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 0f62741c5d..2fac7f2f9c 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -94,6 +94,7 @@ All attributes should be considered read-only, unless stated otherwise below. :attr:`HttpRequest.body` attribute instead. .. versionchanged:: 1.5 + Before Django 1.5, HttpRequest.POST contained non-form data. It's possible that a request can come in via POST with an empty ``POST`` @@ -563,19 +564,19 @@ streaming response if (and only if) no middleware accesses the .. versionchanged:: 1.5 -This technique is fragile and was deprecated in Django 1.5. If you need the -response to be streamed from the iterator to the client, you should use the -:class:`StreamingHttpResponse` class instead. + This technique is fragile and was deprecated in Django 1.5. If you need the + response to be streamed from the iterator to the client, you should use the + :class:`StreamingHttpResponse` class instead. -As of Django 1.7, when :class:`HttpResponse` is instantiated with an -iterator, it will consume it immediately, store the response content as a -string, and discard the iterator. + As of Django 1.7, when :class:`HttpResponse` is instantiated with an + iterator, it will consume it immediately, store the response content as a + string, and discard the iterator. .. versionchanged:: 1.5 -You can now use :class:`HttpResponse` as a file-like object even if it was -instantiated with an iterator. Django will consume and save the content of -the iterator on first access. + You can now use :class:`HttpResponse` as a file-like object even if it was + instantiated with an iterator. Django will consume and save the content of + the iterator on first access. Setting headers ~~~~~~~~~~~~~~~ diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 1fc9d2ff92..04b42aeeb2 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -67,7 +67,7 @@ A list of strings representing the host/domain names that this Django site can serve. This is a security measure to prevent an attacker from poisoning caches and password reset emails with links to malicious hosts by submitting requests with a fake HTTP ``Host`` header, which is possible even under many -seemingly-safe webserver configurations. +seemingly-safe web server configurations. Values in this list can be fully qualified names (e.g. ``'www.example.com'``), in which case they will be matched against the request's ``Host`` header @@ -79,6 +79,20 @@ responsible to provide your own validation of the ``Host`` header (perhaps in a middleware; if so this middleware must be listed first in :setting:`MIDDLEWARE_CLASSES`). +.. note:: + + If you want to also allow the `fully qualified domain name (FQDN)`_, which + some browsers can send in the Host header, you must explicitly add another + ALLOWED_HOSTS entry that includes a trailing period. This entry can also be + a subdomain wildcard:: + + ALLOWED_HOSTS = [ + '.example.com', # Allow domain and subdomains + '.example.com.', # Also allow FQDN and subdomains + ] + +.. _`fully qualified domain name (FQDN)`: http://en.wikipedia.org/wiki/Fully_qualified_domain_name + If the ``Host`` header (or ``X-Forwarded-Host`` if :setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this list, the :meth:`django.http.HttpRequest.get_host()` method will raise @@ -495,7 +509,7 @@ CONN_MAX_AGE .. versionadded:: 1.6 -Default: ``600`` +Default: ``0`` The lifetime of a database connection, in seconds. Use ``0`` to close database connections at the end of each request — Django's historical behavior — and @@ -1265,9 +1279,9 @@ see the current list of translated languages by looking in .. _online source: https://github.com/django/django/blob/master/django/conf/global_settings.py -The list is a tuple of two-tuples in the format -(:term:`language code<language code>`, ``language name``) -- for example, -``('ja', 'Japanese')``. +The list is a tuple of two-tuples in the format +(:term:`language code<language code>`, ``language name``) -- for example, +``('ja', 'Japanese')``. This specifies which languages are available for language selection. See :doc:`/topics/i18n/index`. @@ -1486,6 +1500,7 @@ randomly-generated ``SECRET_KEY`` to each new project. execution vulnerabilities. .. versionchanged:: 1.5 + Django will now refuse to start if :setting:`SECRET_KEY` is not set. .. setting:: SECURE_PROXY_SSL_HEADER @@ -1771,7 +1786,7 @@ See also :setting:`DATE_INPUT_FORMATS` and :setting:`DATETIME_INPUT_FORMATS`. .. versionchanged:: 1.6 -Input format with microseconds has been added. + Input format with microseconds has been added. .. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior @@ -2055,11 +2070,11 @@ decorator, for example. .. versionchanged:: 1.5 -This setting now also accepts view function names and -:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce -configuration duplication since you no longer have to define the URL in two -places (``settings`` and URLconf). -For backward compatibility reasons the default remains unchanged. + This setting now also accepts view function names and + :ref:`named URL patterns <naming-url-patterns>` which can be used to reduce + configuration duplication since you no longer have to define the URL in two + places (``settings`` and URLconf). + For backward compatibility reasons the default remains unchanged. .. setting:: LOGIN_URL @@ -2073,11 +2088,11 @@ The URL where requests are redirected for login, especially when using the .. versionchanged:: 1.5 -This setting now also accepts view function names and -:ref:`named URL patterns <naming-url-patterns>` which can be used to reduce -configuration duplication since you no longer have to define the URL in two -places (``settings`` and URLconf). -For backward compatibility reasons the default remains unchanged. + This setting now also accepts view function names and + :ref:`named URL patterns <naming-url-patterns>` which can be used to reduce + configuration duplication since you no longer have to define the URL in two + places (``settings`` and URLconf). + For backward compatibility reasons the default remains unchanged. .. setting:: LOGOUT_URL diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index 5c13ec7d96..cdefe2fae8 100644 --- a/docs/ref/template-response.txt +++ b/docs/ref/template-response.txt @@ -78,13 +78,13 @@ Methods .. versionchanged:: 1.5 - Historically, this parameter was only called ``mimetype`` (now - deprecated), but since this is actually the value included in the HTTP - ``Content-Type`` header, it can also include the character set - encoding, which makes it more than just a MIME type specification. If - ``mimetype`` is specified (not ``None``), that value is used. - Otherwise, ``content_type`` is used. If neither is given, - :setting:`DEFAULT_CONTENT_TYPE` is used. + Historically, this parameter was only called ``mimetype`` (now + deprecated), but since this is actually the value included in the HTTP + ``Content-Type`` header, it can also include the character set + encoding, which makes it more than just a MIME type specification. If + ``mimetype`` is specified (not ``None``), that value is used. + Otherwise, ``content_type`` is used. If neither is given, + :setting:`DEFAULT_CONTENT_TYPE` is used. .. method:: SimpleTemplateResponse.resolve_context(context) diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 0162f78eed..677aa13cbb 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -272,6 +272,7 @@ Every context contains ``True``, ``False`` and ``None``. As you would expect, these variables resolve to the corresponding Python objects. .. versionadded:: 1.5 + Before Django 1.5, these variables weren't a special case, and they resolved to ``None`` unless you defined them in the context. diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 123e114c4a..287fd4f59e 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -176,7 +176,7 @@ just declare the cycle, but not output the first value, you can add a This will output a list of ``<tr>`` elements with ``class`` alternating between ``row1`` and ``row2``; the subtemplate will have -access to ``rowcolors`` in it's context that matches the class of the +access to ``rowcolors`` in its context that matches the class of the ``<tr>`` that encloses it. If the ``silent`` keyword were to be omitted, ``row1`` would be emitted as normal text, outside the ``<tr>`` element. @@ -191,19 +191,19 @@ call to ``{% cycle %}`` doesn't specify silent:: .. versionchanged:: 1.6 -To improve safety, future versions of ``cycle`` will automatically escape -their output. You're encouraged to activate this behavior by loading -``cycle`` from the ``future`` template library:: + To improve safety, future versions of ``cycle`` will automatically escape + their output. You're encouraged to activate this behavior by loading + ``cycle`` from the ``future`` template library:: - {% load cycle from future %} + {% load cycle from future %} -When using the ``future`` version, you can disable auto-escaping with:: + When using the ``future`` version, you can disable auto-escaping with:: - {% for o in some_list %} - <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}"> - ... - </tr> - {% endfor %} + {% for o in some_list %} + <tr class="{% autoescape off %}{% cycle rowvalue1 rowvalue2 %}{% endautoescape %}"> + ... + </tr> + {% endfor %} .. templatetag:: debug @@ -294,21 +294,21 @@ to escape the variables in the firstof tag, you must do so explicitly:: .. versionchanged:: 1.6 -To improve safety, future versions of ``firstof`` will automatically escape -their output. You're encouraged to activate this behavior by loading -``firstof`` from the ``future`` template library:: + To improve safety, future versions of ``firstof`` will automatically escape + their output. You're encouraged to activate this behavior by loading + ``firstof`` from the ``future`` template library:: - {% load firstof from future %} + {% load firstof from future %} -When using the ``future`` version, you can disable auto-escaping with:: + When using the ``future`` version, you can disable auto-escaping with:: - {% autoescape off %} - {% firstof var1 var2 var3 "<strong>fallback value</strong>" %} - {% endautoescape %} + {% autoescape off %} + {% firstof var1 var2 var3 "<strong>fallback value</strong>" %} + {% endautoescape %} -Or if only some variables should be escaped, you can use:: + Or if only some variables should be escaped, you can use:: - {% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %} + {% firstof var1 var2|safe var3 "<strong>fallback value</strong>"|safe %} .. templatetag:: for @@ -657,11 +657,6 @@ The arguments can be hard-coded strings, so the following is valid:: ... {% endifequal %} -It is only possible to compare an argument to template variables or strings. -You cannot check for equality with Python objects such as ``True`` or -``False``. If you need to test if something is true or false, use the -:ttag:`if` tag instead. - An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator. @@ -1065,6 +1060,7 @@ by the context as to the current application. Don't forget to put quotes around the function path or pattern name! .. versionchanged:: 1.5 + The first parameter used not to be quoted, which was inconsistent with other template tags. Since Django 1.5, it is evaluated according to the usual rules: it can be a quoted string or a variable that will be diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index bd5bdc96a9..e5074285e4 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -47,26 +47,26 @@ You can use Unicode strings, or you can use normal strings (sometimes called .. versionchanged:: 1.5 -In Python 3, the logic is reversed, that is normal strings are Unicode, and -when you want to specifically create a bytestring, you have to prefix the -string with a 'b'. As we are doing in Django code from version 1.5, -we recommend that you import ``unicode_literals`` from the __future__ library -in your code. Then, when you specifically want to create a bytestring literal, -prefix the string with 'b'. + In Python 3, the logic is reversed, that is normal strings are Unicode, and + when you want to specifically create a bytestring, you have to prefix the + string with a 'b'. As we are doing in Django code from version 1.5, + we recommend that you import ``unicode_literals`` from the __future__ library + in your code. Then, when you specifically want to create a bytestring literal, + prefix the string with 'b'. -Python 2 legacy:: + Python 2 legacy:: - my_string = "This is a bytestring" - my_unicode = u"This is an Unicode string" + my_string = "This is a bytestring" + my_unicode = u"This is an Unicode string" -Python 2 with unicode literals or Python 3:: + Python 2 with unicode literals or Python 3:: - from __future__ import unicode_literals + from __future__ import unicode_literals - my_string = b"This is a bytestring" - my_unicode = "This is an Unicode string" + my_string = b"This is a bytestring" + my_unicode = "This is an Unicode string" -See also :doc:`Python 3 compatibility </topics/python3>`. + See also :doc:`Python 3 compatibility </topics/python3>`. .. warning:: diff --git a/docs/ref/views.txt b/docs/ref/views.txt index 3753f83f07..8c9c3e3ed8 100644 --- a/docs/ref/views.txt +++ b/docs/ref/views.txt @@ -18,7 +18,7 @@ convenience, you'd like to have Django serve for you in local development. The :func:`~django.views.static.serve` view can be used to serve any directory you give it. (This view is **not** hardened for production use and should be used only as a development aid; you should serve these files in production -using a real front-end webserver). +using a real front-end web server). The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`. ``django.contrib.staticfiles`` is intended for static assets and has no diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt index be61311232..65ecde2fea 100644 --- a/docs/releases/1.0.txt +++ b/docs/releases/1.0.txt @@ -66,6 +66,7 @@ We can't possibly document everything that's new in 1.0, but the documentation will be your definitive guide. Anywhere you see something like: .. versionadded:: 1.0 + This feature is new in Django 1.0 You'll know that you're looking at something new or changed. diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index c71736dc60..42947d9a44 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/docs/releases/1.3-alpha-1.txt @@ -87,7 +87,7 @@ To access this library, Django provides the ``django.utils.unittest`` module alias. If you are using Python 2.7, or you have installed unittest2 locally, Django will map the alias to the installed version of the unittest library. Otherwise, -Django will use it's own bundled version of unittest2. +Django will use its own bundled version of unittest2. To use this alias, simply use:: diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 2f06756a1b..9cce36aac3 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -66,13 +66,8 @@ Persistent database connections Django now supports reusing the same database connection for several requests. This avoids the overhead of re-establishing a connection at the beginning of -each request. - -By default, database connections will kept open for 10 minutes. This behavior -is controlled by the :setting:`CONN_MAX_AGE` setting. To restore the previous -behavior of closing the connection at the end of each request, set -:setting:`CONN_MAX_AGE` to ``0``. See :ref:`persistent-database-connections` -for details. +each request. For backwards compatibility, this feature is disabled by +default. See :ref:`persistent-database-connections` for details. Time zone aware aggregation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -298,21 +293,6 @@ Django 1.6 introduces ``hour``, ``minute``, and ``second`` lookups on ``hour``, ``minute``, or ``second``, the new lookups will clash with you field names. Append an explicit :lookup:`exact` lookup if this is an issue. -Persistent database connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Connection setup not repeated for each request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When Django establishes a connection to the database, it sets up appropriate -parameters, depending on the backend being used. Since `persistent database -connections <persistent-database-connections>`_ are enabled by default in -Django 1.6, this setup isn't repeated at every request any more. If you -modifiy parameters such as the connection's isolation level or time zone, you -should either restore Django's defaults at the end of each request, force an -appropriate value at the beginning of each request, or disable persistent -connections. - ``BooleanField`` no longer defaults to ``False`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -423,6 +403,13 @@ Miscellaneous ``type='email'``, ``type='url'`` or ``type='number'`` depending on their corresponding field type. +* Form field's :attr:`~django.forms.Field.error_messages` that contain a + placeholder should now always use a named placeholder (``"Value '%(value)s' is + too big"`` instead of ``"Value '%s' is too big"``). See the corresponding + field documentation for details about the names of the placeholders. The + changes in 1.6 particularly affect :class:`~django.forms.DecimalField` and + :class:`~django.forms.ModelMultipleChoiceField`. + Features deprecated in 1.6 ========================== @@ -545,3 +532,55 @@ including it in an URLconf, simply replace:: with:: (r'^prefix/(?P<content_type_id>\d+)/(?P<object_id>.*)/$', 'django.contrib.contenttypes.views.shortcut'), + +``ModelForm`` without ``fields`` or ``exclude`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, if you wanted a :class:`~django.forms.ModelForm` to use all fields on +the model, you could simply omit the ``Meta.fields`` attribute, and all fields +would be used. + +This can lead to security problems where fields are added to the model and, +unintentionally, automatically become editable by end users. In some cases, +particular with boolean fields, it is possible for this problem to be completely +invisible. This is a form of `Mass assignment vulnerability +<http://en.wikipedia.org/wiki/Mass_assignment_vulnerability>`_. + +For this reason, this behaviour is deprecated, and using the ``Meta.exclude`` +option is strongly discouraged. Instead, all fields that are intended for +inclusion in the form should be listed explicitly in the ``fields`` attribute. + +If this security concern really does not apply in your case, there is a shortcut +to explicitly indicate that all fields should be used - use the special value +``"__all__"`` for the fields attribute:: + + class MyModelForm(ModelForm): + class Meta: + fields = "__all__" + model = MyModel + +If you have custom ``ModelForms`` that only need to be used in the admin, there +is another option. The admin has its own methods for defining fields +(``fieldsets`` etc.), and so adding a list of fields to the ``ModelForm`` is +redundant. Instead, simply omit the ``Meta`` inner class of the ``ModelForm``, +or omit the ``Meta.model`` attribute. Since the ``ModelAdmin`` subclass knows +which model it is for, it can add the necessary attributes to derive a +functioning ``ModelForm``. This behaviour also works for earlier Django +versions. + +``UpdateView`` and ``CreateView`` without explicit fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The generic views :class:`~django.views.generic.edit.CreateView` and +:class:`~django.views.generic.edit.UpdateView`, and anything else derived from +:class:`~django.views.generic.edit.ModelFormMixin`, are vulnerable to the +security problem described in the section above, because they can automatically +create a ``ModelForm`` that uses all fields for a model. + +For this reason, if you use these views for editing models, you must also supply +the ``fields`` attribute, which is a list of model fields and works in the same +way as the :class:`~django.forms.ModelForm` ``Meta.fields`` attribute. Alternatively, +you can set set the ``form_class`` attribute to a ``ModelForm`` that explicitly +defines the fields to be used. Defining an ``UpdateView`` or ``CreateView`` +subclass to be used with a model but without an explicit list of fields is +deprecated. diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index 143a729f37..b53bbe8211 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -83,9 +83,9 @@ processing at the first positive match. .. versionadded:: 1.6 -If a backend raises a :class:`~django.core.exceptions.PermissionDenied` -exception, authentication will immediately fail. Django won't check the -backends that follow. + If a backend raises a :class:`~django.core.exceptions.PermissionDenied` + exception, authentication will immediately fail. Django won't check the + backends that follow. Writing an authentication backend --------------------------------- @@ -1051,6 +1051,7 @@ code would be required in the app's ``admin.py`` file:: class Meta: model = MyUser + fields = ['email', 'password', 'date_of_birth', 'is_active', 'is_admin'] def clean_password(self): # Regardless of what the user provides, return the initial value. diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index a38ee84841..e666cded75 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -435,10 +435,10 @@ The login_required decorator .. versionchanged:: 1.5 - The :setting:`settings.LOGIN_URL <LOGIN_URL>` also accepts - view function names and :ref:`named URL patterns <naming-url-patterns>`. - This allows you to freely remap your login view within your URLconf - without having to update the setting. + The :setting:`settings.LOGIN_URL <LOGIN_URL>` also accepts + view function names and :ref:`named URL patterns <naming-url-patterns>`. + This allows you to freely remap your login view within your URLconf + without having to update the setting. .. note:: @@ -759,6 +759,7 @@ patterns. mail will be sent either. .. versionchanged:: 1.6 + Previously, error messages indicated whether a given email was registered. @@ -1041,6 +1042,7 @@ Thus, you can check permissions in template ``{% if %}`` statements: {% endif %} .. versionadded:: 1.5 + Permission lookup by "if in". It is possible to also look permissions up by ``{% if in %}`` statements. diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt index 8cd34f8ad9..86c5280159 100644 --- a/docs/topics/class-based-views/generic-editing.txt +++ b/docs/topics/class-based-views/generic-editing.txt @@ -114,9 +114,11 @@ here; we don't have to write any logic ourselves:: class AuthorCreate(CreateView): model = Author + fields = ['name'] class AuthorUpdate(UpdateView): model = Author + fields = ['name'] class AuthorDelete(DeleteView): model = Author @@ -126,6 +128,17 @@ here; we don't have to write any logic ourselves:: We have to use :func:`~django.core.urlresolvers.reverse_lazy` here, not just ``reverse`` as the urls are not loaded when the file is imported. +.. versionchanged:: 1.6 + +In Django 1.6, the ``fields`` attribute was added, which works the same way as +the ``fields`` attribute on the inner ``Meta`` class on +:class:`~django.forms.ModelForm`. + +Omitting the fields attribute will work as previously, but is deprecated and +this attribute will be required from 1.8 (unless you define the form class in +another way). + + Finally, we hook these new views into the URLconf:: # urls.py @@ -177,33 +190,17 @@ the foreign key relation to the model:: # ... -Create a custom :class:`~django.forms.ModelForm` in order to exclude the -``created_by`` field and prevent the user from editing it: - -.. code-block:: python - - # forms.py - from django import forms - from myapp.models import Author - - class AuthorForm(forms.ModelForm): - class Meta: - model = Author - exclude = ('created_by',) - -In the view, use the custom -:attr:`~django.views.generic.edit.FormMixin.form_class` and override -:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the -user:: +In the view, ensure that you exclude ``created_by`` in the list of fields to +edit, and override +:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the user:: # views.py from django.views.generic.edit import CreateView from myapp.models import Author - from myapp.forms import AuthorForm class AuthorCreate(CreateView): - form_class = AuthorForm model = Author + fields = ['name'] def form_valid(self, form): form.instance.created_by = self.request.user @@ -237,19 +234,24 @@ works for AJAX requests as well as 'normal' form POSTs:: return HttpResponse(data, **response_kwargs) def form_invalid(self, form): + response = super(AjaxableResponseMixin, self).form_invalid(form) if self.request.is_ajax(): return self.render_to_json_response(form.errors, status=400) else: - return super(AjaxableResponseMixin, self).form_invalid(form) + return response def form_valid(self, form): + # We make sure to call the parent's form_valid() method because + # it might do some processing (in the case of CreateView, it will + # call form.save() for example). + response = super(AjaxableResponseMixin, self).form_valid(form) if self.request.is_ajax(): data = { - 'pk': form.instance.pk, + 'pk': self.object.pk, } return self.render_to_json_response(data) else: - return super(AjaxableResponseMixin, self).form_valid(form) + return response class AuthorCreate(AjaxableResponseMixin, CreateView): model = Author diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt index 56bdd16e84..2a0f7e4ce0 100644 --- a/docs/topics/db/managers.txt +++ b/docs/topics/db/managers.txt @@ -176,6 +176,7 @@ your choice of default manager in order to avoid a situation where overriding work with. .. versionchanged:: 1.6 + The ``get_queryset`` method was previously named ``get_query_set``. .. _managers-for-related-objects: diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index 182099cc3a..ac329cc4fc 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -681,6 +681,7 @@ In addition, some objects are automatically created just after database). .. versionchanged:: 1.5 + Previously, ``ContentType`` and ``Permission`` instances were created only in the default database. diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index f19302974d..2553eac27a 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -638,6 +638,7 @@ that were modified more than 3 days after they were published:: >>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3)) .. versionadded:: 1.5 + ``.bitand()`` and ``.bitor()`` The ``F()`` objects now support bitwise operations by ``.bitand()`` and @@ -646,6 +647,7 @@ The ``F()`` objects now support bitwise operations by ``.bitand()`` and >>> F('somefield').bitand(16) .. versionchanged:: 1.5 + The previously undocumented operators ``&`` and ``|`` no longer produce bitwise operations, use ``.bitand()`` and ``.bitor()`` instead. @@ -1110,15 +1112,6 @@ above example code would look like this:: >>> b.entries.filter(headline__contains='Lennon') >>> b.entries.count() -You cannot access a reverse :class:`~django.db.models.ForeignKey` -:class:`~django.db.models.Manager` from the class; it must be accessed from an -instance:: - - >>> Blog.entry_set - Traceback: - ... - AttributeError: "Manager must be accessed via instance". - In addition to the :class:`~django.db.models.query.QuerySet` methods defined in "Retrieving objects" above, the :class:`~django.db.models.ForeignKey` :class:`~django.db.models.Manager` has additional methods used to handle the diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index 34cfa382d3..2ec31a4988 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -211,7 +211,7 @@ For example:: from django.db import connection - def my_custom_sql(): + def my_custom_sql(self): cursor = connection.cursor() cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz]) @@ -222,6 +222,7 @@ For example:: return row .. versionchanged:: 1.6 + In Django 1.5 and earlier, after performing a data changing operation, you had to call ``transaction.commit_unless_managed()`` to ensure your changes were committed to the database. Since Django now defaults to database-level diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt index d48365dc9e..255584c68b 100644 --- a/docs/topics/db/transactions.txt +++ b/docs/topics/db/transactions.txt @@ -22,6 +22,7 @@ integrity of ORM operations that require multiple queries, especially <topics-db-queries-update>` queries. .. versionchanged:: 1.6 + Previous version of Django featured :ref:`a more complicated default behavior <transactions-upgrading-from-1.5>`. @@ -73,11 +74,12 @@ To disable this behavior for a specific view, you must set the In practice, this feature simply wraps every view function in the :func:`atomic` decorator described below. -Note that only the execution of your view in enclosed in the transactions. -Middleware run outside of the transaction, and so does the rendering of +Note that only the execution of your view is enclosed in the transactions. +Middleware runs outside of the transaction, and so does the rendering of template responses. .. versionchanged:: 1.6 + Django used to provide this feature via ``TransactionMiddleware``, which is now deprecated. @@ -204,6 +206,7 @@ To avoid this, you can :ref:`deactivate the transaction management <deactivate-transaction-management>`, but it isn't recommended. .. versionchanged:: 1.6 + Before Django 1.6, autocommit was turned off, and it was emulated by forcing a commit after write operations in the ORM. @@ -224,6 +227,7 @@ where you want to run your own transaction-controlling middleware or do something really strange. .. versionchanged:: 1.6 + This used to be controlled by the ``TRANSACTIONS_MANAGED`` setting. Low-level APIs @@ -312,10 +316,10 @@ rollback that would be performed by ``transaction.rollback()``. .. versionchanged:: 1.6 -When the :func:`atomic` decorator is nested, it creates a savepoint to allow -partial commit or rollback. You're strongly encouraged to use :func:`atomic` -rather than the functions described below, but they're still part of the -public API, and there's no plan to deprecate them. + When the :func:`atomic` decorator is nested, it creates a savepoint to allow + partial commit or rollback. You're strongly encouraged to use :func:`atomic` + rather than the functions described below, but they're still part of the + public API, and there's no plan to deprecate them. Each of these functions takes a ``using`` argument which should be the name of a database for which the behavior applies. If no ``using`` argument is @@ -354,20 +358,20 @@ The following example demonstrates the use of savepoints:: @transaction.atomic def viewfunc(request): - a.save() - # transaction now contains a.save() + a.save() + # transaction now contains a.save() - sid = transaction.savepoint() + sid = transaction.savepoint() - b.save() - # transaction now contains a.save() and b.save() + b.save() + # transaction now contains a.save() and b.save() - if want_to_keep_b: - transaction.savepoint_commit(sid) - # open transaction still contains a.save() and b.save() - else: - transaction.savepoint_rollback(sid) - # open transaction now contains only a.save() + if want_to_keep_b: + transaction.savepoint_commit(sid) + # open transaction still contains a.save() and b.save() + else: + transaction.savepoint_rollback(sid) + # open transaction now contains only a.save() Database-specific notes ======================= diff --git a/docs/topics/files.txt b/docs/topics/files.txt index c05f98ef7e..fb3cdd4af9 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -94,7 +94,7 @@ The following approach may be used to close files automatically:: True Closing files is especially important when accessing file fields in a loop -over a large number of objects:: If files are not manually closed after +over a large number of objects. If files are not manually closed after accessing them, the risk of running out of file descriptors may arise. This may lead to the following error:: diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index 269ac5b4b6..9d77cd5274 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -111,6 +111,7 @@ affect validation. If ``validate_max=True`` is passed to the validation. See :ref:`validate_max`. .. versionchanged:: 1.6 + The ``validate_max`` parameter was added to :func:`~django.forms.formsets.formset_factory`. Also, the behavior of ``FormSet`` was brought in line with that of ``ModelFormSet`` so that it @@ -310,6 +311,7 @@ should use custom formset validation. using forged POST requests. .. versionchanged:: 1.6 + The ``validate_max`` parameter was added to :func:`~django.forms.formsets.formset_factory`. diff --git a/docs/topics/forms/media.txt b/docs/topics/forms/media.txt index 98e70e5e77..c0d63bb8cf 100644 --- a/docs/topics/forms/media.txt +++ b/docs/topics/forms/media.txt @@ -146,7 +146,7 @@ basic Calendar widget from the example above:: <script type="text/javascript" src="http://static.example.com/actions.js"></script> <script type="text/javascript" src="http://static.example.com/whizbang.js"></script> -The FancyCalendar widget inherits all the media from it's parent widget. If +The FancyCalendar widget inherits all the media from its parent widget. If you don't want media to be inherited in this way, add an ``extend=False`` declaration to the media declaration:: diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index eaf2bbbaf2..e58dade736 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -28,6 +28,7 @@ For example:: >>> class ArticleForm(ModelForm): ... class Meta: ... model = Article + ... fields = ['pub_date', 'headline', 'content', 'reporter'] # Creating a form to add an article. >>> form = ArticleForm() @@ -39,11 +40,13 @@ For example:: Field types ----------- -The generated ``Form`` class will have a form field for every model field. Each -model field has a corresponding default form field. For example, a -``CharField`` on a model is represented as a ``CharField`` on a form. A -model ``ManyToManyField`` is represented as a ``MultipleChoiceField``. Here is -the full list of conversions: +The generated ``Form`` class will have a form field for every model field +specified, in the order specified in the ``fields`` attribute. + +Each model field has a corresponding default form field. For example, a +``CharField`` on a model is represented as a ``CharField`` on a form. A model +``ManyToManyField`` is represented as a ``MultipleChoiceField``. Here is the +full list of conversions: =============================== ======================================== Model field Form field @@ -168,10 +171,13 @@ Consider this set of models:: class AuthorForm(ModelForm): class Meta: model = Author + fields = ['name', 'title', 'birth_date'] class BookForm(ModelForm): class Meta: model = Book + fields = ['name', 'authors'] + With these models, the ``ModelForm`` subclasses above would be roughly equivalent to this (the only difference being the ``save()`` method, which @@ -288,47 +294,66 @@ method is used to determine whether a form requires multipart file upload (and hence whether ``request.FILES`` must be passed to the form), etc. See :ref:`binding-uploaded-files` for more information. -Using a subset of fields on the form ------------------------------------- +.. _modelforms-selecting-fields: -In some cases, you may not want all the model fields to appear on the generated -form. There are three ways of telling ``ModelForm`` to use only a subset of the -model fields: +Selecting the fields to use +--------------------------- -1. Set ``editable=False`` on the model field. As a result, *any* form - created from the model via ``ModelForm`` will not include that - field. +It is strongly recommended that you explicitly set all fields that should be +edited in the form using the ``fields`` attribute. Failure to do so can easily +lead to security problems when a form unexpectedly allows a user to set certain +fields, especially when new fields are added to a model. Depending on how the +form is rendered, the problem may not even be visible on the web page. -2. Use the ``fields`` attribute of the ``ModelForm``'s inner ``Meta`` - class. This attribute, if given, should be a list of field names - to include in the form. The order in which the fields names are specified - in that list is respected when the form renders them. +The alternative approach would be to include all fields automatically, or +blacklist only some. This fundamental approach is known to be much less secure +and has led to serious exploits on major websites (e.g. `GitHub +<https://github.com/blog/1068-public-key-security-vulnerability-and-mitigation>`_). -3. Use the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta`` - class. This attribute, if given, should be a list of field names - to exclude from the form. +There are, however, two shortcuts available for cases where you can guarantee +these security concerns do not apply to you: -For example, if you want a form for the ``Author`` model (defined -above) that includes only the ``name`` and ``birth_date`` fields, you would -specify ``fields`` or ``exclude`` like this:: +1. Set the ``fields`` attribute to the special value ``'__all__'`` to indicate + that all fields in the model should be used. For example:: - class PartialAuthorForm(ModelForm): - class Meta: - model = Author - fields = ('name', 'birth_date') + class AuthorForm(ModelForm): + class Meta: + model = Author + fields = '__all__' - class PartialAuthorForm(ModelForm): - class Meta: - model = Author - exclude = ('title',) +2. Set the ``exclude`` attribute of the ``ModelForm``'s inner ``Meta`` class to + a list of fields to be excluded from the form. + + For example:: + + class PartialAuthorForm(ModelForm): + class Meta: + model = Author + exclude = ['title'] + + Since the ``Author`` model has the 3 fields ``name``, ``title`` and + ``birth_date``, this will result in the fields ``name`` and ``birth_date`` + being present on the form. + +If either of these are used, the order the fields appear in the form will be the +order the fields are defined in the model, with ``ManyToManyField`` instances +appearing last. + +In addition, Django applies the following rule: if you set ``editable=False`` on +the model field, *any* form created from the model via ``ModelForm`` will not +include that field. + +.. versionchanged:: 1.6 + + Before version 1.6, the ``'__all__'`` shortcut did not exist, but omitting + the ``fields`` attribute had the same effect. Omitting both ``fields`` and + ``exclude`` is now deprecated, but will continue to work as before until + version 1.8 -Since the Author model has only 3 fields, 'name', 'title', and -'birth_date', the forms above will contain exactly the same fields. .. note:: - If you specify ``fields`` or ``exclude`` when creating a form with - ``ModelForm``, then the fields that are not in the resulting form + Any fields not included in a form by the above logic will not be set by the form's ``save()`` method. Also, if you manually add the excluded fields back to the form, they will not be initialized from the model instance. @@ -401,15 +426,19 @@ field, you could do the following:: class Meta: model = Article + fields = ['pub_date', 'headline', 'content', 'reporter'] + If you want to override a field's default label, then specify the ``label`` parameter when declaring the form field:: - >>> class ArticleForm(ModelForm): - ... pub_date = DateField(label='Publication date') - ... - ... class Meta: - ... model = Article + class ArticleForm(ModelForm): + pub_date = DateField(label='Publication date') + + class Meta: + model = Article + fields = ['pub_date', 'headline', 'content', 'reporter'] + .. note:: @@ -436,6 +465,7 @@ parameter when declaring the form field:: class Meta: model = Article + fields = ['headline', 'content'] You must ensure that the type of the form field can be used to set the contents of the corresponding model field. When they are not compatible, @@ -444,30 +474,6 @@ parameter when declaring the form field:: See the :doc:`form field documentation </ref/forms/fields>` for more information on fields and their arguments. -Changing the order of fields ----------------------------- - -By default, a ``ModelForm`` will render fields in the same order that they are -defined on the model, with ``ManyToManyField`` instances appearing last. If -you want to change the order in which fields are rendered, you can use the -``fields`` attribute on the ``Meta`` class. - -The ``fields`` attribute defines the subset of model fields that will be -rendered, and the order in which they will be rendered. For example given this -model:: - - class Book(models.Model): - author = models.ForeignKey(Author) - title = models.CharField(max_length=100) - -the ``author`` field would be rendered first. If we wanted the title field -to be rendered first, we could specify the following ``ModelForm``:: - - >>> class BookForm(ModelForm): - ... class Meta: - ... model = Book - ... fields = ('title', 'author') - .. _overriding-modelform-clean-method: Overriding the clean() method @@ -550,21 +556,19 @@ definition. This may be more convenient if you do not have many customizations to make:: >>> from django.forms.models import modelform_factory - >>> BookForm = modelform_factory(Book) + >>> BookForm = modelform_factory(Book, fields=("author", "title")) This can also be used to make simple modifications to existing forms, for -example by specifying which fields should be displayed:: - - >>> Form = modelform_factory(Book, form=BookForm, fields=("author",)) - -... or which fields should be excluded:: - - >>> Form = modelform_factory(Book, form=BookForm, exclude=("title",)) - -You can also specify the widgets to be used for a given field:: +example by specifying the widgets to be used for a given field:: >>> from django.forms import Textarea - >>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()}) + >>> Form = modelform_factory(Book, form=BookForm, + widgets={"title": Textarea()}) + +The fields to include can be specified using the ``fields`` and ``exclude`` +keyword arguments, or the corresponding attributes on the ``ModelForm`` inner +``Meta`` class. Please see the ``ModelForm`` :ref:`modelforms-selecting-fields` +documentation. .. _model-formsets: @@ -688,11 +692,10 @@ database. If a given instance's data didn't change in the bound data, the instance won't be saved to the database and won't be included in the return value (``instances``, in the above example). -When fields are missing from the form (for example because they have -been excluded), these fields will not be set by the ``save()`` -method. You can find more information about this restriction, which -also holds for regular ``ModelForms``, in `Using a subset of fields on -the form`_. +When fields are missing from the form (for example because they have been +excluded), these fields will not be set by the ``save()`` method. You can find +more information about this restriction, which also holds for regular +``ModelForms``, in `Selecting the fields to use`_. Pass ``commit=False`` to return the unsaved model instances:: diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt index 18243c77ce..503d4322e0 100644 --- a/docs/topics/http/middleware.txt +++ b/docs/topics/http/middleware.txt @@ -204,6 +204,7 @@ Dealing with streaming responses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionchanged:: 1.5 + ``response`` may also be an :class:`~django.http.StreamingHttpResponse` object. diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index f5c688e254..acad61eb2a 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -71,6 +71,7 @@ default cache. To use another cache, set :setting:`SESSION_CACHE_ALIAS` to the name of that cache. .. versionchanged:: 1.5 + The :setting:`SESSION_CACHE_ALIAS` setting was added. Once your cache is configured, you've got two choices for how to store data in @@ -451,6 +452,7 @@ Similarly, the ``expires`` part of a session cookie is updated each time the session cookie is sent. .. versionchanged:: 1.5 + The session is not saved if the response's status code is 500. .. _browser-length-vs-persistent-sessions: diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 961f0b9d96..52a2935977 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -51,6 +51,7 @@ Optional arguments the :setting:`DEFAULT_CONTENT_TYPE` setting. .. versionchanged:: 1.5 + This parameter used to be called ``mimetype``. ``status`` @@ -129,6 +130,7 @@ Optional arguments the :setting:`DEFAULT_CONTENT_TYPE` setting. .. versionchanged:: 1.5 + This parameter used to be called ``mimetype``. diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 811425d229..2ce9d8d2bc 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -1030,11 +1030,11 @@ prepend the current active language code to all url patterns defined within from django.conf.urls import patterns, include, url from django.conf.urls.i18n import i18n_patterns - urlpatterns = patterns('' + urlpatterns = patterns('', url(r'^sitemap\.xml$', 'sitemap.view', name='sitemap_xml'), ) - news_patterns = patterns('' + news_patterns = patterns('', url(r'^$', 'news.views.index', name='index'), url(r'^category/(?P<slug>[\w-]+)/$', 'news.views.category', name='category'), url(r'^(?P<slug>[\w-]+)/$', 'news.views.details', name='detail'), @@ -1529,6 +1529,7 @@ selection based on data from the request. It customizes content for each user. ``'django.middleware.locale.LocaleMiddleware'``. .. versionchanged:: 1.6 + In previous versions, ``LocaleMiddleware`` wasn't enabled by default. Because middleware order matters, you should follow these guidelines: diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt index cb22a57e84..a31dc01cc5 100644 --- a/docs/topics/logging.txt +++ b/docs/topics/logging.txt @@ -169,7 +169,7 @@ issued on the ``project.interesting`` and ``project.interesting.stuff`` loggers. This propagation can be controlled on a per-logger basis. If -you don't want a particular logger to propagate to it's parents, you +you don't want a particular logger to propagate to its parents, you can turn off this behavior. Making logging calls diff --git a/docs/topics/pagination.txt b/docs/topics/pagination.txt index 17747c22ff..9da71563c3 100644 --- a/docs/topics/pagination.txt +++ b/docs/topics/pagination.txt @@ -252,7 +252,7 @@ Methods .. versionchanged:: 1.5 - Raises :exc:`InvalidPage` if next page doesn't exist. + Raises :exc:`InvalidPage` if next page doesn't exist. .. method:: Page.previous_page_number() @@ -260,7 +260,7 @@ Methods .. versionchanged:: 1.5 - Raises :exc:`InvalidPage` if previous page doesn't exist. + Raises :exc:`InvalidPage` if previous page doesn't exist. .. method:: Page.start_index() diff --git a/docs/topics/python3.txt b/docs/topics/python3.txt index 33f5fcd4c0..22e609c75c 100644 --- a/docs/topics/python3.txt +++ b/docs/topics/python3.txt @@ -317,6 +317,9 @@ Division def __idiv__(self, other): # Python 2 compatibility return type(self).__itruediv__(self, other) +Special methods are looked up on the class and not on the instance to reflect +the behavior of the Python interpreter. + .. module: django.utils.six Writing compatible code with six diff --git a/docs/topics/security.txt b/docs/topics/security.txt index 566202eefa..22135a72ea 100644 --- a/docs/topics/security.txt +++ b/docs/topics/security.txt @@ -168,7 +168,7 @@ certain cases. While these values are sanitized to prevent Cross Site Scripting attacks, a fake ``Host`` value can be used for Cross-Site Request Forgery, cache poisoning attacks, and poisoning links in emails. -Because even seemingly-secure webserver configurations are susceptible to fake +Because even seemingly-secure web server configurations are susceptible to fake ``Host`` headers, Django validates ``Host`` headers against the :setting:`ALLOWED_HOSTS` setting in the :meth:`django.http.HttpRequest.get_host()` method. @@ -181,15 +181,15 @@ For more details see the full :setting:`ALLOWED_HOSTS` documentation. .. warning:: - Previous versions of this document recommended configuring your webserver to + Previous versions of this document recommended configuring your web server to ensure it validates incoming HTTP ``Host`` headers. While this is still - recommended, in many common webservers a configuration that seems to + recommended, in many common web servers a configuration that seems to validate the ``Host`` header may not in fact do so. For instance, even if Apache is configured such that your Django site is served from a non-default virtual host with the ``ServerName`` set, it is still possible for an HTTP request to match this virtual host and supply a fake ``Host`` header. Thus, Django now requires that you set :setting:`ALLOWED_HOSTS` explicitly rather - than relying on webserver configuration. + than relying on web server configuration. Additionally, as of 1.3.1, Django requires you to explicitly enable support for the ``X-Forwarded-Host`` header (via the :setting:`USE_X_FORWARDED_HOST` diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index ce39f6cd28..cb34117997 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -124,8 +124,8 @@ Calling ``DeserializedObject.save()`` saves the object to the database. .. versionchanged:: 1.6 -In previous versions of Django, the ``pk`` attribute had to be present -on the serialized data or a ``DeserializationError`` would be raised. + In previous versions of Django, the ``pk`` attribute had to be present + on the serialized data or a ``DeserializationError`` would be raised. This ensures that deserializing is a non-destructive operation even if the data in your serialized representation doesn't match what's currently in the @@ -144,11 +144,11 @@ The Django object itself can be inspected as ``deserialized_object.object``. .. versionadded:: 1.5 -If fields in the serialized data do not exist on a model, -a ``DeserializationError`` will be raised unless the ``ignorenonexistent`` -argument is passed in as True:: + If fields in the serialized data do not exist on a model, + a ``DeserializationError`` will be raised unless the ``ignorenonexistent`` + argument is passed in as True:: - serializers.deserialize("xml", data, ignorenonexistent=True) + serializers.deserialize("xml", data, ignorenonexistent=True) .. _serialization-formats: diff --git a/docs/topics/signals.txt b/docs/topics/signals.txt index d611da4a37..a97fb2f14f 100644 --- a/docs/topics/signals.txt +++ b/docs/topics/signals.txt @@ -134,7 +134,7 @@ to. .. versionchanged:: 1.5 -The ability to pass a list of signals was added. + The ability to pass a list of signals was added. .. admonition:: Where should this code live? diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt index 26dc8ee1ae..5f2fa65bed 100644 --- a/docs/topics/testing/advanced.txt +++ b/docs/topics/testing/advanced.txt @@ -163,10 +163,12 @@ environment first. Django provides a convenience method to do this:: >>> from django.test.utils import setup_test_environment >>> setup_test_environment() -This convenience method sets up the test database, and puts other -Django features into modes that allow for repeatable testing. +:func:`~django.test.utils.setup_test_environment` puts several Django features +into modes that allow for repeatable testing, but does not create the test +databases; :func:`django.test.simple.DjangoTestSuiteRunner.setup_databases` +takes care of that. -The call to :meth:`~django.test.utils.setup_test_environment` is made +The call to :func:`~django.test.utils.setup_test_environment` is made automatically as part of the setup of ``./manage.py test``. You only need to manually invoke this method if you're not using running your tests via Django's test runner. @@ -282,7 +284,9 @@ Methods .. method:: DjangoTestSuiteRunner.setup_test_environment(**kwargs) - Sets up the test environment ready for testing. + Sets up the test environment by calling + :func:`~django.test.utils.setup_test_environment` and setting + :setting:`DEBUG` to ``False``. .. method:: DjangoTestSuiteRunner.build_suite(test_labels, extra_tests=None, **kwargs) @@ -340,6 +344,9 @@ Methods Testing utilities ----------------- +django.test.utils +~~~~~~~~~~~~~~~~~ + .. module:: django.test.utils :synopsis: Helpers to write custom test runners. @@ -358,10 +365,13 @@ utility methods in the ``django.test.utils`` module. magic hooks into the template system and restoring normal email services. +django.db.connection.creation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. currentmodule:: django.db.connection.creation -The creation module of the database backend (``connection.creation``) -also provides some utilities that can be useful during testing. +The creation module of the database backend also provides some utilities that +can be useful during testing. .. function:: create_test_db([verbosity=1, autoclobber=False]) diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 259c39618b..9228a07b31 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -25,7 +25,7 @@ module defines tests in class-based approach. adding some extremely useful features. To ensure that every Django project can benefit from these new features, Django ships with a copy of unittest2_, a copy of the Python 2.7 unittest library, - backported for Python 2.5 compatibility. + backported for Python 2.6 compatibility. To access this library, Django provides the ``django.utils.unittest`` module alias. If you are using Python @@ -235,6 +235,7 @@ the Django test runner reorders tests in the following way: restoring it to its original state are run. .. versionchanged:: 1.5 + Before Django 1.5, the only guarantee was that :class:`~django.test.TestCase` tests were always ran first, before any other tests. @@ -612,6 +613,7 @@ Use the ``django.test.client.Client`` class to make requests. a ``Content-Type`` header is set to ``content_type``. .. versionchanged:: 1.5 + :meth:`Client.options` used to process ``data`` like :meth:`Client.get`. @@ -627,6 +629,7 @@ Use the ``django.test.client.Client`` class to make requests. a ``Content-Type`` header is set to ``content_type``. .. versionchanged:: 1.5 + :meth:`Client.put` used to process ``data`` like :meth:`Client.post`. @@ -650,6 +653,7 @@ Use the ``django.test.client.Client`` class to make requests. a ``Content-Type`` header is set to ``content_type``. .. versionchanged:: 1.5 + :meth:`Client.delete` used to process ``data`` like :meth:`Client.get`. @@ -940,6 +944,7 @@ to test the effects of commit and rollback: the test has been properly updated. .. versionchanged:: 1.5 + The order in which tests are run has changed. See `Order in which tests are executed`_. @@ -990,6 +995,7 @@ additions, including: errors. .. versionchanged:: 1.5 + The order in which tests are run has changed. See `Order in which tests are executed`_. @@ -1581,6 +1587,7 @@ your test suite. ``False``, which turns the comparison into a Python set comparison. .. versionchanged:: 1.6 + The method now checks for undefined order and raises ``ValueError`` if undefined order is spotted. The ordering is seen as undefined if the given ``qs`` isn't ordered and the comparison is against more |