gis: Merged revisions 5540-5582 via svnmerge from

http://code.djangoproject.com/svn/django/trunk


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

12 files changed, 248 insertions, 34 deletions

diff --git a/docs/authentication.txt b/docs/authentication.txt
index 5e5ecdf908..efe4d47513 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -461,7 +461,7 @@ block::
 Other built-in views
 --------------------
 
-In addition to the `login` view, the authentication system includes a
+In addition to the ``login`` view, the authentication system includes a
 few other useful built-in views:
 
 ``django.contrib.auth.views.logout``
diff --git a/docs/contributing.txt b/docs/contributing.txt
index 31409f27bd..b3c7efa2f7 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -382,6 +382,65 @@ Model style
               ('F', 'Female'),
           )
 
+Documentation style
+===================
+
+We place a high importance on consistency and readability of documentation.
+(After all, Django was created in a journalism environment!)
+
+Guidelines for ReST files
+-------------------------
+
+These guidelines regulate the format of our ReST documentation:
+
+	* In section titles, capitalize only initial words and proper nouns.
+
+	* Wrap the documentation at 80 characters wide, unless a code example
+	  is significantly less readable when split over two lines, or for another
+	  good reason.
+
+Commonly used terms
+-------------------
+
+Here are some style guidelines on commonly used terms throughout the
+documentation:
+
+	* **Django** -- when referring to the framework, capitalize Django. It is
+	  lowercase only in Python code and in the djangoproject.com logo.
+
+	* **e-mail** -- it has a hyphen.
+
+	* **MySQL**
+
+	* **PostgreSQL**
+
+	* **Python** -- when referring to the language, capitalize Python.
+
+	* **realize**, **customize**, **initialize**, etc. -- use the American
+	  "ize" suffix, not "ise."
+
+	* **SQLite**
+
+	* **subclass** -- it's a single word without a hyphen, both as a verb
+	  ("subclass that model") and as a noun ("create a subclass").
+
+	* **Web**, **World Wide Web**, **the Web** -- note Web is always
+	  capitalized when referring to the World Wide Web.
+
+    * **Web site** -- use two words, with Web capitalized.
+
+Django-specific terminology
+---------------------------
+
+	* **model** -- it's not capitalized.
+
+	* **template** -- it's not capitalized.
+
+	* **URLconf** -- use three capitalized letters, with no space before
+	  "conf."
+
+	* **view** -- it's not capitalized.
+
 Committing code
 ===============
 
diff --git a/docs/db-api.txt b/docs/db-api.txt
index e7b8183f6c..a4b920fb33 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -1173,6 +1173,58 @@ like ``contains`` but is significantly faster due to full-text indexing.
 Note this is only available in MySQL and requires direct manipulation of the
 database to add the full-text index.
 
+regex
+~~~~~
+
+**New in Django development version**
+
+Case-sensitive regular expression match.
+
+The regular expression syntax is that of the database backend in use. In the
+case of SQLite, which doesn't natively support regular-expression lookups, the
+syntax is that of Python's ``re`` module.
+
+Example::
+
+    Entry.objects.get(title__regex=r'^(An?|The) +')
+
+SQL equivalents::
+
+    SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL
+
+    SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'c'); -- Oracle
+
+    SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL
+
+    SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite
+
+Using raw strings (e.g., ``r'foo'`` instead of ``'foo'``) for passing in the
+regular expression syntax is recommended.
+
+Regular expression matching is not supported on the ``ado_mssql`` backend.
+It will raise a ``NotImplementedError`` at runtime.
+
+iregex
+~~~~~~
+
+**New in Django development version**
+
+Case-insensitive regular expression match.
+
+Example::
+
+    Entry.objects.get(title__iregex=r'^(an?|the) +')
+
+SQL equivalents::
+
+    SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL
+
+    SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle
+
+    SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL
+
+    SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite
+
 Default lookups are exact
 -------------------------
 
@@ -1779,7 +1831,7 @@ use the default manager, or if you want to search a list of related objects,
 you can provide ``get_object_or_404()`` with a manager object instead.
 For example::
 
-    # Get the author of blog instance `e` with a name of 'Fred'
+    # Get the author of blog instance e with a name of 'Fred'
     a = get_object_or_404(e.authors, name='Fred')
 
     # Use a custom manager 'recent_entries' in the search for an
diff --git a/docs/django-admin.txt b/docs/django-admin.txt
index d20db7edc9..75c2738543 100644
--- a/docs/django-admin.txt
+++ b/docs/django-admin.txt
@@ -513,7 +513,7 @@ Example usage::
 
 Verbosity determines the amount of notification and debug information that
 will be printed to the console. '0' is no output, '1' is normal output,
