[soc2009/model-validation] Merget to trunk at r12009

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@12014 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/internals/contributing.txt

@@ -426,6 +426,47 @@ translated, here's what to do:
 
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
 
+Django conventions
+==================
+
+Various Django-specific code issues are detailed in this section.
+
+Use of ``django.conf.settings``
+-------------------------------
+
+Modules should not in general use settings stored in ``django.conf.settings`` at
+the top level (i.e. evaluated when the module is imported). The explanation for
+this is as follows:
+
+Manual configuration of settings (i.e. not relying on the
+``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
+follows::
+
+    from django.conf import settings
+
+    settings.configure({}, SOME_SETTING='foo')
+
+However, if any setting is accessed before the ``settings.configure`` line, this
+will not work. (Internally, ``setttings`` is a ``LazyObject`` which configures
+itself automatically when the settings are accessed if it has not already been
+configured).
+
+So, if there is a module containing some code as follows::
+
+    from django.conf import settings
+    from django.core.urlresolvers import get_callable
+
+    default_foo_view = get_callable(settings.FOO_VIEW)
+
+...then importing this module will cause the settings object to be configured.
+That means that the ability for third parties to import the module at the top
+level is incompatible with the ability to configure the settings object
+manually, or makes it very difficult in some circumstances.
+
+Instead of the above code, a level of laziness or indirection must be used, such
+as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or
+``lambda``.
+
 Coding style
 ============
 
@@ -752,27 +793,53 @@ To run the tests, ``cd`` to the ``tests/`` directory and type:
     ./runtests.py --settings=path.to.django.settings
 
 Yes, the unit tests need a settings module, but only for database connection
-info, with the ``DATABASE_ENGINE`` setting.
+info. Your :setting:`DATABASES` setting needs to define two databases:
 
-If you're using the ``sqlite3`` database backend, no further settings are
-needed. A temporary database will be created in memory when running the tests.
+    * A ``default`` database. This database should use the backend that
+      you want to use for primary testing
 
-If you're using another backend:
+    * A database with the alias ``other``. The ``other`` database is
+      used to establish that queries can be directed to different
+      databases. As a result, this database can use any backend you
+      want. It doesn't need to use the same backend as the ``default``
+      database (although it can use the same backend if you want to).
 
-    * Your :setting:`DATABASE_USER` setting needs to specify an existing user account
-      for the database engine.
+If you're using the SQLite database backend, you need to define
+:setting:`ENGINE` for both databases, plus a
+:setting:`TEST_NAME` for the ``other`` database. The
+following is a minimal settings file that can be used to test SQLite::
 
-    * The :setting:`DATABASE_NAME` setting must be the name of an existing database to
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.sqlite3'
+        },
+        'other': {
+            'ENGINE': 'django.db.backends.sqlite3',
+            'TEST_NAME': 'other_db'
+        }
+    }
+
+
+If you're using another backend, you will need to provide other details for
+each database:
+
+    * The :setting:`USER` option for each of your databases needs to
+      specify an existing user account for the database.
+
+    * The :setting:`PASSWORD` option needs to provide the password for
+      the :setting:`USER` that has been specified.
+
+    * The :setting:`NAME` option must be the name of an existing database to
       which the given user has permission to connect. The unit tests will not
       touch this database; the test runner creates a new database whose name is
-      :setting:`DATABASE_NAME` prefixed with ``test_``, and this test database is
+      :setting:`NAME` prefixed with ``test_``, and this test database is
       deleted when the tests are finished. This means your user account needs
       permission to execute ``CREATE DATABASE``.
 
 You will also need to ensure that your database uses UTF-8 as the default
 character set. If your database server doesn't use UTF-8 as a default charset,
-you will need to include a value for ``TEST_DATABASE_CHARSET`` in your settings
-file.
+you will need to include a value for ``TEST_CHARSET`` in the settings
+dictionary for the applicable database.
 
 If you want to run the full suite of tests, you'll need to install a number of
 dependencies:
@@ -782,7 +849,8 @@ dependencies:
     *  Textile_
     *  Docutils_
     *  setuptools_
-    *  memcached_, plus the either the python-memcached_ or cmemcached_ Python binding
+    *  memcached_, plus the either the python-memcached_ or cmemcached_
+       Python binding
 
 If you want to test the memcached cache backend, you will also need to define
 a :setting:`CACHE_BACKEND` setting that points at your memcached instance.
@@ -797,7 +865,7 @@ associated tests will be skipped.
 .. _setuptools: http://pypi.python.org/pypi/setuptools/
 .. _memcached: http://www.danga.com/memcached/
 .. _python-memcached: http://pypi.python.org/pypi/python-memcached/
-.. _cmemcached: http://pypi.python.org/pypi/cmemcache
+.. _cmemcached: http://gijsbert.org/cmemcache/index.html
 
 To run a subset of the unit tests, append the names of the test modules to the
 ``runtests.py`` command line. See the list of directories in
