gis: Merged revisions 6394-6441 via svnmerge from [repos:django/trunk trunk].

git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@6442 bcc190cf-cafb-0310-a4f2-bffc1f526a37

9 files changed, 201 insertions, 13 deletions

diff --git a/docs/databases.txt b/docs/databases.txt
index 21ff4c7434..4d8824aa3d 100644
--- a/docs/databases.txt
+++ b/docs/databases.txt
@@ -163,3 +163,118 @@ storage engine, you have a couple of options.
 
 .. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB
 
+
+Oracle Notes
+============
+
+Django supports `Oracle Database Server`_ versions 9i and higher.  Oracle
+version 10g or later is required to use Django's ``regex`` and ``iregex`` query
+operators.  You will also need the `cx_Oracle`_ driver, version 4.3.1 or newer.
+
+.. _`Oracle Database Server`: http://www.oracle.com/
+.. _`cx_Oracle`: http://cx-oracle.sourceforge.net/
+
+To run ``python manage.py syncdb``, you'll need to create an Oracle database
+user with CREATE TABLE, CREATE SEQUENCE, and CREATE PROCEDURE privileges.  To
+run Django's test suite, the user also needs CREATE and DROP DATABASE and
+CREATE and DROP TABLESPACE privileges.
+
+Connecting to the Database
+--------------------------
+
+Your Django settings.py file should look something like this for Oracle::
+
+    DATABASE_ENGINE = 'oracle'
+    DATABASE_NAME = 'xe'
+    DATABASE_USER = 'a_user'
+    DATABASE_PASSWORD = 'a_password'
+    DATABASE_HOST = ''
+    DATABASE_PORT = ''
+
+If you don't use a ``tnsnames.ora`` file or a similar naming method that
+recognizes the SID ("xe" in this example), then fill in both ``DATABASE_HOST``
+and ``DATABASE_PORT`` like so::
+
+    DATABASE_ENGINE = 'oracle'
+    DATABASE_NAME = 'xe'
+    DATABASE_USER = 'a_user'
+    DATABASE_PASSWORD = 'a_password'
+    DATABASE_HOST = 'dbprod01ned.mycompany.com'
+    DATABASE_PORT = '1540'
+
+You should supply both ``DATABASE_HOST`` and ``DATABASE_PORT``, or leave both
+as empty strings.
+
+Tablespace Options
+------------------
+
+A common paradigm for optimizing performance in Oracle-based systems is the
+use of `tablespaces`_ to organize disk layout. The Oracle backend supports
+this use case by adding ``db_tablespace`` options to the ``Meta`` and
+``Field`` classes.  (When using a backend that lacks support for tablespaces,
+these options are ignored.)
+
+.. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace
+
+A tablespace can be specified for the table(s) generated by a model by
+supplying the ``db_tablespace`` option inside the model's ``Meta`` class.
+Additionally, the ``db_tablespace`` option can be passed to a ``Field``
+constructor to specify an alternate tablespace for the ``Field``'s column
+index.  If no index would be created for the column, the ``db_tablespace``
+option is ignored.
+
+::
+
+    class TablespaceExample(models.Model):
+        name = models.CharField(maxlength=30, db_index=True, db_tablespace="indexes")
+        data = models.CharField(maxlength=255, db_index=True)
+        edges = models.ManyToManyField(to="self", db_tablespace="indexes")
+
+        class Meta:
+            db_tablespace = "tables"
+
+In this example, the tables generated by the ``TablespaceExample`` model
+(i.e., the model table and the many-to-many table) would be stored in the
+``tables`` tablespace.  The index for the name field and the indexes on the
+many-to-many table would be stored in the ``indexes`` tablespace.  The ``data``
+field would also generate an index, but no tablespace for it is specified, so
+it would be stored in the model tablespace ``tables`` by default.
+
+Django does not create the tablespaces for you.  Please refer to `Oracle's
+documentation`_ for details on creating and managing tablespaces.
+
+.. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403
+
+Naming Issues
+-------------
+
+Oracle imposes a name length limit of 30 characters.  To accommodate this, the
+backend truncates database identifiers to fit, replacing the final four
+characters of the truncated name with a repeatable MD5 hash value.
+
+NULL and Empty Strings
+----------------------
+
+Django generally prefers to use the empty string ('') rather than NULL, but
+Oracle treats both identically.  To get around this, the Oracle backend
+coerces the ``null=True`` option on fields that permit the empty string as a
+value.  When fetching from the database, it is assumed that a NULL value in
+one of these fields really means the empty string, and the data is silently
+converted to reflect this assumption.
+
+TextField Limitations
+---------------------
+
+The Oracle backend stores ``TextFields`` as ``NCLOB`` columns.  Oracle imposes
+some limitations on the usage of such LOB columns in general:
+
+  * LOB columns may not be used as primary keys.
+
+  * LOB columns may not be used in indexes.
+
+  * LOB columns may not be used in a ``SELECT DISTINCT`` list.  This means that
+    attempting to use the ``QuerySet.distinct`` method on a model that
+    includes ``TextField`` columns will result in an error when run against
+    Oracle.  A workaround to this is to keep ``TextField`` columns out of any
+    models that you foresee performing ``.distinct`` queries on, and to
+    include the ``TextField`` in a related model instead.
diff --git a/docs/db-api.txt b/docs/db-api.txt
index 08b5391e3c..adca8b4d5c 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -952,7 +952,7 @@ Example::
 If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary.
 
 ``iterator()``
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
 Evaluates the ``QuerySet`` (by performing the query) and returns an
 `iterator`_ over the results. A ``QuerySet`` typically reads all of
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index 0f99987bad..f098dfa988 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -735,3 +735,32 @@ distribution. It enables tab-completion of ``django-admin.py`` and
     * Press [TAB] to see all available options.
     * Type ``sql``, then [TAB], to see all available options whose names start
       with ``sql``.
