newforms-admin: Merged to [4629]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@4630 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/authentication.txt

@@ -317,6 +317,16 @@ This example shows how you might use both ``authenticate()`` and ``login()``::
         else:
             # Return an 'invalid login' error message.
 
+Manually checking a user's password
+-----------------------------------
+
+If you'd like to manually authenticate a user by comparing a
+plain-text password to the hashed password in the database, use the
+convenience function `django.contrib.auth.models.check_password`. It
+takes two arguments: the plain-text password to check, and the full
+value of a user's ``password`` field in the database to check against,
+and returns ``True`` if they match, ``False`` otherwise.
+
 How to log a user out
 ---------------------
 
@@ -444,6 +454,147 @@ block::
 .. _forms documentation: ../forms/
 .. _site framework docs: ../sites/
 
+Other built-in views
+--------------------
+
+In addition to the `login` view, the authentication system includes a
+few other useful built-in views:
+
+``django.contrib.auth.views.logout``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Logs a user out.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to display after
+      logging the user out. This will default to
+      ``registration/logged_out.html`` if no argument is supplied.
+
+**Template context:**
+
+    * ``title``: The string "Logged out", localized.
+
+``django.contrib.auth.views.logout_then_login``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Logs a user out, then redirects to the login page.
+
+**Optional arguments:**
+
+    * ``login_url``: The URL of the login page to redirect to. This
+      will default to ``/accounts/login/`` if not supplied.
+
+``django.contrib.auth.views.password_change``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Allows a user to change their password.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use for
+      displaying the password change form. This will default to
+      ``registration/password_change_form.html`` if not supplied.
+
+**Template context:**
+
+    * ``form``: The password change form.
+
+``django.contrib.auth.views.password_change_done``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+The page shown after a user has changed their password.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use. This will
+      default to ``registration/password_change_done.html`` if not
+      supplied.
+
+``django.contrib.auth.views.password_reset``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Allows a user to reset their password, and sends them the new password
+in an email.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use for
+      displaying the password reset form. This will default to
+      ``registration/password_reset_form.html`` if not supplied.
+
+    * ``email_template_name``: The full name of a template to use for
+      generating the email with the new password. This will default to
+      ``registration/password_reset_email.html`` if not supplied.
+
+**Template context:**
+
+    * ``form``: The form for resetting the user's password.
+
+``django.contrib.auth.views.password_reset_done``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+The page shown after a user has reset their password.
+
+**Optional arguments:**
+
+    * ``template_name``: The full name of a template to use. This will
+      default to ``registration/password_reset_done.html`` if not
+      supplied.
+
+``django.contrib.auth.views.redirect_to_login``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Description:**
+
+Redirects to the login page, and then back to another URL after a
+successful login.
+
+**Required arguments:**
+
+    * ``next``: The URL to redirect to after a successful login.
+
+**Optional arguments:**
+
+    * ``login_url``: The URL of the login page to redirect to. This
+      will default to ``/accounts/login/`` if not supplied.
+
+Built-in manipulators
+---------------------
+
+If you don't want to use the built-in views, but want the convenience
+of not having to write manipulators for this functionality, the
+authentication system provides several built-in manipulators:
+
+    * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A
+      manipulator used in the admin interface to change a user's
+      password.
+
+    * ``django.contrib.auth.forms.AuthenticationForm``: A manipulator
+      for logging a user in.
+
+    * ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator
+      for allowing a user to change their password.
+
+    * ``django.contrib.auth.forms.PasswordResetForm``: A manipulator
+      for resetting a user's password and emailing the new password to
+      them.
+
+    * ``django.contrib.auth.forms.UserCreationForm``: A manipulator
+      for creating a new user.
+
 Limiting access to logged-in users that pass a test
 ---------------------------------------------------
 

docs/distributions.txt