-and `2` is verbose output.
+and ``2`` is verbose output.
 
 --adminmedia
 ------------
diff --git a/docs/email.txt b/docs/email.txt
index 66948e5294..50dafaf8df 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -28,9 +28,9 @@ settings, if set, are used to authenticate to the SMTP server, and the
 .. note::
 
     The character set of e-mail sent with ``django.core.mail`` will be set to
-    the value of your `DEFAULT_CHARSET setting`_.
+    the value of your `DEFAULT_CHARSET`_ setting.
 
-.. _DEFAULT_CHARSET setting: ../settings/#default-charset
+.. _DEFAULT_CHARSET: ../settings/#default-charset
 .. _EMAIL_HOST: ../settings/#email-host
 .. _EMAIL_PORT: ../settings/#email-port
 .. _EMAIL_HOST_USER: ../settings/#email-host-user
@@ -198,27 +198,58 @@ e-mail, you can subclass these two classes to suit your needs.
 .. note::
     Not all features of the ``EmailMessage`` class are available through the
     ``send_mail()`` and related wrapper functions. If you wish to use advanced
-    features, such as BCC'ed recipients or multi-part e-mail, you'll need to
-    create ``EmailMessage`` instances directly.
+    features, such as BCC'ed recipients, file attachments, or multi-part
+    e-mail, you'll need to create ``EmailMessage`` instances directly.
+
+    This is a design feature. ``send_mail()`` and related functions were
+    originally the only interface Django provided. However, the list of
+    parameters they accepted was slowly growing over time. It made sense to
+    move to a more object-oriented design for e-mail messages and retain the
+    original functions only for backwards compatibility.
 
 In general, ``EmailMessage`` is responsible for creating the e-mail message
 itself. ``SMTPConnection`` is responsible for the network connection side of
 the operation. This means you can reuse the same connection (an
 ``SMTPConnection`` instance) for multiple messages.
 
-The ``EmailMessage`` class is initialized as follows::
+E-mail messages
+---------------
+
+The ``EmailMessage`` class is initialized with the following parameters (in
+the given order, if positional arguments are used). All parameters are
+optional and can be set at any time prior to calling the ``send()`` method.
+
+    * ``subject``: The subject line of the e-mail.
+
+    * ``body``: The body text. This should be a plain text message.
+
+    * ``from_email``: The sender's address. Both ``fred@example.com`` and
+      ``Fred <fred@example.com>`` forms are legal. If omitted, the
+      ``DEFAULT_FROM_EMAIL`` setting is used.
+
+    * ``to``: A list or tuple of recipient addresses.
 
-    email = EmailMessage(subject, body, from_email, to, bcc, connection)
+    * ``bcc``: A list or tuple of addresses used in the "Bcc" header when
+      sending the e-mail.
 
-All of these parameters are optional. If ``from_email`` is omitted, the value
-from ``settings.DEFAULT_FROM_EMAIL`` is used. Both the ``to`` and ``bcc``
-parameters are lists of addresses, as strings.
+    * ``connection``: An ``SMTPConnection`` instance. Use this parameter if
+      you want to use the same conneciton for multiple messages. If omitted, a
+      new connection is created when ``send()`` is called.
+
+    * ``attachments``: A list of attachments to put on the message. These can
+      be either ``email.MIMEBase.MIMEBase`` instances, or ``(filename,
+      content, mimetype)`` triples.
+
+    * ``headers``: A dictionary of extra headers to put on the message. The
+      keys are the header name, values are the header values. It's up to the
+      caller to ensure header names and values are in the correct format for
+      an e-mail message.
 
 For example::
 
     email = EmailMessage('Hello', 'Body goes here', 'from@example.com',
-                ['to1@example.com', 'to2@example.com'],
-                ['bcc@example.com'])
+                ['to1@example.com', 'to2@example.com'], ['bcc@example.com'],
+                headers = {'Reply-To': 'another@example.com'})
 
 The class has the following methods:
 
@@ -227,18 +258,83 @@ The class has the following methods:
       if none already exists.
 
     * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a
-      sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the
-      message to be sent. If you ever need to extend the `EmailMessage` class,
-      you'll probably want to override this method to put the content you wish
+      subclass of Python's ``email.MIMEText.MIMEText`` class) or a
+      ``django.core.mail.SafeMIMEMultipart`` object holding the
+      message to be sent. If you ever need to extend the ``EmailMessage`` class,
+      you'll probably want to override this method to put the content you want
       into the MIME object.
 
     * ``recipients()`` returns a list of all the recipients of the message,
       whether they're recorded in the ``to`` or ``bcc`` attributes. This is
