diff options
| author | Derek Anderson <public@kered.org> | 2006-10-26 19:09:51 +0000 |
|---|---|---|
| committer | Derek Anderson <public@kered.org> | 2006-10-26 19:09:51 +0000 |
| commit | 42851d90dadbf62f5d342ce5c4f496ba1eeba987 (patch) | |
| tree | a5d0e5c178afb2d7dbb7bf5ab37db9ced42f4b52 /docs | |
| parent | 450889c9a6f7da3c2fce77a0ccf4c4cea9e29710 (diff) | |
committing to schema-evolution
merge from HEAD
git-svn-id: http://code.djangoproject.com/svn/django/branches/schema-evolution@3937 bcc190cf-cafb-0310-a4f2-bffc1f526a37
Diffstat (limited to 'docs')
37 files changed, 2189 insertions, 261 deletions
diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 90c98b7176..a0377700d7 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -2,12 +2,15 @@ The "contrib" add-ons ===================== -Django aims to follow Python's "batteries included" philosophy. It ships with a -variety of extra, optional tools that solve common Web-development problems. +Django aims to follow Python's `"batteries included" philosophy`_. It ships +with a variety of extra, optional tools that solve common Web-development +problems. This code lives in ``django/contrib`` in the Django distribution. Here's a rundown of the packages in ``contrib``: +.. _"batteries included" philosophy: http://docs.python.org/tut/node12.html#batteries-included + admin ===== @@ -150,6 +153,15 @@ See the `sites documentation`_. .. _sites documentation: http://www.djangoproject.com/documentation/sites/ +sitemaps +======== + +A framework for generating Google sitemap XML files. + +See the `sitemaps documentation`_. + +.. _sitemaps documentation: http://www.djangoproject.com/documentation/sitemaps/ + syndication =========== diff --git a/docs/admin_css.txt b/docs/admin_css.txt index 069012a84b..5822e26e45 100644 --- a/docs/admin_css.txt +++ b/docs/admin_css.txt @@ -82,7 +82,7 @@ There are also a few styles for styling text. .help This is a custom class for blocks of inline help text explaining the function of form elements. It makes text smaller and gray, and when applied - to ``p`` elements withing ``.form-row`` elements (see Form Styles below), + to ``p`` elements within ``.form-row`` elements (see Form Styles below), it will offset the text to align with the form field. Use this for help text, instead of ``small quiet``. It works on other elements, but try to put the class on a ``p`` whenever you can. @@ -118,8 +118,8 @@ additional class on the ``a`` for that tool. These are ``.addlink`` and Example from a changelist page:: <ul class="object-tools"> - <li><a href="/stories/add/" class="addlink">Add redirect</a></li> - </ul> + <li><a href="/stories/add/" class="addlink">Add redirect</a></li> + </ul> .. image:: http://media.djangoproject.com/img/doc/admincss/objecttools_01.gif :alt: Object tools on a changelist page @@ -170,4 +170,4 @@ Labels Form labels should always precede the field, except in the case of checkboxes and radio buttons, where the ``input`` should come first. Any explanation or help text should follow the ``label`` in a ``p`` with class -``.help``.
\ No newline at end of file +``.help``. diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt index 72e0841305..b85057924b 100644 --- a/docs/apache_auth.txt +++ b/docs/apache_auth.txt @@ -6,7 +6,7 @@ Since keeping multiple authentication databases in sync is a common problem when dealing with Apache, you can configuring Apache to authenticate against Django's `authentication system`_ directly. For example, you could: - * Serve media files directly from Apache only to authenticated users. + * Serve static/media files directly from Apache only to authenticated users. * Authenticate access to a Subversion_ repository against Django users with a certain permission. diff --git a/docs/api_stability.txt b/docs/api_stability.txt new file mode 100644 index 0000000000..18885fbe63 --- /dev/null +++ b/docs/api_stability.txt @@ -0,0 +1,123 @@ +============= +API stability +============= + +Although Django has not reached a 1.0 release, the bulk of Django's public APIs are +stable as of the 0.95 release. This document explains which APIs will and will not +change before the 1.0 release. + +What "stable" means +=================== + +In this context, stable means: + + - All the public APIs -- everything documented in the linked documents, and + all methods that don't begin with an underscore -- will not be moved or + renamed without providing backwards-compatible aliases. + + - If new features are added to these APIs -- which is quite possible -- + they will not break or change the meaning of existing methods. In other + words, "stable" does not (necessarily) mean "complete." + + - If, for some reason, an API declared stable must be removed or replaced, it + will be declared deprecated but will remain in the API until at least + version 1.1. Warnings will be issued when the deprecated method is + called. + + - We'll only break backwards compatibility of these APIs if a bug or + security hole makes it completely unavoidable. + +Stable APIs +=========== + +These APIs are stable: + + - `Caching`_. + + - `Custom template tags and libraries`_ (with the possible exception for a + small change in the way templates are registered and loaded). + + - `Database lookup`_ (with the exception of validation; see below). + + - `django-admin utility`_. + + - `FastCGI integration`_. + + - `Flatpages`_. + + - `Generic views`_. + + - `Internationalization`_. + + - `Legacy database integration`_. + + - `Model definition`_ (with the exception of generic relations; see below). + + - `mod_python integration`_. + + - `Redirects`_. + + - `Request/response objects`_. + + - `Sending email`_. + + - `Sessions`_. + + - `Settings`_. + + - `Syndication`_. + + - `Template language`_ (with the exception of some possible disambiguation + of how tag arguments are passed to tags and filters). + + - `Transactions`_. + + - `URL dispatch`_. + +You'll notice that this list comprises the bulk of Django's APIs. That's right +-- most of the changes planned between now and Django 1.0 are either under the +hood, feature additions, or changes to a few select bits. A good estimate is +that 90% of Django can be considered forwards-compatible at this point. + +That said, these APIs should *not* be considered stable, and are likely to +change: + + - `Forms and validation`_ will most likely be completely rewritten to + deemphasize Manipulators in favor of validation-aware models. + + - `Serialization`_ is under heavy development; changes are likely. + + - The `authentication`_ framework is changing to be far more flexible, and + API changes may be necessary. + + - Generic relations will most likely be moved out of core and into the + content-types contrib package to avoid core dependancies on optional + components. + + - The comments framework, which is yet undocumented, will likely get a complete + rewrite before Django 1.0. Even if the change isn't quite that drastic, + there will at least be moderate changes. + +.. _caching: http://www.djangoproject.com/documentation/cache/ +.. _custom template tags and libraries: http://www.djangoproject.com/documentation/templates_python/ +.. _database lookup: http://www.djangoproject.com/documentation/db_api/ +.. _django-admin utility: http://www.djangoproject.com/documentation/django_admin/ +.. _fastcgi integration: http://www.djangoproject.com/documentation/fastcgi/ +.. _flatpages: http://www.djangoproject.com/documentation/flatpages/ +.. _generic views: http://www.djangoproject.com/documentation/generic_views/ +.. _internationalization: http://www.djangoproject.com/documentation/i18n/ +.. _legacy database integration: http://www.djangoproject.com/documentation/legacy_databases/ +.. _model definition: http://www.djangoproject.com/documentation/model_api/ +.. _mod_python integration: http://www.djangoproject.com/documentation/modpython/ +.. _redirects: http://www.djangoproject.com/documentation/redirects/ +.. _request/response objects: http://www.djangoproject.com/documentation/request_response/ +.. _sending email: http://www.djangoproject.com/documentation/email/ +.. _sessions: http://www.djangoproject.com/documentation/sessions/ +.. _settings: http://www.djangoproject.com/documentation/settings/ +.. _syndication: http://www.djangoproject.com/documentation/syndication/ +.. _template language: http://www.djangoproject.com/documentation/templates/ +.. _transactions: http://www.djangoproject.com/documentation/transactions/ +.. _url dispatch: http://www.djangoproject.com/documentation/url_dispatch/ +.. _forms and validation: http://www.djangoproject.com/documentation/forms/ +.. _serialization: http://www.djangoproject.com/documentation/serialization/ +.. _authentication: http://www.djangoproject.com/documentation/authentication/ diff --git a/docs/authentication.txt b/docs/authentication.txt index 68b9024a90..2a61ec82b5 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -66,8 +66,8 @@ Fields long and can contain any character. See the "Passwords" section below. * ``is_staff`` -- Boolean. Designates whether this user can access the admin site. - * ``is_active`` -- Boolean. Designates whether this user can log into the - Django admin. Set this to ``False`` instead of deleting accounts. + * ``is_active`` -- Boolean. Designates whether this account can be used + to log in. Set this flag to ``False`` instead of deleting accounts. * ``is_superuser`` -- Boolean. Designates that this user has all permissions without explicitly assigning them. * ``last_login`` -- A datetime of the user's last login. Is set to the @@ -82,20 +82,26 @@ Methods ``user_permissions``. ``User`` objects can access their related objects in the same way as any other `Django model`_:: - myuser.objects.groups = [group_list] - myuser.objects.groups.add(group, group,...) - myuser.objects.groups.remove(group, group,...) - myuser.objects.groups.clear() - myuser.objects.permissions = [permission_list] - myuser.objects.permissions.add(permission, permission, ...) - myuser.objects.permissions.remove(permission, permission, ...] - myuser.objects.permissions.clear() + myuser.groups = [group_list] + 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() In addition to those automatic API methods, ``User`` objects have the following custom methods: * ``is_anonymous()`` -- Always returns ``False``. This is a way of - comparing ``User`` objects to anonymous users. + differentiating ``User`` and ``AnonymousUser`` objects. Generally, you + should prefer using ``is_authenticated()`` to this method. + + * ``is_authenticated()`` -- Always returns ``True``. This is a way to + tell if the user has been authenticated. This does not imply any + permissions, and doesn't check if the user is active - it only indicates + that the user has provided a valid username and password. * ``get_full_name()`` -- Returns the ``first_name`` plus the ``last_name``, with a space in between. @@ -116,13 +122,16 @@ custom methods: * ``has_perm(perm)`` -- Returns ``True`` if the user has the specified permission, where perm is in the format ``"package.codename"``. + If the user is inactive, this method will always return ``False``. * ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the specified permissions, where each perm is in the format - ``"package.codename"``. + ``"package.codename"``. If the user is inactive, this method will + always return ``False``. * ``has_module_perms(package_name)`` -- Returns ``True`` if the user has any permissions in the given package (the Django app label). + If the user is inactive, this method will always return ``False``. * ``get_and_delete_messages()`` -- Returns a list of ``Message`` objects in the user's queue and deletes the messages from the queue. @@ -219,6 +228,7 @@ the ``django.contrib.auth.models.User`` interface, with these differences: * ``id`` is always ``None``. * ``is_anonymous()`` returns ``True`` instead of ``False``. + * ``is_authenticated()`` returns ``False`` instead of ``True``. * ``has_perm()`` always returns ``False``. * ``set_password()``, ``check_password()``, ``save()``, ``delete()``, ``set_groups()`` and ``set_permissions()`` raise ``NotImplementedError``. @@ -254,12 +264,12 @@ Once you have those middlewares installed, you'll be able to access ``request.user`` in views. ``request.user`` will give you a ``User`` object representing the currently logged-in user. If a user isn't currently logged in, ``request.user`` will be set to an instance of ``AnonymousUser`` (see the -previous section). You can tell them apart with ``is_anonymous()``, like so:: +previous section). You can tell them apart with ``is_authenticated()``, like so:: - if request.user.is_anonymous(): - # Do something for anonymous users. + if request.user.is_authenticated(): + # Do something for authenticated users. else: - # Do something for logged-in users. + # Do something for anonymous users. .. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects .. _session documentation: http://www.djangoproject.com/documentation/sessions/ @@ -278,7 +288,10 @@ password is invalid, ``authenticate()`` returns ``None``. Example:: from django.contrib.auth import authenticate user = authenticate(username='john', password='secret') if user is not None: - print "You provided a correct username and password!" + if user.is_active: + print "You provided a correct username and password!" + else: + print "Your account has been disabled!" else: print "Your username and password were incorrect." @@ -296,10 +309,13 @@ This example shows how you might use both ``authenticate()`` and ``login()``:: password = request.POST['password'] user = authenticate(username=username, password=password) if user is not None: - login(request, user) - # Redirect to a success page. + if user.is_active: + login(request, user) + # Redirect to a success page. + else: + # Return a 'disabled account' error message else: - # Return an error message. + # Return an 'invalid login' error message. How to log a user out --------------------- @@ -323,19 +339,19 @@ The raw way ~~~~~~~~~~~ The simple, raw way to limit access to pages is to check -``request.user.is_anonymous()`` and either redirect to a login page:: +``request.user.is_authenticated()`` and either redirect to a login page:: from django.http import HttpResponseRedirect def my_view(request): - if request.user.is_anonymous(): + if not request.user.is_authenticated(): return HttpResponseRedirect('/login/?next=%s' % request.path) # ... ...or display an error message:: def my_view(request): - if request.user.is_anonymous(): + if not request.user.is_authenticated(): return render_to_response('myapp/login_error.html') # ... @@ -439,7 +455,7 @@ For example, this view checks to make sure the user is logged in and has the permission ``polls.can_vote``:: def my_view(request): - if request.user.is_anonymous() or not request.user.has_perm('polls.can_vote'): + if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')): return HttpResponse("You can't vote in this poll.") # ... @@ -451,6 +467,10 @@ As a shortcut, you can use the convenient ``user_passes_test`` decorator:: # ... my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view) +We're using this particular test as a relatively simple example. However, if +you just want to test whether a permission is available to a user, you can use +the ``permission_required()`` decorator, described later in this document. + Here's the same thing, using Python 2.4's decorator syntax:: from django.contrib.auth.decorators import user_passes_test @@ -483,6 +503,34 @@ Example in Python 2.4 syntax:: def my_view(request): # ... +The permission_required decorator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**New in Django development version** + +It's a relatively common task to check whether a user has a particular +permission. For that reason, Django provides a shortcut for that case: the +``permission_required()`` decorator. Using this decorator, the earlier example +can be written as:: + + from django.contrib.auth.decorators import permission_required + + def my_view(request): + # ... + my_view = permission_required('polls.can_vote')(my_view) + +Note that ``permission_required()`` also takes an optional ``login_url`` +parameter. Example:: + + from django.contrib.auth.decorators import permission_required + + def my_view(request): + # ... + my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view) + +As in the ``login_required`` decorator, ``login_url`` defaults to +``'/accounts/login/'``. + Limiting access to generic views -------------------------------- @@ -605,10 +653,10 @@ Users The currently logged-in user, either a ``User`` instance or an``AnonymousUser`` instance, is stored in the template variable ``{{ user }}``:: - {% if user.is_anonymous %} - <p>Welcome, new user. Please log in.</p> - {% else %} + {% if user.is_authenticated %} <p>Welcome, {{ user.username }}. Thanks for logging in.</p> + {% else %} + <p>Welcome, new user. Please log in.</p> {% endif %} Permissions @@ -672,7 +720,7 @@ timestamps. Messages are used by the Django admin after successful actions. For example, ``"The poll Foo was created successfully."`` is a message. -The API is simple:: +The API is simple: * To create a new message, use ``user_obj.message_set.create(message='message_text')``. diff --git a/docs/cache.txt b/docs/cache.txt index 2ef3d6503f..1795345ed9 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -230,8 +230,16 @@ Then, add the following required settings to your Django settings file: collisions. Use an empty string if you don't care. The cache middleware caches every page that doesn't have GET or POST -parameters. Additionally, ``CacheMiddleware`` automatically sets a few headers -in each ``HttpResponse``: +parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is +``True``, only anonymous requests (i.e., not those made by a logged-in user) +will be cached. This is a simple and effective way of disabling caching for any +user-specific pages (include Django's admin interface). Note that if you use +``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated +``AuthenticationMiddleware`` and that ``AuthenticationMiddleware`` appears +before ``CacheMiddleware`` in your ``MIDDLEWARE_CLASSES``. + +Additionally, ``CacheMiddleware`` automatically sets a few headers in each +``HttpResponse``: * Sets the ``Last-Modified`` header to the current date/time when a fresh (uncached) version of the page is requested. diff --git a/docs/contributing.txt b/docs/contributing.txt index d7552cdc7c..6ff0b038a3 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -168,6 +168,23 @@ Please follow these coding standards when writing code for inclusion in Django: {{foo}} + * In Django views, the first parameter in a view function should be called + ``request``. + + Do this:: + + def my_view(request, foo): + # ... + + Don't do this:: + + 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. + Committing code =============== @@ -212,6 +229,10 @@ repository: first, then the "Fixed #abc." For example: "magic-removal: Fixed #123 -- Added whizbang feature." + For the curious: We're using a `Trac post-commit hook`_ for this. + + .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook + * If your commit references a ticket in the Django `ticket tracker`_ but does *not* close the ticket, include the phrase "Refs #abc", where "abc" is the number of the ticket your commit references. We've rigged @@ -226,18 +247,23 @@ Django tarball. It's our policy to make sure all tests pass at all times. The tests cover: - * Models and the database API (``tests/testapp/models``). - * The cache system (``tests/otherthests/cache.py``). - * The ``django.utils.dateformat`` module (``tests/othertests/dateformat.py``). - * Database typecasts (``tests/othertests/db_typecasts.py``). - * The template system (``tests/othertests/templates.py`` and - ``tests/othertests/defaultfilters.py``). - * ``QueryDict`` objects (``tests/othertests/httpwrappers.py``). - * Markup template tags (``tests/othertests/markup.py``). - * The ``django.utils.timesince`` module (``tests/othertests/timesince.py``). + * Models and the database API (``tests/modeltests/``). + * The cache system (``tests/regressiontests/cache.py``). + * The ``django.utils.dateformat`` module (``tests/regressiontests/dateformat/``). + * Database typecasts (``tests/regressiontests/db_typecasts/``). + * The template system (``tests/regressiontests/templates/`` and + ``tests/regressiontests/defaultfilters/``). + * ``QueryDict`` objects (``tests/regressiontests/httpwrappers/``). + * Markup template tags (``tests/regressiontests/markup/``). We appreciate any and all contributions to the test suite! +The Django tests all use the testing infrastructure that ships with Django for +testing applications. See `Testing Django applications`_ for an explanation of +how to write new tests. + +.. _Testing Django applications: http://www.djangoproject.com/documentation/testing/ + Running the unit tests ---------------------- @@ -247,10 +273,14 @@ To run the tests, ``cd`` to the ``tests/`` directory and type:: Yes, the unit tests need a settings module, but only for database connection info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``. +You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just +needs to be present) and a ``SITE_ID`` setting (any integer value will do) in +order for all the tests to pass. -The unit tests will not touch your database; they create a new database, called -``django_test_db``, which is deleted when the tests are finished. This means -your user account needs permission to execute ``CREATE DATABASE``. +The unit tests will not touch your existing databases; they create a new +database, called ``django_test_db``, which is deleted when the tests are +finished. This means your user account needs permission to execute ``CREATE +DATABASE``. Requesting features =================== diff --git a/docs/db-api.txt b/docs/db-api.txt index ce6bb0ab3b..2f0c8b0589 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -578,6 +578,9 @@ related ``Person`` *and* the related ``City``:: p = b.author # Hits the database. c = p.hometown # Hits the database. +Note that ``select_related()`` does not follow foreign keys that have +``null=True``. + ``extra(select=None, where=None, params=None, tables=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -715,12 +718,12 @@ The ``DoesNotExist`` exception inherits from A convenience method for creating an object and saving it all in one step. Thus:: p = Person.objects.create(first_name="Bruce", last_name="Springsteen") - + and:: p = Person(first_name="Bruce", last_name="Springsteen") p.save() - + are equivalent. ``get_or_create(**kwargs)`` @@ -873,15 +876,18 @@ The database API supports the following lookup types: exact ~~~~~ -Exact match. +Exact match. If the value provided for comparison is ``None``, it will +be interpreted as an SQL ``NULL`` (See isnull_ for more details). -Example:: +Examples:: Entry.objects.get(id__exact=14) + Entry.objects.get(id__exact=None) -SQL equivalent:: +SQL equivalents:: SELECT ... WHERE id = 14; + SELECT ... WHERE id = NULL; iexact ~~~~~~ @@ -1100,8 +1106,8 @@ such as January 3, July 3, etc. isnull ~~~~~~ -``NULL`` or ``IS NOT NULL`` match. Takes either ``True`` or ``False``, which -correspond to ``IS NULL`` and ``IS NOT NULL``, respectively. +Takes either ``True`` or ``False``, which correspond to SQL queries of +``IS NULL`` and ``IS NOT NULL``, respectively. Example:: @@ -1111,6 +1117,14 @@ SQL equivalent:: SELECT ... WHERE pub_date IS NULL; +.. admonition:: ``__isnull=True`` vs ``__exact=None`` + + There is an important difference between ``__isnull=True`` and + ``__exact=None``. ``__exact=None`` will *always* return an empty result + set, because SQL requires that no value is equal to ``NULL``. + ``__isnull`` determines if the field is currently holding the value + of ``NULL`` without performing a comparison. + search ~~~~~~ @@ -1137,7 +1151,7 @@ The pk lookup shortcut ---------------------- For convenience, Django provides a ``pk`` lookup type, which stands for -"primary_key". This is shorthand for "an exact lookup on the primary-key." +"primary_key". In the example ``Blog`` model, the primary key is the ``id`` field, so these three statements are equivalent:: @@ -1146,6 +1160,14 @@ three statements are equivalent:: Blog.objects.get(id=14) # __exact is implied Blog.objects.get(pk=14) # pk implies id__exact +The use of ``pk`` isn't limited to ``__exact`` queries -- any query term +can be combined with ``pk`` to perform a query on the primary key of a model:: + + # Get blogs entries with id 1, 4 and 7 + Blog.objects.filter(pk__in=[1,4,7]) + # Get all blog entries with id > 14 + Blog.objects.filter(pk__gt=14) + ``pk`` lookups also work across joins. For example, these three statements are equivalent:: @@ -1468,11 +1490,12 @@ the ``ForeignKey`` ``Manager`` has these additional methods: b.entry_set.remove(e) # Disassociates Entry e from Blog b. In order to prevent database inconsistency, this method only exists on - ``ForeignKey``s where ``null=True``. If the related field can't be set to - ``None`` (``NULL``), then an object can't be removed from a relation - without being added to another. In the above example, removing ``e`` from - ``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because - the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid. + ``ForeignKey`` objects where ``null=True``. If the related field can't be + set to ``None`` (``NULL``), then an object can't be removed from a + relation without being added to another. In the above example, removing + ``e`` from ``b.entry_set()`` is equivalent to doing ``e.blog = None``, + and because the ``blog`` ``ForeignKey`` doesn't have ``null=True``, this + is invalid. * ``clear()``: Removes all objects from the related object set. @@ -1507,7 +1530,7 @@ Many-to-many relationships -------------------------- Both ends of a many-to-many relationship get automatic API access to the other -end. The API works just as a "backward" one-to-many relationship. See _Backward +end. The API works just as a "backward" one-to-many relationship. See Backward_ above. The only difference is in the attribute naming: The model that defines the @@ -1556,13 +1579,13 @@ Queries over related objects ---------------------------- Queries involving related objects follow the same rules as queries involving -normal value fields. When specifying the the value for a query to match, you -may use either an object instance itself, or the primary key value for the +normal value fields. When specifying the the value for a query to match, you +may use either an object instance itself, or the primary key value for the object. For example, if you have a Blog object ``b`` with ``id=5``, the following three queries would be identical:: - + Entry.objects.filter(blog=b) # Query using object instance Entry.objects.filter(blog=b.id) # Query using id from instance Entry.objects.filter(blog=5) # Query using id directly diff --git a/docs/design_philosophies.txt b/docs/design_philosophies.txt index 17ed3ad6da..7fdc7ea01b 100644 --- a/docs/design_philosophies.txt +++ b/docs/design_philosophies.txt @@ -274,8 +274,8 @@ Loose coupling A view shouldn't care about which template system the developer uses -- or even whether a template system is used at all. -Designate between GET and POST ------------------------------- +Differentiate between GET and POST +---------------------------------- GET and POST are distinct; developers should explicitly use one or the other. The framework should make it easy to distinguish between GET and POST data. diff --git a/docs/django-admin.txt b/docs/django-admin.txt index 04d86aa3b4..7f9682b443 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -192,6 +192,14 @@ documentation. .. _serving static files: http://www.djangoproject.com/documentation/static_files/ +Turning off auto-reload +~~~~~~~~~~~~~~~~~~~~~~~ + +To disable auto-reloading of code while the development server is running, use the +``--noreload`` option, like so:: + + django-admin.py runserver --noreload + shell ----- @@ -284,6 +292,15 @@ 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. +test +---- + +**New in Django development version** + +Discover and run tests for all installed models. See `Testing Django applications`_ for more information. + +.. _testing django applications: ../testing/ + validate -------- @@ -330,6 +347,20 @@ setting the Python path for you. Displays a help message that includes a terse list of all available actions and options. +--noinput +--------- + +**New in Django development version** + +Inform django-admin that the user should NOT be prompted for any input. Useful +if the django-admin script will be executed as an unattended, automated +script. + +--noreload +---------- + +Disable the use of the auto-reloader when running the development server. + --version --------- @@ -340,6 +371,32 @@ Example output:: 0.9.1 0.9.1 (SVN) +--verbosity +----------- + +**New in Django development version** + +Example usage:: + + django-admin.py syncdb --verbosity=2 + +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. + +--adminmedia +------------ + +**New in Django development version** + +Example usage:: + django-admin.py manage.py --adminmedia=/tmp/new-admin-style/ + +Tells Django where to find the various CSS and JavaScript files for the admin +interface when running the development server. Normally these files are served +out of the Django source tree, but because some designers customize these files +for their site, this option allows you to test against custom versions. + Extra niceties ============== diff --git a/docs/documentation.txt b/docs/documentation.txt new file mode 100644 index 0000000000..bacfb176b1 --- /dev/null +++ b/docs/documentation.txt @@ -0,0 +1,148 @@ +==================================== +How to read the Django documentation +==================================== + +We've put a lot of effort into making Django's documentation useful, easy to +read and as complete as possible. Here are a few tips on how to make the best +of it, along with some style guidelines. + +(Yes, this is documentation about documentation. Rest assured we have no plans +to write a document about how to read the document about documentation.) + +How documentation is updated +============================ + +Just as the Django code base is developed and improved on a daily basis, our +documentation is consistently improving. We improve documentation for several +reasons: + + * To make content fixes, such as grammar/typo corrections. + * To add information and/or examples to existing sections that need to be + expanded. + * To document Django features that aren't yet documented. (The list of + such features is shrinking but exists nonetheless.) + * To add documentation for new features as new features get added, or as + Django APIs or behaviors change. + +Django's documentation is kept in the same source control system as its code. +It lives in the `django/trunk/docs`_ directory of our Subversion repository. +Each document is a separate text file that covers a narrowly focused topic, +such as the "generic views" framework or how to construct a database model. + +.. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs + +Where to get it +=============== + +You can read Django documentation in several ways. They are, in order of +preference: + +On the Web +---------- + +The most recent version of the Django documentation lives at +http://www.djangoproject.com/documentation/ . These HTML pages are generated +automatically from the text files in source control every 15 minutes. That +means they reflect the "latest and greatest" in Django -- they include the very +latest corrections and additions, and they discuss the latest Django features, +which may only be available to users of the Django development version. (See +"Differences between versions" below.) + +A key advantage of the Web-based documentation is the comment section at the +bottom of each document. This is an area for anybody to submit changes, +corrections and suggestions about the given document. The Django developers +frequently monitor the comments there and use them to improve the documentation +for everybody. + +We encourage you to help improve the docs: it's easy! Note, however, that +comments should explicitly relate to the documentation, rather than asking +broad tech-support questions. If you need help with your particular Django +setup, try the `django-users mailing list`_ instead of posting a comment to the +documentation. + +.. _django-users mailing list: http://groups.google.com/group/django-users + +In plain text +------------- + +For offline reading, or just for convenience, you can read the Django +documentation in plain text. + +If you're using an official release of Django, note that the zipped package +(tarball) of the code includes a ``docs/`` directory, which contains all the +documentation for that release. + +If you're using the development version of Django (aka the Subversion "trunk"), +note that the ``docs/`` directory contains all of the documentation. You can +``svn update`` it, just as you ``svn update`` the Python code, in order to get +the latest changes. + +You can check out the latest Django documentation from Subversion using this +shell command:: + + svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs + +One low-tech way of taking advantage of the text documentation is by using the +Unix ``grep`` utility to search for a phrase in all of the documentation. For +example, this will show you each mention of the phrase "edit_inline" in any +Django document:: + + grep edit_inline /path/to/django/docs/*.txt + +Formatting +~~~~~~~~~~ + +The text documentation is written in ReST (ReStructured Text) format. That +means it's easy to read but is also formatted in a way that makes it easy to +convert into other formats, such as HTML. If you're interested, the script that +converts the ReST text docs into djangoproject.com's HTML lives at +`djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ in +the Django Subversion repository. + +.. _djangoproject.com/django_website/apps/docs/parts/build_documentation.py: http://code.djangoproject.com/browser/djangoproject.com/django_website/apps/docs/parts/build_documentation.py + +Differences between versions +============================ + +As previously mentioned, the text documentation in our Subversion repository +contains the "latest and greatest" changes and additions. These changes often +include documentation of new features added in the Django development version +-- the Subversion ("trunk") version of Django. For that reason, it's worth +pointing out our policy on keeping straight the documentation for various +versions of the framework. + +We follow this policy: + + * The primary documentation on djangoproject.com is an HTML version of the + latest docs in Subversion. These docs always correspond to the latest + official Django release, plus whatever features we've added/changed in + the framework *since* the latest release. + + * As we add features to Django's development version, we try to update the + documentation in the same Subversion commit transaction. + + * To distinguish feature changes/additions in the docs, we use the phrase + **New in Django development version**. In practice, this means that the + current documentation on djangoproject.com can be used by users of either + the latest release *or* the development version. + + * Documentation for a particular Django release is frozen once the version + has been released officially. It remains a snapshot of the docs as of the + moment of the release. We will make exceptions to this rule in + the case of retroactive security updates or other such retroactive + changes. Once documentation is frozen, we add a note to the top of each + frozen document that says "These docs are frozen for Django version XXX" + and links to the current version of that document. + + * Once a document is frozen for a Django release, we remove comments from + that page, in favor of having comments on the latest version of that + document. This is for the sake of maintainability and usability, so that + users have one, and only one, place to leave comments on a particular + document. We realize that some people may be stuck on a previous version + of Django, but we believe the usability problems with multiple versions + of a document the outweigh the benefits. + + * The `main documentation Web page`_ includes links to documentation for + all previous versions. + +.. _main documentation Web page: http://www.djangoproject.com/documentation/ diff --git a/docs/faq.txt b/docs/faq.txt index b374abfbf3..eaccc6be43 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -16,12 +16,17 @@ hours to take a complicated Web application from concept to public launch. At the same time, the World Online Web developers have consistently been perfectionists when it comes to following best practices of Web development. -Thus, Django was designed not only to allow fast Web development, but -*best-practice* Web development. +In fall 2003, the World Online developers (Adrian Holovaty and Simon Willison) +ditched PHP and began using Python to develop its Web sites. As they built +intensive, richly interactive sites such as Lawrence.com, they began to extract +a generic Web development framework that let them build Web applications more +and more quickly. They tweaked this framework constantly, adding improvements +over two years. -Django would not be possible without a whole host of open-source projects -- -`Apache`_, `Python`_, and `PostgreSQL`_ to name a few -- and we're thrilled to -be able to give something back to the open-source community. +In summer 2005, World Online decided to open-source the resulting software, +Django. Django would not be possible without a whole host of open-source +projects -- `Apache`_, `Python`_, and `PostgreSQL`_ to name a few -- and we're +thrilled to be able to give something back to the open-source community. .. _Apache: http://httpd.apache.org/ .. _Python: http://www.python.org/ @@ -42,8 +47,8 @@ Django is pronounced **JANG**-oh. Rhymes with FANG-oh. The "D" is silent. Is Django stable? ----------------- -Yes. World Online has been using Django for more than two years. Sites built on -Django have weathered traffic spikes of over one million hits an hour and a +Yes. World Online has been using Django for more than three years. Sites built +on Django have weathered traffic spikes of over one million hits an hour and a number of Slashdottings. Yes, it's quite stable. Does Django scale? @@ -98,10 +103,9 @@ Lawrence, Kansas, USA. On IRC, Simon goes by ``SimonW``. `Wilson Miner`_ - Wilson's design-fu makes us all look like rock stars. When not sneaking - into apartment complex swimming pools, he's the Commercial Development - Director for World Online, which means he makes the money that pays all our - paychecks. He lives in Lawrence, Kansas. + Wilson's design-fu makes us all look like rock stars. By day, he's an + interactive designer for `Apple`. Don't ask him what he's working on, or + he'll have to kill you. He lives in San Francisco. On IRC, Wilson goes by ``wilsonian``. @@ -113,6 +117,7 @@ Lawrence, Kansas, USA. .. _`simon.incutio.com`: http://simon.incutio.com/ .. _`Jacob Kaplan-Moss`: http://www.jacobian.org/ .. _`Wilson Miner`: http://www.wilsonminer.com/ +.. _`Apple`: http://www.apple.com/ Which sites use Django? ----------------------- @@ -156,7 +161,7 @@ logical to us. ----------------------------------------------------- We're well aware that there are other awesome Web frameworks out there, and -we're not adverse to borrowing ideas where appropriate. However, Django was +we're not averse to borrowing ideas where appropriate. However, Django was developed precisely because we were unhappy with the status quo, so please be aware that "because <Framework X>" does it is not going to be sufficient reason to add a given feature to Django. @@ -222,9 +227,7 @@ When will you release Django 1.0? Short answer: When we're comfortable with Django's APIs, have added all features that we feel are necessary to earn a "1.0" status, and are ready to -begin maintaining backwards compatibility. This should happen in a couple of -months or so, although it's entirely possible that it could happen earlier. -That translates into summer 2006. +begin maintaining backwards compatibility. The merging of Django's `magic-removal branch`_ went a long way toward Django 1.0. @@ -251,6 +254,16 @@ information than the docs that come with the latest Django release. .. _stored in revision control: http://code.djangoproject.com/browser/django/trunk/docs +Where can I find Django developers for hire? +-------------------------------------------- + +Consult our `developers for hire page`_ for a list of Django developers who +would be happy to help you. + +You might also be interested in posting a job to http://www.gypsyjobs.com/ . + +.. _developers for hire page: http://code.djangoproject.com/wiki/DevelopersForHire + Installation questions ====================== @@ -298,6 +311,18 @@ PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported. .. _MySQL: http://www.mysql.com/ .. _`SQLite 3`: http://www.sqlite.org/ +Do I lose anything by using Python 2.3 versus newer Python versions, such as Python 2.5? +---------------------------------------------------------------------------------------- + +No. Django itself is guaranteed to work with any version of Python from 2.3 +and higher. + +If you use a Python version newer than 2.3, you will, of course, be able to +take advantage of newer Python features in your own code, along with the speed +improvements and other optimizations that have been made to the Python language +itself. But the Django framework itself should work equally well on 2.3 as it +does on 2.4 or 2.5. + Do I have to use mod_python? ---------------------------- @@ -472,7 +497,7 @@ specify an object to edit or delete. How do I add database-specific options to my CREATE TABLE statements, such as specifying MyISAM as the table type? ------------------------------------------------------------------------------------------------------------------ -We try to avoid adding special cases in the Django code to accomodate all the +We try to avoid adding special cases in the Django code to accommodate all the database-specific options such as table type, etc. If you'd like to use any of these options, create an `SQL initial data file`_ that contains ``ALTER TABLE`` statements that do what you want to do. The initial data files are executed in @@ -535,13 +560,26 @@ If you're sure your username and password are correct, make sure your user account has ``is_active`` and ``is_staff`` set to True. The admin site only allows access to users with those two fields both set to True. +How can I prevent the cache middleware from caching the admin site? +------------------------------------------------------------------- + +Set the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting to ``True``. See the +`cache documentation`_ for more information. + +.. _cache documentation: ../cache/#the-per-site-cache + How do I automatically set a field's value to the user who last edited the object in the admin? ----------------------------------------------------------------------------------------------- -At this point, you can't do this. But it's an oft-requested feature, so we're -discussing how it can be implemented. The problem is we don't want to couple -the model layer with the admin layer with the request layer (to get the current -user). It's a tricky problem. +At this point, Django doesn't have an official way to do this. But it's an oft-requested +feature, so we're discussing how it can be implemented. The problem is we don't want to couple +the model layer with the admin layer with the request layer (to get the current user). It's a +tricky problem. + +One person hacked up a `solution that doesn't require patching Django`_, but note that it's an +unofficial solution, and there's no guarantee it won't break at some point. + +.. _solution that doesn't require patching Django: http://lukeplant.me.uk/blog.php?id=1107301634 How do I limit admin access so that objects can only be edited by the users who created them? --------------------------------------------------------------------------------------------- @@ -597,12 +635,35 @@ like to make should be possible by editing the stylesheet. We've got a How do I create users without having to edit password hashes? ------------------------------------------------------------- -We don't recommend you create users via the admin interface, because at the -moment it requires you to edit password hashes manually. (Passwords are hashed -using one-way hash algorithms for security; there's currently no Web interface -for changing passwords by entering the actual password rather than the hash.) +If you'd like to use the admin site to create users, upgrade to the Django +development version, where this problem was fixed on Aug. 4, 2006. -To create a user, you'll have to use the Python API. See `creating users`_ for -full info. +You can also use the Python API. See `creating users`_ for full info. .. _creating users: http://www.djangoproject.com/documentation/authentication/#creating-users + +Contributing code +================= + +How can I get started contributing code to Django? +-------------------------------------------------- + +Thanks for asking! We've written an entire document devoted to this question. +It's titled `Contributing to Django`_. + +.. _Contributing to Django: http://www.djangoproject.com/documentation/contributing/ + +I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch? +-------------------------------------------------------------------------------------------- + +Don't worry: We're not ignoring you! + +It's important to understand there is a difference between "a ticket is being +ignored" and "a ticket has not been attended to yet." Django's ticket system +contains hundreds of open tickets, of various degrees of impact on end-user +functionality, and Django's developers have to review and prioritize. + +Besides, if your feature request stands no chance of inclusion in Django, we +won't ignore it -- we'll just close the ticket. So if your ticket is still +open, it doesn't mean we're ignoring you; it just means we haven't had time to +look at it yet. diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index 41d50d97a1..e2f4e933b4 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -270,7 +270,7 @@ In your Web root directory, add this to a file named ``.htaccess`` :: AddHandler fastcgi-script .fcgi RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f - RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L] + RewriteRule ^(.*)$ mysite.fcgi/$1 [QSA,L] 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 @@ -289,7 +289,7 @@ be sure to make it executable :: os.environ['DJANGO_SETTINGS_MODULE'] = "myproject.settings" from django.core.servers.fastcgi import runfastcgi - runfastcgi(["method=threaded", "daemonize=false"]) + runfastcgi(method="threaded", daemonize="false") Restarting the spawned server ----------------------------- diff --git a/docs/forms.txt b/docs/forms.txt index 2fbe373744..4a4ba37289 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -136,7 +136,7 @@ template:: {% endblock %} Before we get back to the problems with these naive set of views, let's go over -some salient points of the above template:: +some salient points of the above template: * Field "widgets" are handled for you: ``{{ form.field }}`` automatically creates the "right" type of widget for the form, as you can see with the @@ -148,8 +148,8 @@ some salient points of the above template:: If you must use tables, use tables. If you're a semantic purist, you can probably find better HTML than in the above template. - * To avoid name conflicts, the ``id``s of form elements take the form - "id_*fieldname*". + * To avoid name conflicts, the ``id`` values of form elements take the + form "id_*fieldname*". By creating a creation form we've solved problem number 3 above, but we still don't have any validation. Let's revise the validation issue by writing a new @@ -211,7 +211,7 @@ Below is the finished view:: def create_place(request): manipulator = Place.AddManipulator() - if request.POST: + if request.method == 'POST': # If data was POSTed, we're trying to create a new Place. new_data = request.POST.copy() @@ -309,7 +309,7 @@ about editing an existing one? It's shockingly similar to creating a new one:: # Grab the Place object in question for future use. place = manipulator.original_object - if request.POST: + if request.method == 'POST': new_data = request.POST.copy() errors = manipulator.get_validation_errors(new_data) if not errors: @@ -321,7 +321,7 @@ about editing an existing one? It's shockingly similar to creating a new one:: else: errors = {} # This makes sure the form accurate represents the fields of the place. - new_data = place.__dict__ + new_data = manipulator.flatten_data() form = forms.FormWrapper(manipulator, new_data, errors) return render_to_response('places/edit_form.html', {'form': form, 'place': place}) @@ -336,10 +336,10 @@ The only real differences are: * ``ChangeManipulator.original_object`` stores the instance of the object being edited. - * We set ``new_data`` to the original object's ``__dict__``. This makes - sure the form fields contain the current values of the object. - ``FormWrapper`` does not modify ``new_data`` in any way, and templates - cannot, so this is perfectly safe. + * We set ``new_data`` based upon ``flatten_data()`` from the manipulator. + ``flatten_data()`` takes the data from the original object under + manipulation, and converts it into a data dictionary that can be used + to populate form elements with the existing values for the object. * The above example uses a different template, so create and edit can be "skinned" differently if needed, but the form chunk itself is completely @@ -391,7 +391,7 @@ Here's a simple function that might drive the above form:: def contact_form(request): manipulator = ContactManipulator() - if request.POST: + if request.method == 'POST': new_data = request.POST.copy() errors = manipulator.get_validation_errors(new_data) if not errors: @@ -405,6 +405,43 @@ Here's a simple function that might drive the above form:: form = forms.FormWrapper(manipulator, new_data, errors) return render_to_response('contact_form.html', {'form': form}) +``FileField`` and ``ImageField`` special cases +============================================== + +Dealing with ``FileField`` and ``ImageField`` objects is a little more +complicated. + +First, you'll need to make sure that your ``<form>`` element correctly defines +the ``enctype`` as ``"multipart/form-data"``, in order to upload files:: + + <form enctype="multipart/form-data" method="post" action="/foo/"> + +Next, you'll need to treat the field in the template slightly differently. A +``FileField`` or ``ImageField`` is represented by *two* HTML form elements. + +For example, given this field in a model:: + + photo = model.ImageField('/path/to/upload/location') + +You'd need to display two formfields in the template:: + + <p><label for="id_photo">Photo:</label> {{ form.photo }}{{ form.photo_file }}</p> + +The first bit (``{{ form.photo }}``) displays the currently-selected file, +while the second (``{{ form.photo_file }}``) actually contains the file upload +form field. Thus, at the validation layer you need to check the ``photo_file`` +key. + +Finally, in your view, make sure to access ``request.FILES``, rather than +``request.POST``, for the uploaded files. This is necessary because +``request.POST`` does not contain file-upload data. + +For example, following the ``new_data`` convention, you might do something like +this:: + + new_data = request.POST.copy() + new_data.update(request.FILES) + Validators ========== @@ -444,7 +481,33 @@ the data being validated. Also, because consistency in user interfaces is important, we strongly urge you to put punctuation at the end of your validation messages. -Ready-made Validators +When are validators called? +--------------------------- + +After a form has been submitted, Django first checks to see that all the +required fields are present and non-empty. For each field that passes that +test *and if the form submission contained data* for that field, all the +validators for that field are called in turn. The emphasized portion in the +last sentence is important: if a form field is not submitted (because it +contains no data -- which is normal HTML behavior), the validators are not +run against the field. + +This feature is particularly important for models using +``models.BooleanField`` or custom manipulators using things like +``forms.CheckBoxField``. If the checkbox is not selected, it will not +contribute to the form submission. + +If you would like your validator to run *always*, regardless of whether its +attached field contains any data, set the ``always_test`` attribute on the +validator function. For example:: + + def my_custom_validator(field_data, all_data): + # ... + my_custom_validator.always_test = True + +This validator will always be executed for any field it is attached to. + +Ready-made validators --------------------- Writing your own validator is not difficult, but there are some situations @@ -516,7 +579,7 @@ fails. If no message is passed in, a default message is used. ``ValidateIfOtherFieldEquals`` Takes three parameters: ``other_field``, ``other_value`` and ``validator_list``, in that order. If ``other_field`` has a value of - ``other_vaue``, then the validators in ``validator_list`` are all run + ``other_value``, then the validators in ``validator_list`` are all run against the current field. ``RequiredIfOtherFieldNotGiven`` diff --git a/docs/generic_views.txt b/docs/generic_views.txt index d14fe12418..99a9b7cf6b 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -127,7 +127,7 @@ If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). This example redirects from ``/foo/<id>/`` to ``/bar/<id>/``:: urlpatterns = patterns('django.views.generic.simple', - ('^foo/(?p<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}), + ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}), ) This example returns a 410 HTTP error for requests to ``/bar/``:: @@ -148,7 +148,8 @@ are views for displaying drilldown pages for date-based data. **Description:** A top-level index page showing the "latest" objects, by date. Objects with -a date in the *future* are not included. +a date in the *future* are not included unless you set ``allow_future`` to +``True``. **Required arguments:** @@ -183,7 +184,12 @@ a date in the *future* are not included. the view's template. See the `RequestContext docs`_. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. + + * ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -217,7 +223,8 @@ In addition to ``extra_context``, the template's context will be: **Description:** A yearly archive page showing all available months in a given year. Objects -with a date in the *future* are not displayed. +with a date in the *future* are not displayed unless you set ``allow_future`` +to ``True``. **Required arguments:** @@ -263,7 +270,12 @@ with a date in the *future* are not displayed. this is ``False``. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. + + * ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -296,7 +308,8 @@ In addition to ``extra_context``, the template's context will be: **Description:** A monthly archive page showing all objects in a given month. Objects with a -date in the *future* are not displayed. +date in the *future* are not displayed unless you set ``allow_future`` to +``True``. **Required arguments:** @@ -344,7 +357,12 @@ date in the *future* are not displayed. determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. + + * ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -378,7 +396,7 @@ In addition to ``extra_context``, the template's context will be: **Description:** A weekly archive page showing all objects in a given week. Objects with a date -in the *future* are not displayed. +in the *future* are not displayed unless you set ``allow_future`` to ``True``. **Required arguments:** @@ -420,7 +438,12 @@ in the *future* are not displayed. determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. + + * ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -445,7 +468,8 @@ In addition to ``extra_context``, the template's context will be: **Description:** A day archive page showing all objects in a given day. Days in the future throw -a 404 error, regardless of whether any objects exist for future days. +a 404 error, regardless of whether any objects exist for future days, unless +you set ``allow_future`` to ``True``. **Required arguments:** @@ -499,7 +523,12 @@ a 404 error, regardless of whether any objects exist for future days. determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. + + * ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -537,7 +566,9 @@ and today's date is used instead. **Description:** -A page representing an individual object. +A page representing an individual object. If the object has a date value in the +future, the view will throw a 404 error by default, unless you set +``allow_future`` to ``True``. **Required arguments:** @@ -602,7 +633,12 @@ A page representing an individual object. to use in the template context. By default, this is ``'object'``. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. + + * ``allow_future``: A boolean specifying whether to include "future" + objects on this page, where "future" means objects in which the field + specified in ``date_field`` is greater than the current date/time. By + default, this is ``False``. **Template name:** @@ -671,7 +707,7 @@ A page representing a list of objects. determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. **Template name:** @@ -783,7 +819,7 @@ A page representing an individual object. to use in the template context. By default, this is ``'object'``. * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_MIME_TYPE`` setting. + to the value of the ``DEFAULT_CONTENT_TYPE`` setting. **Template name:** diff --git a/docs/i18n.txt b/docs/i18n.txt index 212fb41488..4d0d92b082 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -48,9 +48,10 @@ bit of i18n-related overhead in certain places of the framework. If you don't use internationalization, you should take the two seconds to set ``USE_I18N = False`` in your settings file. If ``USE_I18N`` is set to ``False``, then Django will make some optimizations so as not to load the -internationalization machinery. +internationalization machinery. See the `documentation for USE_I18N`_. -See the `documentation for USE_I18N`_. +You'll probably also want to remove ``'django.core.context_processors.i18n'`` +from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting. .. _documentation for USE_I18N: http://www.djangoproject.com/documentation/settings/#use-i18n @@ -224,11 +225,18 @@ block:: This will have {{ myvar }} inside. {% endblocktrans %} +If you need to bind more than one expression inside a ``blocktrans`` tag, +separate the pieces with ``and``:: + + {% blocktrans with book|title as book_t and author|title as author_t %} + This is {{ book_t }} by {{ author_t }} + {% endblocktrans %} + To pluralize, specify both the singular and plural forms with the ``{% plural %}`` tag, which appears within ``{% blocktrans %}`` and ``{% endblocktrans %}``. Example:: - {% blocktrans count list|counted as counter %} + {% blocktrans count list|count as counter %} There is only one {{ name }} object. {% plural %} There are {{ counter }} {{ name }} objects. @@ -306,7 +314,7 @@ marked for translation. It creates (or updates) a message file in the directory ``conf/locale``. In the ``de`` example, the file will be ``conf/locale/de/LC_MESSAGES/django.po``. -If run over your project source tree or your appliation source tree, it will +If run over your project source tree or your application source tree, it will do the same, but the location of the locale directory is ``locale/LANG/LC_MESSAGES`` (note the missing ``conf`` prefix). @@ -349,7 +357,7 @@ A quick explanation: Long messages are a special case. There, the first string directly after the ``msgstr`` (or ``msgid``) is an empty string. Then the content itself will be written over the next few lines as one string per line. Those strings are -directlyconcatenated. Don't forget trailing spaces within the strings; +directly concatenated. Don't forget trailing spaces within the strings; otherwise, they'll be tacked together without whitespace! .. admonition:: Mind your charset @@ -647,7 +655,7 @@ The ``javascript_catalog`` view ------------------------------- The main solution to these problems is the ``javascript_catalog`` view, which -sends out a JavaScript code library with functions that mimick the ``gettext`` +sends out a JavaScript code library with functions that mimic the ``gettext`` interface, plus an array of translation strings. Those translation strings are taken from the application, project or Django core, according to what you specify in either the {{{info_dict}}} or the URL. @@ -665,7 +673,7 @@ You hook it up like this:: Each string in ``packages`` should be in Python dotted-package syntax (the same format as the strings in ``INSTALLED_APPS``) and should refer to a package that contains a ``locale`` directory. If you specify multiple packages, all -those catalogs aremerged into one catalog. This is useful if you have +those catalogs are merged into one catalog. This is useful if you have JavaScript that uses strings from different applications. You can make the view dynamic by putting the packages into the URL pattern:: diff --git a/docs/install.txt b/docs/install.txt index 800c49b596..ff8e1a8318 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -77,44 +77,54 @@ It's easy either way. Installing the official version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Download Django-0.91.tar.gz from our `download page`_. -2. ``tar xzvf Django-0.91.tar.gz`` -3. ``cd Django-0.91`` +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`` Note that the last command will automatically download and install setuptools_ if you don't already have it installed. This requires a working Internet +connection and may cause problems on Python 2.5. If you run into problems, +try using our development version by following the instructions below. The +development version no longer uses setuptools nor requires an Internet connection. -This will install Django in your Python installation's ``site-packages`` +The command will install Django in your Python installation's ``site-packages`` directory. -.. note:: - - Due to recent backwards-incompatible changes, it is strongly recommended - that you use the development version (below) for any new applications or - if you are just starting to work with Django. The 0.91 release is a - dead-end branch that is primarily of use for supporting legacy Django - applications. - .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools Installing the development version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you'd like to be able to update your Django code occasionally with the +latest bug fixes and improvements, follow these instructions: + 1. Make sure you have Subversion_ installed. -2. ``svn co http://code.djangoproject.com/svn/django/trunk/ django_src`` -3. Symlink ``django_src/django`` so that ``django`` is within your Python - ``site-packages`` directory: +2. Check out the Django code into your Python ``site-packages`` directory. + On Linux / Mac OSX / Unix, do this:: - ``ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django`` + svn co http://code.djangoproject.com/svn/django/trunk/ django_src + ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django (In the above line, change ``python2.3`` to match your current Python version.) -You don't have to run ``python setup.py install``. + On Windows, do this:: + + svn co http://code.djangoproject.com/svn/django/trunk/django c:\Python24\lib\site-packages\django + +4. Copy the file ``django_src/django/bin/django-admin.py`` to somewhere on your + system path, such as ``/usr/local/bin`` (Unix) or ``C:\Python24\Scripts`` + (Windows). This step simply lets you type ``django-admin.py`` from within + any directory, rather than having to qualify the command with the full path + to the file. + +You *don't* have to run ``python setup.py install``, because that command +takes care of steps 3 and 4 for you. -When you want to update your code, just run the command ``svn update`` from -within the ``django_src`` directory. +When you want to update your copy of the Django source code, just run the +command ``svn update`` from within the ``django`` directory. When you do this, +Subversion will automatically download any changes. .. _`download page`: http://www.djangoproject.com/download/ .. _Subversion: http://subversion.tigris.org/ diff --git a/docs/middleware.txt b/docs/middleware.txt index bad00fd890..efc4d89569 100644 --- a/docs/middleware.txt +++ b/docs/middleware.txt @@ -63,7 +63,7 @@ Adds a few conveniences for perfectionists: last component in the path contains a period. So ``foo.com/bar`` is redirected to ``foo.com/bar/``, but ``foo.com/bar/file.txt`` is passed through unchanged. - + If ``PREPEND_WWW`` is ``True``, URLs that lack a leading "www." will be redirected to the same URL with a leading "www." @@ -101,6 +101,22 @@ Handles conditional GET operations. If the response has a ``ETag`` or Also removes the content from any response to a HEAD request and sets the ``Date`` and ``Content-Length`` response-headers. +django.middleware.http.SetRemoteAddrFromForwardedFor +---------------------------------------------------- + +**New in Django development version** + +Sets ``request['REMOTE_ADDR']`` based on ``request.['HTTP_X_FORWARDED_FOR']``, +if the latter is set. This is useful if you're sitting behind a reverse proxy +that causes each request's ``REMOTE_ADDR`` to be set to ``127.0.0.1``. + +**Important note:** This does NOT validate ``HTTP_X_FORWARDED_FOR``. If you're +not behind a reverse proxy that sets ``HTTP_X_FORWARDED_FOR`` automatically, do +not use this middleware. Anybody can spoof the value of +``HTTP_X_FORWARDED_FOR``, and because this sets ``REMOTE_ADDR`` based on +``HTTP_X_FORWARDED_FOR``, that means anybody can "fake" their IP address. Only +use this when you can absolutely trust the value of ``HTTP_X_FORWARDED_FOR``. + django.contrib.sessions.middleware.SessionMiddleware ---------------------------------------------------- diff --git a/docs/model-api.txt b/docs/model-api.txt index c4d57bf8c4..1aa8c811f4 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -188,7 +188,8 @@ JavaScript shortcuts. ~~~~~~~~~~~~~~ A ``CharField`` that checks that the value is a valid e-mail address. -This doesn't accept ``maxlength``. +This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to +75. ``FileField`` ~~~~~~~~~~~~~ @@ -217,12 +218,27 @@ steps: subdirectory of ``MEDIA_ROOT`` it should upload files. 3. All that will be stored in your database is a path to the file - (relative to ``MEDIA_ROOT``). You'll must likely want to use the + (relative to ``MEDIA_ROOT``). You'll most likely want to use the convenience ``get_<fieldname>_url`` function provided by Django. For example, if your ``ImageField`` is called ``mug_shot``, you can get the absolute URL to your image in a template with ``{{ object.get_mug_shot_url }}``. +For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and +``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of +``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year, +``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you +upload a file on Jan. 15, 2007, it will be saved in the directory +``/home/media/photos/2007/01/15``. + +Note that whenever you deal with uploaded files, you should pay close attention +to where you're uploading them and what type of files they are, to avoid +security holes. *Validate all uploaded files* so that you're sure the files are +what you think they are. For example, if you blindly let somebody upload files, +without validation, to a directory that's within your Web server's document +root, then somebody could upload a CGI or PHP script and execute that script by +visiting its URL on your site. Don't allow that. + .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 ``FilePathField`` @@ -528,7 +544,9 @@ The default value for the field. ``editable`` ~~~~~~~~~~~~ -If ``False``, the field will not be editable in the admin. Default is ``True``. +If ``False``, the field will not be editable in the admin or via form +processing using the object's ``AddManipulator`` or ``ChangeManipulator`` +classes. Default is ``True``. ``help_text`` ~~~~~~~~~~~~~ @@ -671,8 +689,9 @@ you can use the name of the model, rather than the model object itself:: class Manufacturer(models.Model): # ... -Note, however, that support for strings around model names in ``ForeignKey`` is -quite new, and it can be buggy in some cases. +Note, however, that you can only use strings to refer to models in the same +models.py file -- you cannot use a string to reference a model in a different +application, or to reference a model that has been imported from elsewhere. Behind the scenes, Django appends ``"_id"`` to the field name to create its database column name. In the above example, the database table for the ``Car`` @@ -794,7 +813,10 @@ here's how you'd represent that:: As with ``ForeignKey``, a relationship to self can be defined by using the string ``'self'`` instead of the model name, and you can refer to as-yet -undefined models by using a string containing the model name. +undefined models by using a string containing the model name. However, you +can only use strings to refer to models in the same models.py file -- you +cannot use a string to reference a model in a different application, or to +reference a model that has been imported from elsewhere. It's suggested, but not required, that the name of a ``ManyToManyField`` (``toppings`` in the example above) be a plural describing the set of related @@ -1203,10 +1225,13 @@ A few special cases to note about ``list_display``: of the related object. * ``ManyToManyField`` fields aren't supported, because that would entail - executing a separate SQL statement for each row in the table. + executing a separate SQL statement for each row in the table. If you + want to do this nonetheless, give your model a custom method, and add + that method's name to ``list_display``. (See below for more on custom + methods in ``list_display``.) - * If the field is a ``BooleanField``, Django will display a pretty "on" or - "off" icon instead of ``True`` or ``False``. + * If the field is a ``BooleanField`` or ``NullBooleanField``, Django will + display a pretty "on" or "off" icon instead of ``True`` or ``False``. * If the string given is a method of the model, Django will call it and display the output. This method should have a ``short_description`` @@ -1225,6 +1250,34 @@ A few special cases to note about ``list_display``: return self.birthday.strftime('%Y')[:3] + "0's" decade_born_in.short_description = 'Birth decade' + * If the string given is a method of the model, Django will HTML-escape the + output by default. If you'd rather not escape the output of the method, + give the method an ``allow_tags`` attribute whose value is ``True``. + + Here's a full example model:: + + class Person(models.Model): + first_name = models.CharField(maxlength=50) + last_name = models.CharField(maxlength=50) + color_code = models.CharField(maxlength=6) + + class Admin: + list_display = ('first_name', 'last_name', 'colored_name') + + def colored_name(self): + return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name) + colored_name.allow_tags = True + + * The ``__str__()`` method is just as valid in ``list_display`` as any + other model method, so it's perfectly OK to do this:: + + list_display = ('__str__', 'some_other_field') + + * For any element of ``list_display`` that is not a field on the model, the + change list page will not allow ordering by that column. This is because + ordering is done at the database level, and Django has no way of knowing + how to order the result of a custom method at the SQL level. + ``list_display_links`` ---------------------- @@ -1349,6 +1402,41 @@ user searches for ``john lennon``, Django will do the equivalent of this SQL WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%') AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%') +**New in Django development version:** For faster and/or more restrictive +searches, prefix the field name with an operator: + +``^`` + Matches the beginning of the field. For example, if ``search_fields`` is + set to ``['^first_name', '^last_name']`` and a user searches for + ``john lennon``, Django will do the equivalent of this SQL ``WHERE`` + clause:: + + WHERE (first_name ILIKE 'john%' OR last_name ILIKE 'john%') + AND (first_name ILIKE 'lennon%' OR last_name ILIKE 'lennon%') + + This query is more efficient than the normal ``'%john%'`` query, because + the database only needs to check the beginning of a column's data, rather + than seeking through the entire column's data. Plus, if the column has an + index on it, some databases may be able to use the index for this query, + even though it's a ``LIKE`` query. + +``=`` + Matches exactly, case-insensitive. For example, if + ``search_fields`` is set to ``['=first_name', '=last_name']`` and + a user searches for ``john lennon``, Django will do the equivalent + of this SQL ``WHERE`` clause:: + + WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john') + AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon') + + Note that the query input is split by spaces, so, following this example, + it's not currently not possible to search for all records in which + ``first_name`` is exactly ``'john winston'`` (containing a space). + +``@`` + Performs a full-text match. This is like the default search method but uses + an index. Currently this is only available for MySQL. + Managers ======== diff --git a/docs/overview.txt b/docs/overview.txt index 5a399582e8..8e6274dd9a 100644 --- a/docs/overview.txt +++ b/docs/overview.txt @@ -159,7 +159,7 @@ of contents for your app, it contains a simple mapping between URL patterns and Python callback functions. URLconfs also serve to decouple URLs from Python code. -Here's what a URLconf might look like for the above ``Reporter``/``Article`` +Here's what a URLconf might look like for the ``Reporter``/``Article`` example above:: from django.conf.urls.defaults import * diff --git a/docs/release_notes_0.95.txt b/docs/release_notes_0.95.txt new file mode 100644 index 0000000000..3709cacf5a --- /dev/null +++ b/docs/release_notes_0.95.txt @@ -0,0 +1,126 @@ +================================= +Django version 0.95 release notes +================================= + + +Welcome to the Django 0.95 release. + +This represents a significant advance in Django development since the 0.91 +release in January 2006. The details of every change in this release would be +too extensive to list in full, but a summary is presented below. + +Suitability and API stability +============================= + +This release is intended to provide a stable reference point for developers +wanting to work on production-level applications that use Django. + +However, it's not the 1.0 release, and we'll be introducing further changes +before 1.0. For a clear look at which areas of the framework will change (and +which ones will *not* change) before 1.0, see the api-stability.txt file, which +lives in the docs/ directory of the distribution. + +You may have a need to use some of the features that are marked as +"subject to API change" in that document, but that's OK with us as long as it's +OK with you, and as long as you understand APIs may change in the future. + +Fortunately, most of Django's core APIs won't be changing before version 1.0. +There likely won't be as big of a change between 0.95 and 1.0 versions as there +was between 0.91 and 0.95. + +Changes and new features +======================== + +The major changes in this release (for developers currently using the 0.91 +release) are a result of merging the 'magic-removal' branch of development. +This branch removed a number of constraints in the way Django code had to be +written that were a consequence of decisions made in the early days of Django, +prior to its open-source release. It's now possible to write more natural, +Pythonic code that works as expected, and there's less "black magic" happening +behind the scenes. + +Aside from that, another main theme of this release is a dramatic increase in +usability. We've made countless improvements in error messages, documentation, +etc., to improve developers' quality of life. + +The new features and changes introduced in 0.95 include: + + * Django now uses a more consistent and natural filtering interface for + retrieving objects from the database. + + * User-defined models, functions and constants now appear in the module + namespace they were defined in. (Previously everything was magically + transferred to the django.models.* namespace.) + + * Some optional applications, such as the FlatPage, Sites and Redirects + apps, have been decoupled and moved into django.contrib. If you don't + want to use these applications, you no longer have to install their + database tables. + + * Django now has support for managing database transactions. + + * We've added the ability to write custom authentication and authorization + backends for authenticating users against alternate systems, such as + LDAP. + + * We've made it easier to add custom table-level functions to models, + through a new "Manager" API. + + * It's now possible to use Django without a database. This simply means + that the framework no longer requires you to have a working database set + up just to serve dynamic pages. In other words, you can just use + URLconfs/views on their own. Previously, the framework required that a + database be configured, regardless of whether you actually used it. + + * It's now more explicit and natural to override save() and delete() + methods on models, rather than needing to hook into the pre_save() and + post_save() method hooks. + + * Individual pieces of the framework now can be configured without + requiring the setting of an environment variable. This permits use of, + for example, the Django templating system inside other applications. + + * More and more parts of the framework have been internationalized, as + we've expanded internationalization (i18n) support. The Django + codebase, including code and templates, has now been translated, at least + in part, into 31 languages. From Arabic to Chinese to Hungarian to Welsh, + it is now possible to use Django's admin site in your native language. + +The number of changes required to port from 0.91-compatible code to the 0.95 +code base are significant in some cases. However, they are, for the most part, +reasonably routine and only need to be done once. A list of the necessary +changes is described in the `Removing The Magic`_ wiki page. There is also an +easy checklist_ for reference when undertaking the porting operation. + +.. _Removing The Magic: http://code.djangoproject.com/wiki/RemovingTheMagic +.. _checklist: http://code.djangoproject.com/wiki/MagicRemovalCheatSheet1 + +Problem reports and getting help +================================ + +Need help resolving a problem with Django? The documentation in the +distribution is also available online_ at the `Django website`_. The FAQ_ +document is especially recommended, as it contains a number of issues that +come up time and again. + +For more personalized help, the `django-users`_ mailing list is a very active +list, with more than 2,000 subscribers who can help you solve any sort of +Django problem. We recommend you search the archives first, though, because +many common questions appear with some regularity, and any particular problem +may already have been answered. + +Finally, for those who prefer the more immediate feedback offered by IRC, +there's a #django channel on irc.freenode.net that is regularly populated by +Django users and developers from around the world. Friendly people are usually +available at any hour of the day -- to help, or just to chat. + +.. _online: http://www.djangoproject.com/documentation/ +.. _Django website: http://www.djangoproject.com/ +.. _FAQ: http://www.djangoproject.com/documentation/faq/ +.. _django-users: http://groups.google.com/group/django-users + +Thanks for using Django! + +The Django Team +July 2006 + diff --git a/docs/request_response.txt b/docs/request_response.txt index 0bcb3a7f5b..006ac6b648 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -106,12 +106,12 @@ All attributes except ``session`` should be considered read-only. A ``django.contrib.auth.models.User`` object representing the currently logged-in user. If the user isn't currently logged in, ``user`` will be set to an instance of ``django.contrib.auth.models.AnonymousUser``. You - can tell them apart with ``is_anonymous()``, like so:: + can tell them apart with ``is_authenticated()``, like so:: - if request.user.is_anonymous(): - # Do something for anonymous users. - else: + if request.user.is_authenticated(): # Do something for logged-in users. + else: + # Do something for anonymous users. ``user`` is only available if your Django installation has the ``AuthenticationMiddleware`` activated. For more, see @@ -134,21 +134,25 @@ Methods ------- ``__getitem__(key)`` - Returns the GET/POST value for the given key, checking POST first, then - GET. Raises ``KeyError`` if the key doesn't exist. + Returns the GET/POST value for the given key, checking POST first, then + GET. Raises ``KeyError`` if the key doesn't exist. - This lets you use dictionary-accessing syntax on an ``HttpRequest`` - instance. Example: ``request["foo"]`` would return ``True`` if either - ``request.POST`` or ``request.GET`` had a ``"foo"`` key. + This lets you use dictionary-accessing syntax on an ``HttpRequest`` + instance. Example: ``request["foo"]`` would return ``True`` if either + ``request.POST`` or ``request.GET`` had a ``"foo"`` key. ``has_key()`` - Returns ``True`` or ``False``, designating whether ``request.GET`` or - ``request.POST`` has the given key. + Returns ``True`` or ``False``, designating whether ``request.GET`` or + ``request.POST`` has the given key. ``get_full_path()`` - Returns the ``path``, plus an appended query string, if applicable. + Returns the ``path``, plus an appended query string, if applicable. + + Example: ``"/music/bands/the_beatles/?print=true"`` - Example: ``"/music/bands/the_beatles/?print=true"`` +``is_secure()`` + Returns ``True`` if the request is secure; that is, if it was made with + HTTPS. QueryDict objects ----------------- @@ -337,9 +341,9 @@ hard-coded strings. If you use this technique, follow these guidelines: Methods ------- -``__init__(content='', mimetype=DEFAULT_MIME_TYPE)`` +``__init__(content='', mimetype=DEFAULT_CONTENT_TYPE)`` Instantiates an ``HttpResponse`` object with the given page content (a - string) and MIME type. The ``DEFAULT_MIME_TYPE`` is ``'text/html'``. + string) and MIME type. The ``DEFAULT_CONTENT_TYPE`` is ``'text/html'``. ``content`` can be an iterator or a string. If it's an iterator, it should return strings, and those strings will be joined together to form the @@ -376,10 +380,14 @@ Methods .. _`cookie Morsel`: http://www.python.org/doc/current/lib/morsel-objects.html -``delete_cookie(key)`` +``delete_cookie(key, path='/', domain=None)`` Deletes the cookie with the given key. Fails silently if the key doesn't exist. + The ``path`` and ``domain`` arguments are new in the Django development version. + Due to the way cookies work, ``path`` and ``domain`` should be the same + values you used in ``set_cookie()`` -- otherwise the cookie may not be deleted. + ``content`` Returns the content as a Python string, encoding it from a Unicode object if necessary. Note this is a property, not a method, so use ``r.content`` diff --git a/docs/serialization.txt b/docs/serialization.txt index 25199e7a50..aee1b9a3bb 100644 --- a/docs/serialization.txt +++ b/docs/serialization.txt @@ -3,12 +3,12 @@ Serializing Django objects ========================== .. note:: - + This API is currently under heavy development and may change -- perhaps drastically -- in the future. - + You have been warned. - + Django's serialization framework provides a mechanism for "translating" Django objects into other formats. Usually these other formats will be text-based and used for sending Django objects over a wire, but it's possible for a @@ -21,7 +21,7 @@ At the highest level, serializing data is a very simple operation:: from django.core import serializers data = serializers.serialize("xml", SomeModel.objects.all()) - + The arguments to the ``serialize`` function are the format to serialize the data to (see `Serialization formats`_) and a QuerySet_ to serialize. (Actually, the second argument can be any iterator that yields Django objects, @@ -34,7 +34,7 @@ You can also use a serializer object directly:: xml_serializer = serializers.get_serializer("xml") xml_serializer.serialize(queryset) data = xml_serializer.getvalue() - + This is useful if you want to serialize data directly to a file-like object (which includes a HTTPResponse_):: @@ -50,7 +50,7 @@ Deserializing data is also a fairly simple operation:: for obj in serializers.deserialize("xml", data): do_something_with(obj) - + As you can see, the ``deserialize`` function takes the same format argument as ``serialize``, a string or stream of data, and returns an iterator. @@ -69,7 +69,7 @@ something like:: for deserialized_object in serializers.deserialize("xml", data): if object_should_be_saved(deserialized_object): obj.save() - + In other words, the usual use is to examine the deserialized objects to make sure that they are "appropriate" for saving before doing so. Of course, if you trust your data source you could just save the object and move on. @@ -89,13 +89,28 @@ Django "ships" with a few included serializers: bundled with Django). ``python`` Translates to and from "simple" Python objects (lists, dicts, - strings, etc.). Not really all that useful on its own, but + strings, etc.). Not really all that useful on its own, but used as a base for other serializers. ========== ============================================================== .. _json: http://json.org/ .. _simplejson: http://undefined.org/python/#simplejson +Notes for specific serialization formats +---------------------------------------- + +json +~~~~ + +If you're using UTF-8 (or any other non-ASCII encoding) data with the JSON +serializer, you must pass ``ensure_ascii=False`` as a parameter to the +``serialize()`` call. Otherwise, the output won't be encoded correctly. + +For example:: + + json_serializer = serializers.get_serializer("json") + json_serializer.serialize(queryset, ensure_ascii=False, stream=response) + Writing custom serializers `````````````````````````` diff --git a/docs/sessions.txt b/docs/sessions.txt index c473d0a3db..d39f42c3bf 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -245,6 +245,17 @@ Default: ``'sessionid'`` The name of the cookie to use for sessions. This can be whatever you want. +SESSION_COOKIE_SECURE +--------------------- + +**New in Django development version** + +Default: ``False`` + +Whether to use a secure cookie for the session cookie. If this is set to +``True``, the cookie will be marked as "secure," which means browsers may +ensure that the cookie is only sent under an HTTPS connection. + SESSION_EXPIRE_AT_BROWSER_CLOSE ------------------------------- diff --git a/docs/settings.txt b/docs/settings.txt index 5b75e29172..272b20f753 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -401,15 +401,6 @@ Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins or ``django.core.mail.mail_managers``. You'll probably want to include the trailing space. -ENABLE_PSYCO ------------- - -Default: ``False`` - -Whether to enable Psyco, which optimizes Python code. Requires Psyco_. - -.. _Psyco: http://psyco.sourceforge.net/ - IGNORABLE_404_ENDS ------------------ @@ -473,25 +464,36 @@ LANGUAGES Default: A tuple of all available languages. Currently, this is:: LANGUAGES = ( + ('ar', _('Arabic')), ('bn', _('Bengali')), ('cs', _('Czech')), ('cy', _('Welsh')), ('da', _('Danish')), ('de', _('German')), + ('el', _('Greek')), ('en', _('English')), ('es', _('Spanish')), + ('es_AR', _('Argentinean Spanish')), ('fr', _('French')), ('gl', _('Galician')), + ('hu', _('Hungarian')), + ('he', _('Hebrew')), ('is', _('Icelandic')), ('it', _('Italian')), + ('ja', _('Japanese')), + ('nl', _('Dutch')), ('no', _('Norwegian')), ('pt-br', _('Brazilian')), ('ro', _('Romanian')), ('ru', _('Russian')), ('sk', _('Slovak')), + ('sl', _('Slovenian')), ('sr', _('Serbian')), ('sv', _('Swedish')), + ('ta', _('Tamil')), + ('uk', _('Ukrainian')), ('zh-cn', _('Simplified Chinese')), + ('zh-tw', _('Traditional Chinese')), ) A tuple of two-tuples in the format (language code, language name). This @@ -526,7 +528,7 @@ any code that uses ``LANGUAGES`` at runtime. MANAGERS -------- -Default: ``ADMINS`` (Whatever ``ADMINS`` is set to) +Default: ``()`` (Empty tuple) A tuple in the same format as ``ADMINS`` that specifies who should get broken-link notifications when ``SEND_BROKEN_LINK_EMAILS=True``. @@ -585,6 +587,15 @@ Whether to prepend the "www." subdomain to URLs that don't have it. This is only used if ``CommonMiddleware`` is installed (see the `middleware docs`_). See also ``APPEND_SLASH``. +PROFANITIES_LIST +---------------- + +A tuple of profanities, as strings, that will trigger a validation error when +the ``hasNoProfanities`` validator is called. + +We don't list the default values here, because that would be profane. To see +the default values, see the file ``django/conf/global_settings.py``. + ROOT_URLCONF ------------ @@ -647,6 +658,18 @@ Default: ``'sessionid'`` The name of the cookie to use for sessions. This can be whatever you want. See the `session docs`_. +SESSION_COOKIE_SECURE +--------------------- + +**New in Django development version** + +Default: ``False`` + +Whether to use a secure cookie for the session cookie. If this is set to +``True``, the cookie will be marked as "secure," which means browsers may +ensure that the cookie is only sent under an HTTPS connection. +See the `session docs`_. + SESSION_EXPIRE_AT_BROWSER_CLOSE ------------------------------- @@ -731,6 +754,30 @@ misspelled) variables. See `How invalid variables are handled`_. .. _How invalid variables are handled: http://www.djangoproject.com/documentation/templates_python/#how-invalid-variables-are-handled +TEST_RUNNER +----------- + +**New in Django development version** + +Default: ``'django.test.simple.run_tests'`` + +The name of the method to use for starting the test suite. See +`Testing Django Applications`_. + +.. _Testing Django Applications: ../testing/ + +TEST_DATABASE_NAME +------------------ + +**New in Django development version** + +Default: ``None`` + +The name of database to use when running the test suite. If a value of +``None`` is specified, the test database will use the name ``'test_' + settings.DATABASE_NAME``. See `Testing Django Applications`_. + +.. _Testing Django Applications: ../testing/ + TIME_FORMAT ----------- @@ -760,6 +807,13 @@ Note that this is the time zone to which Django will convert all dates/times -- not necessarily the timezone of the server. For example, one server may serve multiple Django-powered sites, each with a separate time-zone setting. +Normally, Django sets the ``os.environ['TZ']`` variable to the time zone you +specify in the ``TIME_ZONE`` setting. Thus, all your views and models will +automatically operate in the correct time zone. However, if you're using the +manual configuration option (see below), Django will *not* touch the ``TZ`` +environment variable, and it'll be up to you to ensure your processes are +running in the correct environment. + USE_ETAGS --------- @@ -837,6 +891,15 @@ uppercase, with the same name as the settings described above. If a particular setting is not passed to ``configure()`` and is needed at some later point, Django will use the default setting value. +Configuring Django in this fashion is mostly necessary -- and, indeed, +recommended -- when you're using a piece of the framework inside a larger +application. + +Consequently, when configured via ``settings.configure()``, Django will not +make any modifications to the process environment variables. (See the +explanation of ``TIME_ZONE``, above, for why this would normally occur.) It's +assumed that you're already in full control of your environment in these cases. + Custom default settings ----------------------- diff --git a/docs/sitemaps.txt b/docs/sitemaps.txt new file mode 100644 index 0000000000..fec65572f2 --- /dev/null +++ b/docs/sitemaps.txt @@ -0,0 +1,320 @@ +===================== +The sitemap framework +===================== + +**New in Django development version**. + +Django comes with a high-level sitemap-generating framework that makes +creating `Google Sitemap`_ XML files easy. + +.. _Google Sitemap: http://www.google.com/webmasters/sitemaps/docs/en/protocol.html + +Overview +======== + +A sitemap is an XML file on your Web site that tells search-engine indexers how +frequently your pages change and how "important" certain pages are in relation +to other pages on your site. This information helps search engines index your +site. + +The Django sitemap framework automates the creation of this XML file by letting +you express this information in Python code. + +It works much like Django's `syndication framework`_. To create a sitemap, just +write a ``Sitemap`` class and point to it in your URLconf_. + +.. _syndication framework: http://www.djangoproject.com/documentation/syndication/ +.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/ + +Installation +============ + +To install the sitemap app, follow these steps: + + 1. Add ``'django.contrib.sitemaps'`` to your INSTALLED_APPS_ setting. + 2. Make sure ``'django.template.loaders.app_directories.load_template_source'`` + is in your TEMPLATE_LOADERS_ setting. It's in there by default, so + you'll only need to change this if you've changed that setting. + 3. Make sure you've installed the `sites framework`_. + +(Note: The sitemap application doesn't install any database tables. The only +reason it needs to go into ``INSTALLED_APPS`` is so that the +``load_template_source`` template loader can find the default templates.) + +.. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps +.. _TEMPLATE_LOADERS: http://www.djangoproject.com/documentation/settings/#template-loaders +.. _sites framework: http://www.djangoproject.com/documentation/sites/ + +Initialization +============== + +To activate sitemap generation on your Django site, add this line to your +URLconf_: + + (r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) + +This tells Django to build a sitemap when a client accesses ``/sitemap.xml``. + +The name of the sitemap file is not important, but the location is. Google will +only index links in your sitemap for the current URL level and below. For +instance, if ``sitemap.xml`` lives in your root directory, it may reference any +URL in your site. However, if your sitemap lives at ``/content/sitemap.xml``, +it may only reference URLs that begin with ``/content/``. + +The sitemap view takes an extra, required argument: ``{'sitemaps': sitemaps}``. +``sitemaps`` should be a dictionary that maps a short section label (e.g., +``blog`` or ``news``) to its ``Sitemap`` class (e.g., ``BlogSitemap`` or +``NewsSitemap``). It may also map to an *instance* of a ``Sitemap`` class +(e.g., ``BlogSitemap(some_var)``). + +.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/ + +Sitemap classes +=============== + +A ``Sitemap`` class is a simple Python class that represents a "section" of +entries in your sitemap. For example, one ``Sitemap`` class could represent all +the entries of your weblog, while another could represent all of the events in +your events calendar. + +In the simplest case, all these sections get lumped together into one +``sitemap.xml``, but it's also possible to use the framework to generate a +sitemap index that references individual sitemap files, one per section. (See +`Creating a sitemap index`_ below.) + +``Sitemap`` classes must subclass ``django.contrib.sitemaps.Sitemap``. They can +live anywhere in your codebase. + +A simple example +================ + +Let's assume you have a blog system, with an ``Entry`` model, and you want your +sitemap to include all the links to your individual blog entries. Here's how +your sitemap class might look:: + + from django.contrib.sitemaps import Sitemap + from mysite.blog.models import Entry + + class BlogSitemap(Sitemap): + changefreq = "never" + priority = 0.5 + + def items(self): + return Entry.objects.filter(is_draft=False) + + def lastmod(self, obj): + return obj.pub_date + +Note: + + * ``changefreq`` and ``priority`` are class attributes corresponding to + ``<changefreq>`` and ``<priority>`` elements, respectively. They can be + made callable as functions, as ``lastmod`` was in the example. + * ``items()`` is simply a method that returns a list of objects. The objects + returned will get passed to any callable methods corresponding to a + sitemap property (``location``, ``lastmod``, ``changefreq``, and + ``priority``). + * ``lastmod`` should return a Python ``datetime`` object. + * There is no ``location`` method in this example, but you can provide it + in order to specify the URL for your object. By default, ``location()`` + calls ``get_absolute_url()`` on each object and returns the result. + +Sitemap class reference +======================= + +A ``Sitemap`` class can define the following methods/attributes: + +``items`` +--------- + +**Required.** A method that returns a list of objects. The framework doesn't +care what *type* of objects they are; all that matters is that these objects +get passed to the ``location()``, ``lastmod()``, ``changefreq()`` and +``priority()`` methods. + +``location`` +------------ + +**Optional.** Either a method or attribute. + +If it's a method, it should return the absolute URL for a given object as +returned by ``items()``. + +If it's an attribute, its value should be a string representing an absolute URL +to use for *every* object returned by ``items()``. + +In both cases, "absolute URL" means a URL that doesn't include the protocol or +domain. Examples: + + * Good: ``'/foo/bar/'`` + * Bad: ``'example.com/foo/bar/'`` + * Bad: ``'http://example.com/foo/bar/'`` + +If ``location`` isn't provided, the framework will call the +``get_absolute_url()`` method on each object as returned by ``items()``. + +``lastmod`` +----------- + +**Optional.** Either a method or attribute. + +If it's a method, it should take one argument -- an object as returned by +``items()`` -- and return that object's last-modified date/time, as a Python +``datetime.datetime`` object. + +If it's an attribute, its value should be a Python ``datetime.datetime`` object +representing the last-modified date/time for *every* object returned by +``items()``. + +``changefreq`` +-------------- + +**Optional.** Either a method or attribute. + +If it's a method, it should take one argument -- an object as returned by +``items()`` -- and return that object's change frequency, as a Python string. + +If it's an attribute, its value should be a string representing the change +frequency of *every* object returned by ``items()``. + +Possible values for ``changefreq``, whether you use a method or attribute, are: + + * ``'always'`` + * ``'hourly'`` + * ``'daily'`` + * ``'weekly'`` + * ``'monthly'`` + * ``'yearly'`` + * ``'never'`` + +``priority`` +------------ + +**Optional.** Either a method or attribute. + +If it's a method, it should take one argument -- an object as returned by +``items()`` -- and return that object's priority, as either a string or float. + +If it's an attribute, its value should be either a string or float representing +the priority of *every* object returned by ``items()``. + +Example values for ``priority``: ``0.4``, ``1.0``. The default priority of a +page is ``0.5``. See Google's documentation for more documentation. + +.. _Google's documentation: http://www.google.com/webmasters/sitemaps/docs/en/protocol.html + +Shortcuts +========= + +The sitemap framework provides a couple convenience classes for common cases: + +``FlatPageSitemap`` +------------------- + +The ``django.contrib.sitemaps.FlatPageSitemap`` class looks at all flatpages_ +defined for the current ``SITE_ID`` (see the `sites documentation`_) and +creates an entry in the sitemap. These entries include only the ``location`` +attribute -- not ``lastmod``, ``changefreq`` or ``priority``. + +.. _flatpages: http://www.djangoproject.com/documentation/flatpages/ +.. _sites documentation: http://www.djangoproject.com/documentation/sites/ + +``GenericSitemap`` +------------------ + +The ``GenericSitemap`` class works with any `generic views`_ you already have. +To use it, create an instance, passing in the same ``info_dict`` you pass to +the generic views. The only requirement is that the dictionary have a +``queryset`` entry. It may also have a ``date_field`` entry that specifies a +date field for objects retrieved from the ``queryset``. This will be used for +the ``lastmod`` attribute in the generated sitemap. You may also pass +``priority`` and ``changefreq`` keyword arguments to the ``GenericSitemap`` +constructor to specify these attributes for all URLs. + +.. _generic views: http://www.djangoproject.com/documentation/generic_views/ + +Example +------- + +Here's an example of a URLconf_ using both:: + + from django.conf.urls.defaults import * + from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap + from mysite.blog.models import Entry + + info_dict = { + 'queryset': Entry.objects.all(), + 'date_field': 'pub_date', + } + + sitemaps = { + 'flatpages': FlatPageSitemap, + 'blog': GenericSitemap(info_dict, priority=0.6), + } + + urlpatterns = patterns('', + # some generic view using info_dict + # ... + + # the sitemap + (r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) + ) + +.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/ + +Creating a sitemap index +======================== + +The sitemap framework also has the ability to create a sitemap index that +references individual sitemap files, one per each section defined in your +``sitemaps`` dictionary. The only differences in usage are: + + * You use two views in your URLconf: ``django.contrib.sitemaps.views.index`` + and ``django.contrib.sitemaps.views.sitemap``. + * The ``django.contrib.sitemaps.views.sitemap`` view should take a + ``section`` keyword argument. + +Here is what the relevant URLconf lines would look like for the example above:: + + (r'^sitemap.xml$', 'django.contrib.sitemaps.views.index', {'sitemaps': sitemaps}) + (r'^sitemap-(?P<section>.+).xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) + +This will automatically generate a ``sitemap.xml`` file that references +both ``sitemap-flatpages.xml`` and ``sitemap-blog.xml``. The ``Sitemap`` +classes and the ``sitemaps`` dict don't change at all. + +Pinging Google +============== + +You may want to "ping" Google when your sitemap changes, to let it know to +reindex your site. The framework provides a function to do just that: +``django.contrib.sitemaps.ping_google()``. + +``ping_google()`` takes an optional argument, ``sitemap_url``, which should be +the absolute URL of your site's sitemap (e.g., ``'/sitemap.xml'``). If this +argument isn't provided, ``ping_google()`` will attempt to figure out your +sitemap by performing a reverse looking in your URLconf. + +``ping_google()`` raises the exception +``django.contrib.sitemaps.SitemapNotFound`` if it cannot determine your sitemap +URL. + +One useful way to call ``ping_google()`` is from a model's ``save()`` method:: + + from django.contrib.sitemaps import ping_google + + class Entry(models.Model): + # ... + def save(self): + super(Entry, self).save() + try: + ping_google() + except Exception: + # Bare 'except' because we could get a variety + # of HTTP-related exceptions. + pass + +A more efficient solution, however, would be to call ``ping_google()`` from a +cron script, or some other scheduled task. The function makes an HTTP request +to Google's servers, so you may not want to introduce that network overhead +each time you call ``save()``. diff --git a/docs/sites.txt b/docs/sites.txt index cca9f14f31..8c5f1fc64b 100644 --- a/docs/sites.txt +++ b/docs/sites.txt @@ -266,7 +266,18 @@ this:: If you attempt to use ``CurrentSiteManager`` and pass a field name that doesn't exist, Django will raise a ``ValueError``. +Finally, note that you'll probably want to keep a normal (non-site-specific) +``Manager`` on your model, even if you use ``CurrentSiteManager``. As explained +in the `manager documentation`_, if you define a manager manually, then Django +won't create the automatic ``objects = models.Manager()`` manager for you. +Also, note that certain parts of Django -- namely, the Django admin site and +generic views -- use whichever manager is defined *first* in the model, so if +you want your admin site to have access to all objects (not just site-specific +ones), put ``objects = models.Manager()`` in your model, before you define +``CurrentSiteManager``. + .. _manager: http://www.djangoproject.com/documentation/model_api/#managers +.. _manager documentation: http://www.djangoproject.com/documentation/model_api/#managers How Django uses the sites framework =================================== diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index c84785b20b..225b67eb02 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -427,7 +427,7 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas author's e-mail as a normal Python string. """ - def author_name(self): + def author_email(self): """ Returns the feed's author's e-mail as a normal Python string. """ @@ -707,7 +707,7 @@ This example creates an Atom 1.0 feed and prints it to standard output:: ... title=u"My Weblog", ... link=u"http://www.example.com/", ... description=u"In which I write about what I ate today.", - ... language=u"en"), + ... language=u"en") >>> f.add_item(title=u"Hot dog today", ... link=u"http://www.example.com/entries/1/", ... description=u"<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>") diff --git a/docs/templates.txt b/docs/templates.txt index 4ba52b3263..0f0009b495 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -47,7 +47,7 @@ explained later in this document.:: JavaScript and CSV. You can use the template language for any text-based format. - Oh, and one more thing: Making humans edit XML is masochistic! + Oh, and one more thing: Making humans edit XML is sadistic! Variables ========= @@ -109,6 +109,21 @@ Some tags require beginning and ending tags (i.e. below describes all the built-in tags. You can create your own tags, if you know how to write Python code. +Comments +======== + +**New in Django development version** + +To comment-out part of a template, use the comment syntax: ``{# #}``. + +For example, this template would render as ``'hello'``:: + + {# greeting #}hello + +A comment can contain any template code, invalid or not. For example:: + + {# {% if foo %}bar{% else %} #} + Template inheritance ==================== @@ -141,6 +156,7 @@ It's easiest to understand template inheritance by starting with an example:: {% block content %}{% endblock %} </div> </body> + </html> This template, which we'll call ``base.html``, defines a simple HTML skeleton document that you might use for a simple two-column page. It's the job of @@ -196,6 +212,7 @@ like:: <p>This is my second entry.</p> </div> </body> + </html> Note that since the child template didn't define the ``sidebar`` block, the value from the parent template is used instead. Content within a ``{% block %}`` @@ -363,10 +380,15 @@ extends Signal that this template extends a parent template. -This tag may be used in two ways: ``{% extends "base.html" %}`` (with quotes) -uses the literal value "base.html" as the name of the parent template to -extend, or ``{% extends variable %}`` uses the value of ``variable`` as the -name of the parent template to extend. +This tag can be used in two ways: + + * ``{% extends "base.html" %}`` (with quotes) uses the literal value + ``"base.html"`` as the name of the parent template to extend. + + * ``{% extends variable %}`` uses the value of ``variable``. If the variable + evaluates to a string, Django will use that string as the name of the + parent template. If the variable evaluates to a ``Template`` object, + Django will use that object as the parent template. See `Template inheritance`_ for more information. @@ -493,6 +515,11 @@ If you need to combine ``and`` and ``or`` to do advanced logic, just use nested {% endif %} {% endif %} +Multiple uses of the same logical operator are fine, as long as you use the +same operator. For example, this is valid:: + + {% if athlete_list or coach_list or parent_list or teacher_list %} + ifchanged ~~~~~~~~~ @@ -528,6 +555,11 @@ The arguments can be hard-coded strings, so the following is valid:: ... {% endifequal %} +It is only possible to compare an argument to template variables or strings. +You cannot check for equality with Python objects such as ``True`` or +``False``. If you need to test if something is true or false, use the ``if`` +and ``ifnot`` tags instead. + ifnotequal ~~~~~~~~~~ @@ -951,13 +983,13 @@ any string. pluralize ~~~~~~~~~ -Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. +Returns a plural suffix if the value is not 1. By default, this suffix is ``'s'``. Example:: You have {{ num_messages }} message{{ num_messages|pluralize }}. -For words that require a suffix other than ``'s'``, you can provide an alternate +For words that require a suffix other than ``'s'``, you can provide an alternate suffix as a parameter to the filter. Example:: @@ -1039,7 +1071,7 @@ Formats a date as the time since that date (i.e. "4 days, 6 hours"). Takes an optional argument that is a variable containing the date to use as the comparison point (without the argument, the comparison point is *now*). For example, if ``blog_date`` is a date instance representing midnight on 1 -June 2006, and ``comment_date`` is a date instanace for 08:00 on 1 June 2006, +June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006, then ``{{ comment_date|timesince:blog_date }}`` would return "8 hours". timeuntil diff --git a/docs/templates_python.txt b/docs/templates_python.txt index d353abb5bc..ae2582d7b8 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -198,25 +198,35 @@ some things to keep in mind: How invalid variables are handled ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In Django 0.91, if a variable doesn't exist, the template system fails -silently. The variable is replaced with an empty string:: +Generally, if a variable doesn't exist, the template system inserts the +value of the ``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''`` +(the empty string) by default. - >>> t = Template("My name is {{ my_name }}.") - >>> c = Context({"foo": "bar"}) - >>> t.render(c) - "My name is ." - -This applies to any level of lookup:: +Filters that are applied to an invalid variable will only be applied if +``TEMPLATE_STRING_IF_INVALID`` is set to ``''`` (the empty string). If +``TEMPLATE_STRING_IF_INVALID`` is set to any other value, variable +filters will be ignored. - >>> t = Template("My name is {{ person.fname }} {{ person.lname }}.") - >>> c = Context({"person": {"fname": "Stan"}}) - >>> t.render(c) - "My name is Stan ." +This behavior is slightly different for the ``if``, ``for`` and ``regroup`` +template tags. If an invalid variable is provided to one of these template +tags, the variable will be interpreted as ``None``. Filters are always +applied to invalid variables within these template tags. -If a variable doesn't exist, the template system inserts the value of the -``TEMPLATE_STRING_IF_INVALID`` setting, which is set to ``''`` (the empty -string) by default. +.. admonition:: For debug purposes only! + While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool, + it is a bad idea to turn it on as a 'development default'. + + Many templates, including those in the Admin site, rely upon the + silence of the template system when a non-existent variable is + encountered. If you assign a value other than ``''`` to + ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering + problems with these templates and sites. + + Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled + in order to debug a specific template problem, then cleared + once debugging is complete. + Playing with Context objects ---------------------------- @@ -274,9 +284,10 @@ an `HttpRequest object`_ as its first argument. For example:: The second difference is that it automatically populates the context with a few variables, according to your `TEMPLATE_CONTEXT_PROCESSORS setting`_. -The ``TEMPLATE_CONTEXT_PROCESSORS`` setting is a tuple of callables that take a -request object as their argument and return a dictionary of items to be merged -into the context. By default, ``TEMPLATE_CONTEXT_PROCESSORS`` is set to:: +The ``TEMPLATE_CONTEXT_PROCESSORS`` setting is a tuple of callables -- called +**context processors** -- that take a request object as their argument and +return a dictionary of items to be merged into the context. By default, +``TEMPLATE_CONTEXT_PROCESSORS`` is set to:: ("django.core.context_processors.auth", "django.core.context_processors.debug", @@ -300,6 +311,20 @@ optional, third positional argument, ``processors``. In this example, the 'foo': 'bar', }, [ip_address_processor]) +Note:: + If you're using Django's ``render_to_response()`` shortcut to populate a + template with the contents of a dictionary, your template will be passed a + ``Context`` instance by default (not a ``RequestContext``). To use a + ``RequestContext`` in your template rendering, pass an optional third + argument to ``render_to_response()``: a ``RequestContext`` + instance. Your code might look like this:: + + def some_view(request): + # ... + return render_to_response('my_template'html', + my_data_dictionary, + context_instance=RequestContext(request)) + Here's what each of the default processors does: .. _HttpRequest object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects @@ -314,13 +339,22 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every * ``user`` -- An ``auth.User`` instance representing the currently logged-in user (or an ``AnonymousUser`` instance, if the client isn't logged in). See the `user authentication docs`. - * ``messages`` -- A list of ``auth.Message`` objects for the currently - logged-in user. - * ``perms`` -- An instance of ``django.core.context_processors.PermWrapper``, - representing the permissions that the currently logged-in user has. See - the `permissions docs`_. + + * ``messages`` -- A list of messages (as strings) for the currently + logged-in user. Behind the scenes, this calls + ``request.user.get_and_delete_messages()`` for every request. That method + collects the user's messages and deletes them from the database. + + Note that messages are set with ``user.add_message()``. See the + `message docs`_ for more. + + * ``perms`` -- An instance of + ``django.core.context_processors.PermWrapper``, representing the + permissions that the currently logged-in user has. See the `permissions + docs`_. .. _user authentication docs: http://www.djangoproject.com/documentation/authentication/#users +.. _message docs: http://www.djangoproject.com/documentation/authentication/#messages .. _permissions docs: http://www.djangoproject.com/documentation/authentication/#permissions django.core.context_processors.debug @@ -357,10 +391,22 @@ django.core.context_processors.request ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every -``DjangoContext`` will contain a variable ``request``, which is the current +``RequestContext`` will contain a variable ``request``, which is the current `HttpRequest object`_. Note that this processor is not enabled by default; you'll have to activate it. +Writing your own context processors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A context processor has a very simple interface: It's just a Python function +that takes one argument, an ``HttpRequest`` object, and returns a dictionary +that gets added to the template context. Each context processor *must* return +a dictionary. + +Custom context processors can live anywhere in your code base. All Django cares +about is that your custom context processors are pointed-to by your +``TEMPLATE_CONTEXT_PROCESSORS`` setting. + Loading templates ----------------- @@ -758,17 +804,17 @@ will use the function's name as the tag name. Shortcut for simple tags ~~~~~~~~~~~~~~~~~~~~~~~~ -Many template tags take a single argument -- a string or a template variable -reference -- and return a string after doing some processing based solely on +Many template tags take a number of arguments -- strings or a template variables +-- and return a string after doing some processing based solely on the input argument and some external information. For example, the ``current_time`` tag we wrote above is of this variety: we give it a format string, it returns the time as a string. To ease the creation of the types of tags, Django provides a helper function, ``simple_tag``. This function, which is a method of -``django.template.Library``, takes a function that accepts one argument, wraps -it in a ``render`` function and the other necessary bits mentioned above and -registers it with the template system. +``django.template.Library``, takes a function that accepts any number of +arguments, wraps it in a ``render`` function and the other necessary bits +mentioned above and registers it with the template system. Our earlier ``current_time`` function could thus be written like this:: @@ -784,18 +830,23 @@ In Python 2.4, the decorator syntax also works:: ... A couple of things to note about the ``simple_tag`` helper function: - * Only the (single) argument is passed into our function. * Checking for the required number of arguments, etc, has already been done by the time our function is called, so we don't need to do that. * The quotes around the argument (if any) have already been stripped away, so we just receive a plain string. + * If the argument was a template variable, our function is passed the + current value of the variable, not the variable itself. + +When your template tag does not need access to the current context, writing a +function to work with the input values and using the ``simple_tag`` helper is +the easiest way to create a new tag. Inclusion tags ~~~~~~~~~~~~~~ Another common type of template tag is the type that displays some data by rendering *another* template. For example, Django's admin interface uses custom -template tags to display the buttons along the botton of the "add/change" form +template tags to display the buttons along the bottom of the "add/change" form pages. Those buttons always look the same, but the link targets change depending on the object being edited -- so they're a perfect case for using a small template that is filled with details from the current object. (In the admin's @@ -1041,7 +1092,7 @@ Configuring the template system in standalone mode .. note:: This section is only of interest to people trying to use the template - system as an output component in another application. If you are using the + system as an output component in another application. If you're using the template system as part of a Django application, nothing here applies to you. @@ -1058,7 +1109,7 @@ described in the `settings file`_ documentation. Simply import the appropriate pieces of the templating system and then, *before* you call any of the templating functions, call ``django.conf.settings.configure()`` with any settings you wish to specify. You might want to consider setting at least -``TEMPLATE_DIRS`` (if you are going to use template loaders), +``TEMPLATE_DIRS`` (if you're going to use template loaders), ``DEFAULT_CHARSET`` (although the default of ``utf-8`` is probably fine) and ``TEMPLATE_DEBUG``. All available settings are described in the `settings documentation`_, and any setting starting with *TEMPLATE_* diff --git a/docs/testing.txt b/docs/testing.txt new file mode 100644 index 0000000000..19eef9f071 --- /dev/null +++ b/docs/testing.txt @@ -0,0 +1,453 @@ +=========================== +Testing Django applications +=========================== + +**New in Django development version**. + +Automated testing is an extremely useful weapon in the bug-killing arsenal +of the modern developer. When initially writing code, a test suite can be +used to validate that code behaves as expected. When refactoring or +modifying code, tests serve as a guide to ensure that behavior hasn't +changed unexpectedly as a result of the refactor. + +Testing an web application is a complex task, as there are many +components of a web application that must be validated and tested. To +help you test your application, Django provides a test execution +framework, and range of utilities that can be used to stimulate and +inspect various facets of a web application. + + This testing framework is currently under development, and may change + slightly before the next official Django release. + + (That's *no* excuse not to write tests, though!) + +Writing tests +============= + +Tests in Django come in two forms: doctests and unit tests. + +Writing doctests +---------------- + +Doctests use Python's standard doctest_ module, which searches for tests in +your docstrings. Django's test runner looks for doctests in your ``models.py`` +file, and executes any that it finds. Django will also search for a file +called ``tests.py`` in the application directory (i.e., the directory that +holds ``models.py``). If a ``tests.py`` is found, it will also be searched +for doctests. + +.. admonition:: What's a **docstring**? + + A good explanation of docstrings (and some guidlines for using them + effectively) can be found in :PEP:`257`: + + A docstring is a string literal that occurs as the first statement in + a module, function, class, or method definition. Such a docstring + becomes the ``__doc__`` special attribute of that object. + + Since tests often make great documentation, doctest lets you put your + tests directly in your docstrings. + +You can put doctest strings on any object in your ``models.py``, but it's +common practice to put application-level doctests in the module docstring, and +model-level doctests in the docstring for each model. + +For example:: + + from django.db import model + + class Animal(models.Model): + """ + An animal that knows how to make noise + + # Create some animals + >>> lion = Animal.objects.create(name="lion", sound="roar") + >>> cat = Animal.objects.create(name="cat", sound="meow") + + # Make 'em speak + >>> lion.speak() + 'The lion says "roar"' + >>> cat.speak() + 'The cat says "meow"' + """ + + name = models.CharField(maxlength=20) + sound = models.CharField(maxlength=20) + + def speak(self): + return 'The %s says "%s"' % (self.name, self.sound) + +When you `run your tests`_, the test utility will find this docstring, notice +that portions of it look like an interactive Python session, and execute those +lines while checking that the results match. + +For more details about how doctest works, see the `standard library +documentation for doctest`_ + +.. _doctest: http://docs.python.org/lib/module-doctest.html +.. _standard library documentation for doctest: doctest_ + +Writing unittests +----------------- + +Like doctests, Django's unit tests use a standard library module: unittest_. +As with doctests, Django's test runner looks for any unit test cases defined +in ``models.py``, or in a ``tests.py`` file stored in the application +directory. + +An equivalent unittest test case for the above example would look like:: + + import unittest + from myapp.models import Animal + + class AnimalTestCase(unittest.TestCase): + + def setUp(self): + self.lion = Animal.objects.create(name="lion", sound="roar") + self.cat = Animal.objects.create(name="cat", sound="meow") + + def testSpeaking(self): + self.assertEquals(self.lion.speak(), 'The lion says "roar"') + self.assertEquals(self.cat.speak(), 'The cat says "meow"') + +When you `run your tests`_, the test utility will find all the test cases +(that is, subclasses of ``unittest.TestCase``) in ``models.py`` and +``tests.py``, automatically build a test suite out of those test cases, +and run that suite. + +For more details about ``unittest``, see the `standard library unittest +documentation`_. + +.. _unittest: http://docs.python.org/lib/module-unittest.html +.. _standard library unittest documentation: unittest_ +.. _run your tests: `Running tests`_ + +Which should I use? +------------------- + +Choosing a test framework is often contentious, so Django simply supports +both of the standard Python test frameworks. Choosing one is up to each +developer's personal tastes; each is supported equally. Since each test +system has different benefits, the best approach is probably to use both +together, picking the test system to match the type of tests you need to +write. + +For developers new to testing, however, this choice can seem +confusing, so here are a few key differences to help you decide weather +doctests or unit tests are right for you. + +If you've been using Python for a while, ``doctest`` will probably feel more +"pythonic". It's designed to make writing tests as easy as possible, so +there's no overhead of writing classes or methods; you simply put tests in +docstrings. This gives the added advantage of given your modules automatic +documentation -- well-written doctests can kill both the documentation and the +testing bird with a single stone. + +For developers just getting started with testing, using doctests will probably +get you started faster. + +The ``unittest`` framework will probably feel very familiar to developers +coming from Java. Since ``unittest`` is inspired by Java's JUnit, if +you've used testing frameworks in other languages that similarly were +inspired by JUnit, ``unittest`` should also feel pretty familiar. + +Since ``unittest`` is organized around classes and methods, if you need +to write a bunch of tests that all share similar code, you can easily use +subclass to abstract common tasks; this makes test code shorter and cleaner. +There's also support for explicit setup and/or cleanup routines, which give +you a high level of control over the environment your test cases run in. + +Again, remember that you can use both systems side-by-side (even in the same +app). In the end, most projects will eventually end up using both; each shines +in different circumstances. + +Testing Tools +============= + +To assist in testing various features of your application, Django provides +tools that can be used to establish tests and test conditions. + +* `Test Client`_ +* Fixtures_ + +Test Client +----------- + +The Test Client is a simple dummy browser. It allows you to simulate +GET and POST requests on a URL, and observe the response that is received. +This allows you to test that the correct view is executed for a given URL, +and that the view constructs the correct response. + +As the response is generated, the Test Client gathers details on the +Template and Context objects that were used to generate the response. These +Templates and Contexts are then provided as part of the response, and can be +used as test conditions. + +.. admonition:: Test Client vs Browser Automation? + + The Test Client is not intended as a replacement for Twill_, Selenium_, + or other browser automation frameworks - it is intended to allow + testing of the contexts and templates produced by a view, + rather than the HTML rendered to the end-user. + + A comprehensive test suite should use a combination of both: Test Client + tests to establish that the correct view is being called and that + the view is collecting the correct context data, and Browser Automation + tests to check that user interface behaves as expected. + +.. _Twill: http://twill.idyll.org/ +.. _Selenium: http://www.openqa.org/selenium/ + +The Test Client is stateful; if a cookie is returned as part of a response, +that cookie is provided as part of the next request issued to that Client +instance. Expiry policies for these cookies are not followed; if you want +a cookie to expire, either delete it manually from ``client.cookies``, or +create a new Client instance (which will effectively delete all cookies). + +Making requests +~~~~~~~~~~~~~~~ + +Creating an instance of ``Client`` (``django.test.client.Client``) requires +no arguments at time of construction. Once constructed, the following methods +can be invoked on the ``Client`` instance. + +``get(path, data={})`` + Make a GET request on the provided ``path``. The key-value pairs in the + data dictionary will be used to create a GET data payload. For example:: + + c = Client() + c.get('/customers/details/', {'name':'fred', 'age':7}) + + will result in the evaluation of a GET request equivalent to:: + + http://yoursite.com/customers/details/?name='fred'&age=7 + +``post(path, data={})`` + Make a POST request on the provided ``path``. The key-value pairs in the + data dictionary will be used to create the POST data payload. This payload + will be transmitted with the mimetype ``multipart/form-data``. + + However submitting files is a special case. To POST a file, you need only + provide the file field name as a key, and a file handle to the file you wish to + upload as a value. The Test Client will populate the two POST fields (i.e., + ``field`` and ``field_file``) required by FileField. For example:: + + c = Client() + f = open('wishlist.doc') + c.post('/customers/wishes/', {'name':'fred', 'attachment':f}) + 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 + need to manually close the file after it has been provided to the POST. + +``login(path, username, password)`` + In a production site, it is likely that some views will be protected with + the @login_required URL provided by ``django.contrib.auth``. Interacting + with a URL that has been login protected is a slightly complex operation, + so the Test Client provides a simple URL to automate the login process. A + call to ``login()`` stimulates the series of GET and POST calls required + to log a user into a @login_required protected URL. + + If login is possible, the final return value of ``login()`` is the response + that is generated by issuing a GET request on the protected URL. If login + is not possible, ``login()`` returns False. + + Note that since the test suite will be executed using the test database, + which contains no users by default. As a result, logins for your production + site will not work. You will need to create users as part of the test suite + to be able to test logins to your application. + +Testing Responses +~~~~~~~~~~~~~~~~~ + +The ``get()``, ``post()`` and ``login()`` methods all return a Response +object. This Response object has the following properties that can be used +for testing purposes: + + =============== ========================================================== + Property Description + =============== ========================================================== + ``status_code`` The HTTP status of the response. See RFC2616_ for a + full list of HTTP status codes. + + ``content`` The body of the response. The is the final page + content as rendered by the view, or any error message + (such as the URL for a 302 redirect). + + ``template`` The Template instance that was used to render the final + content. Testing ``template.name`` can be particularly + useful; if the template was loaded from a file, + ``template.name`` will be the file name that was loaded. + + If multiple templates were rendered, (e.g., if one + template includes another template),``template`` will + be a list of Template objects, in the order in which + they were rendered. + + ``context`` The Context that was used to render the template that + produced the response content. + + As with ``template``, if multiple templates were rendered + ``context`` will be a list of Context objects, stored in + the order in which they were rendered. + =============== ========================================================== + +.. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html + +The following is a simple unit test using the Test Client:: + + import unittest + from django.test.client import Client + + class SimpleTest(unittest.TestCase): + def setUp(self): + # Every test needs a client + self.client = Client() + def test_details(self): + # Issue a GET request + response = self.client.get('/customer/details/') + + # Check that the respose is 200 OK + self.failUnlessEqual(response.status_code, 200) + # Check that the rendered context contains 5 customers + self.failUnlessEqual(len(response.context['customers']), 5) + +Fixtures +-------- + +Feature still to come... + +Running tests +============= + +Run your tests using your project's ``manage.py`` utility:: + + $ ./manage.py test + +If you only want to run tests for a particular application, add the +application name to the command line. For example, if your +``INSTALLED_APPS`` contains ``myproject.polls`` and ``myproject.animals``, +but you only want to run the animals unit tests, run:: + + $ ./manage.py test animals + +When you run your tests, you'll see a bunch of text flow by as the test +database is created and models are initialized. This test database is +created from scratch every time you run your tests. + +By default, the test database gets its name by prepending ``test_`` to +the database name specified by the ``DATABASE_NAME`` setting; all other +database settings will the same as they would be for the project normally. +If you wish to use a name other than the default for the test database, +you can use the ``TEST_DATABASE_NAME`` setting to provide a name. + +Once the test database has been established, Django will run your tests. +If everything goes well, at the end you'll see:: + + ---------------------------------------------------------------------- + Ran 22 tests in 0.221s + + OK + +If there are test failures, however, you'll see full details about what tests +failed:: + + ====================================================================== + FAIL: Doctest: ellington.core.throttle.models + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "/dev/django/test/doctest.py", line 2153, in runTest + raise self.failureException(self.format_failure(new.getvalue())) + AssertionError: Failed doctest test for myapp.models + File "/dev/myapp/models.py", line 0, in models + + ---------------------------------------------------------------------- + File "/dev/myapp/models.py", line 14, in myapp.models + Failed example: + throttle.check("actor A", "action one", limit=2, hours=1) + Expected: + True + Got: + False + + ---------------------------------------------------------------------- + Ran 2 tests in 0.048s + + FAILED (failures=1) + +When the tests have all been executed, the test database is destroyed. + +Using a different testing framework +=================================== + +Doctest and Unittest are not the only Python testing frameworks. While +Django doesn't provide explicit support these alternative frameworks, +it does provide a mechanism to allow you to invoke tests constructed for +an alternative framework as if they were normal Django tests. + +When you run ``./manage.py test``, Django looks at the ``TEST_RUNNER`` +setting to determine what to do. By default, ``TEST_RUNNER`` points to ``django.test.simple.run_tests``. This method defines the default Django +testing behavior. This behavior involves: + +#. Performing global pre-test setup +#. Creating the test database +#. Running ``syncdb`` to install models and initial data into the test database +#. Looking for Unit Tests and Doctests in ``models.py`` and ``tests.py`` file for each installed application +#. Running the Unit Tests and Doctests that are found +#. Destroying the test database. +#. Performing global post-test teardown + +If you define your own test runner method and point ``TEST_RUNNER`` +at that method, Django will execute your test runner whenever you run +``./manage.py test``. In this way, it is possible to use any test +framework that can be executed from Python code. + +Defining a test runner +---------------------- +By convention, a test runner should be called ``run_tests``; however, you +can call it anything you want. The only requirement is that it accept two +arguments: + +``run_tests(module_list, verbosity=1)`` + The module list is the list of Python modules that contain the models to be + 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. + +Testing utilities +----------------- + +To assist in the creation of your own test runner, Django provides +a number of utility methods in the ``django.test.utils`` module. + +``setup_test_environment()`` + Performs any global pre-test setup, such as the installing the + instrumentation of the template rendering system. + +``teardown_test_environment()`` + Performs any global post-test teardown, such as removing the instrumentation + of the template rendering system. + +``create_test_db(verbosity=1, autoclobber=False)`` + Creates a new test database, and run ``syncdb`` against it. + + ``verbosity`` has the same behavior as in the test runner. + + ``Autoclobber`` describes the behavior that will occur if a database with + the same name as the test database is discovered. If ``autoclobber`` is False, + the user will be asked to approve destroying the existing database. ``sys.exit`` + is called if the user does not approve. If autoclobber is ``True``, the database + will be destroyed without consulting the user. + + ``create_test_db()`` has the side effect of modifying + ``settings.DATABASE_NAME`` to match the name of the test database. + +``destroy_test_db(old_database_name, verbosity=1)`` + Destroys the database with the name ``settings.DATABASE_NAME`` matching, + and restores the value of ``settings.DATABASE_NAME`` to the provided name. + + ``verbosity`` has the same behavior as in the test runner. diff --git a/docs/transactions.txt b/docs/transactions.txt index c1cd5aa984..2b0755a257 100644 --- a/docs/transactions.txt +++ b/docs/transactions.txt @@ -2,7 +2,8 @@ Managing database transactions ============================== -Django gives you a few ways to control how database transactions are managed. +Django gives you a few ways to control how database transactions are managed, +if you're using a database that supports transactions. Django's default transaction behavior ===================================== @@ -144,3 +145,19 @@ Thus, this is best used in situations where you want to run your own transaction-controlling middleware or do something really strange. In almost all situations, you'll be better off using the default behavior, or the transaction middleware, and only modify selected functions as needed. + +Transactions in MySQL +===================== + +If you're using MySQL, your tables may or may not support transactions; it +depends on your MySQL version and the table types you're using. (By +"table types," we mean something like "InnoDB" or "MyISAM".) MySQL transaction +peculiarities are outside the scope of this article, but the MySQL site has +`information on MySQL transactions`_. + +If your MySQL setup does *not* support transactions, then Django will function +in auto-commit mode: Statements will be executed and committed as soon as +they're called. If your MySQL setup *does* support transactions, Django will +handle transactions as explained in this document. + +.. _information on MySQL transactions: http://dev.mysql.com/books/mysqlpress/mysql-tutorial/ch10.html diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index c353e1ab4b..1113b603da 100644 --- a/docs/tutorial01.txt +++ b/docs/tutorial01.txt @@ -81,7 +81,7 @@ the following output on the command line:: Validating models... 0 errors found. - Django version 0.95 (post-magic-removal), using settings 'mysite.settings' + Django version 0.95, using settings 'mysite.settings' Development server is running at http://127.0.0.1:8000/ Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows). @@ -346,6 +346,8 @@ Note the following: the SQL to the database. If you're interested, also run the following commands: + * ``python manage.py validate polls`` -- Checks for any errors in the + construction of your models. * ``python manage.py sqlinitialdata polls`` -- Outputs any initial data required for Django's admin framework and your models. diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt index 84eae3eb83..f6d4045fa3 100644 --- a/docs/tutorial02.txt +++ b/docs/tutorial02.txt @@ -54,7 +54,8 @@ http://127.0.0.1:8000/admin/. You should see the admin's login screen: Enter the admin site ==================== -Now, try logging in. You should see the Django admin index page: +Now, try logging in. (You created a superuser account in the first part of this +tutorial, remember?) You should see the Django admin index page: .. image:: http://media.djangoproject.com/img/doc/tutorial/admin02t.png :alt: Django admin index page @@ -376,16 +377,16 @@ By default, ``TEMPLATE_DIRS`` is empty. So, let's add a line to it, to tell Django where our templates live:: TEMPLATE_DIRS = ( - "/home/mytemplates", # Change this to your own directory. + "/home/my_username/mytemplates", # Change this to your own directory. ) Now copy the template ``admin/base_site.html`` from within the default Django admin template directory (``django/contrib/admin/templates``) into an ``admin`` subdirectory of whichever directory you're using in ``TEMPLATE_DIRS``. For -example, if your ``TEMPLATE_DIRS`` includes ``"/home/mytemplates"``, as above, -then copy ``django/contrib/admin/templates/admin/base_site.html`` to -``/home/mytemplates/admin/base_site.html``. Don't forget that ``admin`` -subdirectory. +example, if your ``TEMPLATE_DIRS`` includes ``"/home/my_username/mytemplates"``, +as above, then copy ``django/contrib/admin/templates/admin/base_site.html`` to +``/home/my_username/mytemplates/admin/base_site.html``. Don't forget that +``admin`` subdirectory. Then, just edit the file and replace the generic Django text with your own site's name and URL as you see fit. diff --git a/docs/tutorial03.txt b/docs/tutorial03.txt index 3a830eb76f..c4c1b4c546 100644 --- a/docs/tutorial03.txt +++ b/docs/tutorial03.txt @@ -91,7 +91,7 @@ Finally, it calls that ``detail()`` function like so:: The ``poll_id='23'`` part comes from ``(?P<poll_id>\d+)``. Using parenthesis around a pattern "captures" the text matched by that pattern and sends it as an argument to the view function; the ``?P<poll_id>`` defines the name that will be used to -identify the matched pattern; and ``\d+`` is a regular experession to match a sequence of +identify the matched pattern; and ``\d+`` is a regular expression to match a sequence of digits (i.e., a number). Because the URL patterns are regular expressions, there really is no limit on @@ -189,7 +189,7 @@ publication date:: from django.http import HttpResponse def index(request): - latest_poll_list = Poll.objects.all().order_by('-pub_date') + latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5] output = ', '.join([p.question for p in latest_poll_list]) return HttpResponse(output) @@ -202,7 +202,7 @@ So let's use Django's template system to separate the design from Python:: from django.http import HttpResponse def index(request): - latest_poll_list = Poll.objects.all().order_by('-pub_date') + latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5] t = loader.get_template('polls/index.html') c = Context({ 'latest_poll_list': latest_poll_list, @@ -257,7 +257,7 @@ provides a shortcut. Here's the full ``index()`` view, rewritten:: from mysite.polls.models import Poll def index(request): - latest_poll_list = Poll.objects.all().order_by('-pub_date') + latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5] return render_to_response('polls/index.html', {'latest_poll_list': latest_poll_list}) Note that we no longer need to import ``loader``, ``Context`` or @@ -288,7 +288,7 @@ exception if a poll with the requested ID doesn't exist. A shortcut: get_object_or_404() ------------------------------- -It's a very common idiom to use ``get_object()`` and raise ``Http404`` if the +It's a very common idiom to use ``get()`` and raise ``Http404`` if the object doesn't exist. Django provides a shortcut. Here's the ``detail()`` view, rewritten:: @@ -313,8 +313,8 @@ exist. foremost design goals of Django is to maintain loose coupling. There's also a ``get_list_or_404()`` function, which works just as -``get_object_or_404()`` -- except using ``get_list()`` instead of -``get_object()``. It raises ``Http404`` if the list is empty. +``get_object_or_404()`` -- except using ``filter()`` instead of +``get()``. It raises ``Http404`` if the list is empty. Write a 404 (page not found) view ================================= diff --git a/docs/tutorial04.txt b/docs/tutorial04.txt index 8ef4a03c6d..c5e2ea3cea 100644 --- a/docs/tutorial04.txt +++ b/docs/tutorial04.txt @@ -198,7 +198,7 @@ By default, the ``object_detail`` generic view uses a template called ``vote()``. Similarly, the ``object_list`` generic view uses a template called -``<app name>/<module name>_list.html``. Thus, rename ``poll/index.html`` to +``<app name>/<module name>_list.html``. Thus, rename ``polls/index.html`` to ``polls/poll_list.html``. Because we have more than one entry in the URLconf that uses ``object_detail`` @@ -206,8 +206,8 @@ for the polls app, we manually specify a template name for the results view: ``template_name='polls/results.html'``. Otherwise, both views would use the same template. Note that we use ``dict()`` to return an altered dictionary in place. -In previous versions of the tutorial, the templates have been provided with a context -that contains the ``poll` and ``latest_poll_list`` context variables. However, +In previous parts of the tutorial, the templates have been provided with a context +that contains the ``poll`` and ``latest_poll_list`` context variables. However, the generic views provide the variables ``object`` and ``object_list`` as context. Therefore, you need to change your templates to match the new context variables. Go through your templates, and modify any reference to ``latest_poll_list`` to diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt index 498a906d5e..00a7af027a 100644 --- a/docs/url_dispatch.txt +++ b/docs/url_dispatch.txt @@ -263,12 +263,12 @@ Here's the example URLconf from the `Django overview`_:: from django.conf.urls.defaults import * urlpatterns = patterns('', - (r'^articles/(\d{4})/$', 'myproject.news.views.year_archive'), - (r'^articles/(\d{4})/(\d{2})/$', 'myproject.news.views.month_archive'), - (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'myproject.news.views.article_detail'), + (r'^articles/(\d{4})/$', 'mysite.news.views.year_archive'), + (r'^articles/(\d{4})/(\d{2})/$', 'mysite.news.views.month_archive'), + (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'mysite.news.views.article_detail'), ) -In this example, each view has a common prefix -- ``'myproject.news.views'``. +In this example, each view has a common prefix -- ``'mysite.news.views'``. Instead of typing that out for each entry in ``urlpatterns``, you can use the first argument to the ``patterns()`` function to specify a prefix to apply to each view function. @@ -277,7 +277,7 @@ With this in mind, the above example can be written more concisely as:: from django.conf.urls.defaults import * - urlpatterns = patterns('myproject.news.views', + urlpatterns = patterns('mysite.news.views', (r'^articles/(\d{4})/$', 'year_archive'), (r'^articles/(\d{4})/(\d{2})/$', 'month_archive'), (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'article_detail'), @@ -389,3 +389,90 @@ to pass metadata and options to views. .. _generic views: http://www.djangoproject.com/documentation/generic_views/ .. _syndication framework: http://www.djangoproject.com/documentation/syndication/ + +Passing extra options to ``include()`` +-------------------------------------- + +**New in the Django development version.** + +Similarly, you can pass extra options to ``include()``. When you pass extra +options to ``include()``, *each* line in the included URLconf will be passed +the extra options. + +For example, these two URLconf sets are functionally identical: + +Set one:: + + # main.py + urlpatterns = patterns('', + (r'^blog/', include('inner'), {'blogid': 3}), + ) + + # inner.py + urlpatterns = patterns('', + (r'^archive/$', 'mysite.views.archive'), + (r'^about/$', 'mysite.views.about'), + ) + +Set two:: + + # main.py + urlpatterns = patterns('', + (r'^blog/', include('inner')), + ) + + # inner.py + urlpatterns = patterns('', + (r'^archive/$', 'mysite.views.archive', {'blogid': 3}), + (r'^about/$', 'mysite.views.about', {'blogid': 3}), + ) + +Note that extra options will *always* be passed to *every* line in the included +URLconf, regardless of whether the line's view actually accepts those options +as valid. For this reason, this technique is only useful if you're certain that +every view in the the included URLconf accepts the extra options you're passing. + +Passing callable objects instead of strings +=========================================== + +**New in the Django development version.** + +Some developers find it more natural to pass the actual Python function object +rather than a string containing the path to its module. This alternative is +supported -- you can pass any callable object as the view. + +For example, given this URLconf in "string" notation:: + + urlpatterns = patterns('', + (r'^archive/$', 'mysite.views.archive'), + (r'^about/$', 'mysite.views.about'), + (r'^contact/$', 'mysite.views.contact'), + ) + +You can accomplish the same thing by passing objects rather than strings. Just +be sure to import the objects:: + + from mysite.views import archive, about, contact + + urlpatterns = patterns('', + (r'^archive/$', archive), + (r'^about/$', about), + (r'^contact/$', contact), + ) + +The following example is functionally identical. It's just a bit more compact +because it imports the module that contains the views, rather than importing +each view individually:: + + from mysite import views + + urlpatterns = patterns('', + (r'^archive/$', views.archive), + (r'^about/$', views.about), + (r'^contact/$', views.contact), + ) + +The style you use is up to you. + +Note that if you use this technique -- passing objects rather than strings -- +the view prefix (as explained in "The view prefix" above) will have no effect. |