diff options
| -rw-r--r-- | docs/authentication.txt | 151 | ||||
| -rw-r--r-- | docs/distributions.txt | 76 | ||||
| -rw-r--r-- | docs/django-admin.txt | 14 | ||||
| -rw-r--r-- | docs/install.txt | 29 | ||||
| -rw-r--r-- | docs/model-api.txt | 6 | ||||
| -rw-r--r-- | docs/settings.txt | 55 | ||||
| -rw-r--r-- | docs/tutorial01.txt | 7 | ||||
| -rwxr-xr-x | tests/runtests.py | 4 |
8 files changed, 329 insertions, 13 deletions
diff --git a/docs/authentication.txt b/docs/authentication.txt index a7c28fc7a8..f5736a3cd7 100644 --- a/docs/authentication.txt +++ b/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 --------------------------------------------------- diff --git a/docs/distributions.txt b/docs/distributions.txt new file mode 100644 index 0000000000..a77d3a1959 --- /dev/null +++ b/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/ diff --git a/docs/django-admin.txt b/docs/django-admin.txt index cf15168030..96316702c8 100644 --- a/docs/django-admin.txt +++ b/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] ------------------------------------------------ diff --git a/docs/install.txt b/docs/install.txt index 89a1415f5a..f73a734aba 100644 --- a/docs/install.txt +++ b/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 -- - not version 1.0 or version 2, which is still in beta). If you're on Windows, - check out the unofficial `compiled Windows version`_. -* If you're using MySQL, you'll need MySQLdb_. +* If you're using PostgreSQL, you'll need the psycopg_ package (version 2 is + recommended with ``postgresql_psycopg2`` backend, version 1.1 works also with the + ``postgresql``` backend). + + 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`_. -2. ``tar xzvf Django-0.95.tar.gz`` -3. ``cd Django-0.95`` -4. ``sudo python setup.py install`` + 1. Check the `distribution specific notes`_ to see if your + platform/distribution provides official Django packages/installers. + Distribution-provided packages will typically allow for automatic + 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/model-api.txt b/docs/model-api.txt index 9f87d53719..1e7f69903d 100644 --- a/docs/model-api.txt +++ b/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 diff --git a/docs/settings.txt b/docs/settings.txt index b9e46a858c..3f928a2234 100644 --- a/docs/settings.txt +++ b/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 -``IGNORABLE_404_ENDS``. +`middleware docs`_). See also ``IGNORABLE_404_STARTS``, +``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. diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index d47dd4a19d..56c5fa769e 100644 --- a/docs/tutorial01.txt +++ b/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 diff --git a/tests/runtests.py b/tests/runtests.py index b21a3536ac..a111ef1436 100755 --- a/tests/runtests.py +++ b/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) |