-      another method you might need to override when sub-classing, because the
+      another method you might need to override when subclassing, because the
       SMTP server needs to be told the full list of recipients when the message
       is sent. If you add another way to specify recipients in your class, they
       need to be returned from this method as well.
 
+    * ``attach()`` creates a new file attachment and adds it to the message.
+      There are two ways to call ``attach()``:
+
+       * You can pass it a single argument that is an
+         ``email.MIMBase.MIMEBase`` instance. This will be inserted directly
+         into the resulting message.
+
+       * Alternatively, you can pass ``attach()`` three arguments:
+         ``filename``, ``content`` and ``mimetype``. ``filename`` is the name
+         of the file attachment as it will appear in the e-mail, ``content`` is
+         the data that will be contained inside the attachment and
+         ``mimetype`` is the optional MIME type for the attachment. If you
+         omit ``mimetype``, the MIME content type will be guessed from the
+         filename of the attachment.
+
+         For example::
+
+            message.attach('design.png', img_data, 'image/png')
+
+    * ``attach_file()`` creates a new attachment using a file from your
+      filesystem. Call it with the path of the file to attach and, optionally,
+      the MIME type to use for the attachment. If the MIME type is omitted, it
+      will be guessed from the filename. The simplest use would be::
+
+        message.attach_file('/images/weather_map.png')
+
+Sending alternative content types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It can be useful to include multiple versions of the content in an e-mail;
+the classic example is to send both text and HTML versions of a message. With
+Django's e-mail library, you can do this using the ``EmailMultiAlternatives``
+class. This subclass of ``EmailMessage`` has an ``attach_alternative()`` method
+for including extra versions of the message body in the e-mail. All the other
+methods (including the class initialization) are inherited directly from
+``EmailMessage``.
+
+To send a text and HTML combination, you could write::
+
+    from django.core.mail import EmailMultiAlternatives
+
+    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.'
+    msg = EmailMultiAlternatives(subject, text_content, from_email, to)
+    msg.attach_alternative(html_content, "text/html")
+    msg.send()
+
+By default, the MIME type of the ``body`` parameter in an ``EmailMessage`` is
+``"text/plain"``. It is good practice to leave this alone, because it
+guarantees that any recipient will be able to read the e-mail, regardless of
+their mail client. However, if you are confident that your recipients can
+handle an alternative content type, you can use the ``content_subtype``
+attribute on the ``EmailMessage`` class to change the main content type. The
+major type will always be ``"text"``, but you can change it to the subtype. For
+example::
+
+    msg = EmailMessage(subject, html_content, from_email, to)
+    msg.content_subtype = "html"  # Main content is now text/html
+    msg.send()
+
+SMTP network connections
+------------------------
+
 The ``SMTPConnection`` class is initialized with the host, port, username and
 password for the SMTP server. If you don't specify one or more of those
 options, they are read from your settings file.
diff --git a/docs/install.txt b/docs/install.txt
index 99aad4e52d..e850e48955 100644
--- a/docs/install.txt
+++ b/docs/install.txt
@@ -48,7 +48,8 @@ Get your database running
 
 If you plan to use Django's database API functionality, you'll need to
 make sure a database server is running. Django works with PostgreSQL_,
-MySQL_ and SQLite_.
+MySQL_, Oracle_ and SQLite_ (the latter doesn't require a separate server to
+be running).
 
 Additionally, you'll need to make sure your Python database bindings are
 installed.
@@ -76,6 +77,7 @@ installed.
 .. _pysqlite: http://initd.org/tracker/pysqlite
 .. _MySQL backend: ../databases/
 .. _cx_Oracle: http://www.python.net/crew/atuining/cx_Oracle/
+.. _Oracle: http://www.oracle.com/
 
 Remove any old versions of Django
 =================================
diff --git a/docs/legacy_databases.txt b/docs/legacy_databases.txt
index ca3927e52f..b87a661f90 100644
--- a/docs/legacy_databases.txt
+++ b/docs/legacy_databases.txt
@@ -18,7 +18,7 @@ You'll need to tell Django what your database connection parameters are, and
 what the name of the database is. Do that by editing these settings in your
 `settings file`_:
 
-    * `DATABASE_NAME`
+    * `DATABASE_NAME`_
     * `DATABASE_ENGINE`_
     * `DATABASE_USER`_
     * `DATABASE_PASSWORD`_
