From 0b7dd14d1f87e2ecef7aacc39fe4189667ed4fdf Mon Sep 17 00:00:00 2001 From: Boulder Sprinters Date: Fri, 9 Mar 2007 17:43:46 +0000 Subject: boulder-oracle-sprint: Merged to trunk [4692]. git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@4695 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/add_ons.txt | 9 ++ docs/authentication.txt | 165 ++++++++++++++++++++++++++++++-- docs/contributing.txt | 62 +++++++++++- docs/db-api.txt | 30 +++++- docs/distributions.txt | 76 +++++++++++++++ docs/django-admin.txt | 174 ++++++++++++++++++++++++++++++++-- docs/email.txt | 6 +- docs/fastcgi.txt | 2 +- docs/forms.txt | 12 ++- docs/generic_views.txt | 8 +- docs/install.txt | 31 ++++-- docs/model-api.txt | 75 ++++++++++++--- docs/newforms.txt | 47 +++++++++- docs/outputting_pdf.txt | 2 +- docs/request_response.txt | 115 +++++++++++++++++++++++ docs/settings.txt | 97 +++++++++++++++++-- docs/syndication_feeds.txt | 35 ++++++- docs/templates.txt | 55 +++++++++++ docs/templates_python.txt | 76 +++++++++++++++ docs/testing.txt | 229 +++++++++++++++++++++++++++++++-------------- docs/tutorial01.txt | 16 ++++ docs/tutorial04.txt | 15 +++ docs/url_dispatch.txt | 7 ++ 23 files changed, 1206 insertions(+), 138 deletions(-) create mode 100644 docs/distributions.txt (limited to 'docs') diff --git a/docs/add_ons.txt b/docs/add_ons.txt index d937eb2141..1756fe5720 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -139,6 +139,15 @@ See the `flatpages documentation`_. .. _flatpages documentation: ../flatpages/ +localflavor +=========== + +**New in Django development version** + +A collection of various Django snippets that are useful only for a particular +country or culture. For example, ``django.contrib.localflavor.usa.forms`` +contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. + markup ====== diff --git a/docs/authentication.txt b/docs/authentication.txt index ef30879ae0..aff336f67a 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -86,10 +86,10 @@ objects in the same way as any other `Django model`_:: myuser.groups.add(group, group,...) myuser.groups.remove(group, group,...) myuser.groups.clear() - myuser.permissions = [permission_list] - myuser.permissions.add(permission, permission, ...) - myuser.permissions.remove(permission, permission, ...] - myuser.permissions.clear() + myuser.user_permissions = [permission_list] + myuser.user_permissions.add(permission, permission, ...) + myuser.user_permissions.remove(permission, permission, ...] + myuser.user_permissions.clear() In addition to those automatic API methods, ``User`` objects have the following custom methods: @@ -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 --------------------- @@ -388,7 +398,7 @@ To do this, add the following line to your URLconf:: (r'^accounts/login/$', 'django.contrib.auth.views.login'), -Here's what ``django.contrib.auth.views.login`` does:: +Here's what ``django.contrib.auth.views.login`` does: * If called via ``GET``, it displays a login form that POSTs to the same URL. More on this in a bit. @@ -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 --------------------------------------------------- @@ -813,13 +964,13 @@ The ``authenticate`` method takes credentials as keyword arguments. Most of the time, it'll just look like this:: class MyBackend: - def authenticate(username=None, password=None): + def authenticate(self, username=None, password=None): # Check the username/password and return a User. But it could also authenticate a token, like so:: class MyBackend: - def authenticate(token=None): + def authenticate(self, token=None): # Check the token and return a User. Either way, ``authenticate`` should check the credentials it gets, and it diff --git a/docs/contributing.txt b/docs/contributing.txt index d802d3eaf6..8364405775 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -195,7 +195,7 @@ The second part of this workflow involves a set of flags the describe what the ticket has or needs in order to be "ready for checkin": "Has patch" - The means the ticket has an associated patch_. These will be + This means the ticket has an associated patch_. These will be reviewed to see if the patch is "good". "Needs documentation" @@ -212,6 +212,33 @@ ticket has or needs in order to be "ready for checkin": ready for checkin. This could mean the patch no longer applies cleanly, or that the code doesn't live up to our standards. +A ticket can be resolved in a number of ways: + + "fixed" + Used by one of the core developers once a patch has been rolled into + Django and the issue is fixed. + + "invalid" + Used if the ticket is found to be incorrect or a user error. + + "wontfix" + Used when a core developer decides that this request is not + appropriate for consideration in Django. This is usually chosen after + discussion in the ``django-developers`` mailing list, and you should + feel free to join in when it's something you care about. + + "duplicate" + Used when another ticket covers the same issue. By closing duplicate + tickets, we keep all the discussion in one place, which helps everyone. + + "worksforme" + Used when the triage team is unable to replicate the original bug. + +If you believe that the ticket was closed in error -- because you're +still having the issue, or it's popped up somewhere else, or the triagers have +-- made a mistake, please reopen the ticket and tell us why. Please do not +reopen tickets that have been marked as "wontfix" by core developers. + .. _required details: `Reporting bugs`_ .. _good patch: `Patch style`_ .. _patch: `Submitting patches`_ @@ -276,9 +303,11 @@ Please follow these coding standards when writing code for inclusion in Django: def my_view(req, foo): # ... - * Please don't put your name in the code. While we appreciate all - contributions to Django, our policy is not to publish individual - developer names in code -- for instance, at the top of Python modules. + * Our policy is to keep the names of developers and contributors + in the ``AUTHORS`` file distributed with Django, so please don't include + your name in the actual code. Feel free to include a change to the + ``AUTHORS`` file in your patch if you make more than a single trivial + change. Committing code =============== @@ -484,6 +513,29 @@ Alternatively, you can use a symlink called ``django`` that points to the location of the branch's ``django`` package. If you want to switch back, just change the symlink to point to the old code. +A third option is to use a `path file`_ (``.pth``) which should +work on all systems (including Windows, which doesn't have symlinks +available). First, make sure there are no files, directories or symlinks named +``django`` in your ``site-packages`` directory. Then create a text file named +``django.pth`` and save it to your ``site-packages`` directory. That file +should contain a path to your copy of Django on a single line and optional +comments. Here is an example that points to multiple branches. Just uncomment +the line for the branch you want to use ('Trunk' in this example) and make +sure all other lines are commented:: + + # Trunk is a svn checkout of: + # http://code.djangoproject.com/svn/django/trunk/ + # + /path/to/trunk + + # is a svn checkout of: + # http://code.djangoproject.com/svn/django/branches// + # + #/path/to/ + + # On windows a path may look like this: + # C:/path/to/ + If you're using Django 0.95 or earlier and installed it using ``python setup.py install``, you'll have a directory called something like ``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file @@ -491,6 +543,8 @@ 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 + Official releases ================= diff --git a/docs/db-api.txt b/docs/db-api.txt index 99bb30054b..64db3def96 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -6,7 +6,7 @@ Once you've created your `data models`_, Django automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects. This document explains that API. -.. _`data models`: http://www.djangoproject.com/documentation/model_api/ +.. _`data models`: ../model_api/ Throughout this reference, we'll refer to the following models, which comprise a weblog application:: @@ -85,7 +85,7 @@ There's no way to tell what the value of an ID will be before you call unless you explicitly specify ``primary_key=True`` on a field. See the `AutoField documentation`_.) -.. _AutoField documentation: http://www.djangoproject.com/documentation/model_api/#autofield +.. _AutoField documentation: ../model_api/#autofield Explicitly specifying auto-primary-key values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -596,6 +596,21 @@ related ``Person`` *and* the related ``City``:: Note that ``select_related()`` does not follow foreign keys that have ``null=True``. +Usually, using ``select_related()`` can vastly improve performance because your +app can avoid many database calls. However, in situations with deeply nested +sets of relationships ``select_related()`` can sometimes end up following "too +many" relations, and can generate queries so large that they end up being slow. + +In these situations, you can use the ``depth`` argument to ``select_related()`` +to control how many "levels" of relations ``select_related()`` will actually +follow:: + + b = Book.objects.select_related(depth=1).get(id=4) + p = b.author # Doesn't hit the database. + c = p.hometown # Requires a database call. + +The ``depth`` argument is new in the Django development version. + ``extra(select=None, where=None, params=None, tables=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1621,6 +1636,15 @@ For example, this deletes all ``Entry`` objects with a ``pub_date`` year of Entry.objects.filter(pub_date__year=2005).delete() +When Django deletes an object, it emulates the behavior of the SQL +constraint ``ON DELETE CASCADE`` -- in other words, any objects which +had foreign keys pointing at the object to be deleted will be deleted +along with it. For example:: + + b = Blog.objects.get(pk=1) + # This will delete the Blog and all of its Entry objects. + b.delete() + Note that ``delete()`` is the only ``QuerySet`` method that is not exposed on a ``Manager`` itself. This is a safety mechanism to prevent you from accidentally requesting ``Entry.objects.delete()``, and deleting *all* the entries. If you @@ -1777,4 +1801,4 @@ interface to your database. You can access your database via other tools, programming languages or database frameworks; there's nothing Django-specific about your database. -.. _Executing custom SQL: http://www.djangoproject.com/documentation/model_api/#executing-custom-sql +.. _Executing custom SQL: ../model_api/#executing-custom-sql 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 310e8dff0e..371c44e010 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -17,7 +17,12 @@ two things for you before delegating to ``django-admin.py``: The ``django-admin.py`` script should be on your system path if you installed Django via its ``setup.py`` utility. If it's not on your path, you can find it in ``site-packages/django/bin`` within your Python installation. Consider -symlinking to it from some place on your path, such as ``/usr/local/bin``. +symlinking it from some place on your path, such as ``/usr/local/bin``. + +For Windows users, who do not have symlinking functionality available, you +can copy ``django-admin.py`` to a location on your existing path or edit the +``PATH`` settings (under ``Settings - Control Panel - System - Advanced - Environment...``) +to point to its installed location. Generally, when working on a single Django project, it's easier to use ``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the @@ -92,6 +97,33 @@ example, the default settings don't define ``ROOT_URLCONF``, so Note that Django's default settings live in ``django/conf/global_settings.py``, if you're ever curious to see the full list of defaults. +dumpdata [appname appname ...] +------------------------------ + +**New in Django development version** + +Output to standard output all data in the database associated with the named +application(s). + +By default, the database will be dumped in JSON format. If you want the output +to be in another format, use the ``--format`` option (e.g., ``format=xml``). +You may specify any Django serialization backend (including any user specified +serialization backends named in the ``SERIALIZATION_MODULES`` setting). + +If no application name is provided, all installed applications will be dumped. + +The output of ``dumpdata`` can be used as input for ``loaddata``. + +flush +----- + +**New in Django development version** + +Return the database to the state it was in immediately after syncdb was +executed. This means that all data will be removed from the database, any +post-synchronization handlers will be re-executed, and the ``initial_data`` +fixture will be re-installed. + inspectdb --------- @@ -136,8 +168,92 @@ only works in PostgreSQL and with certain types of MySQL tables. install [appname appname ...] ----------------------------- +**Removed in Django development version** + Executes the equivalent of ``sqlall`` for the given appnames. +loaddata [fixture fixture ...] +------------------------------ + +**New in Django development version** + +Searches for and loads the contents of the named fixture into the database. + +A *Fixture* is a collection of files that contain the serialized contents of +the database. Each fixture has a unique name; however, the files that +comprise the fixture can be distributed over multiple directories, in +multiple applications. + +Django will search in three locations for fixtures: + + 1. In the ``fixtures`` directory of every installed application + 2. In any directory named in the ``FIXTURE_DIRS`` setting + 3. In the literal path named by the fixture + +Django will load any and all fixtures it finds in these locations that match +the provided fixture names. + +If the named fixture has a file extension, only fixtures of that type +will be loaded. For example:: + + django-admin.py loaddata mydata.json + +would only load JSON fixtures called ``mydata``. The fixture extension +must correspond to the registered name of a serializer (e.g., ``json`` or +``xml``). + +If you omit the extension, Django will search all available fixture types +for a matching fixture. For example:: + + django-admin.py loaddata mydata + +would look for any fixture of any fixture type called ``mydata``. If a fixture +directory contained ``mydata.json``, that fixture would be loaded +as a JSON fixture. However, if two fixtures with the same name but different +fixture type are discovered (for example, if ``mydata.json`` and +``mydata.xml`` were found in the same fixture directory), fixture +installation will be aborted, and any data installed in the call to +``loaddata`` will be removed from the database. + +The fixtures that are named can include directory components. These +directories will be inluded in the search path. For example:: + + django-admin.py loaddata foo/bar/mydata.json + +would search ``/fixtures/foo/bar/mydata.json`` for each installed +application, ``/foo/bar/mydata.json`` for each directory in +``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. + +Note that the order in which fixture files are processed is undefined. However, +all fixture data is installed as a single transaction, so data in +one fixture can reference data in another fixture. If the database backend +supports row-level constraints, these constraints will be checked at the +end of the transaction. + +.. admonition:: MySQL and Fixtures + + Unfortunately, MySQL isn't capable of completely supporting all the + features of Django fixtures. If you use MyISAM tables, MySQL doesn't + support transactions or constraints, so you won't get a rollback if + multiple transaction files are found, or validation of fixture data. + If you use InnoDB tables, you won't be able to have any forward + references in your data files - MySQL doesn't provide a mechanism to + defer checking of row constraints until a transaction is committed. + +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] ------------------------------------------------ @@ -231,15 +347,12 @@ sqlclear [appname appname ...] Prints the DROP TABLE SQL statements for the given appnames. -sqlindexes [appname appname ...] ----------------------------------------- +sqlcustom [appname appname ...] +------------------------------- -Prints the CREATE INDEX SQL statements for the given appnames. - -sqlinitialdata [appname appname ...] --------------------------------------------- +**New in Django development version** -Prints the initial INSERT SQL statements for the given appnames. +Prints the custom SQL statements for the given appnames. For each model in each specified app, this command looks for the file ``/sql/.sql``, where ```` is the given appname and @@ -250,11 +363,23 @@ command. Each of the SQL files, if given, is expected to contain valid SQL. The SQL files are piped directly into the database after all of the models' -table-creation statements have been executed. Use this SQL hook to populate -tables with any necessary initial records, SQL functions or test data. +table-creation statements have been executed. Use this SQL hook to make any +table modifications, or insert any SQL functions into the database. Note that the order in which the SQL files are processed is undefined. +sqlindexes [appname appname ...] +---------------------------------------- + +Prints the CREATE INDEX SQL statements for the given appnames. + +sqlinitialdata [appname appname ...] +-------------------------------------------- + +**Removed in Django development version** + +This method has been renamed ``sqlcustom`` in the development version of Django. + sqlreset [appname appname ...] -------------------------------------- @@ -294,6 +419,10 @@ this command to install the default apps. If you're installing the ``django.contrib.auth`` application, ``syncdb`` will give you the option of creating a superuser immediately. +``syncdb`` will also search for and install any fixture named ``initial_data``. +See the documentation for ``loaddata`` for details on the specification of +fixture data files. + test ---- @@ -343,12 +472,37 @@ setting the Python path for you. .. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html +--format +-------- + +**New in Django development version** + +Example usage:: + + django-admin.py dumpdata --format=xml + +Specifies the output format that will be used. The name provided must be the name +of a registered serializer. + --help ------ Displays a help message that includes a terse list of all available actions and options. +--indent +-------- + +**New in Django development version** + +Example usage:: + + django-admin.py dumpdata --indent=4 + +Specifies the number of spaces that will be used for indentation when +pretty-printing output. By default, output will *not* be pretty-printed. +Pretty-printing will only be enabled if the indent option is provided. + --noinput --------- diff --git a/docs/email.txt b/docs/email.txt index 1edce88cef..1f4ce4ef42 100644 --- a/docs/email.txt +++ b/docs/email.txt @@ -34,8 +34,8 @@ The simplest way to send e-mail is using the function ``django.core.mail.send_mail()``. Here's its definition:: send_mail(subject, message, from_email, recipient_list, - fail_silently=False, auth_user=EMAIL_HOST_USER, - auth_password=EMAIL_HOST_PASSWORD) + fail_silently=False, auth_user=None, + auth_password=None) The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters are required. @@ -65,7 +65,7 @@ send_mass_mail() Here's the definition:: send_mass_mail(datatuple, fail_silently=False, - auth_user=EMAIL_HOST_USER, auth_password=EMAIL_HOST_PASSWORD): + auth_user=None, auth_password=None): ``datatuple`` is a tuple in which each element is in this format:: diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index b61df49190..1efeaf09cf 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -274,7 +274,7 @@ In your Web root directory, add this to a file named ``.htaccess`` :: Then, create a small script that tells Apache how to spawn your FastCGI program. Create a file ``mysite.fcgi`` and place it in your Web directory, and -be sure to make it executable :: +be sure to make it executable:: #!/usr/bin/python import sys, os diff --git a/docs/forms.txt b/docs/forms.txt index 3fa11fea64..8c40eeb997 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -173,10 +173,10 @@ creation view that takes validation into account:: # Check for validation errors errors = manipulator.get_validation_errors(new_data) + manipulator.do_html2python(new_data) if errors: return render_to_response('places/errors.html', {'errors': errors}) else: - manipulator.do_html2python(new_data) new_place = manipulator.save(new_data) return HttpResponse("Place created: %s" % new_place) @@ -229,10 +229,10 @@ Below is the finished view:: # Check for errors. errors = manipulator.get_validation_errors(new_data) + manipulator.do_html2python(new_data) if not errors: # No errors. This means we can save the data! - manipulator.do_html2python(new_data) new_place = manipulator.save(new_data) # Redirect to the object's "edit" page. Always use a redirect @@ -324,8 +324,8 @@ about editing an existing one? It's shockingly similar to creating a new one:: if request.method == 'POST': new_data = request.POST.copy() errors = manipulator.get_validation_errors(new_data) + manipulator.do_html2python(new_data) if not errors: - manipulator.do_html2python(new_data) manipulator.save(new_data) # Do a post-after-redirect so that reload works, etc. @@ -406,8 +406,8 @@ Here's a simple function that might drive the above form:: if request.method == 'POST': new_data = request.POST.copy() errors = manipulator.get_validation_errors(new_data) + manipulator.do_html2python(new_data) if not errors: - manipulator.do_html2python(new_data) # Send e-mail using new_data here... @@ -608,6 +608,10 @@ fails. If no message is passed in, a default message is used. order). If the given field does (or does not have, in the latter case) the given value, then the current field being validated is required. + An optional ``other_label`` argument can be passed which, if given, is used + in error messages instead of the value. This allows more user friendly error + messages if the value itself is not descriptive enough. + Note that because validators are called before any ``do_html2python()`` functions, the value being compared against is a string. So ``RequiredIfOtherFieldEquals('choice', '1')`` is correct, whilst diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 23f40acb24..a136c72a07 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -686,7 +686,7 @@ A page representing a list of objects. * ``paginate_by``: An integer specifying how many objects should be displayed per page. If this is given, the view will paginate objects with ``paginate_by`` objects per page. The view will expect either a ``page`` - query string parameter (via ``GET``) containing a zero-indexed page + query string parameter (via ``GET``) containing a 1-based page number, or a ``page`` variable specified in the URLconf. See "Notes on pagination" below. @@ -752,6 +752,12 @@ If the results are paginated, the context will contain these extra variables: * ``previous``: The previous page number, as an integer. This is 1-based. + * `last_on_page`: **New in Django development version** The number of the + last result on the current page. This is 1-based. + + * `first_on_page`: **New in Django development version** The number of the + first result on the current page. This is 1-based. + * ``pages``: The total number of pages, as an integer. * ``hits``: The total number of objects across *all* pages, not just this diff --git a/docs/install.txt b/docs/install.txt index 89a1415f5a..3eede02af0 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -51,16 +51,20 @@ 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/ .. _MySQL: http://www.mysql.com/ .. _Django's ticket system: http://code.djangoproject.com/report/1 -.. _psycopg: http://initd.org/projects/psycopg1 +.. _psycopg: http://initd.org/tracker/psycopg .. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/ .. _MySQLdb: http://sourceforge.net/projects/mysql-python .. _SQLite: http://www.sqlite.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 8abd88f7ec..e66e96de68 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 @@ -874,8 +880,8 @@ the relationship should work. All are optional: force Django to add the descriptor for the reverse relationship, allowing ``ManyToMany`` relationships to be non-symmetrical. - - ``db_table`` The name of the table to create for storing the many-to-many + + ``db_table`` The name of the table to create for storing the many-to-many data. If this is not provided, Django will assume a default name based upon the names of the two tables being joined. @@ -1210,6 +1216,9 @@ screen via ``