@@ -0,0 +1,76 @@
+===================================
+Third-party distributions of Django
+===================================
+
+Several third-party distributors are now providing versions of Django integrated
+with their package-management systems. These can make installation and upgrading
+much easier for users of Django since the integration includes the ability to
+automatically install dependancies (like database adapters) that Django
+requires.
+
+Typically, these packages are based on the latest stable release of Django, so
+if you want to use the development version of Django you'll need to follow the
+instructions for `installing the development version`_ from our Subversion
+repository.
+
+.. _installing the development version: ../install/#installing-the-development-version
+
+Linux distributions
+===================
+
+Debian
+------
+
+A `packaged version of Django`_ is available for `Debian GNU/Linux`_, and can be
+installed from either the "testing" or the "unstable" repositories by typing
+``apt-get install python-django``.
+
+When you install this package, ``apt`` will recommend installing a database
+adapter; you should select and install the adapter for whichever database you
+plan to use with Django.
+
+.. _Debian GNU/Linux: http://www.debian.org/
+.. _packaged version of Django: http://packages.debian.org/testing/python/python-django
+
+Ubuntu
+------
+
+The Debian ``python-django`` package is also available for `Ubuntu Linux`_, in
+the "universe" repository for Ubuntu 7.04 ("Feisty Fawn"). The `current Ubuntu
+package`_ is also based on Django 0.95.1 and can be installed in the same
+fashion as for Debian.
+
+.. _Ubuntu Linux: http://www.ubuntu.com/
+.. _current Ubuntu package: http://packages.ubuntu.com/feisty/python/python-django
+
+Fedora
+------
+
+A Django package is available for `Fedora Linux`_, in the "Fedora Extras"
+repository. The `current Fedora package`_ is based on Django 0.95.1, and can be
+installed by typing ``yum install Django``.
+
+.. _Fedora Linux: http://fedora.redhat.com/
+.. _current Fedora package: http://fedoraproject.org/extras/6/i386/repodata/repoview/Django-0-0.95.1-1.fc6.html
+
+Gentoo
+------
+
+A Django build is available for `Gentoo Linux`_, and is based on Django 0.95.1.
+The `current Gentoo build`_ can be installed by typing ``emerge Django``.
+
+.. _Gentoo Linux: http://www.gentoo.org/
+.. _current Gentoo build: http://packages.gentoo.org/packages/?category=dev-python;name=django
+
+For distributors
+================
+
+If you'd like to package Django for distribution, we'd be happy to help out!
+Please join the `django-developers mailing list`_ and introduce yourself. 
+
+We also encourage all distributors to subscribe to the `django-announce mailing
+list`_, which is a (very) low-traffic list for announcing new releases of Django
+and important bugfixes.
+
+.. _django-developers mailing list: http://groups.google.com/group/django-developers/
+.. _django-announce mailing list: http://groups.google.com/group/django-announce/

docs/django-admin.txt

@@ -143,6 +143,20 @@ install [appname appname ...]
 
 Executes the equivalent of ``sqlall`` for the given appnames.
 
+reset [appname appname ...]
+---------------------------
+Executes the equivalent of ``sqlreset`` for the given appnames.
+
+runfcgi [options]
+-----------------
+Starts a set of FastCGI processes suitable for use with any web server
+which supports the FastCGI protocol. See the `FastCGI deployment
+documentation`- for details. Requires the Python FastCGI module from
+`flup`_.
+
+.. _FastCGI deployment documentation: ../fastcgi/
+.. _flup: http://www.saddi.com/software/flup/
+
 runserver [optional port number, or ipaddr:port]
 ------------------------------------------------
 

docs/install.txt

@@ -51,10 +51,14 @@ make sure a database server is running. Django works with PostgreSQL_
 Additionally, you'll need to make sure your Python database bindings are
 installed.
 