diff --git a/docs/model-api.txt b/docs/model-api.txt
index f7b56110d6..22ff7445b5 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -493,9 +493,9 @@ possible values for "no data;" Django convention is to use the empty
 string, not ``NULL``.
 
 .. note::
-    Due to database limitations, when using the Oracle backend the
-    ``null=True`` option will be coerced for string-based fields that can
-    blank, and the value ``NULL`` will be stored to denote the empty string.
+    When using the Oracle database backend, the ``null=True`` option will
+    be coerced for string-based fields that can blank, and the value
+    ``NULL`` will be stored to denote the empty string.
 
 ``blank``
 ~~~~~~~~~
@@ -594,9 +594,12 @@ statement for this field.
 ``db_tablespace``
 ~~~~~~~~~~~~~~~~~
 
-If this field is indexed, the name of the database tablespace to use for the
-index. The default is the ``db_tablespace`` of the model, if any. If the
-backend doesn't support tablespaces, this option is ignored.
+**New in Django development version**
+
+The name of the database tablespace to use for this field's index, if
+indeed this field is indexed. The default is the ``db_tablespace`` of
+the model, if any. If the backend doesn't support tablespaces, this
+option is ignored.
 
 ``default``
 ~~~~~~~~~~~
@@ -1011,6 +1014,8 @@ that's OK. Django quotes column and table names behind the scenes.
 ``db_tablespace``
 -----------------
 
+**New in Django development version**
+
 The name of the database tablespace to use for the model. If the backend
 doesn't support tablespaces, this option is ignored.
 
diff --git a/docs/release_notes_0.96.txt b/docs/release_notes_0.96.txt
index f62780c6b2..4227de8155 100644
--- a/docs/release_notes_0.96.txt
+++ b/docs/release_notes_0.96.txt
@@ -28,7 +28,7 @@ The following changes may require you to update your code when you switch from
 
 Due to a bug in older versions of the ``MySQLdb`` Python module (which
 Django uses to connect to MySQL databases), Django's MySQL backend now
-requires version 1.2.1p2 or higher of `MySQLdb`, and will raise
+requires version 1.2.1p2 or higher of ``MySQLdb``, and will raise
 exceptions if you attempt to use an older version.
 
 If you're currently unable to upgrade your copy of ``MySQLdb`` to meet
diff --git a/docs/serialization.txt b/docs/serialization.txt
index 01afa2708c..fa9b4edd51 100644
--- a/docs/serialization.txt
+++ b/docs/serialization.txt
@@ -48,12 +48,12 @@ Subset of fields
 ~~~~~~~~~~~~~~~~
 
 If you only want a subset of fields to be serialized, you can 
-specify a `fields` argument to the serializer::
+specify a ``fields`` argument to the serializer::
 
     from django.core import serializers
     data = serializers.serialize('xml', SomeModel.objects.all(), fields=('name','size'))
 
-In this example, only the `name` and `size` attributes of each model will
+In this example, only the ``name`` and ``size`` attributes of each model will
 be serialized. 
 
 .. note::
diff --git a/docs/testing.txt b/docs/testing.txt
index 50c4ec3046..b326e0099d 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -253,8 +253,8 @@ can be invoked on the ``Client`` instance.
         f.close()
 
     will result in the evaluation of a POST request on ``/customers/wishes/``,
-    with a POST dictionary that contains `name`, `attachment` (containing the
-    file name), and `attachment_file` (containing the file data). Note that you
+    with a POST dictionary that contains ``name``, ``attachment`` (containing the
+    file name), and ``attachment_file`` (containing the file data). Note that you
     need to manually close the file after it has been provided to the POST.
 
 ``login(**credentials)``
@@ -660,8 +660,8 @@ arguments:
     tested. This is the same format returned by ``django.db.models.get_apps()``
 
     Verbosity determines the amount of notification and debug information that
-    will be printed to the console; `0` is no output, `1` is normal output,
-    and `2` is verbose output.
+    will be printed to the console; ``0`` is no output, ``1`` is normal output,
+    and ``2`` is verbose output.
 
     This method should return the number of tests that failed.
 
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index d26f654f87..fdac9c554e 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -360,7 +360,7 @@ Note the following:
       quotes. The author of this tutorial runs PostgreSQL, so the example
       output is in PostgreSQL syntax.
 
-    * The `sql` command doesn't actually run the SQL in your database - it just
+    * The ``sql`` command doesn't actually run the SQL in your database - it just
       prints it to the screen so that you can see what SQL Django thinks is required.
       If you wanted to, you could copy and paste this SQL into your database prompt.
       However, as we will see shortly, Django provides an easier way of committing