+
+Customized actions
+==================
+
+**New in Django development version**
+
+If you want to add an action of your own to ``manage.py``, you can.
+Simply add a ``management/commands`` directory to your application.
+Each python module in that directory will be discovered and registered as
+a command that can be executed as an action when you run ``manage.py``::
+
+    /fancy_blog
+        __init__.py
+        models.py
+        /management
+            __init__.py
+            /commands
+                __init__.py
+                explode.py
+        views.py
+        
+In this example, ``explode`` command will be made available to any project
+that includes the ``fancy_blog`` application in ``settings.INSTALLED_APPS``.
+
+The ``explode.py`` module has only one requirement -- it must define a class
+called ``Command`` that extends ``django.core.management.base.BaseCommand``.
+
+For more details on how to define your own commands, look at the code for the
+existing ``django-admin.py`` commands, in ``/django/core/management/commands``.
diff --git a/docs/email.txt b/docs/email.txt
index 2bad79ce33..effc5e24cf 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -317,7 +317,7 @@ To send a text and HTML combination, you could write::
     subject, from_email, to = 'hello', 'from@example.com', 'to@example.com'
     text_content = 'This is an important message.'
     html_content = '<p>This is an <strong>important</strong> message.</p>'
-    msg = EmailMultiAlternatives(subject, text_content, from_email, to)
+    msg = EmailMultiAlternatives(subject, text_content, from_email, [to])
     msg.attach_alternative(html_content, "text/html")
     msg.send()
 
diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index 87b82f7adf..08ff01c372 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -800,9 +800,14 @@ specify the page number in the URL in one of two ways:
       variable. You can iterate over the list provided by ``page_range`` 
       to create a link to every page of results.
 
-These values and lists are is 1-based, not 0-based, so the first page would be
+These values and lists are 1-based, not 0-based, so the first page would be
 represented as page ``1``. 
 
+An example of the use of pagination can be found in the `object pagination`_
+example model. 
+	 
+.. _`object pagination`: ../models/pagination/
+
 **New in Django development version:** 
 
 As a special case, you are also permitted to use 