-* If you're using PostgreSQL, you'll need the psycopg_ package (version 1.1 --
+* If you're using PostgreSQL, you'll need the psycopg_ package (version 2 is
-  not version 1.0 or version 2, which is still in beta). If you're on Windows,
+  recommended with ``postgresql_psycopg2`` backend, version 1.1 works also with the
-  check out the unofficial `compiled Windows version`_.
+  ``postgresql``` backend). 
-* If you're using MySQL, you'll need MySQLdb_.
+  
+  If you're on Windows, check out the unofficial `compiled Windows version`_.
+  
+* If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher.
+
 * If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher.
 
 .. _PostgreSQL: http://www.postgresql.org/
@@ -77,10 +81,18 @@ It's easy either way.
 Installing the official version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Download Django-0.95.tar.gz from our `download page`_.
+    1. Check the `distribution specific notes`_ to see if your
-2. ``tar xzvf Django-0.95.tar.gz``
+       platform/distribution provides official Django packages/installers.
-3. ``cd Django-0.95``
+       Distribution-provided packages will typically allow for automatic
-4. ``sudo python setup.py install``
+       installation of dependancies and easy upgrade paths.
+
+    2. Download Django-0.95.tar.gz from our `download page`_.
+
+    3. ``tar xzvf Django-0.95.tar.gz``
+
+    4. ``cd Django-0.95``
+
+    5. ``sudo python setup.py install``
 
 Note that the last command will automatically download and install setuptools_
 if you don't already have it installed. This requires a working Internet
@@ -93,6 +105,7 @@ The command will install Django in your Python installation's ``site-packages``
 directory.
 
 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+.. _distribution specific notes: ../distributions/
 
 Installing the development version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/model-api.txt

@@ -498,6 +498,12 @@ or outside your model class altogether::
     class Foo(models.Model):
         gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
 
+For each model field that has ``choices`` set, Django will add a method to
+retrieve the human-readable name for the field's current value. See
+`get_FOO_display`_ in the database API documentation.
+
+.. _get_FOO_display: ../db_api/#get-foo-display
+
 Finally, note that choices can be any iterable object -- not necessarily a
 list or tuple. This lets you construct choices dynamically. But if you find
 yourself hacking ``choices`` to be dynamic, you're probably better off using

docs/settings.txt

@@ -197,6 +197,9 @@ of (Full name, e-mail address). Example::
 
     (('John', 'john@example.com'), ('Mary', 'mary@example.com'))
 
+Note that Django will e-mail *all* of these people whenever an error happens. See the
+section on `error reporting via e-mail`_ for more information.
+
 ALLOWED_INCLUDE_ROOTS
 ---------------------
 
@@ -328,6 +331,16 @@ Default: ``False``
 
 A boolean that turns on/off debug mode.
 
+If you define custom settings, django/views/debug.py has a ``HIDDEN_SETTINGS``
+regular expression which will hide from the DEBUG view anything that contins
+``'SECRET``, ``PASSWORD``, or ``PROFANITIES'``. This allows untrusted users to
+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
+the like all give attackers extra information about your server. Never deploy a
+site with ``DEBUG`` turned on.
+
 DEFAULT_CHARSET
 ---------------
 
@@ -414,7 +427,7 @@ IGNORABLE_404_ENDS
 
 Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')``
 
-See also ``IGNORABLE_404_STARTS``.
+See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``.
 
 IGNORABLE_404_STARTS
 --------------------
@@ -422,7 +435,8 @@ IGNORABLE_404_STARTS
 Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')``
 
 A tuple of strings that specify beginnings of URLs that should be ignored by
-the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS`` and ``IGNORABLE_404_ENDS``.
+the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and
+the section on `error reporting via e-mail`_.
 
 INSTALLED_APPS
 --------------
@@ -636,8 +650,8 @@ Default: ``False``
 Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a
 Django-powered page that is 404ed with a non-empty referer (i.e., a broken
 link). This is only used if ``CommonMiddleware`` is installed (see the
-`middleware docs`_). See also ``IGNORABLE_404_STARTS`` and
+`middleware docs`_). See also ``IGNORABLE_404_STARTS``,
-``IGNORABLE_404_ENDS``.
+``IGNORABLE_404_ENDS`` and the section on `error reporting via e-mail`_
 
 SERVER_EMAIL
 ------------
@@ -977,3 +991,36 @@ Also, it's an error to call ``configure()`` more than once, or to call
 
 It boils down to this: Use exactly one of either ``configure()`` or
 ``DJANGO_SETTINGS_MODULE``. Not both, and not neither.
+
+Error reporting via e-mail
+==========================
+
+Server errors
+-------------
+
+When ``DEBUG`` is ``False``, Django will e-mail the users listed in the
+``ADMIN`` setting whenever your code raises an unhandled exception and results
+in an internal server error (HTTP status code 500). This gives the
+administrators immediate notification of any errors.
+
+To disable this behavior, just remove all entries from the ``ADMINS`` setting.
+
+404 errors
+----------
+
+When ``DEBUG`` is ``False`` and your ``MIDDLEWARE_CLASSES`` setting includes
+``CommonMiddleware``, Django will e-mail the users listed in the ``MANAGERS``
+setting whenever your code raises a 404 and the request has a referer.
+(It doesn't bother to e-mail for 404s that don't have a referer.)
+
+You can tell Django to stop reporting particular 404s by tweaking the
+``IGNORABLE_404_ENDS`` and ``IGNORABLE_404_STARTS`` settings. Both should be a
+tuple of strings. For example::
+
+    IGNORABLE_404_ENDS = ('.php', '.cgi')
+    IGNORABLE_404_STARTS = ('/phpmyadmin/')
+
+In this example, a 404 to any URL ending with ``.php`` or ``.cgi`` will *not*
+be reported. Neither will any URL starting with ``/phpmyadmin/``.
+
+To disable this behavior, just remove all entries from the ``MANAGERS`` setting.

docs/tutorial01.txt

@@ -41,6 +41,13 @@ From the command line, ``cd`` into a directory where you'd like to store your
 code, then run the command ``django-admin.py startproject mysite``. This
 will create a ``mysite`` directory in your current directory.
 
+.. note::
+    
+    You'll need to avoid naming projects after built-in Python or Django
+    components. In particular, this means you should avoid using names like
+    ``django`` (which will conflict with Django itself) or ``site`` (which
+    conflicts with a built-in Python package).
+
 (``django-admin.py`` should be on your system path if you installed Django via
 ``python setup.py``. If it's not on your path, you can find it in
 ``site-packages/django/bin``, where ``site-packages`` is a directory within

tests/runtests.py

@@ -148,5 +148,7 @@ if __name__ == "__main__":
     options, args = parser.parse_args()
     if options.settings:
         os.environ['DJANGO_SETTINGS_MODULE'] = options.settings
-
+    elif "DJANGO_SETTINGS_MODULE" not in os.environ:
+        parser.error("DJANGO_SETTINGS_MODULE is not set in the environment. "
+                      "Set it or use --settings.")
     django_tests(int(options.verbosity), args)