@@ -892,9 +960,9 @@ for feature branches:
        If you want a feature branch in SVN, you'll need to ask in
        `django-developers`_ for a mentor.
 
-.. _git: http://git.or.cz/
-.. _mercurial: http://www.selenic.com/mercurial/
-.. _bazaar: http://bazaar-vcs.org/
+.. _git: http://git-scm.com/
+.. _mercurial: http://mercurial.selenic.com/
+.. _bazaar: http://bazaar.canonical.com/
 .. _django branches: http://code.djangoproject.com/wiki/DjangoBranches
 
 Branch rules
@@ -1026,7 +1094,7 @@ If you're using Django 0.95 or earlier and installed it using
 file. Then copy the branch's version of the ``django`` directory into
 ``site-packages``.
 
-.. _path file: http://docs.python.org/lib/module-site.html
+.. _path file: http://docs.python.org/library/site.html
 
 Deciding on features
 ====================
@@ -1092,6 +1160,6 @@ requests for commit access are potential flame-war starters, and will be ignored
 .. _django-users: http://groups.google.com/group/django-users
 .. _`#django`: irc://irc.freenode.net/django
 .. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
-.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py
+.. _pep8.py: http://pypi.python.org/pypi/pep8/
 .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
 .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases

docs/internals/deprecation.txt

@@ -13,6 +13,10 @@ their deprecation, as per the :ref:`Django deprecation policy
           hooking up admin URLs.  This has been deprecated since the 1.1
           release.
 
+        * Authentication backends need to define the boolean attribute
+          ``supports_object_permissions``. The old backend style is deprecated
+          since the 1.2 release.
+
     * 1.4
         * ``CsrfResponseMiddleware``.  This has been deprecated since the 1.2
           release, in favour of the template tag method for inserting the CSRF
@@ -26,7 +30,49 @@ their deprecation, as per the :ref:`Django deprecation policy
           class in favor of a generic E-mail backend API.
 
         * The many to many SQL generation functions on the database backends
-          will be removed.  These have been deprecated since the 1.2 release.
+          will be removed.
+
+        * The ability to use the ``DATABASE_*`` family of top-level settings to
+          define database connections will be removed.
+
+        * The ability to use shorthand notation to specify a database backend
+          (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
+          removed.
+
+        * The ``get_db_prep_save``, ``get_db_prep_value`` and
+          ``get_db_prep_lookup`` methods on Field were modified in 1.2 to support
+          multiple databases. In 1.4, the support functions that allow methods
+          with the old prototype to continue working will be removed.
+
+        * The ``Message`` model (in ``django.contrib.auth``), its related
+          manager in the ``User`` model (``user.message_set``), and the
+          associated methods (``user.message_set.create()`` and
+          ``user.get_and_delete_messages()``), which have
+          been deprecated since the 1.2 release, will be removed.  The
+          :ref:`messages framework <ref-contrib-messages>` should be used
+          instead.
+
+        * Authentication backends need to support the ``obj`` parameter for
+          permission checking. The ``supports_object_permissions`` variable
+          is not checked any longer and can be removed.
+
+        * The ability to specify a callable template loader rather than a
+          ``Loader`` class will be removed, as will the ``load_template_source``
+          functions that are included with the built in template loaders for
+          backwards compatibility. These have been deprecated since the 1.2
+          release.
+
+        * ``django.utils.translation.get_date_formats()`` and
+          ``django.utils.translation.get_partial_date_formats()``. These
+          functions are replaced by the new locale aware formatting; use
+          ``django.utils.formats.get_format()`` to get the appropriate
+          formats.
+
+        * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``,
+          ``DEFAULT_TIME_INPUT_FORMATS`` and
+          ``DEFAULT_DATETIME_INPUT_FORMATS``. Use
+          ``django.utils.formats.get_format()`` to get the appropriate
+          formats.
 
     * 2.0
         * ``django.views.defaults.shortcut()``. This function has been moved

docs/internals/documentation.txt

@@ -10,7 +10,7 @@ based on docutils__. The basic idea is that lightly-formatted plain-text
 documentation is transformed into HTML, PDF, and any other output format.
 
 __ http://sphinx.pocoo.org/
-__ http://docutils.sf.net/
+__ http://docutils.sourceforge.net/
 
 To actually build the documentation locally, you'll currently need to install
 Sphinx -- ``easy_install Sphinx`` should do the trick.
@@ -130,15 +130,6 @@ TODO
 
 The work is mostly done, but here's what's left, in rough order of priority.
 
-    * Change the "Added/changed in development version" callouts to proper
-      Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives.
-
-    * Check for and fix malformed links. Do this by running ``make linkcheck``
-      and fix all of the 300+ errors/warnings.
-
-      In particular, look at all the relative links; these need to be
-      changed to proper references.
-
     * Most of the various ``index.txt`` documents have *very* short or even
       non-existent intro text. Each of those documents needs a good short intro
       the content below that point.