diff --git a/docs/install.txt b/docs/install.txt
index 2de8529d24..95aa82b2e3 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -66,6 +66,7 @@ installed.
 * If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher.
 
 * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher.
+  You will also want to read the database-specific notes for the `Oracle backend`_.
 
 If you plan to use Django's ``manage.py syncdb`` command to
 automatically create database tables for your models, you'll need to
@@ -88,6 +89,7 @@ to create a temporary test database.
 .. _MySQL backend: ../databases/
 .. _cx_Oracle: http://cx-oracle.sourceforge.net/
 .. _Oracle: http://www.oracle.com/
+.. _Oracle backend: ../databases/#oracle-notes
 .. _testing framework: ../testing/
 
 Remove any old versions of Django
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 2c8f67ce32..11e19e847f 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1923,11 +1923,22 @@ of the model fields:
 .. note::
 
     If you specify ``fields`` when creating a form with ``form_for_model()``,
-    make sure that the fields that are *not* specified can provide default
-    values, or are allowed to have a value of ``None``. If a field isn't
-    specified on a form, the object created from the form can't provide
-    a value for that attribute, which will prevent the new instance from
-    being saved.
+    then the fields that are *not* specified will not be set by the form's
+    ``save()`` method. Django will prevent any attempt to save an incomplete
+    model, so if the model does not allow the missing fields to be empty, and
+    does not provide a default value for the missing fields, any attempt to
+    ``save()`` a ``form_for_model`` with missing fields will fail. To avoid
+    this failure, you must use ``save(commit=False)`` and manually set any
+    extra required fields::
+
+        instance = form.save(commit=False)
+        instance.required_field = 'new value'
+        instance.save()
+
+    See the `section on saving forms`_ for more details on using
+    ``save(commit=False)``.
+
+.. _section on saving forms: `The save() method`_
 
 Overriding the default field types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/settings.txt b/docs/settings.txt
index e40374a822..7ad1f6441d 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -363,7 +363,7 @@ regular expression which will hide from the DEBUG view anything that contains
 be able to give backtraces without seeing sensitive (or offensive) settings.
 
 Still, note that there are always going to be sections of your debug output that
-are inapporpriate for public consumption. File paths, configuration options, and
+are inappropriate for public consumption. File paths, configuration options, and
 the like all give attackers extra information about your server. Never deploy a
 site with ``DEBUG`` turned on.
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 232f54061f..b6173ad39a 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -928,10 +928,36 @@ current context, available in the ``render`` method::
 ``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then
 format it accordingly.
 
-.. note::
-    The ``resolve_variable()`` function will throw a ``VariableDoesNotExist``
-    exception if it cannot resolve the string passed to it in the current
-    context of the page.
+.. admonition:: New in development version:
+
+    Variable resolution has changed in the development version of Django.
+    ``template.resolve_variable()`` is still available, but has been deprecated
+    in favor of a new ``template.Variable`` class. Using this class will usually
+    be more efficient than calling ``template.resolve_variable``
+    
+    To use the ``Variable`` class, simply instantiate it with the name of the
+    variable to be resolved, and then call ``variable.resolve(context)``. So,
+    in the development version, the above example would be more correctly
+    written as:
+    
+    .. parsed-literal::
+    
+        class FormatTimeNode(template.Node):
+            def __init__(self, date_to_be_formatted, format_string):
+                self.date_to_be_formatted = **Variable(date_to_be_formatted)**
+                self.format_string = format_string
+        
+            def render(self, context):
+                try:
+                    actual_date = **self.date_to_be_formatted.resolve(context)**
+                    return actual_date.strftime(self.format_string)
+                except template.VariableDoesNotExist:
+                    return ''
+    
+    Changes are highlighted in bold.
+
+Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot
+resolve the string passed to it in the current context of the page.
 
 Shortcut for simple tags
 ~~~~~~~~~~~~~~~~~~~~~~~~