diff options
Diffstat (limited to 'parts/django/docs/ref')
88 files changed, 0 insertions, 32532 deletions
diff --git a/parts/django/docs/ref/authbackends.txt b/parts/django/docs/ref/authbackends.txt deleted file mode 100644 index a50b414..0000000 --- a/parts/django/docs/ref/authbackends.txt +++ /dev/null @@ -1,35 +0,0 @@ -======================= -Authentication backends -======================= - -.. module:: django.contrib.auth.backends - :synopsis: Django's built-in authentication backend classes. - -This document details the authentication backends that come with Django. For -information on how to use them and how to write your own authentication -backends, see the :ref:`Other authentication sources section -<authentication-backends>` of the :doc:`User authentication guide -</topics/auth>`. - - -Available authentication backends -================================= - -The following backends are available in :mod:`django.contrib.auth.backends`: - -.. class:: ModelBackend - - This is the default authentication backend used by Django. It - authenticates using usernames and passwords stored in the - :class:`~django.contrib.auth.models.User` model. - - -.. class:: RemoteUserBackend - - .. versionadded:: 1.1 - - Use this backend to take advantage of external-to-Django-handled - authentication. It authenticates using usernames passed in - :attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See - the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>` - documentation. diff --git a/parts/django/docs/ref/contrib/admin/_images/article_actions.png b/parts/django/docs/ref/contrib/admin/_images/article_actions.png Binary files differdeleted file mode 100644 index 78a78ae..0000000 --- a/parts/django/docs/ref/contrib/admin/_images/article_actions.png +++ /dev/null diff --git a/parts/django/docs/ref/contrib/admin/_images/article_actions_message.png b/parts/django/docs/ref/contrib/admin/_images/article_actions_message.png Binary files differdeleted file mode 100644 index 6ea9439..0000000 --- a/parts/django/docs/ref/contrib/admin/_images/article_actions_message.png +++ /dev/null diff --git a/parts/django/docs/ref/contrib/admin/_images/flatfiles_admin.png b/parts/django/docs/ref/contrib/admin/_images/flatfiles_admin.png Binary files differdeleted file mode 100644 index 391a629..0000000 --- a/parts/django/docs/ref/contrib/admin/_images/flatfiles_admin.png +++ /dev/null diff --git a/parts/django/docs/ref/contrib/admin/_images/user_actions.png b/parts/django/docs/ref/contrib/admin/_images/user_actions.png Binary files differdeleted file mode 100644 index fdbe2ad..0000000 --- a/parts/django/docs/ref/contrib/admin/_images/user_actions.png +++ /dev/null diff --git a/parts/django/docs/ref/contrib/admin/_images/users_changelist.png b/parts/django/docs/ref/contrib/admin/_images/users_changelist.png Binary files differdeleted file mode 100644 index d5f9c01..0000000 --- a/parts/django/docs/ref/contrib/admin/_images/users_changelist.png +++ /dev/null diff --git a/parts/django/docs/ref/contrib/admin/actions.txt b/parts/django/docs/ref/contrib/admin/actions.txt deleted file mode 100644 index 0fab59e..0000000 --- a/parts/django/docs/ref/contrib/admin/actions.txt +++ /dev/null @@ -1,351 +0,0 @@ -============= -Admin actions -============= - -.. versionadded:: 1.1 - -.. currentmodule:: django.contrib.admin - -The basic workflow of Django's admin is, in a nutshell, "select an object, -then change it." This works well for a majority of use cases. However, if you -need to make the same change to many objects at once, this workflow can be -quite tedious. - -In these cases, Django's admin lets you write and register "actions" -- simple -functions that get called with a list of objects selected on the change list -page. - -If you look at any change list in the admin, you'll see this feature in -action; Django ships with a "delete selected objects" action available to all -models. For example, here's the user module from Django's built-in -:mod:`django.contrib.auth` app: - -.. image:: _images/user_actions.png - -.. warning:: - - The "delete selected objects" action uses :meth:`QuerySet.delete() - <django.db.models.QuerySet.delete>` for efficiency reasons, which has an - important caveat: your model's ``delete()`` method will not be called. - - If you wish to override this behavior, simply write a custom action which - accomplishes deletion in your preferred manner -- for example, by calling - ``Model.delete()`` for each of the selected items. - - For more background on bulk deletion, see the documentation on :ref:`object - deletion <topics-db-queries-delete>`. - -Read on to find out how to add your own actions to this list. - -Writing actions -=============== - -The easiest way to explain actions is by example, so let's dive in. - -A common use case for admin actions is the bulk updating of a model. Imagine a -simple news application with an ``Article`` model:: - - from django.db import models - - STATUS_CHOICES = ( - ('d', 'Draft'), - ('p', 'Published'), - ('w', 'Withdrawn'), - ) - - class Article(models.Model): - title = models.CharField(max_length=100) - body = models.TextField() - status = models.CharField(max_length=1, choices=STATUS_CHOICES) - - def __unicode__(self): - return self.title - -A common task we might perform with a model like this is to update an -article's status from "draft" to "published". We could easily do this in the -admin one article at a time, but if we wanted to bulk-publish a group of -articles, it'd be tedious. So, let's write an action that lets us change an -article's status to "published." - -Writing action functions ------------------------- - -First, we'll need to write a function that gets called when the action is -trigged from the admin. Action functions are just regular functions that take -three arguments: - - * The current :class:`ModelAdmin` - * An :class:`~django.http.HttpRequest` representing the current request, - * A :class:`~django.db.models.QuerySet` containing the set of objects - selected by the user. - -Our publish-these-articles function won't need the :class:`ModelAdmin` or the -request object, but we will use the queryset:: - - def make_published(modeladmin, request, queryset): - queryset.update(status='p') - -.. note:: - - For the best performance, we're using the queryset's :ref:`update method - <topics-db-queries-update>`. Other types of actions might need to deal - with each object individually; in these cases we'd just iterate over the - queryset:: - - for obj in queryset: - do_something_with(obj) - -That's actually all there is to writing an action! However, we'll take one -more optional-but-useful step and give the action a "nice" title in the admin. -By default, this action would appear in the action list as "Make published" -- -the function name, with underscores replaced by spaces. That's fine, but we -can provide a better, more human-friendly name by giving the -``make_published`` function a ``short_description`` attribute:: - - def make_published(modeladmin, request, queryset): - queryset.update(status='p') - make_published.short_description = "Mark selected stories as published" - -.. note:: - - This might look familiar; the admin's ``list_display`` option uses the - same technique to provide human-readable descriptions for callback - functions registered there, too. - -Adding actions to the :class:`ModelAdmin` ------------------------------------------ - -Next, we'll need to inform our :class:`ModelAdmin` of the action. This works -just like any other configuration option. So, the complete ``admin.py`` with -the action and its registration would look like:: - - from django.contrib import admin - from myapp.models import Article - - def make_published(modeladmin, request, queryset): - queryset.update(status='p') - make_published.short_description = "Mark selected stories as published" - - class ArticleAdmin(admin.ModelAdmin): - list_display = ['title', 'status'] - ordering = ['title'] - actions = [make_published] - - admin.site.register(Article, ArticleAdmin) - -That code will give us an admin change list that looks something like this: - -.. image:: _images/article_actions.png - -That's really all there is to it! If you're itching to write your own actions, -you now know enough to get started. The rest of this document just covers more -advanced techniques. - -Advanced action techniques -========================== - -There's a couple of extra options and possibilities you can exploit for more -advanced options. - -Actions as :class:`ModelAdmin` methods --------------------------------------- - -The example above shows the ``make_published`` action defined as a simple -function. That's perfectly fine, but it's not perfect from a code design point -of view: since the action is tightly coupled to the ``Article`` object, it -makes sense to hook the action to the ``ArticleAdmin`` object itself. - -That's easy enough to do:: - - class ArticleAdmin(admin.ModelAdmin): - ... - - actions = ['make_published'] - - def make_published(self, request, queryset): - queryset.update(status='p') - make_published.short_description = "Mark selected stories as published" - -Notice first that we've moved ``make_published`` into a method and renamed the -`modeladmin` parameter to `self`, and second that we've now put the string -``'make_published'`` in ``actions`` instead of a direct function reference. This -tells the :class:`ModelAdmin` to look up the action as a method. - -Defining actions as methods gives the action more straightforward, idiomatic -access to the :class:`ModelAdmin` itself, allowing the action to call any of the -methods provided by the admin. - -.. _custom-admin-action: - -For example, we can use ``self`` to flash a message to the user informing her -that the action was successful:: - - class ArticleAdmin(admin.ModelAdmin): - ... - - def make_published(self, request, queryset): - rows_updated = queryset.update(status='p') - if rows_updated == 1: - message_bit = "1 story was" - else: - message_bit = "%s stories were" % rows_updated - self.message_user(request, "%s successfully marked as published." % message_bit) - -This make the action match what the admin itself does after successfully -performing an action: - -.. image:: _images/article_actions_message.png - -Actions that provide intermediate pages ---------------------------------------- - -By default, after an action is performed the user is simply redirected back -to the original change list page. However, some actions, especially more -complex ones, will need to return intermediate pages. For example, the -built-in delete action asks for confirmation before deleting the selected -objects. - -To provide an intermediary page, simply return an -:class:`~django.http.HttpResponse` (or subclass) from your action. For -example, you might write a simple export function that uses Django's -:doc:`serialization functions </topics/serialization>` to dump some selected -objects as JSON:: - - from django.http import HttpResponse - from django.core import serializers - - def export_as_json(modeladmin, request, queryset): - response = HttpResponse(mimetype="text/javascript") - serializers.serialize("json", queryset, stream=response) - return response - -Generally, something like the above isn't considered a great idea. Most of the -time, the best practice will be to return an -:class:`~django.http.HttpResponseRedirect` and redirect the user to a view -you've written, passing the list of selected objects in the GET query string. -This allows you to provide complex interaction logic on the intermediary -pages. For example, if you wanted to provide a more complete export function, -you'd want to let the user choose a format, and possibly a list of fields to -include in the export. The best thing to do would be to write a small action -that simply redirects to your custom export view:: - - from django.contrib import admin - from django.contrib.contenttypes.models import ContentType - from django.http import HttpResponseRedirect - - def export_selected_objects(modeladmin, request, queryset): - selected = request.POST.getlist(admin.ACTION_CHECKBOX_NAME) - ct = ContentType.objects.get_for_model(queryset.model) - return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected))) - -As you can see, the action is the simple part; all the complex logic would -belong in your export view. This would need to deal with objects of any type, -hence the business with the ``ContentType``. - -Writing this view is left as an exercise to the reader. - -.. _adminsite-actions: - -Making actions available site-wide ----------------------------------- - -.. method:: AdminSite.add_action(action[, name]) - - Some actions are best if they're made available to *any* object in the admin - site -- the export action defined above would be a good candidate. You can - make an action globally available using :meth:`AdminSite.add_action()`. For - example:: - - from django.contrib import admin - - admin.site.add_action(export_selected_objects) - - This makes the `export_selected_objects` action globally available as an - action named `"export_selected_objects"`. You can explicitly give the action - a name -- good if you later want to programatically :ref:`remove the action - <disabling-admin-actions>` -- by passing a second argument to - :meth:`AdminSite.add_action()`:: - - admin.site.add_action(export_selected_objects, 'export_selected') - -.. _disabling-admin-actions: - -Disabling actions ------------------ - -Sometimes you need to disable certain actions -- especially those -:ref:`registered site-wide <adminsite-actions>` -- for particular objects. -There's a few ways you can disable actions: - -Disabling a site-wide action -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. method:: AdminSite.disable_action(name) - - If you need to disable a :ref:`site-wide action <adminsite-actions>` you can - call :meth:`AdminSite.disable_action()`. - - For example, you can use this method to remove the built-in "delete selected - objects" action:: - - admin.site.disable_action('delete_selected') - - Once you've done the above, that action will no longer be available - site-wide. - - If, however, you need to re-enable a globally-disabled action for one - particular model, simply list it explicitly in your ``ModelAdmin.actions`` - list:: - - # Globally disable delete selected - admin.site.disable_action('delete_selected') - - # This ModelAdmin will not have delete_selected available - class SomeModelAdmin(admin.ModelAdmin): - actions = ['some_other_action'] - ... - - # This one will - class AnotherModelAdmin(admin.ModelAdmin): - actions = ['delete_selected', 'a_third_action'] - ... - - -Disabling all actions for a particular :class:`ModelAdmin` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want *no* bulk actions available for a given :class:`ModelAdmin`, simply -set :attr:`ModelAdmin.actions` to ``None``:: - - class MyModelAdmin(admin.ModelAdmin): - actions = None - -This tells the :class:`ModelAdmin` to not display or allow any actions, -including any :ref:`site-wide actions <adminsite-actions>`. - -Conditionally enabling or disabling actions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. method:: ModelAdmin.get_actions(request) - - Finally, you can conditionally enable or disable actions on a per-request - (and hence per-user basis) by overriding :meth:`ModelAdmin.get_actions`. - - This returns a dictionary of actions allowed. The keys are action names, and - the values are ``(function, name, short_description)`` tuples. - - Most of the time you'll use this method to conditionally remove actions from - the list gathered by the superclass. For example, if I only wanted users - whose names begin with 'J' to be able to delete objects in bulk, I could do - the following:: - - class MyModelAdmin(admin.ModelAdmin): - ... - - def get_actions(self, request): - actions = super(MyModelAdmin, self).get_actions(request) - if request.user.username[0].upper() != 'J': - del actions['delete_selected'] - return actions - - diff --git a/parts/django/docs/ref/contrib/admin/admindocs.txt b/parts/django/docs/ref/contrib/admin/admindocs.txt deleted file mode 100644 index 6743921..0000000 --- a/parts/django/docs/ref/contrib/admin/admindocs.txt +++ /dev/null @@ -1,161 +0,0 @@ -========================================
-The Django admin documentation generator
-========================================
-
-.. module:: django.contrib.admindocs
- :synopsis: Django's admin documentation generator.
-
-.. currentmodule:: django.contrib.admindocs
-
-Django's :mod:`~django.contrib.admindocs` app pulls documentation from the
-docstrings of models, views, template tags, and template filters for any app in
-:setting:`INSTALLED_APPS` and makes that documentation available from the
-:mod:`Django admin <django.contrib.admin>`.
-
-In addition to providing offline documentation for all template tags and
-template filters that ship with Django, you may utilize admindocs to quickly
-document your own code.
-
-Overview
-========
-
-To activate the :mod:`~django.contrib.admindocs`, you will need to do
-the following:
-
- * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`.
- * Add ``(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to
- your :data:`urlpatterns`. Make sure it's included *before* the
- ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get
- handled by the latter entry.
- * Install the docutils Python module (http://docutils.sf.net/).
- * **Optional:** Linking to templates requires the :setting:`ADMIN_FOR`
- setting to be configured.
- * **Optional:** Using the admindocs bookmarklets requires the
- :mod:`XViewMiddleware<django.middleware.doc>` to be installed.
-
-Once those steps are complete, you can start browsing the documentation by
-going to your admin interface and clicking the "Documentation" link in the
-upper right of the page.
-
-Documentation helpers
-=====================
-
-The following special markup can be used in your docstrings to easily create
-hyperlinks to other components:
-
-================= =======================
-Django Component reStructuredText roles
-================= =======================
-Models ``:model:`appname.ModelName```
-Views ``:view:`appname.view_name```
-Template tags ``:tag:`tagname```
-Template filters ``:filter:`filtername```
-Templates ``:template:`path/to/template.html```
-================= =======================
-
-Model reference
-===============
-
-The **models** section of the ``admindocs`` page describes each model in the
-system along with all the fields and methods available on it. Relationships to
-other models appear as hyperlinks. Descriptions are pulled from ``help_text``
-attributes on fields or from docstrings on model methods.
-
-A model with useful documentation might look like this::
-
- class BlogEntry(models.Model):
- """
- Stores a single blog entry, related to :model:`blog.Blog` and
- :model:`auth.User`.
-
- """
- slug = models.SlugField(help_text="A short label, generally used in URLs.")
- author = models.ForeignKey(User)
- blog = models.ForeignKey(Blog)
- ...
-
- def publish(self):
- """Makes the blog entry live on the site."""
- ...
-
-View reference
-==============
-
-Each URL in your site has a separate entry in the ``admindocs`` page, and
-clicking on a given URL will show you the corresponding view. Helpful things
-you can document in your view function docstrings include:
-
- * A short description of what the view does.
- * The **context**, or a list of variables available in the view's template.
- * The name of the template or templates that are used for that view.
-
-For example::
-
- from myapp.models import MyModel
-
- def my_view(request, slug):
- """
- Display an individual :model:`myapp.MyModel`.
-
- **Context**
-
- ``RequestContext``
-
- ``mymodel``
- An instance of :model:`myapp.MyModel`.
-
- **Template:**
-
- :template:`myapp/my_template.html`
-
- """
- return render_to_response('myapp/my_template.html', {
- 'mymodel': MyModel.objects.get(slug=slug)
- }, context_instance=RequestContext(request))
-
-
-Template tags and filters reference
-===================================
-
-The **tags** and **filters** ``admindocs`` sections describe all the tags and
-filters that come with Django (in fact, the :ref:`built-in tag reference
-<ref-templates-builtins-tags>` and :ref:`built-in filter reference
-<ref-templates-builtins-filters>` documentation come directly from those
-pages). Any tags or filters that you create or are added by a third-party app
-will show up in these sections as well.
-
-
-Template reference
-==================
-
-While ``admindocs`` does not include a place to document templates by
-themselves, if you use the ``:template:`path/to/template.html``` syntax in a
-docstring the resulting page will verify the path of that template with
-Django's :ref:`template loaders <template-loaders>`. This can be a handy way to
-check if the specified template exists and to show where on the filesystem that
-template is stored.
-
-
-Included Bookmarklets
-=====================
-
-Several useful bookmarklets are available from the ``admindocs`` page:
-
- Documentation for this page
- Jumps you from any page to the documentation for the view that generates
- that page.
-
- Show object ID
- Shows the content-type and unique ID for pages that represent a single
- object.
-
- Edit this object
- Jumps to the admin page for pages that represent a single object.
-
-Using these bookmarklets requires that you are either logged into the
-:mod:`Django admin <django.contrib.admin>` as a
-:class:`~django.contrib.auth.models.User` with
-:attr:`~django.contrib.auth.models.User.is_staff` set to `True`, or
-that the :mod:`django.middleware.doc` middleware and
-:mod:`XViewMiddleware <django.middleware.doc>` are installed and you
-are accessing the site from an IP address listed in :setting:`INTERNAL_IPS`.
diff --git a/parts/django/docs/ref/contrib/admin/index.txt b/parts/django/docs/ref/contrib/admin/index.txt deleted file mode 100644 index b99cfdc..0000000 --- a/parts/django/docs/ref/contrib/admin/index.txt +++ /dev/null @@ -1,1613 +0,0 @@ -===================== -The Django admin site -===================== - -.. module:: django.contrib.admin - :synopsis: Django's admin site. - -One of the most powerful parts of Django is the automatic admin interface. It -reads metadata in your model to provide a powerful and production-ready -interface that content producers can immediately use to start adding content to -the site. In this document, we discuss how to activate, use and customize -Django's admin interface. - -.. admonition:: Note - - The admin site has been refactored significantly since Django 0.96. This - document describes the newest version of the admin site, which allows for - much richer customization. If you follow the development of Django itself, - you may have heard this described as "newforms-admin." - -Overview -======== - -There are six steps in activating the Django admin site: - - 1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS` - setting. - - 2. Admin has two dependencies - ``django.contrib.auth`` and - ``django.contrib.contenttypes``. If these applications are not - in your :setting:`INSTALLED_APPS` list, add them. - - 3. Determine which of your application's models should be editable in the - admin interface. - - 4. For each of those models, optionally create a ``ModelAdmin`` class that - encapsulates the customized admin functionality and options for that - particular model. - - 5. Instantiate an ``AdminSite`` and tell it about each of your models and - ``ModelAdmin`` classes. - - 6. Hook the ``AdminSite`` instance into your URLconf. - -Other topics ------------- - -.. toctree:: - :maxdepth: 1 - - actions - admindocs - -.. seealso:: - - For information about serving the media files (images, JavaScript, and CSS) - associated with the admin in production, see :ref:`serving-media-files`. - -``ModelAdmin`` objects -====================== - -.. class:: ModelAdmin - -The ``ModelAdmin`` class is the representation of a model in the admin -interface. These are stored in a file named ``admin.py`` in your application. -Let's take a look at a very simple example of the ``ModelAdmin``:: - - from django.contrib import admin - from myproject.myapp.models import Author - - class AuthorAdmin(admin.ModelAdmin): - pass - admin.site.register(Author, AuthorAdmin) - -.. admonition:: Do you need a ``ModelAdmin`` object at all? - - In the preceding example, the ``ModelAdmin`` class doesn't define any - custom values (yet). As a result, the default admin interface will be - provided. If you are happy with the default admin interface, you don't - need to define a ``ModelAdmin`` object at all -- you can register the - model class without providing a ``ModelAdmin`` description. The - preceding example could be simplified to:: - - from django.contrib import admin - from myproject.myapp.models import Author - - admin.site.register(Author) - -``ModelAdmin`` Options ----------------------- - -The ``ModelAdmin`` is very flexible. It has several options for dealing with -customizing the interface. All options are defined on the ``ModelAdmin`` -subclass:: - - class AuthorAdmin(admin.ModelAdmin): - date_hierarchy = 'pub_date' - -.. attribute:: ModelAdmin.date_hierarchy - -Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in -your model, and the change list page will include a date-based drilldown -navigation by that field. - -Example:: - - date_hierarchy = 'pub_date' - -.. attribute:: ModelAdmin.form - -By default a ``ModelForm`` is dynamically created for your model. It is used -to create the form presented on both the add/change pages. You can easily -provide your own ``ModelForm`` to override any default form behavior on the -add/change pages. - -For an example see the section `Adding custom validation to the admin`_. - -.. attribute:: ModelAdmin.fieldsets - -Set ``fieldsets`` to control the layout of admin "add" and "change" pages. - -``fieldsets`` is a list of two-tuples, in which each two-tuple represents a -``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the -form.) - -The two-tuples are in the format ``(name, field_options)``, where ``name`` is a -string representing the title of the fieldset and ``field_options`` is a -dictionary of information about the fieldset, including a list of fields to be -displayed in it. - -A full example, taken from the ``django.contrib.flatpages.FlatPage`` model:: - - class FlatPageAdmin(admin.ModelAdmin): - fieldsets = ( - (None, { - 'fields': ('url', 'title', 'content', 'sites') - }), - ('Advanced options', { - 'classes': ('collapse',), - 'fields': ('enable_comments', 'registration_required', 'template_name') - }), - ) - -This results in an admin page that looks like: - - .. image:: _images/flatfiles_admin.png - -If ``fieldsets`` isn't given, Django will default to displaying each field -that isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, -in the same order as the fields are defined in the model. - -The ``field_options`` dictionary can have the following keys: - - * ``fields`` - A tuple of field names to display in this fieldset. This key is - required. - - Example:: - - { - 'fields': ('first_name', 'last_name', 'address', 'city', 'state'), - } - - To display multiple fields on the same line, wrap those fields in - their own tuple. In this example, the ``first_name`` and ``last_name`` - fields will display on the same line:: - - { - 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'), - } - - .. versionadded:: 1.2 - - ``fields`` can contain values defined in - :attr:`ModelAdmin.readonly_fields` to be displayed as read-only. - - * ``classes`` - A list containing extra CSS classes to apply to the fieldset. - - Example:: - - { - 'classes': ['wide', 'extrapretty'], - } - - Two useful classes defined by the default admin site stylesheet are - ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will - be initially collapsed in the admin and replaced with a small - "click to expand" link. Fieldsets with the ``wide`` style will be - given extra horizontal space. - - * ``description`` - A string of optional extra text to be displayed at the top of each - fieldset, under the heading of the fieldset. - - Note that this value is *not* HTML-escaped when it's displayed in - the admin interface. This lets you include HTML if you so desire. - Alternatively you can use plain text and - ``django.utils.html.escape()`` to escape any HTML special - characters. - -.. attribute:: ModelAdmin.fields - -Use this option as an alternative to ``fieldsets`` if the layout does not -matter and if you want to only show a subset of the available fields in the -form. For example, you could define a simpler version of the admin form for -the ``django.contrib.flatpages.FlatPage`` model as follows:: - - class FlatPageAdmin(admin.ModelAdmin): - fields = ('url', 'title', 'content') - -In the above example, only the fields 'url', 'title' and 'content' will be -displayed, sequentially, in the form. - -.. versionadded:: 1.2 - -``fields`` can contain values defined in :attr:`ModelAdmin.readonly_fields` -to be displayed as read-only. - -.. admonition:: Note - - This ``fields`` option should not be confused with the ``fields`` - dictionary key that is within the ``fieldsets`` option, as described in - the previous section. - -.. attribute:: ModelAdmin.exclude - -This attribute, if given, should be a list of field names to exclude from the -form. - -For example, let's consider the following model:: - - class Author(models.Model): - name = models.CharField(max_length=100) - title = models.CharField(max_length=3) - birth_date = models.DateField(blank=True, null=True) - -If you want a form for the ``Author`` model that includes only the ``name`` -and ``title`` fields, you would specify ``fields`` or ``exclude`` like this:: - - class AuthorAdmin(admin.ModelAdmin): - fields = ('name', 'title') - - class AuthorAdmin(admin.ModelAdmin): - exclude = ('birth_date',) - -Since the Author model only has three fields, ``name``, ``title``, and -``birth_date``, the forms resulting from the above declarations will contain -exactly the same fields. - -.. attribute:: ModelAdmin.filter_horizontal - -Use a nifty unobtrusive JavaScript "filter" interface instead of the -usability-challenged ``<select multiple>`` in the admin form. The value is a -list of fields that should be displayed as a horizontal filter interface. See -``filter_vertical`` to use a vertical interface. - -.. attribute:: ModelAdmin.filter_vertical - -Same as ``filter_horizontal``, but is a vertical display of the filter -interface. - -.. attribute:: ModelAdmin.list_display - -Set ``list_display`` to control which fields are displayed on the change list -page of the admin. - -Example:: - - list_display = ('first_name', 'last_name') - -If you don't set ``list_display``, the admin site will display a single column -that displays the ``__unicode__()`` representation of each object. - -You have four possible values that can be used in ``list_display``: - - * A field of the model. For example:: - - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'last_name') - - * A callable that accepts one parameter for the model instance. For - example:: - - def upper_case_name(obj): - return ("%s %s" % (obj.first_name, obj.last_name)).upper() - upper_case_name.short_description = 'Name' - - class PersonAdmin(admin.ModelAdmin): - list_display = (upper_case_name,) - - * A string representing an attribute on the ``ModelAdmin``. This behaves - same as the callable. For example:: - - class PersonAdmin(admin.ModelAdmin): - list_display = ('upper_case_name',) - - def upper_case_name(self, obj): - return ("%s %s" % (obj.first_name, obj.last_name)).upper() - upper_case_name.short_description = 'Name' - - * A string representing an attribute on the model. This behaves almost - the same as the callable, but ``self`` in this context is the model - instance. Here's a full model example:: - - class Person(models.Model): - name = models.CharField(max_length=50) - birthday = models.DateField() - - def decade_born_in(self): - return self.birthday.strftime('%Y')[:3] + "0's" - decade_born_in.short_description = 'Birth decade' - - class PersonAdmin(admin.ModelAdmin): - list_display = ('name', 'decade_born_in') - -A few special cases to note about ``list_display``: - - * If the field is a ``ForeignKey``, Django will display the - ``__unicode__()`` of the related object. - - * ``ManyToManyField`` fields aren't supported, because that would entail - 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`` 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, ``ModelAdmin`` or a - callable, 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(max_length=50) - last_name = models.CharField(max_length=50) - color_code = models.CharField(max_length=6) - - 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 - - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'last_name', 'colored_name') - - * If the string given is a method of the model, ``ModelAdmin`` or a - callable that returns True or False Django will display a pretty "on" or - "off" icon if you give the method a ``boolean`` attribute whose value is - ``True``. - - Here's a full example model:: - - class Person(models.Model): - first_name = models.CharField(max_length=50) - birthday = models.DateField() - - def born_in_fifties(self): - return self.birthday.strftime('%Y')[:3] == '195' - born_in_fifties.boolean = True - - class PersonAdmin(admin.ModelAdmin): - list_display = ('name', 'born_in_fifties') - - - * The ``__str__()`` and ``__unicode__()`` methods are just as valid in - ``list_display`` as any other model method, so it's perfectly OK to do - this:: - - list_display = ('__unicode__', 'some_other_field') - - * Usually, elements of ``list_display`` that aren't actual database fields - can't be used in sorting (because Django does all the sorting at the - database level). - - However, if an element of ``list_display`` represents a certain database - field, you can indicate this fact by setting the ``admin_order_field`` - attribute of the item. - - For example:: - - class Person(models.Model): - first_name = models.CharField(max_length=50) - color_code = models.CharField(max_length=6) - - def colored_first_name(self): - return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name) - colored_first_name.allow_tags = True - colored_first_name.admin_order_field = 'first_name' - - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'colored_first_name') - - The above will tell Django to order by the ``first_name`` field when - trying to sort by ``colored_first_name`` in the admin. - -.. attribute:: ModelAdmin.list_display_links - -Set ``list_display_links`` to control which fields in ``list_display`` should -be linked to the "change" page for an object. - -By default, the change list page will link the first column -- the first field -specified in ``list_display`` -- to the change page for each item. But -``list_display_links`` lets you change which columns are linked. Set -``list_display_links`` to a list or tuple of field names (in the same format as -``list_display``) to link. - -``list_display_links`` can specify one or many field names. As long as the -field names appear in ``list_display``, Django doesn't care how many (or how -few) fields are linked. The only requirement is: If you want to use -``list_display_links``, you must define ``list_display``. - -In this example, the ``first_name`` and ``last_name`` fields will be linked on -the change list page:: - - class PersonAdmin(admin.ModelAdmin): - list_display = ('first_name', 'last_name', 'birthday') - list_display_links = ('first_name', 'last_name') - -.. _admin-list-editable: - -.. attribute:: ModelAdmin.list_editable - -.. versionadded:: 1.1 - -Set ``list_editable`` to a list of field names on the model which will allow -editing on the change list page. That is, fields listed in ``list_editable`` -will be displayed as form widgets on the change list page, allowing users to -edit and save multiple rows at once. - -.. note:: - - ``list_editable`` interacts with a couple of other options in particular - ways; you should note the following rules: - - * Any field in ``list_editable`` must also be in ``list_display``. You - can't edit a field that's not displayed! - - * The same field can't be listed in both ``list_editable`` and - ``list_display_links`` -- a field can't be both a form and a link. - - You'll get a validation error if either of these rules are broken. - -.. attribute:: ModelAdmin.list_filter - -Set ``list_filter`` to activate filters in the right sidebar of the change list -page of the admin. This should be a list of field names, and each specified -field should be either a ``BooleanField``, ``CharField``, ``DateField``, -``DateTimeField``, ``IntegerField`` or ``ForeignKey``. - -This example, taken from the ``django.contrib.auth.models.User`` model, shows -how both ``list_display`` and ``list_filter`` work:: - - class UserAdmin(admin.ModelAdmin): - list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff') - list_filter = ('is_staff', 'is_superuser') - -The above code results in an admin change list page that looks like this: - - .. image:: _images/users_changelist.png - -(This example also has ``search_fields`` defined. See below.) - -.. attribute:: ModelAdmin.list_per_page - -Set ``list_per_page`` to control how many items appear on each paginated admin -change list page. By default, this is set to ``100``. - -.. attribute:: ModelAdmin.list_select_related - -Set ``list_select_related`` to tell Django to use -:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of -objects on the admin change list page. This can save you a bunch of database -queries. - -The value should be either ``True`` or ``False``. Default is ``False``. - -Note that Django will use :meth:`~django.db.models.QuerySet.select_related`, -regardless of this setting, if one of the ``list_display`` fields is a -``ForeignKey``. - -.. attribute:: ModelAdmin.inlines - -See ``InlineModelAdmin`` objects below. - -.. attribute:: ModelAdmin.ordering - -Set ``ordering`` to specify how objects on the admin change list page should be -ordered. This should be a list or tuple in the same format as a model's -``ordering`` parameter. - -If this isn't provided, the Django admin will use the model's default ordering. - -.. admonition:: Note - - Django will only honor the first element in the list/tuple; any others - will be ignored. - -.. attribute:: ModelAdmin.prepopulated_fields - -Set ``prepopulated_fields`` to a dictionary mapping field names to the fields -it should prepopulate from:: - - class ArticleAdmin(admin.ModelAdmin): - prepopulated_fields = {"slug": ("title",)} - -When set, the given fields will use a bit of JavaScript to populate from the -fields assigned. The main use for this functionality is to automatically -generate the value for ``SlugField`` fields from one or more other fields. The -generated value is produced by concatenating the values of the source fields, -and then by transforming that result into a valid slug (e.g. substituting -dashes for spaces). - -``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``, nor -``ManyToManyField`` fields. - -.. attribute:: ModelAdmin.radio_fields - -By default, Django's admin uses a select-box interface (<select>) for -fields that are ``ForeignKey`` or have ``choices`` set. If a field is present -in ``radio_fields``, Django will use a radio-button interface instead. -Assuming ``group`` is a ``ForeignKey`` on the ``Person`` model:: - - class PersonAdmin(admin.ModelAdmin): - radio_fields = {"group": admin.VERTICAL} - -You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the -``django.contrib.admin`` module. - -Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has -``choices`` set. - -.. attribute:: ModelAdmin.raw_id_fields - -By default, Django's admin uses a select-box interface (<select>) for -fields that are ``ForeignKey``. Sometimes you don't want to incur the -overhead of having to select all the related instances to display in the -drop-down. - -``raw_id_fields`` is a list of fields you would like to change -into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: - - class ArticleAdmin(admin.ModelAdmin): - raw_id_fields = ("newspaper",) - -.. attribute:: ModelAdmin.readonly_fields - -.. versionadded:: 1.2 - -By default the admin shows all fields as editable. Any fields in this option -(which should be a ``list`` or ``tuple``) will display its data as-is and -non-editable. This option behaves nearly identical to :attr:`ModelAdmin.list_display`. -Usage is the same, however, when you specify :attr:`ModelAdmin.fields` or -:attr:`ModelAdmin.fieldsets` the read-only fields must be present to be shown -(they are ignored otherwise). - -If ``readonly_fields`` is used without defining explicit ordering through -:attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets` they will be added -last after all editable fields. - -.. attribute:: ModelAdmin.save_as - -Set ``save_as`` to enable a "save as" feature on admin change forms. - -Normally, objects have three save options: "Save", "Save and continue editing" -and "Save and add another". If ``save_as`` is ``True``, "Save and add another" -will be replaced by a "Save as" button. - -"Save as" means the object will be saved as a new object (with a new ID), -rather than the old object. - -By default, ``save_as`` is set to ``False``. - -.. attribute:: ModelAdmin.save_on_top - -Set ``save_on_top`` to add save buttons across the top of your admin change -forms. - -Normally, the save buttons appear only at the bottom of the forms. If you set -``save_on_top``, the buttons will appear both on the top and the bottom. - -By default, ``save_on_top`` is set to ``False``. - -.. attribute:: ModelAdmin.search_fields - -Set ``search_fields`` to enable a search box on the admin change list page. -This should be set to a list of field names that will be searched whenever -somebody submits a search query in that text box. - -These fields should be some kind of text field, such as ``CharField`` or -``TextField``. You can also perform a related lookup on a ``ForeignKey`` or -``ManyToManyField`` with the lookup API "follow" notation:: - - search_fields = ['foreign_key__related_fieldname'] - -For example, if you have a blog entry with an author, the following definition -would enable search blog entries by the email address of the author:: - - search_fields = ['user__email'] - -When somebody does a search in the admin search box, Django splits the search -query into words and returns all objects that contain each of the words, case -insensitive, where each word must be in at least one of ``search_fields``. 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%') - -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 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. - -.. attribute:: ModelAdmin.formfield_overrides - -.. versionadded:: 1.1 - -This provides a quick-and-dirty way to override some of the -:class:`~django.forms.Field` options for use in the admin. -``formfield_overrides`` is a dictionary mapping a field class to a dict of -arguments to pass to the field at construction time. - -Since that's a bit abstract, let's look at a concrete example. The most common -use of ``formfield_overrides`` is to add a custom widget for a certain type of -field. So, imagine we've written a ``RichTextEditorWidget`` that we'd like to -use for large text fields instead of the default ``<textarea>``. Here's how we'd -do that:: - - from django.db import models - from django.contrib import admin - - # Import our custom widget and our model from where they're defined - from myapp.widgets import RichTextEditorWidget - from myapp.models import MyModel - - class MyModelAdmin(admin.ModelAdmin): - formfield_overrides = { - models.TextField: {'widget': RichTextEditorWidget}, - } - -Note that the key in the dictionary is the actual field class, *not* a string. -The value is another dictionary; these arguments will be passed to -:meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for details. - -.. warning:: - - If you want to use a custom widget with a relation field (i.e. - :class:`~django.db.models.ForeignKey` or - :class:`~django.db.models.ManyToManyField`), make sure you haven't included - that field's name in ``raw_id_fields`` or ``radio_fields``. - - ``formfield_overrides`` won't let you change the widget on relation fields - that have ``raw_id_fields`` or ``radio_fields`` set. That's because - ``raw_id_fields`` and ``radio_fields`` imply custom widgets of their own. - -.. attribute:: ModelAdmin.actions - -.. versionadded:: 1.1 - -A list of actions to make available on the change list page. See -:doc:`/ref/contrib/admin/actions` for details. - -.. attribute:: ModelAdmin.actions_on_top -.. attribute:: ModelAdmin.actions_on_bottom - -.. versionadded:: 1.1 - -Controls where on the page the actions bar appears. By default, the admin -changelist displays actions at the top of the page (``actions_on_top = True; -actions_on_bottom = False``). - -.. attribute:: ModelAdmin.actions_selection_counter - -.. versionadded:: 1.2 - -Controls whether a selection counter is display next to the action dropdown. -By default, the admin changelist will display it -(``actions_selection_counter = True``). - -Custom template options -~~~~~~~~~~~~~~~~~~~~~~~ - -The `Overriding Admin Templates`_ section describes how to override or extend -the default admin templates. Use the following options to override the default -templates used by the :class:`ModelAdmin` views: - -.. attribute:: ModelAdmin.add_form_template - - .. versionadded:: 1.2 - - Path to a custom template, used by :meth:`add_view`. - -.. attribute:: ModelAdmin.change_form_template - - Path to a custom template, used by :meth:`change_view`. - -.. attribute:: ModelAdmin.change_list_template - - Path to a custom template, used by :meth:`changelist_view`. - -.. attribute:: ModelAdmin.delete_confirmation_template - - Path to a custom template, used by :meth:`delete_view` for displaying a - confirmation page when deleting one or more objects. - -.. attribute:: ModelAdmin.delete_selected_confirmation_template - - .. versionadded:: 1.2 - - Path to a custom template, used by the :meth:`delete_selected` - action method for displaying a confirmation page when deleting one - or more objects. See the :doc:`actions - documentation</ref/contrib/admin/actions>`. - -.. attribute:: ModelAdmin.object_history_template - - Path to a custom template, used by :meth:`history_view`. - - -.. _model-admin-methods: - -``ModelAdmin`` methods ----------------------- - -.. method:: ModelAdmin.save_model(self, request, obj, form, change) - -The ``save_model`` method is given the ``HttpRequest``, a model instance, -a ``ModelForm`` instance and a boolean value based on whether it is adding or -changing the object. Here you can do any pre- or post-save operations. - -For example to attach ``request.user`` to the object prior to saving:: - - class ArticleAdmin(admin.ModelAdmin): - def save_model(self, request, obj, form, change): - obj.user = request.user - obj.save() - -.. method:: ModelAdmin.save_formset(self, request, form, formset, change) - -The ``save_formset`` method is given the ``HttpRequest``, the parent -``ModelForm`` instance and a boolean value based on whether it is adding or -changing the parent object. - -For example to attach ``request.user`` to each changed formset -model instance:: - - class ArticleAdmin(admin.ModelAdmin): - def save_formset(self, request, form, formset, change): - instances = formset.save(commit=False) - for instance in instances: - instance.user = request.user - instance.save() - formset.save_m2m() - -.. method:: ModelAdmin.get_readonly_fields(self, request, obj=None) - -.. versionadded:: 1.2 - -The ``get_readonly_fields`` method is given the ``HttpRequest`` and the -``obj`` being edited (or ``None`` on an add form) and is expected to return a -``list`` or ``tuple`` of field names that will be displayed as read-only, as -described above in the :attr:`ModelAdmin.readonly_fields` section. - -.. method:: ModelAdmin.get_urls(self) - -.. versionadded:: 1.1 - -The ``get_urls`` method on a ``ModelAdmin`` returns the URLs to be used for -that ModelAdmin in the same way as a URLconf. Therefore you can extend them as -documented in :doc:`/topics/http/urls`:: - - class MyModelAdmin(admin.ModelAdmin): - def get_urls(self): - urls = super(MyModelAdmin, self).get_urls() - my_urls = patterns('', - (r'^my_view/$', self.my_view) - ) - return my_urls + urls - -.. note:: - - Notice that the custom patterns are included *before* the regular admin - URLs: the admin URL patterns are very permissive and will match nearly - anything, so you'll usually want to prepend your custom URLs to the built-in - ones. - -However, the ``self.my_view`` function registered above suffers from two -problems: - - * It will *not* perform any permission checks, so it will be accessible to - the general public. - * It will *not* provide any header details to prevent caching. This means if - the page retrieves data from the database, and caching middleware is - active, the page could show outdated information. - -Since this is usually not what you want, Django provides a convenience wrapper -to check permissions and mark the view as non-cacheable. This wrapper is -:meth:`AdminSite.admin_view` (i.e. ``self.admin_site.admin_view`` inside a -``ModelAdmin`` instance); use it like so:: - - class MyModelAdmin(admin.ModelAdmin): - def get_urls(self): - urls = super(MyModelAdmin, self).get_urls() - my_urls = patterns('', - (r'^my_view/$', self.admin_site.admin_view(self.my_view)) - ) - return my_urls + urls - -Notice the wrapped view in the fifth line above:: - - (r'^my_view/$', self.admin_site.admin_view(self.my_view)) - -This wrapping will protect ``self.my_view`` from unauthorized access and will -apply the ``django.views.decorators.cache.never_cache`` decorator to make sure -it is not cached if the cache middleware is active. - -If the page is cacheable, but you still want the permission check to be performed, -you can pass a ``cacheable=True`` argument to :meth:`AdminSite.admin_view`:: - - (r'^my_view/$', self.admin_site.admin_view(self.my_view, cacheable=True)) - -.. method:: ModelAdmin.formfield_for_foreignkey(self, db_field, request, **kwargs) - -.. versionadded:: 1.1 - -The ``formfield_for_foreignkey`` method on a ``ModelAdmin`` allows you to -override the default formfield for a foreign key field. For example, to -return a subset of objects for this foreign key field based on the user:: - - class MyModelAdmin(admin.ModelAdmin): - def formfield_for_foreignkey(self, db_field, request, **kwargs): - if db_field.name == "car": - kwargs["queryset"] = Car.objects.filter(owner=request.user) - return super(MyModelAdmin, self).formfield_for_foreignkey(db_field, request, **kwargs) - -This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field -to only display the cars owned by the ``User`` instance. - -.. method:: ModelAdmin.formfield_for_manytomany(self, db_field, request, **kwargs) - -.. versionadded:: 1.1 - -Like the ``formfield_for_foreignkey`` method, the ``formfield_for_manytomany`` -method can be overridden to change the default formfield for a many to many -field. For example, if an owner can own multiple cars and cars can belong -to multiple owners -- a many to many relationship -- you could filter the -``Car`` foreign key field to only display the cars owned by the ``User``:: - - class MyModelAdmin(admin.ModelAdmin): - def formfield_for_manytomany(self, db_field, request, **kwargs): - if db_field.name == "cars": - kwargs["queryset"] = Car.objects.filter(owner=request.user) - return super(MyModelAdmin, self).formfield_for_manytomany(db_field, request, **kwargs) - -.. method:: ModelAdmin.queryset(self, request) - -The ``queryset`` method on a ``ModelAdmin`` returns a -:class:`~django.db.models.QuerySet` of all model instances that can be -edited by the admin site. One use case for overriding this method is -to show objects owned by the logged-in user:: - - class MyModelAdmin(admin.ModelAdmin): - def queryset(self, request): - qs = super(MyModelAdmin, self).queryset(request) - if request.user.is_superuser: - return qs - return qs.filter(author=request.user) - -.. method:: ModelAdmin.message_user(request, message) - - Sends a message to the user. The default implementation creates a message - using the :mod:`django.contrib.messages` backend. See the - :ref:`custom ModelAdmin example <custom-admin-action>`. - -Other methods -~~~~~~~~~~~~~ - -.. method:: ModelAdmin.add_view(self, request, form_url='', extra_context=None) - -Django view for the model instance addition page. See note below. - -.. method:: ModelAdmin.change_view(self, request, object_id, extra_context=None) - -Django view for the model instance edition page. See note below. - -.. method:: ModelAdmin.changelist_view(self, request, extra_context=None) - -Django view for the model instances change list/actions page. See note below. - -.. method:: ModelAdmin.delete_view(self, request, object_id, extra_context=None) - -Django view for the model instance(s) deletion confirmation page. See note below. - -.. method:: ModelAdmin.history_view(self, request, object_id, extra_context=None) - -Django view for the page that shows the modification history for a given model -instance. - -Unlike the hook-type ``ModelAdmin`` methods detailed in the previous section, -these five methods are in reality designed to be invoked as Django views from -the admin application URL dispatching handler to render the pages that deal -with model instances CRUD operations. As a result, completely overriding these -methods will significantly change the behavior of the admin application. - -One common reason for overriding these methods is to augment the context data -that is provided to the template that renders the view. In the following -example, the change view is overridden so that the rendered template is -provided some extra mapping data that would not otherwise be available:: - - class MyModelAdmin(admin.ModelAdmin): - - # A template for a very customized change view: - change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html' - - def get_osm_info(self): - # ... - - def change_view(self, request, object_id, extra_context=None): - my_context = { - 'osm_data': self.get_osm_info(), - } - return super(MyModelAdmin, self).change_view(request, object_id, - extra_context=my_context) - -``ModelAdmin`` media definitions --------------------------------- - -There are times where you would like add a bit of CSS and/or JavaScript to -the add/change views. This can be accomplished by using a Media inner class -on your ``ModelAdmin``:: - - class ArticleAdmin(admin.ModelAdmin): - class Media: - css = { - "all": ("my_styles.css",) - } - js = ("my_code.js",) - -Keep in mind that this will be prepended with ``MEDIA_URL``. The same rules -apply as :doc:`regular media definitions on forms </topics/forms/media>`. - -Django admin Javascript makes use of the `jQuery`_ library. To avoid -conflict with user scripts, Django's jQuery is namespaced as -``django.jQuery``. If you want to use jQuery in your own admin -JavaScript without including a second copy, you can use the -``django.jQuery`` object on changelist and add/edit views. - -.. _jQuery: http://jquery.com - -Adding custom validation to the admin -------------------------------------- - -Adding custom validation of data in the admin is quite easy. The automatic admin -interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you -the ability define your own form:: - - class ArticleAdmin(admin.ModelAdmin): - form = MyArticleAdminForm - -``MyArticleAdminForm`` can be defined anywhere as long as you import where -needed. Now within your form you can add your own custom validation for -any field:: - - class MyArticleAdminForm(forms.ModelForm): - class Meta: - model = Article - - def clean_name(self): - # do something that validates your data - return self.cleaned_data["name"] - -It is important you use a ``ModelForm`` here otherwise things can break. See the -:doc:`forms </ref/forms/index>` documentation on :doc:`custom validation -</ref/forms/validation>` and, more specifically, the -:ref:`model form validation notes <overriding-modelform-clean-method>` for more -information. - -.. _admin-inlines: - -``InlineModelAdmin`` objects -============================ - -.. class:: InlineModelAdmin - -The admin interface has the ability to edit models on the same page as a -parent model. These are called inlines. Suppose you have these two models:: - - class Author(models.Model): - name = models.CharField(max_length=100) - - class Book(models.Model): - author = models.ForeignKey(Author) - title = models.CharField(max_length=100) - -You can edit the books authored by an author on the author page. You add -inlines to a model by specifying them in a ``ModelAdmin.inlines``:: - - class BookInline(admin.TabularInline): - model = Book - - class AuthorAdmin(admin.ModelAdmin): - inlines = [ - BookInline, - ] - -Django provides two subclasses of ``InlineModelAdmin`` and they are: - - * ``TabularInline`` - * ``StackedInline`` - -The difference between these two is merely the template used to render them. - -``InlineModelAdmin`` options ------------------------------ - -The ``InlineModelAdmin`` class is a subclass of ``ModelAdmin`` so it inherits -all the same functionality as well as some of its own: - -.. attribute:: InlineModelAdmin.model - - The model in which the inline is using. This is required. - -.. attribute:: InlineModelAdmin.fk_name - - The name of the foreign key on the model. In most cases this will be dealt - with automatically, but ``fk_name`` must be specified explicitly if there - are more than one foreign key to the same parent model. - -.. attribute:: InlineModelAdmin.formset - - This defaults to ``BaseInlineFormSet``. Using your own formset can give you - many possibilities of customization. Inlines are built around - :ref:`model formsets <model-formsets>`. - -.. attribute:: InlineModelAdmin.form - - The value for ``form`` defaults to ``ModelForm``. This is what is passed - through to ``inlineformset_factory`` when creating the formset for this - inline. - -.. _ref-contrib-admin-inline-extra: - -.. attribute:: InlineModelAdmin.extra - - - This controls the number of extra forms the formset will display in addition - to the initial forms. See the - :doc:`formsets documentation </topics/forms/formsets>` for more information. - - .. versionadded:: 1.2 - - For users with JavaScript-enabled browsers, an "Add another" link is - provided to enable any number of additional inlines to be added in addition - to those provided as a result of the ``extra`` argument. - - The dynamic link will not appear if the number of currently displayed forms - exceeds ``max_num``, or if the user does not have JavaScript enabled. - -.. _ref-contrib-admin-inline-max-num: - -.. attribute:: InlineModelAdmin.max_num - - This controls the maximum number of forms to show in the inline. This - doesn't directly correlate to the number of objects, but can if the value - is small enough. See :ref:`model-formsets-max-num` for more information. - -.. attribute:: InlineModelAdmin.raw_id_fields - - By default, Django's admin uses a select-box interface (<select>) for - fields that are ``ForeignKey``. Sometimes you don't want to incur the - overhead of having to select all the related instances to display in the - drop-down. - - ``raw_id_fields`` is a list of fields you would like to change into a - ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: - - class BookInline(admin.TabularInline): - model = Book - raw_id_fields = ("pages",) - - -.. attribute:: InlineModelAdmin.template - - The template used to render the inline on the page. - -.. attribute:: InlineModelAdmin.verbose_name - - An override to the ``verbose_name`` found in the model's inner ``Meta`` - class. - -.. attribute:: InlineModelAdmin.verbose_name_plural - - An override to the ``verbose_name_plural`` found in the model's inner - ``Meta`` class. - -.. attribute:: InlineModelAdmin.can_delete - - Specifies whether or not inline objects can be deleted in the inline. - Defaults to ``True``. - - -Working with a model with two or more foreign keys to the same parent model ---------------------------------------------------------------------------- - -It is sometimes possible to have more than one foreign key to the same model. -Take this model for instance:: - - class Friendship(models.Model): - to_person = models.ForeignKey(Person, related_name="friends") - from_person = models.ForeignKey(Person, related_name="from_friends") - -If you wanted to display an inline on the ``Person`` admin add/change pages -you need to explicitly define the foreign key since it is unable to do so -automatically:: - - class FriendshipInline(admin.TabularInline): - model = Friendship - fk_name = "to_person" - - class PersonAdmin(admin.ModelAdmin): - inlines = [ - FriendshipInline, - ] - -Working with Many-to-Many Models --------------------------------- - -.. versionadded:: 1.2 - -By default, admin widgets for many-to-many relations will be displayed -on whichever model contains the actual reference to the ``ManyToManyField``. -Depending on your ``ModelAdmin`` definition, each many-to-many field in your -model will be represented by a standard HTML ``<select multiple>``, a -horizontal or vertical filter, or a ``raw_id_admin`` widget. However, it is -also possible to to replace these widgets with inlines. - -Suppose we have the following models:: - - class Person(models.Model): - name = models.CharField(max_length=128) - - class Group(models.Model): - name = models.CharField(max_length=128) - members = models.ManyToManyField(Person, related_name='groups') - -If you want to display many-to-many relations using an inline, you can do -so by defining an ``InlineModelAdmin`` object for the relationship:: - - class MembershipInline(admin.TabularInline): - model = Group.members.through - - class PersonAdmin(admin.ModelAdmin): - inlines = [ - MembershipInline, - ] - - class GroupAdmin(admin.ModelAdmin): - inlines = [ - MembershipInline, - ] - exclude = ('members',) - -There are two features worth noting in this example. - -Firstly - the ``MembershipInline`` class references ``Group.members.through``. -The ``through`` attribute is a reference to the model that manages the -many-to-many relation. This model is automatically created by Django when you -define a many-to-many field. - -Secondly, the ``GroupAdmin`` must manually exclude the ``members`` field. -Django displays an admin widget for a many-to-many field on the model that -defines the relation (in this case, ``Group``). If you want to use an inline -model to represent the many-to-many relationship, you must tell Django's admin -to *not* display this widget - otherwise you will end up with two widgets on -your admin page for managing the relation. - -In all other respects, the ``InlineModelAdmin`` is exactly the same as any -other. You can customize the appearance using any of the normal -``ModelAdmin`` properties. - -Working with Many-to-Many Intermediary Models ----------------------------------------------- - -When you specify an intermediary model using the ``through`` argument to a -``ManyToManyField``, the admin will not display a widget by default. This is -because each instance of that intermediary model requires more information -than could be displayed in a single widget, and the layout required for -multiple widgets will vary depending on the intermediate model. - -However, we still want to be able to edit that information inline. Fortunately, -this is easy to do with inline admin models. Suppose we have the following -models:: - - class Person(models.Model): - name = models.CharField(max_length=128) - - class Group(models.Model): - name = models.CharField(max_length=128) - members = models.ManyToManyField(Person, through='Membership') - - class Membership(models.Model): - person = models.ForeignKey(Person) - group = models.ForeignKey(Group) - date_joined = models.DateField() - invite_reason = models.CharField(max_length=64) - -The first step in displaying this intermediate model in the admin is to -define an inline class for the ``Membership`` model:: - - class MembershipInline(admin.TabularInline): - model = Membership - extra = 1 - -This simple example uses the default ``InlineModelAdmin`` values for the -``Membership`` model, and limits the extra add forms to one. This could be -customized using any of the options available to ``InlineModelAdmin`` classes. - -Now create admin views for the ``Person`` and ``Group`` models:: - - class PersonAdmin(admin.ModelAdmin): - inlines = (MembershipInline,) - - class GroupAdmin(admin.ModelAdmin): - inlines = (MembershipInline,) - -Finally, register your ``Person`` and ``Group`` models with the admin site:: - - admin.site.register(Person, PersonAdmin) - admin.site.register(Group, GroupAdmin) - -Now your admin site is set up to edit ``Membership`` objects inline from -either the ``Person`` or the ``Group`` detail pages. - -Using generic relations as an inline ------------------------------------- - -It is possible to use an inline with generically related objects. Let's say -you have the following models:: - - class Image(models.Model): - image = models.ImageField(upload_to="images") - content_type = models.ForeignKey(ContentType) - object_id = models.PositiveIntegerField() - content_object = generic.GenericForeignKey("content_type", "object_id") - - class Product(models.Model): - name = models.CharField(max_length=100) - -If you want to allow editing and creating ``Image`` instance on the ``Product`` -add/change views you can simply use ``GenericInlineModelAdmin`` provided by -``django.contrib.contenttypes.generic``. In your ``admin.py`` for this -example app:: - - from django.contrib import admin - from django.contrib.contenttypes import generic - - from myproject.myapp.models import Image, Product - - class ImageInline(generic.GenericTabularInline): - model = Image - - class ProductAdmin(admin.ModelAdmin): - inlines = [ - ImageInline, - ] - - admin.site.register(Product, ProductAdmin) - -``django.contrib.contenttypes.generic`` provides both a ``GenericTabularInline`` -and ``GenericStackedInline`` and behave just like any other inline. See the -:doc:`contenttypes documentation </ref/contrib/contenttypes>` for more specific -information. - -Overriding Admin Templates -========================== - -It is relatively easy to override many of the templates which the admin module -uses to generate the various pages of an admin site. You can even override a few -of these templates for a specific app, or a specific model. - -Set up your projects admin template directories ------------------------------------------------ - -The admin template files are located in the ``contrib/admin/templates/admin`` -directory. - -In order to override one or more of them, first create an ``admin`` directory in -your project's ``templates`` directory. This can be any of the directories you -specified in ``TEMPLATE_DIRS``. - -Within this ``admin`` directory, create sub-directories named after your app. -Within these app subdirectories create sub-directories named after your models. -Note, that the admin app will lowercase the model name when looking for the -directory, so make sure you name the directory in all lowercase if you are going -to run your app on a case-sensitive filesystem. - -To override an admin template for a specific app, copy and edit the template -from the ``django/contrib/admin/templates/admin`` directory, and save it to one -of the directories you just created. - -For example, if we wanted to add a tool to the change list view for all the -models in an app named ``my_app``, we would copy -``contrib/admin/templates/admin/change_list.html`` to the -``templates/admin/my_app/`` directory of our project, and make any necessary -changes. - -If we wanted to add a tool to the change list view for only a specific model -named 'Page', we would copy that same file to the -``templates/admin/my_app/page`` directory of our project. - -Overriding vs. replacing an admin template ------------------------------------------- - -Because of the modular design of the admin templates, it is usually neither -necessary nor advisable to replace an entire template. It is almost always -better to override only the section of the template which you need to change. - -To continue the example above, we want to add a new link next to the ``History`` -tool for the ``Page`` model. After looking at ``change_form.html`` we determine -that we only need to override the ``object-tools`` block. Therefore here is our -new ``change_form.html`` : - -.. code-block:: html+django - - {% extends "admin/change_form.html" %} - {% load i18n %} - {% block object-tools %} - {% if change %}{% if not is_popup %} - <ul class="object-tools"> - <li><a href="history/" class="historylink">{% trans "History" %}</a></li> - <li><a href="mylink/" class="historylink">My Link</a></li> - {% if has_absolute_url %} - <li><a href="../../../r/{{ content_type_id }}/{{ object_id }}/" class="viewsitelink"> - {% trans "View on site" %}</a> - </li> - {% endif%} - </ul> - {% endif %}{% endif %} - {% endblock %} - -And that's it! If we placed this file in the ``templates/admin/my_app`` -directory, our link would appear on every model's change form. - -Templates which may be overridden per app or model --------------------------------------------------- - -Not every template in ``contrib/admin/templates/admin`` may be overridden per -app or per model. The following can: - - * ``app_index.html`` - * ``change_form.html`` - * ``change_list.html`` - * ``delete_confirmation.html`` - * ``object_history.html`` - -For those templates that cannot be overridden in this way, you may still -override them for your entire project. Just place the new version in your -``templates/admin`` directory. This is particularly useful to create custom 404 -and 500 pages. - -.. note:: - - Some of the admin templates, such as ``change_list_request.html`` are used - to render custom inclusion tags. These may be overridden, but in such cases - you are probably better off creating your own version of the tag in question - and giving it a different name. That way you can use it selectively. - -Root and login templates ------------------------- - -If you wish to change the index, login or logout templates, you are better off -creating your own ``AdminSite`` instance (see below), and changing the -:attr:`AdminSite.index_template` , :attr:`AdminSite.login_template` or -:attr:`AdminSite.logout_template` properties. - -``AdminSite`` objects -===================== - -.. class:: AdminSite(name=None) - -A Django administrative site is represented by an instance of -``django.contrib.admin.sites.AdminSite``; by default, an instance of -this class is created as ``django.contrib.admin.site`` and you can -register your models and ``ModelAdmin`` instances with it. - -If you'd like to set up your own administrative site with custom -behavior, however, you're free to subclass ``AdminSite`` and override -or add anything you like. Then, simply create an instance of your -``AdminSite`` subclass (the same way you'd instantiate any other -Python class), and register your models and ``ModelAdmin`` subclasses -with it instead of using the default. - -.. versionadded:: 1.1 - -When constructing an instance of an ``AdminSite``, you are able to provide -a unique instance name using the ``name`` argument to the constructor. This -instance name is used to identify the instance, especially when -:ref:`reversing admin URLs <admin-reverse-urls>`. If no instance name is -provided, a default instance name of ``admin`` will be used. - -``AdminSite`` attributes ------------------------- - -Templates can override or extend base admin templates as described in -`Overriding Admin Templates`_. - -.. attribute:: AdminSite.index_template - -Path to a custom template that will be used by the admin site main index view. - -.. attribute:: AdminSite.login_template - -Path to a custom template that will be used by the admin site login view. - -.. attribute:: AdminSite.logout_template - -.. versionadded:: 1.2 - -Path to a custom template that will be used by the admin site logout view. - -.. attribute:: AdminSite.password_change_template - -.. versionadded:: 1.2 - -Path to a custom template that will be used by the admin site password change -view. - -.. attribute:: AdminSite.password_change_done_template - -.. versionadded:: 1.2 - -Path to a custom template that will be used by the admin site password change -done view. - -Hooking ``AdminSite`` instances into your URLconf -------------------------------------------------- - -The last step in setting up the Django admin is to hook your ``AdminSite`` -instance into your URLconf. Do this by pointing a given URL at the -``AdminSite.urls`` method. - -In this example, we register the default ``AdminSite`` instance -``django.contrib.admin.site`` at the URL ``/admin/`` :: - - # urls.py - from django.conf.urls.defaults import * - from django.contrib import admin - - admin.autodiscover() - - urlpatterns = patterns('', - (r'^admin/', include(admin.site.urls)), - ) - -Above we used ``admin.autodiscover()`` to automatically load the -``INSTALLED_APPS`` admin.py modules. - -In this example, we register the ``AdminSite`` instance -``myproject.admin.admin_site`` at the URL ``/myadmin/`` :: - - # urls.py - from django.conf.urls.defaults import * - from myproject.admin import admin_site - - urlpatterns = patterns('', - (r'^myadmin/', include(admin_site.urls)), - ) - -There is really no need to use autodiscover when using your own ``AdminSite`` -instance since you will likely be importing all the per-app admin.py modules -in your ``myproject.admin`` module. - -Multiple admin sites in the same URLconf ----------------------------------------- - -It's easy to create multiple instances of the admin site on the same -Django-powered Web site. Just create multiple instances of ``AdminSite`` and -root each one at a different URL. - -.. versionchanged:: 1.1 - The method for hooking ``AdminSite`` instances into urls has changed in - Django 1.1. - -In this example, the URLs ``/basic-admin/`` and ``/advanced-admin/`` feature -separate versions of the admin site -- using the ``AdminSite`` instances -``myproject.admin.basic_site`` and ``myproject.admin.advanced_site``, -respectively:: - - # urls.py - from django.conf.urls.defaults import * - from myproject.admin import basic_site, advanced_site - - urlpatterns = patterns('', - (r'^basic-admin/', include(basic_site.urls)), - (r'^advanced-admin/', include(advanced_site.urls)), - ) - -``AdminSite`` instances take a single argument to their constructor, their -name, which can be anything you like. This argument becomes the prefix to the -URL names for the purposes of :ref:`reversing them<admin-reverse-urls>`. This -is only necessary if you are using more than one ``AdminSite``. - -Adding views to admin sites ---------------------------- - -.. versionadded:: 1.1 - -Just like :class:`ModelAdmin`, :class:`AdminSite` provides a -:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method -that can be overridden to define additional views for the site. To add -a new view to your admin site, extend the base -:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method to include -a pattern for your new view. - -.. note:: - Any view you render that uses the admin templates, or extends the base - admin template, should provide the ``current_app`` argument to - ``RequestContext`` or ``Context`` when rendering the template. It should - be set to either ``self.name`` if your view is on an ``AdminSite`` or - ``self.admin_site.name`` if your view is on a ``ModelAdmin``. - -.. _admin-reverse-urls: - -Reversing Admin URLs -==================== - -.. versionadded:: 1.1 - -When an :class:`AdminSite` is deployed, the views provided by that site are -accessible using Django's :ref:`URL reversing system <naming-url-patterns>`. - -The :class:`AdminSite` provides the following named URL patterns: - - ====================== ======================== ============= - Page URL name Parameters - ====================== ======================== ============= - Index ``index`` - Logout ``logout`` - Password change ``password_change`` - Password change done ``password_change_done`` - i18n javascript ``jsi18n`` - Application index page ``app_list`` ``app_label`` - ====================== ======================== ============= - -Each :class:`ModelAdmin` instance provides an additional set of named URLs: - - ====================== =============================================== ============= - Page URL name Parameters - ====================== =============================================== ============= - Changelist ``{{ app_label }}_{{ model_name }}_changelist`` - Add ``{{ app_label }}_{{ model_name }}_add`` - History ``{{ app_label }}_{{ model_name }}_history`` ``object_id`` - Delete ``{{ app_label }}_{{ model_name }}_delete`` ``object_id`` - Change ``{{ app_label }}_{{ model_name }}_change`` ``object_id`` - ====================== =============================================== ============= - -These named URLs are registered with the application namespace ``admin``, and -with an instance namespace corresponding to the name of the Site instance. - -So - if you wanted to get a reference to the Change view for a particular -``Choice`` object (from the polls application) in the default admin, you would -call:: - - >>> from django.core import urlresolvers - >>> c = Choice.objects.get(...) - >>> change_url = urlresolvers.reverse('admin:polls_choice_change', args=(c.id,)) - -This will find the first registered instance of the admin application (whatever the instance -name), and resolve to the view for changing ``poll.Choice`` instances in that instance. - -If you want to find a URL in a specific admin instance, provide the name of that instance -as a ``current_app`` hint to the reverse call. For example, if you specifically wanted -the admin view from the admin instance named ``custom``, you would need to call:: - - >>> change_url = urlresolvers.reverse('custom:polls_choice_change', args=(c.id,)) - -For more details, see the documentation on :ref:`reversing namespaced URLs -<topics-http-reversing-url-namespaces>`. diff --git a/parts/django/docs/ref/contrib/auth.txt b/parts/django/docs/ref/contrib/auth.txt deleted file mode 100644 index 619b38e..0000000 --- a/parts/django/docs/ref/contrib/auth.txt +++ /dev/null @@ -1,4 +0,0 @@ -``django.contrib.auth`` -======================= - -See :doc:`/topics/auth`. diff --git a/parts/django/docs/ref/contrib/comments/custom.txt b/parts/django/docs/ref/contrib/comments/custom.txt deleted file mode 100644 index 5411d9c..0000000 --- a/parts/django/docs/ref/contrib/comments/custom.txt +++ /dev/null @@ -1,202 +0,0 @@ -================================== -Customizing the comments framework -================================== - -.. currentmodule:: django.contrib.comments - -If the built-in comment framework doesn't quite fit your needs, you can extend -the comment app's behavior to add custom data and logic. The comments framework -lets you extend the built-in comment model, the built-in comment form, and the -various comment views. - -The :setting:`COMMENTS_APP` setting is where this customization begins. Set -:setting:`COMMENTS_APP` to the name of the app you'd like to use to provide -custom behavior. You'll use the same syntax as you'd use for -:setting:`INSTALLED_APPS`, and the app given must also be in the -:setting:`INSTALLED_APPS` list. - -For example, if you wanted to use an app named ``my_comment_app``, your -settings file would contain:: - - INSTALLED_APPS = [ - ... - 'my_comment_app', - ... - ] - - COMMENTS_APP = 'my_comment_app' - -The app named in :setting:`COMMENTS_APP` provides its custom behavior by -defining some module-level functions in the app's ``__init__.py``. The -:ref:`complete list of these functions <custom-comment-app-api>` can be found -below, but first let's look at a quick example. - -An example custom comments app -============================== - -One of the most common types of customization is modifying the set of fields -provided on the built-in comment model. For example, some sites that allow -comments want the commentator to provide a title for their comment; the built-in -comment model has no field for that title. - -To make this kind of customization, we'll need to do three things: - - #. Create a custom comment :class:`~django.db.models.Model` that adds on the - "title" field. - - #. Create a custom comment :class:`~django.forms.Form` that also adds this - "title" field. - - #. Inform Django of these objects by defining a few functions in a - custom :setting:`COMMENTS_APP`. - -So, carrying on the example above, we're dealing with a typical app structure in -the ``my_custom_app`` directory:: - - my_custom_app/ - __init__.py - models.py - forms.py - -In the ``models.py`` we'll define a ``CommentWithTitle`` model:: - - from django.db import models - from django.contrib.comments.models import Comment - - class CommentWithTitle(Comment): - title = models.CharField(max_length=300) - -Most custom comment models will subclass the :class:`Comment` model. However, -if you want to substantially remove or change the fields available in the -:class:`Comment` model, but don't want to rewrite the templates, you could -try subclassing from :class:`BaseCommentAbstractModel`. - -Next, we'll define a custom comment form in ``forms.py``. This is a little more -tricky: we have to both create a form and override -:meth:`CommentForm.get_comment_model` and -:meth:`CommentForm.get_comment_create_data` to return deal with our custom title -field:: - - from django import forms - from django.contrib.comments.forms import CommentForm - from my_comment_app.models import CommentWithTitle - - class CommentFormWithTitle(CommentForm): - title = forms.CharField(max_length=300) - - def get_comment_model(self): - # Use our custom comment model instead of the built-in one. - return CommentWithTitle - - def get_comment_create_data(self): - # Use the data of the superclass, and add in the title field - data = super(CommentFormWithTitle, self).get_comment_create_data() - data['title'] = self.cleaned_data['title'] - return data - -Django provides a couple of "helper" classes to make writing certain types of -custom comment forms easier; see :mod:`django.contrib.comments.forms` for -more. - -Finally, we'll define a couple of methods in ``my_custom_app/__init__.py`` to -point Django at these classes we've created:: - - from my_comments_app.models import CommentWithTitle - from my_comments_app.forms import CommentFormWithTitle - - def get_model(): - return CommentWithTitle - - def get_form(): - return CommentFormWithTitle - - -.. warning:: - - Be careful not to create cyclic imports in your custom comments app. - If you feel your comment configuration isn't being used as defined -- - for example, if your comment moderation policy isn't being applied -- - you may have a cyclic import problem. - - If you are having unexplained problems with comments behavior, check - if your custom comments application imports (even indirectly) - any module that itself imports Django's comments module. - -The above process should take care of most common situations. For more -advanced usage, there are additional methods you can define. Those are -explained in the next section. - -.. _custom-comment-app-api: - -Custom comment app API -====================== - -The :mod:`django.contrib.comments` app defines the following methods; any -custom comment app must define at least one of them. All are optional, -however. - -.. function:: get_model() - - Return the :class:`~django.db.models.Model` class to use for comments. This - model should inherit from - :class:`django.contrib.comments.models.BaseCommentAbstractModel`, which - defines necessary core fields. - - The default implementation returns - :class:`django.contrib.comments.models.Comment`. - -.. function:: get_form() - - Return the :class:`~django.forms.Form` class you want to use for - creating, validating, and saving your comment model. Your custom - comment form should accept an additional first argument, - ``target_object``, which is the object the comment will be - attached to. - - The default implementation returns - :class:`django.contrib.comments.forms.CommentForm`. - - .. note:: - - The default comment form also includes a number of unobtrusive - spam-prevention features (see - :ref:`notes-on-the-comment-form`). If replacing it with your - own form, you may want to look at the source code for the - built-in form and consider incorporating similar features. - -.. function:: get_form_target() - - Return the URL for POSTing comments. This will be the ``<form action>`` - attribute when rendering your comment form. - - The default implementation returns a reverse-resolved URL pointing - to the :func:`post_comment` view. - - .. note:: - - If you provide a custom comment model and/or form, but you - want to use the default :func:`post_comment` view, you will - need to be aware that it requires the model and form to have - certain additional attributes and methods: see the - :func:`post_comment` view documentation for details. - -.. function:: get_flag_url() - - Return the URL for the "flag this comment" view. - - The default implementation returns a reverse-resolved URL pointing - to the :func:`django.contrib.comments.views.moderation.flag` view. - -.. function:: get_delete_url() - - Return the URL for the "delete this comment" view. - - The default implementation returns a reverse-resolved URL pointing - to the :func:`django.contrib.comments.views.moderation.delete` view. - -.. function:: get_approve_url() - - Return the URL for the "approve this comment from moderation" view. - - The default implementation returns a reverse-resolved URL pointing - to the :func:`django.contrib.comments.views.moderation.approve` view. diff --git a/parts/django/docs/ref/contrib/comments/example.txt b/parts/django/docs/ref/contrib/comments/example.txt deleted file mode 100644 index 424bdb1..0000000 --- a/parts/django/docs/ref/contrib/comments/example.txt +++ /dev/null @@ -1,208 +0,0 @@ -.. highlightlang:: html+django - -=========================================== -Example of using the in-built comments app -=========================================== - -Follow the first three steps of the quick start guide in the -:doc:`documentation </ref/contrib/comments/index>`. - -Now suppose, you have an app (``blog``) with a model (``Post``) -to which you want to attach comments. Let us also suppose that -you have a template called ``blog_detail.html`` where you want -to display the comments list and comment form. - -Template -======== - -First, we should load the ``comment`` template tags in the -``blog_detail.html`` so that we can use it's functionality. So -just like all other custom template tag libraries:: - - {% load comments %} - -Next, let us add the number of comments attached to the particular -model instance of ``Post``. For this we assume that a context -variable ``object_pk`` is present which gives the ``id`` of the -instance of ``Post``. - -The usage of the :ttag:`get_comment_count` tag is like below:: - - {% get_comment_count for blog.post object_pk as comment_count %} - <p>{{ comment_count }} comments have been posted.</p> - -If you have the instance (say ``entry``) of the model (``Post``) -available in the context, then you can refer to it directly:: - - {% get_comment_count for entry as comment_count %} - <p>{{ comment_count }} comments have been posted.</p> - -.. versionadded:: 1.2 - -Next, we can use the :ttag:`render_comment_list` tag, to render all comments -to the given instance (``entry``) by using the ``comments/list.html`` template. - - {% render_comment_list for entry %} - -Django will will look for the ``list.html`` under the following directories -(for our example):: - - comments/blog/post/list.html - comments/blog/list.html - comments/list.html - -To get a list of comments, we make use of the :ttag:`get_comment_list` tag. -This tag's usage is very similar to the :ttag:`get_comment_count` tag. We -need to remember that the :ttag:`get_comment_list` returns a list of comments -and hence we will have to iterate through them to display them:: - - {% get_comment_list for blog.post object_pk as comment_list %} - {% for comment in comment_list %} - <p>Posted by: {{ comment.user_name }} on {{ comment.submit_date }}</p> - ... - <p>Comment: {{ comment.comment }}</p> - ... - {% endfor %} - -Finally, we display the comment form, enabling users to enter their -comments. There are two ways of doing so. The first is when you want to -display the comments template available under your ``comments/form.html``. -The other method gives you a chance to customize the form. - -The first method makes use of the :ttag:`render_comment_form` tag. It's usage -too is similar to the other three tags we have discussed above:: - - {% render_comment_form for entry %} - -It looks for the ``form.html`` under the following directories -(for our example):: - - comments/blog/post/form.html - comments/blog/form.html - comments/form.html - -Since we customize the form in the second method, we make use of another -tag called :ttag:`comment_form_target`. This tag on rendering gives the URL -where the comment form is posted. Without any :doc:`customization -</ref/contrib/comments/custom>`, :ttag:`comment_form_target` evaluates to -``/comments/post/``. We use this tag in the form's ``action`` attribute. - -The :ttag:`get_comment_form` tag renders a ``form`` for a model instance by -creating a context variable. One can iterate over the ``form`` object to -get individual fields. This gives you fine-grain control over the form:: - - {% for field in form %} - {% ifequal field.name "comment" %} - <!-- Customize the "comment" field, say, make CSS changes --> - ... - {% endfor %} - -But let's look at a simple example:: - - {% get_comment_form for entry as form %} - <!-- A context variable called form is created with the necessary hidden - fields, timestamps and security hashes --> - <table> - <form action="{% comment_form_target %}" method="post"> - {{ form }} - <tr> - <td></td> - <td><input type="submit" name="preview" class="submit-post" value="Preview"></td> - </tr> - </form> - </table> - -Flagging -======== - -If you want your users to be able to flag comments (say for profanity), you -can just direct them (by placing a link in your comment list) to ``/flag/{{ -comment.id }}/``. Similarly, a user with requisite permissions (``"Can -moderate comments"``) can approve and delete comments. This can also be -done through the ``admin`` as you'll see later. You might also want to -customize the following templates: - - * ``flag.html`` - * ``flagged.html`` - * ``approve.html`` - * ``approved.html`` - * ``delete.html`` - * ``deleted.html`` - -found under the directory structure we saw for ``form.html``. - -Feeds -===== - -Suppose you want to export a :doc:`feed </ref/contrib/syndication>` of the -latest comments, you can use the in-built :class:`LatestCommentFeed`. Just -enable it in your project's ``urls.py``: - -.. code-block:: python - - from django.conf.urls.defaults import * - from django.contrib.comments.feeds import LatestCommentFeed - - feeds = { - 'latest': LatestCommentFeed, - } - - urlpatterns = patterns('', - # ... - (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed', - {'feed_dict': feeds}), - # ... - ) - -Now you should have the latest comment feeds being served off ``/feeds/latest/``. - -Moderation -========== - -Now that we have the comments framework working, we might want to have some -moderation setup to administer the comments. The comments framework comes -in-built with :doc:`generic comment moderation -</ref/contrib/comments/moderation>`. The comment moderation has the following -features (all of which or only certain can be enabled): - - * Enable comments for a particular model instance. - * Close comments after a particular (user-defined) number of days. - * Email new comments to the site-staff. - -To enable comment moderation, we subclass the :class:`CommentModerator` and -register it with the moderation features we want. Let us suppose we want to -close comments after 7 days of posting and also send out an email to the -site staff. In ``blog/models.py``, we register a comment moderator in the -following way: - -.. code-block:: python - - from django.contrib.comments.moderation import CommentModerator, moderator - from django.db import models - - class Post(models.Model): - title = models.CharField(max_length = 255) - content = models.TextField() - posted_date = models.DateTimeField() - - class PostModerator(CommentModerator): - email_notification = True - auto_close_field = 'posted_date' - # Close the comments after 7 days. - close_after = 7 - - moderator.register(Post, PostModerator) - -The generic comment moderation also has the facility to remove comments. -These comments can then be moderated by any user who has access to the -``admin`` site and the ``Can moderate comments`` permission (can be set -under the ``Users`` page in the ``admin``). - -The moderator can ``Flag``, ``Approve`` or ``Remove`` comments using the -``Action`` drop-down in the ``admin`` under the ``Comments`` page. - -.. note:: - - Only a super-user will be able to delete comments from the database. - ``Remove Comments`` only sets the ``is_public`` attribute to - ``False``. diff --git a/parts/django/docs/ref/contrib/comments/forms.txt b/parts/django/docs/ref/contrib/comments/forms.txt deleted file mode 100644 index c21a27b..0000000 --- a/parts/django/docs/ref/contrib/comments/forms.txt +++ /dev/null @@ -1,46 +0,0 @@ -==================== -Comment form classes -==================== - -.. module:: django.contrib.comments.forms - :synopsis: Forms for dealing with the built-in comment model. - -The ``django.contrib.comments.forms`` module contains a handful of forms -you'll use when writing custom views dealing with comments, or when writing -:doc:`custom comment apps </ref/contrib/comments/custom>`. - -.. class:: CommentForm - - The main comment form representing the standard, built-in way of handling - submitted comments. This is the class used by all the views - :mod:`django.contrib.comments` to handle submitted comments. - - If you want to build custom views that are similar to Django's built-in - comment handling views, you'll probably want to use this form. - -Abstract comment forms for custom comment apps ----------------------------------------------- - -If you're building a :doc:`custom comment app </ref/contrib/comments/custom>`, -you might want to replace *some* of the form logic but still rely on parts of -the existing form. - -:class:`CommentForm` is actually composed of a couple of abstract base class -forms that you can subclass to reuse pieces of the form handling logic: - -.. class:: CommentSecurityForm - - Handles the anti-spoofing protection aspects of the comment form handling. - - This class contains the ``content_type`` and ``object_pk`` fields pointing - to the object the comment is attached to, along with a ``timestamp`` and a - ``security_hash`` of all the form data. Together, the timestamp and the - security hash ensure that spammers can't "replay" form submissions and - flood you with comments. - -.. class:: CommentDetailsForm - - Handles the details of the comment itself. - - This class contains the ``name``, ``email``, ``url``, and the ``comment`` - field itself, along with the associated validation logic.
\ No newline at end of file diff --git a/parts/django/docs/ref/contrib/comments/index.txt b/parts/django/docs/ref/contrib/comments/index.txt deleted file mode 100644 index 817871e..0000000 --- a/parts/django/docs/ref/contrib/comments/index.txt +++ /dev/null @@ -1,302 +0,0 @@ -=========================== -Django's comments framework -=========================== - -.. module:: django.contrib.comments - :synopsis: Django's comment framework - -.. highlightlang:: html+django - -Django includes a simple, yet customizable comments framework. The built-in -comments framework can be used to attach comments to any model, so you can use -it for comments on blog entries, photos, book chapters, or anything else. - -.. note:: - - If you used to use Django's older (undocumented) comments framework, you'll - need to upgrade. See the :doc:`upgrade guide </ref/contrib/comments/upgrade>` - for instructions. - -Quick start guide -================= - -To get started using the ``comments`` app, follow these steps: - - #. Install the comments framework by adding ``'django.contrib.comments'`` to - :setting:`INSTALLED_APPS`. - - #. Run ``manage.py syncdb`` so that Django will create the comment tables. - - #. Add the comment app's URLs to your project's ``urls.py``: - - .. code-block:: python - - urlpatterns = patterns('', - ... - (r'^comments/', include('django.contrib.comments.urls')), - ... - ) - - #. Use the `comment template tags`_ below to embed comments in your - templates. - -You might also want to examine :doc:`/ref/contrib/comments/settings`. - -Comment template tags -===================== - -You'll primarily interact with the comment system through a series of template -tags that let you embed comments and generate forms for your users to post them. - -Like all custom template tag libraries, you'll need to :ref:`load the custom -tags <loading-custom-template-libraries>` before you can use them:: - - {% load comments %} - -Once loaded you can use the template tags below. - -Specifying which object comments are attached to ------------------------------------------------- - -Django's comments are all "attached" to some parent object. This can be any -instance of a Django model. Each of the tags below gives you a couple of -different ways you can specify which object to attach to: - - #. Refer to the object directly -- the more common method. Most of the - time, you'll have some object in the template's context you want - to attach the comment to; you can simply use that object. - - For example, in a blog entry page that has a variable named ``entry``, - you could use the following to load the number of comments:: - - {% get_comment_count for entry as comment_count %}. - - #. Refer to the object by content-type and object id. You'd use this method - if you, for some reason, don't actually have direct access to the object. - - Following the above example, if you knew the object ID was ``14`` but - didn't have access to the actual object, you could do something like:: - - {% get_comment_count for blog.entry 14 as comment_count %} - - In the above, ``blog.entry`` is the app label and (lower-cased) model - name of the model class. - -Displaying comments -------------------- - -To display a list of comments, you can use the template tags -:ttag:`render_comment_list` or :ttag:`get_comment_list`. - -.. templatetag:: render_comment_list - -Quickly rendering a comment list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The easiest way to display a list of comments for some object is by using -:ttag:`render_comment_list`:: - - {% render_comment_list for [object] %} - -For example:: - - {% render_comment_list for event %} - -This will render comments using a template named ``comments/list.html``, a -default version of which is included with Django. - -.. templatetag:: get_comment_list - -Rendering a custom comment list -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To get the list of comments for some object, use :ttag:`get_comment_list`:: - - {% get_comment_list for [object] as [varname] %} - -For example:: - - {% get_comment_list for event as comment_list %} - {% for comment in comment_list %} - ... - {% endfor %} - -This returns a list of :class:`~django.contrib.comments.models.Comment` objects; -see :doc:`the comment model documentation </ref/contrib/comments/models>` for -details. - -.. templatetag:: get_comment_permalink - -Linking to comments -------------------- - -.. versionadded:: 1.2 - -To provide a permalink to a specific comment, use :ttag:`get_comment_permalink`:: - - {% get_comment_permalink comment_obj [format_string] %} - -By default, the named anchor that will be appended to the URL will be the letter -'c' followed by the comment id, for example 'c82'. You may specify a custom -format string if you wish to override this behavior:: - - {% get_comment_permalink comment "#c%(id)s-by-%(user_name)s"%} - -The format string is a standard python format string. Valid mapping keys -include any attributes of the comment object. - -Regardless of whether you specify a custom anchor pattern, you must supply a -matching named anchor at a suitable place in your template. - -For example:: - - {% for comment in comment_list %} - <a name="c{{ comment.id }}"></a> - <a href="{% get_comment_permalink comment %}"> - permalink for comment #{{ forloop.counter }} - </a> - ... - {% endfor %} - -.. warning:: - - There's a known bug in Safari/Webkit which causes the named anchor to be - forgotten following a redirect. The practical impact for comments is that - the Safari/webkit browsers will arrive at the correct page but will not - scroll to the named anchor. - -.. templatetag:: get_comment_count - -Counting comments ------------------ - -To count comments attached to an object, use :ttag:`get_comment_count`:: - - {% get_comment_count for [object] as [varname] %} - -For example:: - - {% get_comment_count for event as comment_count %} - - <p>This event has {{ comment_count }} comments.</p> - - -Displaying the comment post form --------------------------------- - -To show the form that users will use to post a comment, you can use -:ttag:`render_comment_form` or :ttag:`get_comment_form` - -.. templatetag:: render_comment_form - -Quickly rendering the comment form -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The easiest way to display a comment form is by using -:ttag:`render_comment_form`:: - - {% render_comment_form for [object] %} - -For example:: - - {% render_comment_form for event %} - -This will render comments using a template named ``comments/form.html``, a -default version of which is included with Django. - -.. templatetag:: get_comment_form - -Rendering a custom comment form -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want more control over the look and feel of the comment form, you use use -:ttag:`get_comment_form` to get a :doc:`form object </topics/forms/index>` that -you can use in the template:: - - {% get_comment_form for [object] as [varname] %} - -A complete form might look like:: - - {% get_comment_form for event as form %} - <form action="{% comment_form_target %}" method="post"> - {{ form }} - <tr> - <td></td> - <td><input type="submit" name="preview" class="submit-post" value="Preview"></td> - </tr> - </form> - -Be sure to read the `notes on the comment form`_, below, for some special -considerations you'll need to make if you're using this approach. - -.. templatetag:: comment_form_target - -Getting the comment form target -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You may have noticed that the above example uses another template tag -- -:ttag:`comment_form_target` -- to actually get the ``action`` attribute of the -form. This will always return the correct URL that comments should be posted to; -you'll always want to use it like above:: - - <form action="{% comment_form_target %}" method="post"> - -Redirecting after the comment post -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To specify the URL you want to redirect to after the comment has been posted, -you can include a hidden form input called ``next`` in your comment form. For example:: - - <input type="hidden" name="next" value="{% url my_comment_was_posted %}" /> - -.. _notes-on-the-comment-form: - -Notes on the comment form -------------------------- - -The form used by the comment system has a few important anti-spam attributes you -should know about: - - * It contains a number of hidden fields that contain timestamps, information - about the object the comment should be attached to, and a "security hash" - used to validate this information. If someone tampers with this data -- - something comment spammers will try -- the comment submission will fail. - - If you're rendering a custom comment form, you'll need to make sure to - pass these values through unchanged. - - * The timestamp is used to ensure that "reply attacks" can't continue very - long. Users who wait too long between requesting the form and posting a - comment will have their submissions refused. - - * The comment form includes a "honeypot_" field. It's a trap: if any data is - entered in that field, the comment will be considered spam (spammers often - automatically fill in all fields in an attempt to make valid submissions). - - The default form hides this field with a piece of CSS and further labels - it with a warning field; if you use the comment form with a custom - template you should be sure to do the same. - -The comments app also depends on the more general :doc:`Cross Site Request -Forgery protection </ref/contrib/csrf>` that comes with Django. As described in -the documentation, it is best to use ``CsrfViewMiddleware``. However, if you -are not using that, you will need to use the ``csrf_protect`` decorator on any -views that include the comment form, in order for those views to be able to -output the CSRF token and cookie. - -.. _honeypot: http://en.wikipedia.org/wiki/Honeypot_(computing) - -More information -================ - -.. toctree:: - :maxdepth: 1 - - models - settings - signals - upgrade - custom - forms - moderation - example diff --git a/parts/django/docs/ref/contrib/comments/models.txt b/parts/django/docs/ref/contrib/comments/models.txt deleted file mode 100644 index e773790..0000000 --- a/parts/django/docs/ref/contrib/comments/models.txt +++ /dev/null @@ -1,80 +0,0 @@ -=========================== -The built-in comment models -=========================== - -.. module:: django.contrib.comments.models - :synopsis: The built-in comment models - -.. class:: Comment - - Django's built-in comment model. Has the following fields: - - .. attribute:: content_object - - A :class:`~django.contrib.contettypes.generic.GenericForeignKey` - attribute pointing to the object the comment is attached to. You can use - this to get at the related object (i.e. ``my_comment.content_object``). - - Since this field is a - :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's - actually syntactic sugar on top of two underlying attributes, described - below. - - .. attribute:: content_type - - A :class:`~django.db.models.ForeignKey` to - :class:`~django.contrib.contenttypes.models.ContentType`; this is the - type of the object the comment is attached to. - - .. attribute:: object_pk - - A :class:`~django.db.models.TextField` containing the primary - key of the object the comment is attached to. - - .. attribute:: site - - A :class:`~django.db.models.ForeignKey` to the - :class:`~django.contrib.sites.models.Site` on which the comment was - posted. - - .. attribute:: user - - A :class:`~django.db.models.ForeignKey` to the - :class:`~django.contrib.auth.models.User` who posted the comment. - May be blank if the comment was posted by an unauthenticated user. - - .. attribute:: user_name - - The name of the user who posted the comment. - - .. attribute:: user_email - - The email of the user who posted the comment. - - .. attribute:: user_url - - The URL entered by the person who posted the comment. - - .. attribute:: comment - - The actual content of the comment itself. - - .. attribute:: submit_date - - The date the comment was submitted. - - .. attribute:: ip_address - - The IP address of the user posting the comment. - - .. attribute:: is_public - - ``False`` if the comment is in moderation (see - :doc:`/ref/contrib/comments/moderation`); If ``True``, the comment will - be displayed on the site. - - .. attribute:: is_removed - - ``True`` if the comment was removed. Used to keep track of removed - comments instead of just deleting them. - diff --git a/parts/django/docs/ref/contrib/comments/moderation.txt b/parts/django/docs/ref/contrib/comments/moderation.txt deleted file mode 100644 index 519bc5e..0000000 --- a/parts/django/docs/ref/contrib/comments/moderation.txt +++ /dev/null @@ -1,230 +0,0 @@ -========================== -Generic comment moderation -========================== - -.. module:: django.contrib.comments.moderation - :synopsis: Support for automatic comment moderation. - -Django's bundled comments application is extremely useful on its own, -but the amount of comment spam circulating on the Web today -essentially makes it necessary to have some sort of automatic -moderation system in place for any application which makes use of -comments. To make this easier to handle in a consistent fashion, -``django.contrib.comments.moderation`` provides a generic, extensible -comment-moderation system which can be applied to any model or set of -models which want to make use of Django's comment system. - - -Overview -======== - -The entire system is contained within ``django.contrib.comments.moderation``, -and uses a two-step process to enable moderation for any given model: - -1. A subclass of :class:`CommentModerator` - is defined which specifies the moderation options the model wants to - enable. - -2. The model is registered with the moderation system, passing in the - model class and the class which specifies its moderation options. - -A simple example is the best illustration of this. Suppose we have the -following model, which would represent entries in a Weblog:: - - from django.db import models - - class Entry(models.Model): - title = models.CharField(maxlength=250) - body = models.TextField() - pub_date = models.DateTimeField() - enable_comments = models.BooleanField() - -Now, suppose that we want the following steps to be applied whenever a -new comment is posted on an ``Entry``: - -1. If the ``Entry``'s ``enable_comments`` field is ``False``, the - comment will simply be disallowed (i.e., immediately deleted). - -2. If the ``enable_comments`` field is ``True``, the comment will be - allowed to save. - -3. Once the comment is saved, an email should be sent to site staff - notifying them of the new comment. - -Accomplishing this is fairly straightforward and requires very little -code:: - - from django.contrib.comments.moderation import CommentModerator, moderator - - class EntryModerator(CommentModerator): - email_notification = True - enable_field = 'enable_comments' - - moderator.register(Entry, EntryModerator) - -The :class:`CommentModerator` class pre-defines a number of useful moderation -options which subclasses can enable or disable as desired, and ``moderator`` -knows how to work with them to determine whether to allow a comment, whether -to moderate a comment which will be allowed to post, and whether to email -notifications of new comments. - -Built-in moderation options ---------------------------- - -.. class:: CommentModerator - - Most common comment-moderation needs can be handled by subclassing - :class:`CommentModerator` and - changing the values of pre-defined attributes; the full range of built-in - options is as follows. - - .. attribute:: auto_close_field - - If this is set to the name of a - :class:`~django.db.models.fields.DateField` or - :class:`~django.db.models.fields.DateTimeField` on the model for which - comments are being moderated, new comments for objects of that model - will be disallowed (immediately deleted) when a certain number of days - have passed after the date specified in that field. Must be - used in conjunction with :attr:`close_after`, which specifies the - number of days past which comments should be - disallowed. Default value is ``None``. - - .. attribute:: auto_moderate_field - - Like :attr:`auto_close_field`, but instead of outright deleting - new comments when the requisite number of days have elapsed, - it will simply set the ``is_public`` field of new comments to - ``False`` before saving them. Must be used in conjunction with - :attr:`moderate_after`, which specifies the number of days past - which comments should be moderated. Default value is ``None``. - - .. attribute:: close_after - - If :attr:`auto_close_field` is used, this must specify the number - of days past the value of the field specified by - :attr:`auto_close_field` after which new comments for an object - should be disallowed. Default value is ``None``. - - .. attribute:: email_notification - - If ``True``, any new comment on an object of this model which - survives moderation (i.e., is not deleted) will generate an - email to site staff. Default value is ``False``. - - .. attribute:: enable_field - - If this is set to the name of a - :class:`~django.db.models.fields.BooleanField` on the model - for which comments are being moderated, new comments on - objects of that model will be disallowed (immediately deleted) - whenever the value of that field is ``False`` on the object - the comment would be attached to. Default value is ``None``. - - .. attribute:: moderate_after - - If :attr:`auto_moderate_field` is used, this must specify the number - of days past the value of the field specified by - :attr:`auto_moderate_field` after which new comments for an object - should be marked non-public. Default value is ``None``. - -Simply subclassing :class:`CommentModerator` and changing the values of these -options will automatically enable the various moderation methods for any -models registered using the subclass. - -Adding custom moderation methods --------------------------------- - -For situations where the built-in options listed above are not -sufficient, subclasses of :class:`CommentModerator` can also override -the methods which actually perform the moderation, and apply any logic -they desire. :class:`CommentModerator` defines three methods which -determine how moderation will take place; each method will be called -by the moderation system and passed two arguments: ``comment``, which -is the new comment being posted, ``content_object``, which is the -object the comment will be attached to, and ``request``, which is the -:class:`~django.http.HttpRequest` in which the comment is being submitted: - -.. method:: CommentModerator.allow(comment, content_object, request) - - Should return ``True`` if the comment should be allowed to - post on the content object, and ``False`` otherwise (in which - case the comment will be immediately deleted). - -.. method:: CommentModerator.email(comment, content_object, request) - - If email notification of the new comment should be sent to - site staff or moderators, this method is responsible for - sending the email. - -.. method:: CommentModerator.moderate(comment, content_object, request) - - Should return ``True`` if the comment should be moderated (in - which case its ``is_public`` field will be set to ``False`` - before saving), and ``False`` otherwise (in which case the - ``is_public`` field will not be changed). - - -Registering models for moderation ---------------------------------- - -The moderation system, represented by -``django.contrib.comments.moderation.moderator`` is an instance of the class -:class:`Moderator`, which allows registration and "unregistration" of models -via two methods: - -.. function:: moderator.register(model_or_iterable, moderation_class) - - Takes two arguments: the first should be either a model class - or list of model classes, and the second should be a subclass - of ``CommentModerator``, and register the model or models to - be moderated using the options defined in the - ``CommentModerator`` subclass. If any of the models are - already registered for moderation, the exception - :exc:`AlreadyModerated` will be raised. - -.. function:: moderator.unregister(model_or_iterable) - - Takes one argument: a model class or list of model classes, - and removes the model or models from the set of models which - are being moderated. If any of the models are not currently - being moderated, the exception - :exc:`NotModerated` will be raised. - - -Customizing the moderation system ---------------------------------- - -Most use cases will work easily with simple subclassing of -:class:`CommentModerator` and registration with the provided -:class:`Moderator` instance, but customization of global moderation behavior -can be achieved by subclassing :class:`Moderator` and instead registering -models with an instance of the subclass. - -.. class:: Moderator - - In addition to the :meth:`Moderator.register` and - :meth:`Moderator.unregister` methods detailed above, the following methods - on :class:`Moderator` can be overridden to achieve customized behavior: - - .. method:: connect - - Determines how moderation is set up globally. The base - implementation in - :class:`Moderator` does this by - attaching listeners to the :data:`~django.contrib.comments.signals.comment_will_be_posted` - and :data:`~django.contrib.comments.signals.comment_was_posted` signals from the - comment models. - - .. method:: pre_save_moderation(sender, comment, request, **kwargs) - - In the base implementation, applies all pre-save moderation - steps (such as determining whether the comment needs to be - deleted, or whether it needs to be marked as non-public or - generate an email). - - .. method:: post_save_moderation(sender, comment, request, **kwargs) - - In the base implementation, applies all post-save moderation - steps (currently this consists entirely of deleting comments - which were disallowed). diff --git a/parts/django/docs/ref/contrib/comments/settings.txt b/parts/django/docs/ref/contrib/comments/settings.txt deleted file mode 100644 index 1f1aeca..0000000 --- a/parts/django/docs/ref/contrib/comments/settings.txt +++ /dev/null @@ -1,33 +0,0 @@ -================ -Comment settings -================ - -These settings configure the behavior of the comments framework: - -.. setting:: COMMENTS_HIDE_REMOVED - -COMMENTS_HIDE_REMOVED ---------------------- - -If ``True`` (default), removed comments will be excluded from comment -lists/counts (as taken from template tags). Otherwise, the template author is -responsible for some sort of a "this comment has been removed by the site staff" -message. - -.. setting:: COMMENT_MAX_LENGTH - -COMMENT_MAX_LENGTH ------------------- - -The maximum length of the comment field, in characters. Comments longer than -this will be rejected. Defaults to 3000. - -.. setting:: COMMENTS_APP - -COMMENTS_APP ------------- - -An app which provides :doc:`customization of the comments framework -</ref/contrib/comments/custom>`. Use the same dotted-string notation -as in :setting:`INSTALLED_APPS`. Your custom :setting:`COMMENTS_APP` -must also be listed in :setting:`INSTALLED_APPS`. diff --git a/parts/django/docs/ref/contrib/comments/signals.txt b/parts/django/docs/ref/contrib/comments/signals.txt deleted file mode 100644 index 7ae34a1..0000000 --- a/parts/django/docs/ref/contrib/comments/signals.txt +++ /dev/null @@ -1,91 +0,0 @@ -================================ -Signals sent by the comments app -================================ - -.. module:: django.contrib.comments.signals - :synopsis: Signals sent by the comment module. - -The comment app sends a series of :doc:`signals </topics/signals>` to allow for -comment moderation and similar activities. See :doc:`the introduction to signals -</topics/signals>` for information about how to register for and receive these -signals. - -comment_will_be_posted -====================== - -.. data:: django.contrib.comments.signals.comment_will_be_posted - :module: - -Sent just before a comment will be saved, after it's been sanity checked and -submitted. This can be used to modify the comment (in place) with posting -details or other such actions. - -If any receiver returns ``False`` the comment will be discarded and a 403 (not -allowed) response will be returned. - -This signal is sent at more or less the same time (just before, actually) as the -``Comment`` object's :data:`~django.db.models.signals.pre_save` signal. - -Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance about to be posted. Note that it won't have been - saved into the database yet, so it won't have a primary key, and any - relations might not work correctly yet. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. - -comment_was_posted -================== - -.. data:: django.contrib.comments.signals.comment_was_posted - :module: - -Sent just after the comment is saved. - -Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance that was posted. Note that it will have already - been saved, so if you modify it you'll need to call - :meth:`~django.db.models.Model.save` again. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. - -comment_was_flagged -=================== - -.. data:: django.contrib.comments.signals.comment_was_flagged - :module: - -Sent after a comment was "flagged" in some way. Check the flag to see if this -was a user requesting removal of a comment, a moderator approving/removing a -comment, or some other custom user flag. - -Arguments sent with this signal: - - ``sender`` - The comment model. - - ``comment`` - The comment instance that was posted. Note that it will have already - been saved, so if you modify it you'll need to call - :meth:`~django.db.models.Model.save` again. - - ``flag`` - The :class:`~django.contrib.comments.models.CommentFlag` that's been - attached to the comment. - - ``created`` - ``True`` if this is a new flag; ``False`` if it's a duplicate flag. - - ``request`` - The :class:`~django.http.HttpRequest` that posted the comment. diff --git a/parts/django/docs/ref/contrib/comments/upgrade.txt b/parts/django/docs/ref/contrib/comments/upgrade.txt deleted file mode 100644 index 3d6b5af..0000000 --- a/parts/django/docs/ref/contrib/comments/upgrade.txt +++ /dev/null @@ -1,78 +0,0 @@ -=============================================== -Upgrading from Django's previous comment system -=============================================== - -Prior versions of Django included an outdated, undocumented comment system. Users who reverse-engineered this framework will need to upgrade to use the -new comment system; this guide explains how. - -The main changes from the old system are: - - * This new system is documented. - - * It uses modern Django features like :doc:`forms </topics/forms/index>` and - :doc:`modelforms </topics/forms/modelforms>`. - - * It has a single ``Comment`` model instead of separate ``FreeComment`` and - ``Comment`` models. - - * Comments have "email" and "URL" fields. - - * No ratings, photos and karma. This should only effect World Online. - - * The ``{% comment_form %}`` tag no longer exists. Instead, there's now two - functions: ``{% get_comment_form %}``, which returns a form for posting a - new comment, and ``{% render_comment_form %}``, which renders said form - using the ``comments/form.html`` template. - - * The way comments are include in your URLconf have changed; you'll need to - replace:: - - (r'^comments/', include('django.contrib.comments.urls.comments')), - - with:: - - (r'^comments/', include('django.contrib.comments.urls')), - -Upgrading data --------------- - -The data models for Django's comment system have changed, as have the -table names. Before you transfer your existing data into the new comments -system, make sure that you have installed the new comments system as -explained in the -:doc:`quick start guide </ref/contrib/comments/index>`. -This will ensure that the new tables have been properly created. - -To transfer your data into the new comments system, you'll need to directly -run the following SQL: - -.. code-block:: sql - - BEGIN; - - INSERT INTO django_comments - (content_type_id, object_pk, site_id, user_name, user_email, user_url, - comment, submit_date, ip_address, is_public, is_removed) - SELECT - content_type_id, object_id, site_id, person_name, '', '', comment, - submit_date, ip_address, is_public, not approved - FROM comments_freecomment; - - INSERT INTO django_comments - (content_type_id, object_pk, site_id, user_id, user_name, user_email, - user_url, comment, submit_date, ip_address, is_public, is_removed) - SELECT - content_type_id, object_id, site_id, user_id, '', '', '', comment, - submit_date, ip_address, is_public, is_removed - FROM comments_comment; - - UPDATE django_comments SET user_name = ( - SELECT username FROM auth_user - WHERE django_comments.user_id = auth_user.id - ) WHERE django_comments.user_id is not NULL; - UPDATE django_comments SET user_email = ( - SELECT email FROM auth_user - WHERE django_comments.user_id = auth_user.id - ) WHERE django_comments.user_id is not NULL; - - COMMIT; diff --git a/parts/django/docs/ref/contrib/contenttypes.txt b/parts/django/docs/ref/contrib/contenttypes.txt deleted file mode 100644 index b695651..0000000 --- a/parts/django/docs/ref/contrib/contenttypes.txt +++ /dev/null @@ -1,385 +0,0 @@ -========================== -The contenttypes framework -========================== - -.. module:: django.contrib.contenttypes - :synopsis: Provides generic interface to installed models. - -Django includes a :mod:`contenttypes` application that can track all of -the models installed in your Django-powered project, providing a -high-level, generic interface for working with your models. - -Overview -======== - -At the heart of the contenttypes application is the -:class:`~django.contrib.contenttypes.models.ContentType` model, which lives at -``django.contrib.contenttypes.models.ContentType``. Instances of -:class:`~django.contrib.contenttypes.models.ContentType` represent and store -information about the models installed in your project, and new instances of -:class:`~django.contrib.contenttypes.models.ContentType` are automatically -created whenever new models are installed. - -Instances of :class:`~django.contrib.contenttypes.models.ContentType` have -methods for returning the model classes they represent and for querying objects -from those models. :class:`~django.contrib.contenttypes.models.ContentType` -also has a :ref:`custom manager <custom-managers>` that adds methods for -working with :class:`~django.contrib.contenttypes.models.ContentType` and for -obtaining instances of :class:`~django.contrib.contenttypes.models.ContentType` -for a particular model. - -Relations between your models and -:class:`~django.contrib.contenttypes.models.ContentType` can also be used to -enable "generic" relationships between an instance of one of your -models and instances of any model you have installed. - -Installing the contenttypes framework -===================================== - -The contenttypes framework is included in the default -:setting:`INSTALLED_APPS` list created by ``django-admin.py startproject``, -but if you've removed it or if you manually set up your -:setting:`INSTALLED_APPS` list, you can enable it by adding -``'django.contrib.contenttypes'`` to your :setting:`INSTALLED_APPS` setting. - -It's generally a good idea to have the contenttypes framework -installed; several of Django's other bundled applications require it: - - * The admin application uses it to log the history of each object - added or changed through the admin interface. - - * Django's :mod:`authentication framework <django.contrib.auth>` uses it - to tie user permissions to specific models. - - * Django's comments system (:mod:`django.contrib.comments`) uses it to - "attach" comments to any installed model. - -The ``ContentType`` model -========================= - -.. class:: models.ContentType - - Each instance of :class:`~django.contrib.contenttypes.models.ContentType` - has three fields which, taken together, uniquely describe an installed model: - - .. attribute:: models.ContentType.app_label - - The name of the application the model is part of. This is taken from - the :attr:`app_label` attribute of the model, and includes only the *last* - part of the application's Python import path; - "django.contrib.contenttypes", for example, becomes an :attr:`app_label` - of "contenttypes". - - .. attribute:: models.ContentType.model - - The name of the model class. - - .. attribute:: models.ContentType.name - - The human-readable name of the model. This is taken from the - :attr:`verbose_name <django.db.models.fields.Field.verbose_name>` - attribute of the model. - -Let's look at an example to see how this works. If you already have -the contenttypes application installed, and then add -:mod:`the sites application <django.contrib.sites>` to your -:setting:`INSTALLED_APPS` setting and run ``manage.py syncdb`` to install it, -the model :class:`django.contrib.sites.models.Site` will be installed into -your database. Along with it a new instance of -:class:`~django.contrib.contenttypes.models.ContentType` will be -created with the following values: - - * :attr:`app_label` will be set to ``'sites'`` (the last part of the Python - path "django.contrib.sites"). - - * :attr:`model` will be set to ``'site'``. - - * :attr:`name` will be set to ``'site'``. - -.. _the verbose_name attribute: ../model-api/#verbose_name - -Methods on ``ContentType`` instances -==================================== - -.. class:: models.ContentType - - Each :class:`~django.contrib.contenttypes.models.ContentType` instance has - methods that allow you to get from a - :class:`~django.contrib.contenttypes.models.ContentType` instance to the model - it represents, or to retrieve objects from that model: - -.. method:: models.ContentType.get_object_for_this_type(**kwargs) - - Takes a set of valid :ref:`lookup arguments <field-lookups-intro>` for the - model the :class:`~django.contrib.contenttypes.models.ContentType` - represents, and does :lookup:`a get() lookup <get>` on that model, - returning the corresponding object. - -.. method:: models.ContentType.model_class() - - Returns the model class represented by this - :class:`~django.contrib.contenttypes.models.ContentType` instance. - -For example, we could look up the -:class:`~django.contrib.contenttypes.models.ContentType` for the -:class:`~django.contrib.auth.models.User` model:: - - >>> from django.contrib.contenttypes.models import ContentType - >>> user_type = ContentType.objects.get(app_label="auth", model="user") - >>> user_type - <ContentType: user> - -And then use it to query for a particular ``User``, or to get access -to the ``User`` model class:: - - >>> user_type.model_class() - <class 'django.contrib.auth.models.User'> - >>> user_type.get_object_for_this_type(username='Guido') - <User: Guido> - -Together, -:meth:`~django.contrib.contenttypes.models.ContentType.get_object_for_this_type` -and :meth:`~django.contrib.contenttypes.models.ContentType.model_class` -enable two extremely important use cases: - - 1. Using these methods, you can write high-level generic code that - performs queries on any installed model -- instead of importing and using - a single specific model class, you can pass an ``app_label`` and - ``model`` into a :class:`~django.contrib.contenttypes.models.ContentType` - lookup at runtime, and then work with the model class or retrieve objects - from it. - - 2. You can relate another model to - :class:`~django.contrib.contenttypes.models.ContentType` as a way of - tying instances of it to particular model classes, and use these methods - to get access to those model classes. - -Several of Django's bundled applications make use of the latter technique. -For example, -:class:`the permissions system <django.contrib.auth.models.Permission` in -Django's authentication framework uses a -:class:`~django.contrib.auth.models.Permission` model with a foreign -key to :class:`~django.contrib.contenttypes.models.ContentType`; this lets -:class:`~django.contrib.auth.models.Permission` represent concepts like -"can add blog entry" or "can delete news story". - -The ``ContentTypeManager`` --------------------------- - -.. class:: models.ContentTypeManager - - :class:`~django.contrib.contenttypes.models.ContentType` also has a custom - manager, :class:`~django.contrib.contenttypes.models.ContentTypeManager`, - which adds the following methods: - - .. method:: models.ContentTypeManager.clear_cache() - - Clears an internal cache used by - :class:`~django.contrib.contenttypes.models.ContentType` to keep track - of which models for which it has created - :class:`django.contrib.contenttypes.models.ContentType` instances. You - probably won't ever need to call this method yourself; Django will call - it automatically when it's needed. - - .. method:: models.ContentTypeManager.get_for_model(model) - - Takes either a model class or an instance of a model, and returns the - :class:`~django.contrib.contenttypes.models.ContentType` instance - representing that model. - -The :meth:`~models.ContentTypeManager.get_for_model()` method is especially useful when you know you -need to work with a :class:`ContentType <django.contrib.contenttypes.models.ContentType>` but don't want to go to the -trouble of obtaining the model's metadata to perform a manual lookup:: - - >>> from django.contrib.auth.models import User - >>> user_type = ContentType.objects.get_for_model(User) - >>> user_type - <ContentType: user> - -.. _generic-relations: - -Generic relations -================= - -Adding a foreign key from one of your own models to -:class:`~django.contrib.contenttypes.models.ContentType` allows your model to -effectively tie itself to another model class, as in the example of the -:class:`~django.contrib.auth.models.Permission` model above. But it's possible -to go one step further and use -:class:`~django.contrib.contenttypes.models.ContentType` to enable truly -generic (sometimes called "polymorphic") relationships between models. - -A simple example is a tagging system, which might look like this:: - - from django.db import models - from django.contrib.contenttypes.models import ContentType - from django.contrib.contenttypes import generic - - class TaggedItem(models.Model): - tag = models.SlugField() - content_type = models.ForeignKey(ContentType) - object_id = models.PositiveIntegerField() - content_object = generic.GenericForeignKey('content_type', 'object_id') - - def __unicode__(self): - return self.tag - -A normal :class:`~django.db.models.fields.related.ForeignKey` can only "point -to" one other model, which means that if the ``TaggedItem`` model used a -:class:`~django.db.models.fields.related.ForeignKey` it would have to -choose one and only one model to store tags for. The contenttypes -application provides a special field type -- -:class:`django.contrib.contenttypes.generic.GenericForeignKey` -- which -works around this and allows the relationship to be with any -model. There are three parts to setting up a -:class:`~django.contrib.contenttypes.generic.GenericForeignKey`: - - 1. Give your model a :class:`~django.db.models.fields.related.ForeignKey` - to :class:`~django.contrib.contenttypes.models.ContentType`. - - 2. Give your model a field that can store a primary-key value from the - models you'll be relating to. (For most models, this means an - :class:`~django.db.models.fields.IntegerField` or - :class:`~django.db.models.fields.PositiveIntegerField`.) - - This field must be of the same type as the primary key of the models - that will be involved in the generic relation. For example, if you use - :class:`~django.db.models.fields.IntegerField`, you won't be able to - form a generic relation with a model that uses a - :class:`~django.db.models.fields.CharField` as a primary key. - - 3. Give your model a - :class:`~django.contrib.contenttypes.generic.GenericForeignKey`, and - pass it the names of the two fields described above. If these fields - are named "content_type" and "object_id", you can omit this -- those - are the default field names - :class:`~django.contrib.contenttypes.generic.GenericForeignKey` will - look for. - -This will enable an API similar to the one used for a normal -:class:`~django.db.models.fields.related.ForeignKey`; -each ``TaggedItem`` will have a ``content_object`` field that returns the -object it's related to, and you can also assign to that field or use it when -creating a ``TaggedItem``:: - - >>> from django.contrib.auth.models import User - >>> guido = User.objects.get(username='Guido') - >>> t = TaggedItem(content_object=guido, tag='bdfl') - >>> t.save() - >>> t.content_object - <User: Guido> - -Due to the way :class:`~django.contrib.contenttypes.generic.GenericForeignKey` -is implemented, you cannot use such fields directly with filters (``filter()`` -and ``exclude()``, for example) via the database API. They aren't normal field -objects. These examples will *not* work:: - - # This will fail - >>> TaggedItem.objects.filter(content_object=guido) - # This will also fail - >>> TaggedItem.objects.get(content_object=guido) - -Reverse generic relations -------------------------- - -If you know which models you'll be using most often, you can also add -a "reverse" generic relationship to enable an additional API. For example:: - - class Bookmark(models.Model): - url = models.URLField() - tags = generic.GenericRelation(TaggedItem) - -``Bookmark`` instances will each have a ``tags`` attribute, which can -be used to retrieve their associated ``TaggedItems``:: - - >>> b = Bookmark(url='http://www.djangoproject.com/') - >>> b.save() - >>> t1 = TaggedItem(content_object=b, tag='django') - >>> t1.save() - >>> t2 = TaggedItem(content_object=b, tag='python') - >>> t2.save() - >>> b.tags.all() - [<TaggedItem: django>, <TaggedItem: python>] - -Just as :class:`django.contrib.contenttypes.generic.GenericForeignKey` -accepts the names of the content-type and object-ID fields as -arguments, so too does ``GenericRelation``; if the model which has the -generic foreign key is using non-default names for those fields, you -must pass the names of the fields when setting up a -``GenericRelation`` to it. For example, if the ``TaggedItem`` model -referred to above used fields named ``content_type_fk`` and -``object_primary_key`` to create its generic foreign key, then a -``GenericRelation`` back to it would need to be defined like so:: - - tags = generic.GenericRelation(TaggedItem, content_type_field='content_type_fk', object_id_field='object_primary_key') - -Of course, if you don't add the reverse relationship, you can do the -same types of lookups manually:: - - >>> b = Bookmark.objects.get(url='http://www.djangoproject.com/') - >>> bookmark_type = ContentType.objects.get_for_model(b) - >>> TaggedItem.objects.filter(content_type__pk=bookmark_type.id, - ... object_id=b.id) - [<TaggedItem: django>, <TaggedItem: python>] - -Note that if the model in a -:class:`~django.contrib.contenttypes.generic.GenericRelation` uses a -non-default value for ``ct_field`` or ``fk_field`` in its -:class:`~django.contrib.contenttypes.generic.GenericForeignKey` (e.g. the -:mod:`django.contrib.comments` app uses ``ct_field="object_pk"``), -you'll need to set ``content_type_field`` and/or ``object_id_field`` in -the :class:`~django.contrib.contenttypes.generic.GenericRelation` to -match the ``ct_field`` and ``fk_field``, respectively, in the -:class:`~django.contrib.contenttypes.generic.GenericForeignKey`:: - - comments = generic.GenericRelation(Comment, object_id_field="object_pk") - -Note also, that if you delete an object that has a -:class:`~django.contrib.contenttypes.generic.GenericRelation`, any objects -which have a :class:`~django.contrib.contenttypes.generic.GenericForeignKey` -pointing at it will be deleted as well. In the example above, this means that -if a ``Bookmark`` object were deleted, any ``TaggedItem`` objects pointing at -it would be deleted at the same time. - -Generic relations and aggregation ---------------------------------- - -:doc:`Django's database aggregation API </topics/db/aggregation>` -doesn't work with a -:class:`~django.contrib.contenttypes.generic.GenericRelation`. For example, you -might be tempted to try something like:: - - Bookmark.objects.aggregate(Count('tags')) - -This will not work correctly, however. The generic relation adds extra filters -to the queryset to ensure the correct content type, but the ``aggregate`` method -doesn't take them into account. For now, if you need aggregates on generic -relations, you'll need to calculate them without using the aggregation API. - -Generic relations in forms and admin ------------------------------------- - -:mod:`django.contrib.contenttypes.generic` provides both a -:class:`~django.contrib.contenttypes.generic.GenericInlineFormSet` -and :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin`. -This enables the use of generic relations in forms and the admin. See the -:doc:`model formset </topics/forms/modelforms>` and -:doc:`admin </ref/contrib/admin/index>` documentation for more information. - -.. class:: generic.GenericInlineModelAdmin - - The :class:`~django.contrib.contenttypes.generic.GenericInlineModelAdmin` - class inherits all properties from an - :class:`~django.contrib.admin.InlineModelAdmin` class. However, - it adds a couple of its own for working with the generic relation: - - .. attribute:: generic.GenericInlineModelAdmin.ct_field - - The name of the - :class:`~django.contrib.contenttypes.models.ContentType` foreign key - field on the model. Defaults to ``content_type``. - - .. attribute:: generic.GenericInlineModelAdmin.ct_fk_field - - The name of the integer field that represents the ID of the related - object. Defaults to ``object_id``. diff --git a/parts/django/docs/ref/contrib/csrf.txt b/parts/django/docs/ref/contrib/csrf.txt deleted file mode 100644 index c32dd73..0000000 --- a/parts/django/docs/ref/contrib/csrf.txt +++ /dev/null @@ -1,433 +0,0 @@ -===================================== -Cross Site Request Forgery protection -===================================== - -.. module:: django.middleware.csrf - :synopsis: Protects against Cross Site Request Forgeries - -The CSRF middleware and template tag provides easy-to-use protection against -`Cross Site Request Forgeries`_. This type of attack occurs when a malicious -Web site contains a link, a form button or some javascript that is intended to -perform some action on your Web site, using the credentials of a logged-in user -who visits the malicious site in their browser. A related type of attack, -'login CSRF', where an attacking site tricks a user's browser into logging into -a site with someone else's credentials, is also covered. - -The first defense against CSRF attacks is to ensure that GET requests are -side-effect free. POST requests can then be protected by following the steps -below. - -.. versionadded:: 1.2 - The 'contrib' apps, including the admin, use the functionality described - here. Because it is security related, a few things have been added to core - functionality to allow this to happen without any required upgrade steps. - -.. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF - -How to use it -============= - -.. versionchanged:: 1.2 - The template tag functionality (the recommended way to use this) was added - in version 1.2. The previous method (still available) is described under - `Legacy method`_. - -To enable CSRF protection for your views, follow these steps: - - 1. Add the middleware - ``'django.middleware.csrf.CsrfViewMiddleware'`` to your list of - middleware classes, :setting:`MIDDLEWARE_CLASSES`. (It should come - before ``CsrfResponseMiddleware`` if that is being used, and before any - view middleware that assume that CSRF attacks have been dealt with.) - - Alternatively, you can use the decorator - ``django.views.decorators.csrf.csrf_protect`` on particular views you - want to protect (see below). - - 2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside - the ``<form>`` element if the form is for an internal URL, e.g.:: - - <form action="" method="post">{% csrf_token %} - - This should not be done for POST forms that target external URLs, since - that would cause the CSRF token to be leaked, leading to a vulnerability. - - 3. In the corresponding view functions, ensure that the - ``'django.core.context_processors.csrf'`` context processor is - being used. Usually, this can be done in one of two ways: - - 1. Use RequestContext, which always uses - ``'django.core.context_processors.csrf'`` (no matter what your - TEMPLATE_CONTEXT_PROCESSORS setting). If you are using - generic views or contrib apps, you are covered already, since these - apps use RequestContext throughout. - - 2. Manually import and use the processor to generate the CSRF token and - add it to the template context. e.g.:: - - from django.core.context_processors import csrf - from django.shortcuts import render_to_response - - def my_view(request): - c = {} - c.update(csrf(request)) - # ... view code here - return render_to_response("a_template.html", c) - - You may want to write your own ``render_to_response`` wrapper that - takes care of this step for you. - -The utility script ``extras/csrf_migration_helper.py`` can help to automate the -finding of code and templates that may need to be upgraded. It contains full -help on how to use it. - -The decorator method --------------------- - -Rather than adding ``CsrfViewMiddleware`` as a blanket protection, you can use -the ``csrf_protect`` decorator, which has exactly the same functionality, on -particular views that need the protection. It must be used **both** on views -that insert the CSRF token in the output, and on those that accept the POST form -data. (These are often the same view function, but not always). It is used like -this:: - - from django.views.decorators.csrf import csrf_protect - from django.template import RequestContext - - @csrf_protect - def my_view(request): - c = {} - # ... - return render_to_response("a_template.html", c, - context_instance=RequestContext(request)) - -Use of the decorator is **not recommended** by itself, since if you forget to -use it, you will have a security hole. The 'belt and braces' strategy of using -both is fine, and will incur minimal overhead. - -Legacy method -------------- - -In Django 1.1, the template tag did not exist. Instead, a post-processing -middleware that re-wrote POST forms to include the CSRF token was used. If you -are upgrading a site from version 1.1 or earlier, please read this section and -the `Upgrading notes`_ below. The post-processing middleware is still available -as ``CsrfResponseMiddleware``, and it can be used by following these steps: - - 1. Follow step 1 above to install ``CsrfViewMiddleware``. - - 2. Add ``'django.middleware.csrf.CsrfResponseMiddleware'`` to your - :setting:`MIDDLEWARE_CLASSES` setting. - - ``CsrfResponseMiddleware`` needs to process the response before things - like compression or setting ofETags happen to the response, so it must - come after ``GZipMiddleware``, ``CommonMiddleware`` and - ``ConditionalGetMiddleware`` in the list. It also must come after - ``CsrfViewMiddleware``. - -Use of the ``CsrfResponseMiddleware`` is not recommended because of the -performance hit it imposes, and because of a potential security problem (see -below). It can be used as an interim measure until applications have been -updated to use the :ttag:`csrf_token` tag. It is deprecated and will be -removed in Django 1.4. - -Django 1.1 and earlier provided a single ``CsrfMiddleware`` class. This is also -still available for backwards compatibility. It combines the functions of the -two middleware. - -Note also that previous versions of these classes depended on the sessions -framework, but this dependency has now been removed, with backward compatibility -support so that upgrading will not produce any issues. - -Security of legacy method -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The post-processing ``CsrfResponseMiddleware`` adds the CSRF token to all POST -forms (unless the view has been decorated with ``csrf_response_exempt``). If -the POST form has an external untrusted site as its target, rather than an -internal page, that site will be sent the CSRF token when the form is submitted. -Armed with this leaked information, that site will then be able to successfully -launch a CSRF attack on your site against that user. The -``@csrf_response_exempt`` decorator can be used to fix this, but only if the -page doesn't also contain internal forms that require the token. - -.. _ref-csrf-upgrading-notes: - -Upgrading notes ---------------- - -When upgrading to version 1.2 or later, you may have applications that rely on -the old post-processing functionality for CSRF protection, or you may not have -enabled any CSRF protection. This section outlines the steps necessary for a -smooth upgrade, without having to fix all the applications to use the new -template tag method immediately. - -First of all, the location of the middleware and related functions have -changed. There are backwards compatible stub files so that old imports will -continue to work for now, but they are deprecated and will be removed in Django -1.4. The following changes have been made: - - * Middleware have been moved to ``django.middleware.csrf`` - * Decorators have been moved to ``django.views.decorators.csrf`` - -====================================================== ============================================== - Old New -====================================================== ============================================== -django.contrib.csrf.middleware.CsrfMiddleware django.middleware.csrf.CsrfMiddleware -django.contrib.csrf.middleware.CsrfViewMiddleware django.middleware.csrf.CsrfViewMiddleware -django.contrib.csrf.middleware.CsrfResponseMiddleware django.middleware.csrf.CsrfResponseMiddleware -django.contrib.csrf.middleware.csrf_exempt django.views.decorators.csrf.csrf_exempt -django.contrib.csrf.middleware.csrf_view_exempt django.views.decorators.csrf.csrf_view_exempt -django.contrib.csrf.middleware.csrf_response_exempt django.views.decorators.csrf.csrf_response_exempt -====================================================== ============================================== - -You should update any imports, and also the paths in your -:setting:`MIDDLEWARE_CLASSES`. - -If you have ``CsrfMiddleware`` in your :setting:`MIDDLEWARE_CLASSES`, you will now -have a working installation with CSRF protection. It is recommended at this -point that you replace ``CsrfMiddleware`` with its two components, -``CsrfViewMiddleware`` and ``CsrfResponseMiddleware`` (in that order). - -If you do not have any of the middleware in your :setting:`MIDDLEWARE_CLASSES`, -you will have a working installation but without any CSRF protection for your -views (just as you had before). It is strongly recommended to install -``CsrfViewMiddleware`` and ``CsrfResponseMiddleware``, as described above. - -Note that contrib apps, such as the admin, have been updated to use the -``csrf_protect`` decorator, so that they are secured even if you do not add the -``CsrfViewMiddleware`` to your settings. However, if you have supplied -customised templates to any of the view functions of contrib apps (whether -explicitly via a keyword argument, or by overriding built-in templates), **you -MUST update them** to include the :ttag:`csrf_token` template tag as described -above, or they will stop working. (If you cannot update these templates for -some reason, you will be forced to use ``CsrfResponseMiddleware`` for these -views to continue working). - -Note also, if you are using the comments app, and you are not going to add -``CsrfViewMiddleware`` to your settings (not recommended), you will need to add -the ``csrf_protect`` decorator to any views that include the comment forms and -target the comment views (usually using the :ttag:`comment_form_target` template -tag). - -Assuming you have followed the above, all views in your Django site will now be -protected by the ``CsrfViewMiddleware``. Contrib apps meet the requirements -imposed by the ``CsrfViewMiddleware`` using the template tag, and other -applications in your project will meet its requirements by virtue of the -``CsrfResponseMiddleware``. - -The next step is to update all your applications to use the template tag, as -described in `How to use it`_, steps 2-3. This can be done as soon as is -practical. Any applications that are updated will now require Django 1.1.2 or -later, since they will use the CSRF template tag which was not available in -earlier versions. (The template tag in 1.1.2 is actually a no-op that exists -solely to ease the transition to 1.2 — it allows apps to be created that have -CSRF protection under 1.2 without requiring users of the apps to upgrade to the -Django 1.2.X series). - -The utility script ``extras/csrf_migration_helper.py`` can help to automate the -finding of code and templates that may need to be upgraded. It contains full -help on how to use it. - -Finally, once all applications are upgraded, ``CsrfResponseMiddleware`` can be -removed from your settings. - -While ``CsrfResponseMiddleware`` is still in use, the ``csrf_response_exempt`` -decorator, described in `Exceptions`_, may be useful. The post-processing -middleware imposes a performance hit and a potential vulnerability, and any -views that have been upgraded to use the new template tag method no longer need -it. - -Exceptions ----------- - -.. versionadded:: 1.1 -.. versionchanged:: 1.2 - Import paths for the decorators below were changed. - -To manually exclude a view function from being handled by either of the two CSRF -middleware, you can use the ``csrf_exempt`` decorator, found in the -``django.views.decorators.csrf`` module. For example:: - - from django.views.decorators.csrf import csrf_exempt - - @csrf_exempt - def my_view(request): - return HttpResponse('Hello world') - -Like the middleware, the ``csrf_exempt`` decorator is composed of two parts: a -``csrf_view_exempt`` decorator and a ``csrf_response_exempt`` decorator, found -in the same module. These disable the view protection mechanism -(``CsrfViewMiddleware``) and the response post-processing -(``CsrfResponseMiddleware``) respectively. They can be used individually if -required. - -You don't have to worry about doing this for most AJAX views. Any request sent -with "X-Requested-With: XMLHttpRequest" is automatically exempt. (See the `How -it works`_ section.) - -Subdomains ----------- - -By default, CSRF cookies are specific to the subdomain they are set for. This -means that a form served from one subdomain (e.g. server1.example.com) will not -be able to have a target on another subdomain (e.g. server2.example.com). This -restriction can be removed by setting :setting:`CSRF_COOKIE_DOMAIN` to be -something like ``".example.com"``. - -Please note that, with or without use of this setting, this CSRF protection -mechanism is not safe against cross-subdomain attacks -- see `Limitations`_. - -Rejected requests -================= - -By default, a '403 Forbidden' response is sent to the user if an incoming -request fails the checks performed by ``CsrfViewMiddleware``. This should -usually only be seen when there is a genuine Cross Site Request Forgery, or -when, due to a programming error, the CSRF token has not been included with a -POST form. - -No logging is done, and the error message is not very friendly, so you may want -to provide your own page for handling this condition. To do this, simply set -the :setting:`CSRF_FAILURE_VIEW` setting to a dotted path to your own view -function, which should have the following signature:: - - def csrf_failure(request, reason="") - -where ``reason`` is a short message (intended for developers or logging, not for -end users) indicating the reason the request was rejected. - -How it works -============ - -The CSRF protection is based on the following things: - -1. A CSRF cookie that is set to a random value (a session independent nonce, as - it is called), which other sites will not have access to. - - This cookie is set by ``CsrfViewMiddleware``. It is meant to be permanent, - but since there is no way to set a cookie that never expires, it is sent with - every response that has called ``django.middleware.csrf.get_token()`` - (the function used internally to retrieve the CSRF token). - -2. A hidden form field with the name 'csrfmiddlewaretoken' present in all - outgoing POST forms. The value of this field is the value of the CSRF - cookie. - - This part is done by the template tag (and with the legacy method, it is done - by ``CsrfResponseMiddleware``). - -3. For all incoming POST requests, a CSRF cookie must be present, and the - 'csrfmiddlewaretoken' field must be present and correct. If it isn't, the - user will get a 403 error. - - This check is done by ``CsrfViewMiddleware``. - -4. In addition, for HTTPS requests, strict referer checking is done by - ``CsrfViewMiddleware``. This is necessary to address a Man-In-The-Middle - attack that is possible under HTTPS when using a session independent nonce, - due to the fact that HTTP 'Set-Cookie' headers are (unfortunately) accepted - by clients that are talking to a site under HTTPS. (Referer checking is not - done for HTTP requests because the presence of the Referer header is not - reliable enough under HTTP.) - -This ensures that only forms that have originated from your Web site can be used -to POST data back. - -It deliberately only targets HTTP POST requests (and the corresponding POST -forms). GET requests ought never to have any potentially dangerous side effects -(see `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_), and so a CSRF attack with a GET -request ought to be harmless. - -``CsrfResponseMiddleware`` checks the Content-Type before modifying the -response, and only pages that are served as 'text/html' or -'application/xml+xhtml' are modified. - -AJAX ----- - -The middleware tries to be smart about requests that come in via AJAX. Most -modern JavaScript toolkits send an "X-Requested-With: XMLHttpRequest" HTTP -header; these requests are detected and automatically *not* handled by this -middleware. We can do this safely because, in the context of a browser, the -header can only be added by using ``XMLHttpRequest``, and browsers already -implement a same-domain policy for ``XMLHttpRequest``. - -For the more recent browsers that relax this same-domain policy, custom headers -like "X-Requested-With" are only allowed after the browser has done a -'preflight' check to the server to see if the cross-domain request is allowed, -using a strictly 'opt in' mechanism, so the exception for AJAX is still safe—if -the developer has specifically opted in to allowing cross-site AJAX POST -requests on a specific URL, they obviously don't want the middleware to disallow -exactly that. - -.. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html - -Caching -======= - -If the :ttag:`csrf_token` template tag is used by a template (or the ``get_token`` -function is called some other way), ``CsrfViewMiddleware`` will add a cookie and -a ``Vary: Cookie`` header to the response. Similarly, -``CsrfResponseMiddleware`` will send the ``Vary: Cookie`` header if it inserted -a token. This means that these middleware will play well with the cache -middleware if it is used as instructed (``UpdateCacheMiddleware`` goes before -all other middleware). - -However, if you use cache decorators on individual views, the CSRF middleware -will not yet have been able to set the Vary header. In this case, on any views -that will require a CSRF token to be inserted you should use the -:func:`django.views.decorators.vary.vary_on_cookie` decorator first:: - - from django.views.decorators.cache import cache_page - from django.views.decorators.vary import vary_on_cookie - - @cache_page(60 * 15) - @vary_on_cookie - def my_view(request): - # ... - - -Testing -======= - -The ``CsrfViewMiddleware`` will usually be a big hindrance to testing view -functions, due to the need for the CSRF token which must be sent with every POST -request. For this reason, Django's HTTP client for tests has been modified to -set a flag on requests which relaxes the middleware and the ``csrf_protect`` -decorator so that they no longer rejects requests. In every other respect -(e.g. sending cookies etc.), they behave the same. - -If, for some reason, you *want* the test client to perform CSRF -checks, you can create an instance of the test client that enforces -CSRF checks:: - - >>> from django.test import Client - >>> csrf_client = Client(enforce_csrf_checks=True) - -Limitations -=========== - -Subdomains within a site will be able to set cookies on the client for the whole -domain. By setting the cookie and using a corresponding token, subdomains will -be able to circumvent the CSRF protection. The only way to avoid this is to -ensure that subdomains are controlled by trusted users (or, are at least unable -to set cookies). Note that even without CSRF, there are other vulnerabilities, -such as session fixation, that make giving subdomains to untrusted parties a bad -idea, and these vulnerabilities cannot easily be fixed with current browsers. - -If you are using ``CsrfResponseMiddleware`` and your app creates HTML pages and -forms in some unusual way, (e.g. it sends fragments of HTML in JavaScript -document.write statements) you might bypass the filter that adds the hidden -field to the form, in which case form submission will always fail. You should -use the template tag or :meth:`django.middleware.csrf.get_token` to get -the CSRF token and ensure it is included when your form is submitted. - -Contrib and reusable apps -========================= - -Because it is possible for the developer to turn off the ``CsrfViewMiddleware``, -all relevant views in contrib apps use the ``csrf_protect`` decorator to ensure -the security of these applications against CSRF. It is recommended that the -developers of other reusable apps that want the same guarantees also use the -``csrf_protect`` decorator on their views. diff --git a/parts/django/docs/ref/contrib/databrowse.txt b/parts/django/docs/ref/contrib/databrowse.txt deleted file mode 100644 index 33c8228..0000000 --- a/parts/django/docs/ref/contrib/databrowse.txt +++ /dev/null @@ -1,90 +0,0 @@ -========== -Databrowse -========== - -.. module:: django.contrib.databrowse - :synopsis: Databrowse is a Django application that lets you browse your data. - -Databrowse is a Django application that lets you browse your data. - -As the Django admin dynamically creates an admin interface by introspecting -your models, Databrowse dynamically creates a rich, browsable Web site by -introspecting your models. - -.. admonition:: Note - - Databrowse is **very** new and is currently under active development. It - may change substantially before the next Django release. - - With that said, it's easy to use, and it doesn't require writing any - code. So you can play around with it today, with very little investment in - time or coding. - -How to use Databrowse -===================== - - 1. Point Django at the default Databrowse templates. There are two ways to - do this: - - * Add ``'django.contrib.databrowse'`` to your :setting:`INSTALLED_APPS` - setting. This will work if your :setting:`TEMPLATE_LOADERS` setting - includes the ``app_directories`` template loader (which is the case by - default). See the :ref:`template loader docs <template-loaders>` for - more. - - * Otherwise, determine the full filesystem path to the - :file:`django/contrib/databrowse/templates` directory, and add that - directory to your :setting:`TEMPLATE_DIRS` setting. - - 2. Register a number of models with the Databrowse site:: - - from django.contrib import databrowse - from myapp.models import SomeModel, SomeOtherModel - - databrowse.site.register(SomeModel) - databrowse.site.register(SomeOtherModel) - - Note that you should register the model *classes*, not instances. - - It doesn't matter where you put this, as long as it gets executed at some - point. A good place for it is in your :doc:`URLconf file - </topics/http/urls>` (``urls.py``). - - 3. Change your URLconf to import the :mod:`~django.contrib.databrowse` module:: - - from django.contrib import databrowse - - ...and add the following line to your URLconf:: - - (r'^databrowse/(.*)', databrowse.site.root), - - The prefix doesn't matter -- you can use ``databrowse/`` or ``db/`` or - whatever you'd like. - - 4. Run the Django server and visit ``/databrowse/`` in your browser. - -Requiring user login -==================== - -You can restrict access to logged-in users with only a few extra lines of -code. Simply add the following import to your URLconf:: - - from django.contrib.auth.decorators import login_required - -Then modify the :doc:`URLconf </topics/http/urls>` so that the -:func:`databrowse.site.root` view is decorated with -:func:`django.contrib.auth.decorators.login_required`:: - - (r'^databrowse/(.*)', login_required(databrowse.site.root)), - -If you haven't already added support for user logins to your :doc:`URLconf -</topics/http/urls>`, as described in the :doc:`user authentication docs -</ref/contrib/auth>`, then you will need to do so now with the following -mapping:: - - (r'^accounts/login/$', 'django.contrib.auth.views.login'), - -The final step is to create the login form required by -:func:`django.contrib.auth.views.login`. The -:doc:`user authentication docs </ref/contrib/auth>` provide full details and a -sample template that can be used for this purpose. diff --git a/parts/django/docs/ref/contrib/flatpages.txt b/parts/django/docs/ref/contrib/flatpages.txt deleted file mode 100644 index 46b28dc..0000000 --- a/parts/django/docs/ref/contrib/flatpages.txt +++ /dev/null @@ -1,167 +0,0 @@ -================= -The flatpages app -================= - -.. module:: django.contrib.flatpages - :synopsis: A framework for managing simple ?flat? HTML content in a database. - -Django comes with an optional "flatpages" application. It lets you store simple -"flat" HTML content in a database and handles the management for you via -Django's admin interface and a Python API. - -A flatpage is a simple object with a URL, title and content. Use it for -one-off, special-case pages, such as "About" or "Privacy Policy" pages, that -you want to store in a database but for which you don't want to develop a -custom Django application. - -A flatpage can use a custom template or a default, systemwide flatpage -template. It can be associated with one, or multiple, sites. - -.. versionadded:: 1.0 - -The content field may optionally be left blank if you prefer to put your -content in a custom template. - -Here are some examples of flatpages on Django-powered sites: - - * http://www.lawrence.com/about/contact/ - * http://www2.ljworld.com/site/rules/ - -Installation -============ - -To install the flatpages app, follow these steps: - - 1. Install the :mod:`sites framework <django.contrib.sites>` by adding - ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, - if it's not already in there. - - Also make sure you've correctly set :setting:`SITE_ID` to the ID of the - site the settings file represents. This will usually be ``1`` (i.e. - ``SITE_ID = 1``, but if you're using the sites framework to manage - multiple sites, it could be the ID of a different site. - - 2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` - setting. - - 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'`` - to your :setting:`MIDDLEWARE_CLASSES` setting. - - 4. Run the command :djadmin:`manage.py syncdb <syncdb>`. - -How it works -============ - -``manage.py syncdb`` creates two tables in your database: ``django_flatpage`` -and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table -that simply maps a URL to a title and bunch of text content. -``django_flatpage_sites`` associates a flatpage with a site. - -The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` -does all of the work. Each time any Django application raises a 404 error, this -middleware checks the flatpages database for the requested URL as a last resort. -Specifically, it checks for a flatpage with the given URL with a site ID that -corresponds to the :setting:`SITE_ID` setting. - -If it finds a match, it follows this algorithm: - - * If the flatpage has a custom template, it loads that template. Otherwise, - it loads the template :file:`flatpages/default.html`. - - * It passes that template a single context variable, :data:`flatpage`, which - is the flatpage object. It uses - :class:`~django.template.context.RequestContext` in rendering the - template. - -If it doesn't find a match, the request continues to be processed as usual. - -The middleware only gets activated for 404s -- not for 500s or responses of any -other status code. - -.. admonition:: Flatpages will not apply view middleware - - Because the ``FlatpageFallbackMiddleware`` is applied only after - URL resolution has failed and produced a 404, the response it - returns will not apply any :ref:`view middleware <view-middleware>` - methods. Only requests which are successfully routed to a view via - normal URL resolution apply view middleware. - -Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you can -put :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` at -the end of the list, because it's a last resort. - -For more on middleware, read the :doc:`middleware docs -</topics/http/middleware>`. - -.. admonition:: Ensure that your 404 template works - - Note that the - :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` - only steps in once another view has successfully produced a 404 response. - If another view or middleware class attempts to produce a 404 but ends up - raising an exception instead (such as a ``TemplateDoesNotExist`` - exception if your site does not have an appropriate template to - use for HTTP 404 responses), the response will become an HTTP 500 - ("Internal Server Error") and the - :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` - will not attempt to serve a flat page. - -How to add, change and delete flatpages -======================================= - -Via the admin interface ------------------------ - -If you've activated the automatic Django admin interface, you should see a -"Flatpages" section on the admin index page. Edit flatpages as you edit any -other object in the system. - -Via the Python API ------------------- - -.. class:: models.FlatPage - - Flatpages are represented by a standard - :doc:`Django model </topics/db/models>`, - which lives in `django/contrib/flatpages/models.py`_. You can access - flatpage objects via the :doc:`Django database API </topics/db/queries>`. - -.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py - -Flatpage templates -================== - -By default, flatpages are rendered via the template -:file:`flatpages/default.html`, but you can override that for a -particular flatpage: in the admin, a collapsed fieldset titled -"Advanced options" (clicking will expand it) contains a field for -specifying a template name. If you're creating a flat page via the -Python API you can simply set the template name as the field -``template_name`` on the ``FlatPage`` object. - -Creating the :file:`flatpages/default.html` template is your responsibility; -in your template directory, just create a :file:`flatpages` directory -containing a file :file:`default.html`. - -Flatpage templates are passed a single context variable, :data:`flatpage`, -which is the flatpage object. - -Here's a sample :file:`flatpages/default.html` template: - -.. code-block:: html+django - - <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" - "http://www.w3.org/TR/REC-html40/loose.dtd"> - <html> - <head> - <title>{{ flatpage.title }}</title> - </head> - <body> - {{ flatpage.content }} - </body> - </html> - -Since you're already entering raw HTML into the admin page for a flatpage, -both ``flatpage.title`` and ``flatpage.content`` are marked as **not** -requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the -template. diff --git a/parts/django/docs/ref/contrib/formtools/form-preview.txt b/parts/django/docs/ref/contrib/formtools/form-preview.txt deleted file mode 100644 index a2cbea7..0000000 --- a/parts/django/docs/ref/contrib/formtools/form-preview.txt +++ /dev/null @@ -1,121 +0,0 @@ -============ -Form preview -============ - -.. module:: django.contrib.formtools - :synopsis: Displays an HTML form, forces a preview, then does something - with the submission. - -Django comes with an optional "form preview" application that helps automate -the following workflow: - -"Display an HTML form, force a preview, then do something with the submission." - -To force a preview of a form submission, all you have to do is write a short -Python class. - -Overview -========= - -Given a :class:`django.forms.Form` subclass that you define, this -application takes care of the following workflow: - - 1. Displays the form as HTML on a Web page. - 2. Validates the form data when it's submitted via POST. - a. If it's valid, displays a preview page. - b. If it's not valid, redisplays the form with error messages. - 3. When the "confirmation" form is submitted from the preview page, calls - a hook that you define -- a - :meth:`~django.contrib.formtools.FormPreview.done()` method that gets - passed the valid data. - -The framework enforces the required preview by passing a shared-secret hash to -the preview page via hidden form fields. If somebody tweaks the form parameters -on the preview page, the form submission will fail the hash-comparison test. - -How to use ``FormPreview`` -========================== - - 1. Point Django at the default FormPreview templates. There are two ways to - do this: - - * Add ``'django.contrib.formtools'`` to your - :setting:`INSTALLED_APPS` setting. This will work if your - :setting:`TEMPLATE_LOADERS` setting includes the - ``app_directories`` template loader (which is the case by - default). See the :ref:`template loader docs <template-loaders>` - for more. - - * Otherwise, determine the full filesystem path to the - :file:`django/contrib/formtools/templates` directory, and add that - directory to your :setting:`TEMPLATE_DIRS` setting. - - 2. Create a :class:`~django.contrib.formtools.FormPreview` subclass that - overrides the :meth:`~django.contrib.formtools.FormPreview.done()` - method:: - - from django.contrib.formtools.preview import FormPreview - from myapp.models import SomeModel - - class SomeModelFormPreview(FormPreview): - - def done(self, request, cleaned_data): - # Do something with the cleaned_data, then redirect - # to a "success" page. - return HttpResponseRedirect('/form/success') - - This method takes an :class:`~django.http.HttpRequest` object and a - dictionary of the form data after it has been validated and cleaned. - It should return an :class:`~django.http.HttpResponseRedirect` that - is the end result of the form being submitted. - - 3. Change your URLconf to point to an instance of your - :class:`~django.contrib.formtools.FormPreview` subclass:: - - from myapp.preview import SomeModelFormPreview - from myapp.forms import SomeModelForm - from django import forms - - ...and add the following line to the appropriate model in your URLconf:: - - (r'^post/$', SomeModelFormPreview(SomeModelForm)), - - where ``SomeModelForm`` is a Form or ModelForm class for the model. - - 4. Run the Django server and visit :file:`/post/` in your browser. - -``FormPreview`` classes -======================= - -.. class:: FormPreview - -A :class:`~django.contrib.formtools.FormPreview` class is a simple Python class -that represents the preview workflow. -:class:`~django.contrib.formtools.FormPreview` classes must subclass -``django.contrib.formtools.preview.FormPreview`` and override the -:meth:`~django.contrib.formtools.FormPreview.done()` method. They can live -anywhere in your codebase. - -``FormPreview`` templates -========================= - -By default, the form is rendered via the template :file:`formtools/form.html`, -and the preview page is rendered via the template :file:`formtools/preview.html`. -These values can be overridden for a particular form preview by setting -:attr:`~django.contrib.formtools.FormPreview.preview_template` and -:attr:`~django.contrib.formtools.FormPreview.form_template` attributes on the -FormPreview subclass. See :file:`django/contrib/formtools/templates` for the -default templates. - -Advanced ``FormPreview`` methods -================================ - -.. versionadded:: 1.2 - -.. method:: FormPreview.process_preview - - Given a validated form, performs any extra processing before displaying the - preview page, and saves any extra data in context. - - By default, this method is empty. It is called after the form is validated, - but before the context is modified with hash information and rendered. diff --git a/parts/django/docs/ref/contrib/formtools/form-wizard.txt b/parts/django/docs/ref/contrib/formtools/form-wizard.txt deleted file mode 100644 index 390d575..0000000 --- a/parts/django/docs/ref/contrib/formtools/form-wizard.txt +++ /dev/null @@ -1,312 +0,0 @@ -=========== -Form wizard -=========== - -.. module:: django.contrib.formtools.wizard - :synopsis: Splits forms across multiple Web pages. - -.. versionadded:: 1.0 - -Django comes with an optional "form wizard" application that splits -:doc:`forms </topics/forms/index>` across multiple Web pages. It maintains -state in hashed HTML :samp:`<input type="hidden">` fields, and the data isn't -processed server-side until the final form is submitted. - -You might want to use this if you have a lengthy form that would be too -unwieldy for display on a single page. The first page might ask the user for -core information, the second page might ask for less important information, -etc. - -The term "wizard," in this context, is `explained on Wikipedia`_. - -.. _explained on Wikipedia: http://en.wikipedia.org/wiki/Wizard_%28software%29 -.. _forms: ../forms/ - -How it works -============ - -Here's the basic workflow for how a user would use a wizard: - - 1. The user visits the first page of the wizard, fills in the form and - submits it. - 2. The server validates the data. If it's invalid, the form is displayed - again, with error messages. If it's valid, the server calculates a - secure hash of the data and presents the user with the next form, - saving the validated data and hash in :samp:`<input type="hidden">` - fields. - 3. Step 1 and 2 repeat, for every subsequent form in the wizard. - 4. Once the user has submitted all the forms and all the data has been - validated, the wizard processes the data -- saving it to the database, - sending an e-mail, or whatever the application needs to do. - -Usage -===== - -This application handles as much machinery for you as possible. Generally, you -just have to do these things: - - 1. Define a number of :class:`~django.forms.Form` classes -- one per wizard - page. - - 2. Create a :class:`FormWizard` class that specifies what to do once all of - your forms have been submitted and validated. This also lets you - override some of the wizard's behavior. - - 3. Create some templates that render the forms. You can define a single, - generic template to handle every one of the forms, or you can define a - specific template for each form. - - 4. Point your URLconf at your :class:`FormWizard` class. - -Defining ``Form`` classes -========================= - -The first step in creating a form wizard is to create the -:class:`~django.forms.Form` classes. These should be standard -:class:`django.forms.Form` classes, covered in the :doc:`forms documentation -</topics/forms/index>`. These classes can live anywhere in your codebase, but -convention is to put them in a file called :file:`forms.py` in your -application. - -For example, let's write a "contact form" wizard, where the first page's form -collects the sender's e-mail address and subject, and the second page collects -the message itself. Here's what the :file:`forms.py` might look like:: - - from django import forms - - class ContactForm1(forms.Form): - subject = forms.CharField(max_length=100) - sender = forms.EmailField() - - class ContactForm2(forms.Form): - message = forms.CharField(widget=forms.Textarea) - -**Important limitation:** Because the wizard uses HTML hidden fields to store -data between pages, you may not include a :class:`~django.forms.FileField` -in any form except the last one. - -Creating a ``FormWizard`` class -=============================== - -The next step is to create a -:class:`django.contrib.formtools.wizard.FormWizard` subclass. As with your -:class:`~django.forms.Form` classes, this :class:`FormWizard` class can live -anywhere in your codebase, but convention is to put it in :file:`forms.py`. - -The only requirement on this subclass is that it implement a -:meth:`~FormWizard.done()` method. - -.. method:: FormWizard.done - - This method specifies what should happen when the data for *every* form is - submitted and validated. This method is passed two arguments: - - * ``request`` -- an :class:`~django.http.HttpRequest` object - * ``form_list`` -- a list of :class:`~django.forms.Form` classes - -In this simplistic example, rather than perform any database operation, the -method simply renders a template of the validated data:: - - from django.shortcuts import render_to_response - from django.contrib.formtools.wizard import FormWizard - - class ContactWizard(FormWizard): - def done(self, request, form_list): - return render_to_response('done.html', { - 'form_data': [form.cleaned_data for form in form_list], - }) - -Note that this method will be called via ``POST``, so it really ought to be a -good Web citizen and redirect after processing the data. Here's another -example:: - - from django.http import HttpResponseRedirect - from django.contrib.formtools.wizard import FormWizard - - class ContactWizard(FormWizard): - def done(self, request, form_list): - do_something_with_the_form_data(form_list) - return HttpResponseRedirect('/page-to-redirect-to-when-done/') - -See the section `Advanced FormWizard methods`_ below to learn about more -:class:`FormWizard` hooks. - -Creating templates for the forms -================================ - -Next, you'll need to create a template that renders the wizard's forms. By -default, every form uses a template called :file:`forms/wizard.html`. (You can -change this template name by overriding :meth:`~FormWizard.get_template()`, -which is documented below. This hook also allows you to use a different -template for each form.) - -This template expects the following context: - - * ``step_field`` -- The name of the hidden field containing the step. - * ``step0`` -- The current step (zero-based). - * ``step`` -- The current step (one-based). - * ``step_count`` -- The total number of steps. - * ``form`` -- The :class:`~django.forms.Form` instance for the current step - (either empty or with errors). - * ``previous_fields`` -- A string representing every previous data field, - plus hashes for completed forms, all in the form of hidden fields. Note - that you'll need to run this through the :tfilter:`safe` template filter, - to prevent auto-escaping, because it's raw HTML. - -You can supply extra context to this template in two ways: - - * Set the :attr:`~FormWizard.extra_context` attribute on your - :class:`FormWizard` subclass to a dictionary. - - * Pass a dictionary as a parameter named ``extra_context`` to your wizard's - URL pattern in your URLconf. See :ref:`hooking-wizard-into-urlconf`. - -Here's a full example template: - -.. code-block:: html+django - - {% extends "base.html" %} - - {% block content %} - <p>Step {{ step }} of {{ step_count }}</p> - <form action="." method="post">{% csrf_token %} - <table> - {{ form }} - </table> - <input type="hidden" name="{{ step_field }}" value="{{ step0 }}" /> - {{ previous_fields|safe }} - <input type="submit"> - </form> - {% endblock %} - -Note that ``previous_fields``, ``step_field`` and ``step0`` are all required -for the wizard to work properly. - -.. _hooking-wizard-into-urlconf: - -Hooking the wizard into a URLconf -================================= - -Finally, we need to specify which forms to use in the wizard, and then -deploy the new :class:`FormWizard` object a URL in ``urls.py``. The -wizard takes a list of your :class:`~django.forms.Form` objects as -arguments when you instantiate the Wizard:: - - from django.conf.urls.defaults import * - from testapp.forms import ContactForm1, ContactForm2, ContactWizard - - urlpatterns = patterns('', - (r'^contact/$', ContactWizard([ContactForm1, ContactForm2])), - ) - -Advanced ``FormWizard`` methods -=============================== - -.. class:: FormWizard - - Aside from the :meth:`~done()` method, :class:`FormWizard` offers a few - advanced method hooks that let you customize how your wizard works. - - Some of these methods take an argument ``step``, which is a zero-based - counter representing the current step of the wizard. (E.g., the first form - is ``0`` and the second form is ``1``.) - -.. method:: FormWizard.prefix_for_step - - Given the step, returns a form prefix to use. By default, this simply uses - the step itself. For more, see the :ref:`form prefix documentation - <form-prefix>`. - - Default implementation:: - - def prefix_for_step(self, step): - return str(step) - -.. method:: FormWizard.render_hash_failure - - Renders a template if the hash check fails. It's rare that you'd need to - override this. - - Default implementation:: - - def render_hash_failure(self, request, step): - return self.render(self.get_form(step), request, step, - context={'wizard_error': - 'We apologize, but your form has expired. Please' - ' continue filling out the form from this page.'}) - -.. method:: FormWizard.security_hash - - Calculates the security hash for the given request object and - :class:`~django.forms.Form` instance. - - By default, this uses an MD5 hash of the form data and your - :setting:`SECRET_KEY` setting. It's rare that somebody would need to - override this. - - Example:: - - def security_hash(self, request, form): - return my_hash_function(request, form) - -.. method:: FormWizard.parse_params - - A hook for saving state from the request object and ``args`` / ``kwargs`` - that were captured from the URL by your URLconf. - - By default, this does nothing. - - Example:: - - def parse_params(self, request, *args, **kwargs): - self.my_state = args[0] - -.. method:: FormWizard.get_template - - Returns the name of the template that should be used for the given step. - - By default, this returns :file:`'forms/wizard.html'`, regardless of step. - - Example:: - - def get_template(self, step): - return 'myapp/wizard_%s.html' % step - - If :meth:`~FormWizard.get_template` returns a list of strings, then the - wizard will use the template system's - :func:`~django.template.loader.select_template` function. - This means the system will use the first template that exists on the - filesystem. For example:: - - def get_template(self, step): - return ['myapp/wizard_%s.html' % step, 'myapp/wizard.html'] - -.. method:: FormWizard.render_template - - Renders the template for the given step, returning an - :class:`~django.http.HttpResponse` object. - - Override this method if you want to add a custom context, return a - different MIME type, etc. If you only need to override the template name, - use :meth:`~FormWizard.get_template` instead. - - The template will be rendered with the context documented in the - "Creating templates for the forms" section above. - -.. method:: FormWizard.process_step - - Hook for modifying the wizard's internal state, given a fully validated - :class:`~django.forms.Form` object. The Form is guaranteed to have clean, - valid data. - - This method should *not* modify any of that data. Rather, it might want to - set ``self.extra_context`` or dynamically alter ``self.form_list``, based - on previously submitted forms. - - Note that this method is called every time a page is rendered for *all* - submitted steps. - - The function signature:: - - def process_step(self, request, form, step): - # ... diff --git a/parts/django/docs/ref/contrib/formtools/index.txt b/parts/django/docs/ref/contrib/formtools/index.txt deleted file mode 100644 index f364706..0000000 --- a/parts/django/docs/ref/contrib/formtools/index.txt +++ /dev/null @@ -1,10 +0,0 @@ -django.contrib.formtools -======================== - -A set of high-level abstractions for Django forms (:mod:`django.forms`). - -.. toctree:: - :maxdepth: 1 - - form-preview - form-wizard diff --git a/parts/django/docs/ref/contrib/gis/admin.txt b/parts/django/docs/ref/contrib/gis/admin.txt deleted file mode 100644 index 011bb6b..0000000 --- a/parts/django/docs/ref/contrib/gis/admin.txt +++ /dev/null @@ -1,72 +0,0 @@ -.. _ref-gis-admin: - -====================== -GeoDjango's admin site -====================== - -.. module:: django.contrib.gis.admin - :synopsis: GeoDjango's extensions to the admin site. - - -``GeoModelAdmin`` -================= - -.. class:: GeoModelAdmin - - .. attribute:: default_lon - - The default center longitude. - - .. attribute:: default_lat - - The default center latitude. - - .. attribute:: default_zoom - - The default zoom level to use. Defaults to 18. - - .. attribute:: extra_js - - Sequence of URLs to any extra JavaScript to include. - - .. attribute:: map_template - - Override the template used to generate the JavaScript slippy map. - Default is ``'gis/admin/openlayers.html'``. - - .. attribute:: map_width - - Width of the map, in pixels. Defaults to 600. - - .. attribute:: map_height - - Height of the map, in pixels. Defaults to 400. - - .. attribute:: openlayers_url - - Link to the URL of the OpenLayers JavaScript. Defaults to - ``'http://openlayers.org/api/2.8/OpenLayers.js'``. - - - .. attribute:: modifiable - - Defaults to ``False``. When set to to ``True``, disables editing of - existing geometry fields in the admin. - - .. note:: - - This is different from adding the geometry field to - :attr:`~django.contrib.admin.ModelAdmin.readonly_fields`, - which will only display the WKT of the geometry. Setting - ``modifiable=False``, actually displays the geometry in a map, - but disables the ability to edit its vertices. - -``OSMGeoAdmin`` -=============== - -.. class:: OSMGeoAdmin - - A subclass of :class:`GeoModelAdmin` that uses a spherical mercator projection - with `OpenStreetMap <http://openstreetmap.org/>`_ street data tiles. - See the :ref:`OSMGeoAdmin introduction <osmgeoadmin-intro>` - in the tutorial for a usage example. diff --git a/parts/django/docs/ref/contrib/gis/commands.txt b/parts/django/docs/ref/contrib/gis/commands.txt deleted file mode 100644 index 3dd161c..0000000 --- a/parts/django/docs/ref/contrib/gis/commands.txt +++ /dev/null @@ -1,83 +0,0 @@ -.. ref-geodjango-admin: - -============================= -GeoDjango Management Commands -============================= - -inspectdb -========= - -.. describe:: django-admin.py inspectdb - -When :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`, the -:djadmin:`inspectdb` management command is overridden with one from GeoDjango. -The overridden command is spatially-aware, and places geometry fields in the -auto-generated model definition, where appropriate. - -ogrinspect <data_source> <model_name> -===================================== - -.. django-admin:: ogrinspect - -The ``ogrinpsect`` management command will inspect the given OGR-compatible -:class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will -output a GeoDjango model with the given model name. There's a detailed example -of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. - -.. django-admin-option:: --blank <blank_field(s)> - - Use a comma separated list of OGR field names to add the ``blank=True`` - keyword option to the field definition. Set with ``true`` to apply - to all applicable fields. - -.. django-admin-option:: --decimal <decimal_field(s)> - - Use a comma separated list of OGR float fields to generate - :class:`~django.db.models.DecimalField` instead of the default - :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all - OGR float fields. - -.. django-admin-option:: --geom-name <name> - - Specifies the model attribute name to use for the geometry field. - Defaults to ``'geom'``. - -.. django-admin-option:: --layer <layer> - - The key for specifying which layer in the OGR - :class:`~django.contrib.gis.gdal.DataSource` source to use. - Defaults to 0 (the first layer). May be an integer or a string identifier - for the :class:`~django.contrib.gis.gdal.Layer`. - -.. django-admin-option:: --mapping - - Automatically generate a mapping dictionary for use with - :class:`~django.contrib.gis.utils.LayerMapping`. - -.. django-admin-option:: --multi-geom - - When generating the geometry field, treat it as a geometry collection. - For example, if this setting is enabled then a - :class:`~django.contrib.gis.db.models.MultiPolygonField` will be placed - in the generated model rather than - :class:`~django.contrib.gis.db.models.PolygonField`. - -.. django-admin-option:: --name-field <name_field> - - Generates a ``__unicode__`` routine on the model that will return the - the given field name. - -.. django-admin-option:: --no-imports - - Suppresses the ``from django.contrib.gis.db import models`` import statement. - -.. django-admin-option:: --null <null_field(s)> - - Use a comma separated list of OGR field names to add the ``null=True`` - keyword option to the field definition. Set with ``true`` to apply to - all applicable fields. - -.. django-admin-option:: --srid - - The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts - to automatically determine of the SRID of the data source. diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.3.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.3.sh deleted file mode 100755 index c9ab4fc..0000000 --- a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.3.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env bash -POSTGIS_SQL_PATH=`pg_config --sharedir` -createdb -E UTF8 template_postgis # Create the template spatial database. -createlang -d template_postgis plpgsql # Adding PLPGSQL language support. -psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" -psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines -psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql -psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables. -psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;" diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.4.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.4.sh deleted file mode 100755 index 57a1373..0000000 --- a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.4.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env bash -POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib -createdb -E UTF8 template_postgis # Create the template spatial database. -createlang -d template_postgis plpgsql # Adding PLPGSQL language support. -psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" -psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines -psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql -psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables. -psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;" diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.5.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-1.5.sh deleted file mode 100755 index 081b5f2..0000000 --- a/parts/django/docs/ref/contrib/gis/create_template_postgis-1.5.sh +++ /dev/null @@ -1,10 +0,0 @@ -#!/usr/bin/env bash -POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5 -createdb -E UTF8 template_postgis # Create the template spatial database. -createlang -d template_postgis plpgsql # Adding PLPGSQL language support. -psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" -psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines -psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql -psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables. -psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;" -psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;" diff --git a/parts/django/docs/ref/contrib/gis/create_template_postgis-debian.sh b/parts/django/docs/ref/contrib/gis/create_template_postgis-debian.sh deleted file mode 100755 index 46bd074..0000000 --- a/parts/django/docs/ref/contrib/gis/create_template_postgis-debian.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/usr/bin/env bash -POSTGIS_SQL_PATH=/usr/share/postgresql-8.3-postgis -createdb -E UTF8 template_postgis # Create the template spatial database. -createlang -d template_postgis plpgsql # Adding PLPGSQL language support. -psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" -psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines -psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql -psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables. -psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;" diff --git a/parts/django/docs/ref/contrib/gis/db-api.txt b/parts/django/docs/ref/contrib/gis/db-api.txt deleted file mode 100644 index fbced8e..0000000 --- a/parts/django/docs/ref/contrib/gis/db-api.txt +++ /dev/null @@ -1,349 +0,0 @@ -.. _ref-gis-db-api: - -====================== -GeoDjango Database API -====================== - -.. module:: django.contrib.gis.db.models - :synopsis: GeoDjango's database API. - -.. _spatial-backends: - -Spatial Backends -================ - -.. versionadded:: 1.2 - -In Django 1.2, support for :doc:`multiple databases </topics/db/multi-db>` was -introduced. In order to support multiple databases, GeoDjango has segregated -its functionality into full-fledged spatial database backends: - -* :mod:`django.contrib.gis.db.backends.postgis` -* :mod:`django.contrib.gis.db.backends.mysql` -* :mod:`django.contrib.gis.db.backends.oracle` -* :mod:`django.contrib.gis.db.backends.spatialite` - -Database Settings Backwards-Compatibility ------------------------------------------ - -In :doc:`Django 1.2 </releases/1.2>`, the way -to :ref:`specify databases <specifying-databases>` in your settings was changed. -The old database settings format (e.g., the ``DATABASE_*`` settings) -is backwards compatible with GeoDjango, and will automatically use the -appropriate spatial backend as long as :mod:`django.contrib.gis` is in -your :setting:`INSTALLED_APPS`. For example, if you have the following in -your settings:: - - DATABASE_ENGINE='postgresql_psycopg2' - - ... - - INSTALLED_APPS = ( - ... - 'django.contrib.gis', - ... - ) - -Then, :mod:`django.contrib.gis.db.backends.postgis` is automatically used as your -spatial backend. - -.. _mysql-spatial-limitations: - -MySQL Spatial Limitations -------------------------- - -MySQL's spatial extensions only support bounding box operations -(what MySQL calls minimum bounding rectangles, or MBR). Specifically, -`MySQL does not conform to the OGC standard <http://dev.mysql.com/doc/refman/5.1/en/functions-that-test-spatial-relationships-between-geometries.html>`_: - - Currently, MySQL does not implement these functions - [``Contains``, ``Crosses``, ``Disjoint``, ``Intersects``, ``Overlaps``, - ``Touches``, ``Within``] - according to the specification. Those that are implemented return - the same result as the corresponding MBR-based functions. - -In other words, while spatial lookups such as :lookup:`contains <gis-contains>` -are available in GeoDjango when using MySQL, the results returned are really -equivalent to what would be returned when using :lookup:`bbcontains` -on a different spatial backend. - -.. warning:: - - True spatial indexes (R-trees) are only supported with - MyISAM tables on MySQL. [#fnmysqlidx]_ In other words, when using - MySQL spatial extensions you have to choose between fast spatial - lookups and the integrity of your data -- MyISAM tables do - not support transactions or foreign key constraints. - -Creating and Saving Geographic Models -===================================== -Here is an example of how to create a geometry object (assuming the ``Zipcode`` -model):: - - >>> from zipcode.models import Zipcode - >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))') - >>> z.save() - -:class:`~django.contrib.gis.geos.GEOSGeometry` objects may also be used to save geometric models:: - - >>> from django.contrib.gis.geos import GEOSGeometry - >>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))') - >>> z = Zipcode(code=77096, poly=poly) - >>> z.save() - -Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a -different SRID value) than that of the field, then it will be implicitly -transformed into the SRID of the model's field, using the spatial database's -transform procedure:: - - >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal' - >>> z = Zipcode(code=78212, poly=poly_3084) - >>> z.save() - >>> from django.db import connection - >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed (requires DEBUG=True) - INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326)) - -Thus, geometry parameters may be passed in using the ``GEOSGeometry`` object, WKT -(Well Known Text [#fnwkt]_), HEXEWKB (PostGIS specific -- a WKB geometry in -hexadecimal [#fnewkb]_), and GeoJSON [#fngeojson]_ (requires GDAL). Essentially, -if the input is not a ``GEOSGeometry`` object, the geometry field will attempt to -create a ``GEOSGeometry`` instance from the input. - -For more information creating :class:`~django.contrib.gis.geos.GEOSGeometry` -objects, refer to the :ref:`GEOS tutorial <geos-tutorial>`. - -.. _spatial-lookups-intro: - -Spatial Lookups -=============== - -GeoDjango's lookup types may be used with any manager method like -``filter()``, ``exclude()``, etc. However, the lookup types unique to -GeoDjango are only available on geometry fields. -Filters on 'normal' fields (e.g. :class:`~django.db.models.CharField`) -may be chained with those on geographic fields. Thus, geographic queries -take the following general form (assuming the ``Zipcode`` model used in the -:ref:`ref-gis-model-api`):: - - >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>) - >>> qs = Zipcode.objects.exclude(...) - -For example:: - - >>> qs = Zipcode.objects.filter(poly__contains=pnt) - -In this case, ``poly`` is the geographic field, :lookup:`contains <gis-contains>` -is the spatial lookup type, and ``pnt`` is the parameter (which may be a -:class:`~django.contrib.gis.geos.GEOSGeometry` object or a string of -GeoJSON , WKT, or HEXEWKB). - -A complete reference can be found in the :ref:`spatial lookup reference -<spatial-lookups>`. - -.. note:: - - GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a - subclass of :class:`~django.db.models.QuerySet`. The - :class:`GeoManager` instance attached to your model is what - enables use of :class:`GeoQuerySet`. - -.. _distance-queries: - -Distance Queries -================ - -Introduction ------------- -Distance calculations with spatial data is tricky because, unfortunately, -the Earth is not flat. Some distance queries with fields in a geographic -coordinate system may have to be expressed differently because of -limitations in PostGIS. Please see the :ref:`selecting-an-srid` section -in the :ref:`ref-gis-model-api` documentation for more details. - -.. _distance-lookups-intro: - -Distance Lookups ----------------- -*Availability*: PostGIS, Oracle, SpatiaLite - -The following distance lookups are available: - -* :lookup:`distance_lt` -* :lookup:`distance_lte` -* :lookup:`distance_gt` -* :lookup:`distance_gte` -* :lookup:`dwithin` - -.. note:: - - For *measuring*, rather than querying on distances, use the - :meth:`GeoQuerySet.distance` method. - -Distance lookups take a tuple parameter comprising: - -#. A geometry to base calculations from; and -#. A number or :class:`~django.contrib.gis.measure.Distance` object containing the distance. - -If a :class:`~django.contrib.gis.measure.Distance` object is used, -it may be expressed in any units (the SQL generated will use units -converted to those of the field); otherwise, numeric parameters are assumed -to be in the units of the field. - -.. note:: - - For users of PostGIS 1.4 and below, the routine ``ST_Distance_Sphere`` - is used by default for calculating distances on geographic coordinate systems - (e.g., WGS84) -- which may only be called with point geometries [#fndistsphere14]_. - Thus, geographic distance lookups on traditional PostGIS geometry columns are - only allowed on :class:`PointField` model fields using a point for the - geometry parameter. - -.. note:: - - In PostGIS 1.5, ``ST_Distance_Sphere`` does *not* limit the geometry types - geographic distance queries are performed with. [#fndistsphere15]_ However, - these queries may take a long time, as great-circle distances must be - calculated on the fly for *every* row in the query. This is because the - spatial index on traditional geometry fields cannot be used. - - For much better performance on WGS84 distance queries, consider using - :ref:`geography columns <geography-type>` in your database instead because - they are able to use their spatial index in distance queries. - You can tell GeoDjango to use a geography column by setting ``geography=True`` - in your field definition. - -For example, let's say we have a ``SouthTexasCity`` model (from the -`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities -in southern Texas:: - - from django.contrib.gis.db import models - - class SouthTexasCity(models.Model): - name = models.CharField(max_length=30) - # A projected coordinate system (only valid for South Texas!) - # is used, units are in meters. - point = models.PointField(srid=32140) - objects = models.GeoManager() - -Then distance queries may be performed as follows:: - - >>> from django.contrib.gis.geos import * - >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance`` - >>> from geoapp import SouthTexasCity - # Distances will be calculated from this point, which does not have to be projected. - >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) - # If numeric parameter, units of field (meters in this case) are assumed. - >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000)) - # Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit) - >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7))) - >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20))) - >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100))) - -__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py - -.. _compatibility-table: - -Compatibility Tables -==================== - -.. _spatial-lookup-compatibility: - -Spatial Lookups ---------------- - -The following table provides a summary of what spatial lookups are available -for each spatial database backend. - -================================= ========= ======== ============ ========== -Lookup Type PostGIS Oracle MySQL [#]_ SpatiaLite -================================= ========= ======== ============ ========== -:lookup:`bbcontains` X X X -:lookup:`bboverlaps` X X X -:lookup:`contained` X X X -:lookup:`contains <gis-contains>` X X X X -:lookup:`contains_properly` X -:lookup:`coveredby` X X -:lookup:`covers` X X -:lookup:`crosses` X X -:lookup:`disjoint` X X X X -:lookup:`distance_gt` X X X -:lookup:`distance_gte` X X X -:lookup:`distance_lt` X X X -:lookup:`distance_lte` X X X -:lookup:`dwithin` X X -:lookup:`equals` X X X X -:lookup:`exact` X X X X -:lookup:`intersects` X X X X -:lookup:`overlaps` X X X X -:lookup:`relate` X X X -:lookup:`same_as` X X X X -:lookup:`touches` X X X X -:lookup:`within` X X X X -:lookup:`left` X -:lookup:`right` X -:lookup:`overlaps_left` X -:lookup:`overlaps_right` X -:lookup:`overlaps_above` X -:lookup:`overlaps_below` X -:lookup:`strictly_above` X -:lookup:`strictly_below` X -================================= ========= ======== ============ ========== - -.. _geoqueryset-method-compatibility: - -``GeoQuerySet`` Methods ------------------------ -The following table provides a summary of what :class:`GeoQuerySet` methods -are available on each spatial backend. Please note that MySQL does not -support any of these methods, and is thus excluded from the table. - -==================================== ======= ====== ========== -Method PostGIS Oracle SpatiaLite -==================================== ======= ====== ========== -:meth:`GeoQuerySet.area` X X X -:meth:`GeoQuerySet.centroid` X X X -:meth:`GeoQuerySet.collect` X -:meth:`GeoQuerySet.difference` X X X -:meth:`GeoQuerySet.distance` X X X -:meth:`GeoQuerySet.envelope` X X -:meth:`GeoQuerySet.extent` X X -:meth:`GeoQuerySet.extent3d` X -:meth:`GeoQuerySet.force_rhr` X -:meth:`GeoQuerySet.geohash` X -:meth:`GeoQuerySet.geojson` X -:meth:`GeoQuerySet.gml` X X -:meth:`GeoQuerySet.intersection` X X X -:meth:`GeoQuerySet.kml` X -:meth:`GeoQuerySet.length` X X X -:meth:`GeoQuerySet.make_line` X -:meth:`GeoQuerySet.mem_size` X -:meth:`GeoQuerySet.num_geom` X X X -:meth:`GeoQuerySet.num_points` X X X -:meth:`GeoQuerySet.perimeter` X X -:meth:`GeoQuerySet.point_on_surface` X X X -:meth:`GeoQuerySet.reverse_geom` X X -:meth:`GeoQuerySet.scale` X X -:meth:`GeoQuerySet.snap_to_grid` X -:meth:`GeoQuerySet.svg` X X -:meth:`GeoQuerySet.sym_difference` X X X -:meth:`GeoQuerySet.transform` X X X -:meth:`GeoQuerySet.translate` X X -:meth:`GeoQuerySet.union` X X X -:meth:`GeoQuerySet.unionagg` X X X -==================================== ======= ====== ========== - -.. rubric:: Footnotes -.. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry). -.. [#fnewkb] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2. -.. [#fngeojson] *See* Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, `The GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_, Revision 1.0 (June 16, 2008). -.. [#fndistsphere14] *See* `PostGIS 1.4 documentation <http://postgis.refractions.net/documentation/manual-1.4/ST_Distance_Sphere.html>`_ on ``ST_distance_sphere``. -.. [#fndistsphere15] *See* `PostGIS 1.5 documentation <http://postgis.refractions.net/documentation/manual-1.5/ST_Distance_Sphere.html>`_ on ``ST_distance_sphere``. -.. [#fnmysqlidx] *See* `Creating Spatial Indexes <http://dev.mysql.com/doc/refman/5.1/en/creating-spatial-indexes.html>`_ - in the MySQL 5.1 Reference Manual: - - For MyISAM tables, ``SPATIAL INDEX`` creates an R-tree index. For storage - engines that support nonspatial indexing of spatial columns, the engine - creates a B-tree index. A B-tree index on spatial values will be useful - for exact-value lookups, but not for range scans. - -.. [#] Refer :ref:`mysql-spatial-limitations` section for more details. diff --git a/parts/django/docs/ref/contrib/gis/deployment.txt b/parts/django/docs/ref/contrib/gis/deployment.txt deleted file mode 100644 index 035b23f..0000000 --- a/parts/django/docs/ref/contrib/gis/deployment.txt +++ /dev/null @@ -1,99 +0,0 @@ -=================== -Deploying GeoDjango -=================== - -.. warning:: - - GeoDjango uses the GDAL geospatial library which is - not thread safe at this time. Thus, it is *highly* recommended - to not use threading when deploying -- in other words, use a - an appropriate configuration of Apache or the prefork method - when using FastCGI through another Web server. - -Apache -====== -In this section there are some example ``VirtualHost`` directives for -when deploying using either ``mod_python`` or ``mod_wsgi``. At this -time, we recommend ``mod_wsgi``, as it is now officially recommended -way to deploy Django applications with Apache. Moreover, if -``mod_python`` is used, then a prefork version of Apache must also be -used. As long as ``mod_wsgi`` is configured correctly, it does not -matter whether the version of Apache is prefork or worker. - -.. note:: - - The ``Alias`` and ``Directory`` configurations in the the examples - below use an example path to a system-wide installation folder of Django. - Substitute in an appropriate location, if necessary, as it may be - different than the path on your system. - -``mod_wsgi`` ------------- - -Example:: - - <VirtualHost *:80> - WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1 - WSGIProcessGroup geodjango - WSGIScriptAlias / /home/geo/geodjango/world.wsgi - - Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" - <Directory "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"> - Order allow,deny - Options Indexes - Allow from all - IndexOptions FancyIndexing - </Directory> - - </VirtualHost> - -.. warning:: - - If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then - Apache may crash when running your GeoDjango application. Increase the - number of ``processes`` instead. - -For more information, please consult Django's -:doc:`mod_wsgi documentation </howto/deployment/modwsgi>`. - -``mod_python`` --------------- - -Example:: - - <VirtualHost *:80> - - <Location "/"> - SetHandler mod_python - PythonHandler django.core.handlers.modpython - SetEnv DJANGO_SETTINGS_MODULE world.settings - PythonDebug On - PythonPath "['/var/www/apps'] + sys.path" - </Location> - - Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/" - <Location "/media"> - SetHandler None - </Location> - - </VirtualHost> - -.. warning:: - - When using ``mod_python`` you *must* be using a prefork version of Apache, or - else your GeoDjango application may crash Apache. - -For more information, please consult Django's -:doc:`mod_python documentation </howto/deployment/modpython>`. - -Lighttpd -======== - -FastCGI -------- - -Nginx -===== - -FastCGI -------- diff --git a/parts/django/docs/ref/contrib/gis/feeds.txt b/parts/django/docs/ref/contrib/gis/feeds.txt deleted file mode 100644 index 7c3a2d0..0000000 --- a/parts/django/docs/ref/contrib/gis/feeds.txt +++ /dev/null @@ -1,95 +0,0 @@ -================ -Geographic Feeds -================ - -.. module:: django.contrib.gis.feeds - :synopsis: GeoDjango's framework for generating spatial feeds. - -GeoDjango has its own :class:`Feed` subclass that may embed location information -in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or -`W3C Geo`_ standards. Because GeoDjango's syndication API is a superset of -Django's, please consult :doc:`Django's syndication documentation -</ref/contrib/syndication>` for details on general usage. - -.. _W3C Geo: http://www.w3.org/2003/01/geo/ - -__ http://georss.org/1.0#simple - -Example -======= - -API Reference -============= - -``Feed`` Subclass ------------------ - -.. class:: Feed - - In addition to methods provided by - the :class:`django.contrib.syndication.feeds.Feed` - base class, GeoDjango's ``Feed`` class provides - the following overrides. Note that these overrides may be done in multiple ways:: - - from django.contrib.gis.feeds import Feed - - class MyFeed(Feed): - - # First, as a class attribute. - geometry = ... - item_geometry = ... - - # Also a function with no arguments - def geometry(self): - ... - - def item_geometry(self): - ... - - # And as a function with a single argument - def geometry(self, obj): - ... - - def item_geometry(self, item): - ... - - .. method:: geometry(obj) - - Takes the object returned by ``get_object()`` and returns the *feed's* - geometry. Typically this is a ``GEOSGeometry`` instance, or can be a - tuple to represent a point or a box. For example:: - - class ZipcodeFeed(Feed): - - def geometry(self, obj): - # Can also return: `obj.poly`, and `obj.poly.centroid`. - return obj.poly.extent # tuple like: (X0, Y0, X1, Y1). - - .. method:: item_geometry(item) - - Set this to return the geometry for each *item* in the feed. This - can be a ``GEOSGeometry`` instance, or a tuple that represents a - point coordinate or bounding box. For example:: - - class ZipcodeFeed(Feed): - - def item_geometry(self, obj): - # Returns the polygon. - return obj.poly - -``SyndicationFeed`` Subclasses ------------------------------- - -The following :class:`django.utils.feedgenerator.SyndicationFeed` subclasses -are available: - -.. class:: GeoRSSFeed - -.. class:: GeoAtom1Feed - -.. class:: W3CGeoFeed - -.. note:: - - `W3C Geo`_ formatted feeds only support - :class:`~django.contrib.gis.db.models.PointField` geometries. diff --git a/parts/django/docs/ref/contrib/gis/gdal.txt b/parts/django/docs/ref/contrib/gis/gdal.txt deleted file mode 100644 index 1ce21d9..0000000 --- a/parts/django/docs/ref/contrib/gis/gdal.txt +++ /dev/null @@ -1,1114 +0,0 @@ -.. _ref-gdal: - -======== -GDAL API -======== - -.. module:: django.contrib.gis.gdal - :synopsis: GeoDjango's high-level interface to the GDAL library. - -`GDAL`__ stands for **G**\ eospatial **D**\ ata **A**\ bstraction **L**\ ibrary, -and is a veritable "swiss army knife" of GIS data functionality. A subset -of GDAL is the `OGR`__ Simple Features Library, which specializes -in reading and writing vector geographic data in a variety of standard -formats. - -GeoDjango provides a high-level Python interface for some of the -capabilities of OGR, including the reading and coordinate transformation -of vector spatial data. - -.. note:: - - Although the module is named ``gdal``, GeoDjango only supports - some of the capabilities of OGR. Thus, none of GDAL's features - with respect to raster (image) data are supported at this time. - -__ http://www.gdal.org/ -__ http://www.gdal.org/ogr/ - -Overview -======== - -Sample Data ------------ - -The GDAL/OGR tools described here are designed to help you read in -your geospatial data, in order for most of them to be useful you have -to have some data to work with. If you're starting out and don't yet -have any data of your own to use, GeoDjango comes with a number of -simple data sets that you can use for testing. This snippet will -determine where these sample files are installed on your computer:: - - >>> import os - >>> import django.contrib.gis - >>> GIS_PATH = os.path.dirname(django.contrib.gis.__file__) - >>> CITIES_PATH = os.path.join(GIS_PATH, 'tests/data/cities/cities.shp') - -Vector Data Source Objects -========================== - -``DataSource`` --------------- - -:class:`DataSource` is a wrapper for the OGR data source object that -supports reading data from a variety of OGR-supported geospatial file -formats and data sources using a simple, consistent interface. Each -data source is represented by a :class:`DataSource` object which contains -one or more layers of data. Each layer, represented by a :class:`Layer` -object, contains some number of geographic features (:class:`Feature`), -information about the type of features contained in that layer (e.g. -points, polygons, etc.), as well as the names and types of any -additional fields (:class:`Field`) of data that may be associated with -each feature in that layer. - -.. class:: DataSource(ds_input) - - The constructor for ``DataSource`` just a single parameter: the path of - the file you want to read. However, OGR - also supports a variety of more complex data sources, including - databases, that may be accessed by passing a special name string instead - of a path. For more information, see the `OGR Vector Formats`__ - documentation. The :attr:`name` property of a ``DataSource`` - instance gives the OGR name of the underlying data source that it is - using. - - Once you've created your ``DataSource``, you can find out how many - layers of data it contains by accessing the :attr:`layer_count` property, - or (equivalently) by using the ``len()`` function. For information on - accessing the layers of data themselves, see the next section:: - - >>> from django.contrib.gis.gdal import DataSource - >>> ds = DataSource(CITIES_PATH) - >>> ds.name # The exact filename may be different on your computer - '/usr/local/lib/python2.6/site-packages/django/contrib/gis/tests/data/cities/cities.shp' - >>> ds.layer_count # This file only contains one layer - 1 - - .. attribute:: layer_count - - Returns the number of layers in the data source. - - .. attribute:: name - - Returns the name of the data source. - -__ http://www.gdal.org/ogr/ogr_formats.html - -``Layer`` ---------- - -.. class:: Layer - - ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object. - You never create a ``Layer`` object directly. Instead, you retrieve - them from a :class:`DataSource` object, which is essentially a standard - Python container of ``Layer`` objects. For example, you can access a - specific layer by its index (e.g. ``ds[0]`` to access the first - layer), or you can iterate over all the layers in the container in a - ``for`` loop. The ``Layer`` itself acts as a container for geometric - features. - - Typically, all the features in a given layer have the same geometry type. - The :attr:`geom_type` property of a layer is an :class:`OGRGeomType` - that identifies the feature type. We can use it to print out some basic - information about each layer in a :class:`DataSource`:: - - >>> for layer in ds: - ... print 'Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name) - ... - Layer "cities": 3 Points - - The example output is from the cities data source, loaded above, which - evidently contains one layer, called ``"cities"``, which contains three - point features. For simplicity, the examples below assume that you've - stored that layer in the variable ``layer``:: - - >>> layer = ds[0] - - .. attribute:: name - - Returns the name of this layer in the data source. - - >>> layer.name - 'cities' - - .. attribute:: num_feat - - Returns the number of features in the layer. Same as ``len(layer)``:: - - >>> layer.num_feat - 3 - - .. attribute:: geom_type - - Returns the geometry type of the layer, as an :class:`OGRGeomType` - object:: - - >>> layer.geom_type.name - 'Point' - - .. attribute:: num_fields - - Returns the number of fields in the layer, i.e the number of fields of - data associated with each feature in the layer:: - - >>> layer.num_fields - 4 - - .. attribute:: fields - - Returns a list of the names of each of the fields in this layer:: - - >>> layer.fields - ['Name', 'Population', 'Density', 'Created'] - - .. attribute field_types - - Returns a list of the data types of each of the fields in this layer. - These are subclasses of ``Field``, discussed below:: - - >>> [ft.__name__ for ft in layer.field_types] - ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] - - .. attribute:: field_widths - - Returns a list of the maximum field widths for each of the fields in - this layer:: - - >>> layer.field_widths - [80, 11, 24, 10] - - .. attribute:: field_precisions - - Returns a list of the numeric precisions for each of the fields in - this layer. This is meaningless (and set to zero) for non-numeric - fields:: - - >>> layer.field_precisions - [0, 0, 15, 0] - - .. attribute:: extent - - Returns the spatial extent of this layer, as an :class:`Envelope` - object:: - - >>> layer.extent.tuple - (-104.609252, 29.763374, -95.23506, 38.971823) - - .. attribute:: srs - - Property that returns the :class:`SpatialReference` associated - with this layer:: - - >>> print layer.srs - GEOGCS["GCS_WGS_1984", - DATUM["WGS_1984", - SPHEROID["WGS_1984",6378137,298.257223563]], - PRIMEM["Greenwich",0], - UNIT["Degree",0.017453292519943295]] - - If the :class:`Layer` has no spatial reference information associated - with it, ``None`` is returned. - - .. attribute:: spatial_filter - - .. versionadded:: 1.2 - - Property that may be used to retrieve or set a spatial filter for this - layer. A spatial filter can only be set with an :class:`OGRGeometry` - instance, a 4-tuple extent, or ``None``. When set with something - other than ``None``, only features that intersect the filter will be - returned when iterating over the layer:: - - >>> print layer.spatial_filter - None - >>> print len(layer) - 3 - >>> [feat.get('Name') for feat in layer] - ['Pueblo', 'Lawrence', 'Houston'] - >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas - >>> layer.spatial_filter = ks_extent - >>> len(layer) - 1 - >>> [feat.get('Name') for feat in layer] - ['Lawrence'] - >>> layer.spatial_filter = None - >>> len(layer) - 3 - - .. method:: get_fields() - - A method that returns a list of the values of a given field for each - feature in the layer:: - - >>> layer.get_fields('Name') - ['Pueblo', 'Lawrence', 'Houston'] - - .. method:: get_geoms([geos=False]) - - A method that returns a list containing the geometry of each feature - in the layer. If the optional argument ``geos`` is set to ``True`` - then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry` - objects. Otherwise, they are returned as :class:`OGRGeometry` objects:: - - >>> [pt.tuple for pt in layer.get_geoms()] - [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)] - - .. method:: test_capability(capability) - - Returns a boolean indicating whether this layer supports the - given capability (a string). Examples of valid capability strings - include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``, - ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``, - ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and - ``'FastSetNextByIndex'``. - -``Feature`` ------------ - -.. class:: Feature - - - ``Feature`` wraps an OGR feature. You never create a ``Feature`` - object directly. Instead, you retrieve them from a :class:`Layer` object. - Each feature consists of a geometry and a set of fields containing - additional properties. The geometry of a field is accessible via its - ``geom`` property, which returns an :class:`OGRGeometry` object. A ``Feature`` - behaves like a standard Python container for its fields, which it returns as - :class:`Field` objects: you can access a field directly by its index or name, - or you can iterate over a feature's fields, e.g. in a ``for`` loop. - - .. attribute:: geom - - Returns the geometry for this feature, as an ``OGRGeometry`` object:: - - >>> city.geom.tuple - (-104.609252, 38.255001) - - .. attribute:: get - - A method that returns the value of the given field (specified by name) - for this feature, **not** a ``Field`` wrapper object:: - - >>> city.get('Population') - 102121 - - .. attribute:: geom_type - - Returns the type of geometry for this feature, as an :class:`OGRGeomType` - object. This will be the same for all features in a given layer, and - is equivalent to the :attr:`Layer.geom_type` property of the - :class:`Layer`` object the feature came from. - - .. attribute:: num_fields - - Returns the number of fields of data associated with the feature. - This will be the same for all features in a given layer, and is - equivalent to the :attr:`Layer.num_fields` property of the - :class:`Layer` object the feature came from. - - .. attribute:: fields - - Returns a list of the names of the fields of data associated with the - feature. This will be the same for all features in a given layer, and - is equivalent to the :attr:`Layer.fields` property of the :class:`Layer` - object the feature came from. - - .. attribute:: fid - - Returns the feature identifier within the layer:: - - >>> city.fid - 0 - - .. attribute:: layer_name - - Returns the name of the :class:`Layer` that the feature came from. - This will be the same for all features in a given layer:: - - >>> city.layer_name - 'cities' - - .. attribute:: index - - A method that returns the index of the given field name. This will be - the same for all features in a given layer:: - - >>> city.index('Population') - 1 - -``Field`` ---------- - -.. class:: Field - - .. attribute:: name - - Returns the name of this field:: - - >>> city['Name'].name - 'Name' - - .. attribute:: type - - Returns the OGR type of this field, as an integer. The - ``FIELD_CLASSES`` dictionary maps these values onto - subclasses of ``Field``:: - - >>> city['Density'].type - 2 - - .. attribute:: type_name - - Returns a string with the name of the data type of this field:: - - >>> city['Name'].type_name - 'String' - - .. attribute:: value - - Returns the value of this field. The ``Field`` class itself - returns the value as a string, but each subclass returns the - value in the most appropriate form:: - - >>> city['Population'].value - 102121 - - .. attribute:: width - - Returns the width of this field:: - - >>> city['Name'].width - 80 - - .. attribute:: precision - - Returns the numeric precision of this field. This is meaningless (and - set to zero) for non-numeric fields:: - - >>> city['Density'].precision - 15 - - .. method:: as_double() - - Returns the value of the field as a double (float):: - - >>> city['Density'].as_double() - 874.7 - - .. method:: as_int() - - Returns the value of the field as an integer:: - - >>> city['Population'].as_int() - 102121 - - .. method:: as_string() - - Returns the value of the field as a string:: - - >>> city['Name'].as_string() - 'Pueblo' - - .. method:: as_datetime() - - Returns the value of the field as a tuple of date and time components:: - - >>> city['Created'].as_datetime() - (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0)) - -``Driver`` ----------- - -.. class:: Driver(dr_input) - - The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver. - - .. attribute:: driver_count - - Returns the number of OGR vector drivers currently registered. - - -OGR Geometries -============== - -``OGRGeometry`` ---------------- - -:class:`OGRGeometry` objects share similar functionality with -:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin -wrappers around OGR's internal geometry representation. Thus, -they allow for more efficient access to data when using :class:`DataSource`. -Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference -systems and coordinate transformation:: - - >>> from django.contrib.gis.gdal import OGRGeometry - >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))') - -.. class:: OGRGeometry(geom_input[, srs=None]) - - This object is a wrapper for the `OGR Geometry`__ class. - These objects are instantiated directly from the given ``geom_input`` - parameter, which may be a string containing WKT or HEX, a ``buffer`` - containing WKB data, or an :class:`OGRGeomType` object. These objects - are also returned from the :class:`Feature.geom` attribute, when - reading vector data from :class:`Layer` (which is in turn a part of - a :class:`DataSource`). - - __ http://www.gdal.org/ogr/classOGRGeometry.html - - .. classmethod:: from_bbox(bbox) - - .. versionadded:: 1.1 - - Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple). - - .. method:: __len__ - - Returns the number of points in a :class:`LineString`, the - number of rings in a :class:`Polygon`, or the number of geometries in a - :class:`GeometryCollection`. Not applicable to other geometry types. - - .. method:: __iter__ - - Iterates over the points in a :class:`LineString`, the rings in a - :class:`Polygon`, or the geometries in a :class:`GeometryCollection`. - Not applicable to other geometry types. - - .. method:: __getitem__ - - Returns the point at the specified index for a :class:`LineString`, the - interior ring at the specified index for a :class:`Polygon`, or the geometry - at the specified index in a :class:`GeometryCollection`. Not applicable to - other geometry types. - - .. attribute:: dimension - - Returns the number of coordinated dimensions of the geometry, i.e. 0 - for points, 1 for lines, and so forth:: - - >> polygon.dimension - 2 - - .. attribute:: coord_dim - - .. versionchanged:: 1.2 - - Returns or sets the coordinate dimension of this geometry. For - example, the value would be 2 for two-dimensional geometries. - - .. note:: - - Setting this property is only available in versions 1.2 and above. - - .. attribute:: geom_count - - Returns the number of elements in this geometry:: - - >>> polygon.geom_count - 1 - - .. attribute:: point_count - - Returns the number of points used to describe this geometry:: - - >>> polygon.point_count - 4 - - .. attribute:: num_points - - Alias for :attr:`point_count`. - - .. attribute:: num_coords - - Alias for :attr:`point_count`. - - .. attribute:: geom_type - - Returns the type of this geometry, as an :class:`OGRGeomType` object. - - .. attribute:: geom_name - - Returns the name of the type of this geometry:: - - >>> polygon.geom_name - 'POLYGON' - - .. attribute:: area - - Returns the area of this geometry, or 0 for geometries that do not - contain an area:: - - >>> polygon.area - 25.0 - - .. attribute:: envelope - - Returns the envelope of this geometry, as an :class:`Envelope` object. - - .. attribute:: extent - - Returns the envelope of this geometry as a 4-tuple, instead of as an - :class:`Envelope` object:: - - >>> point.extent - (0.0, 0.0, 5.0, 5.0) - - .. attribute:: srs - - This property controls the spatial reference for this geometry, or - ``None`` if no spatial reference system has been assigned to it. - If assigned, accessing this property returns a :class:`SpatialReference` - object. It may be set with another :class:`SpatialReference` object, - or any input that :class:`SpatialReference` accepts. Example:: - - >>> city.geom.srs.name - 'GCS_WGS_1984' - - .. attribute:: srid - - Returns or sets the spatial reference identifier corresponding to - :class:`SpatialReference` of this geometry. Returns ``None`` if - there is no spatial reference information associated with this - geometry, or if an SRID cannot be determined. - - .. attribute:: geos - - Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object - corresponding to this geometry. - - .. attribute:: gml - - Returns a string representation of this geometry in GML format:: - - >>> OGRGeometry('POINT(1 2)').gml - '<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>' - - .. attribute:: hex - - Returns a string representation of this geometry in HEX WKB format:: - - >>> OGRGeometry('POINT(1 2)').hex - '0101000000000000000000F03F0000000000000040' - - .. attribute:: json - - Returns a string representation of this geometry in JSON format:: - - >>> OGRGeometry('POINT(1 2)').json - '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }' - - - .. attribute:: kml - - .. versionadded:: 1.1 - - Returns a string representation of this geometry in KML format. - - .. attribute:: wkb_size - - Returns the size of the WKB buffer needed to hold a WKB representation - of this geometry:: - - >>> OGRGeometry('POINT(1 2)').wkb_size - 21 - - .. attribute:: wkb - - Returns a ``buffer`` containing a WKB representation of this geometry. - - .. attribute:: wkt - - Returns a string representation of this geometry in WKT format. - - .. attribute:: ewkt - - .. versionadded:: 1.2 - - Returns the EWKT representation of this geometry. - - .. method:: clone() - - Returns a new :class:`OGRGeometry` clone of this geometry object. - - .. method:: close_rings() - - If there are any rings within this geometry that have not been closed, - this routine will do so by adding the starting point to the end:: - - >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)') - >>> triangle.close_rings() - >>> triangle.wkt - 'LINEARRING (0 0,0 1,1 0,0 0)' - - .. method:: transform(coord_trans, clone=False) - - Transforms this geometry to a different spatial reference system. May - take a :class:`CoordTransform` object, a :class:`SpatialReference` object, - or any other input accepted by :class:`SpatialReference` (including - spatial reference WKT and PROJ.4 strings, or an integer SRID). - By default nothing is returned and the geometry is transformed in-place. - However, if the `clone` keyword is set to ``True`` then a transformed clone - of this geometry is returned instead. - - .. method:: intersects(other) - - Returns ``True`` if this geometry intersects the other, otherwise returns - ``False``. - - .. method:: equals(other) - - Returns ``True`` if this geometry is equivalent to the other, otherwise returns - ``False``. - - .. method:: disjoint(other) - - Returns ``True`` if this geometry is spatially disjoint to (i.e. does - not intersect) the other, otherwise returns ``False``. - - .. method:: touches(other) - - Returns ``True`` if this geometry touches the other, otherwise returns - ``False``. - - .. method:: crosses(other) - - Returns ``True`` if this geometry crosses the other, otherwise returns - ``False``. - - .. method:: within(other) - - Returns ``True`` if this geometry is contained within the other, otherwise returns - ``False``. - - .. method:: contains(other) - - Returns ``True`` if this geometry contains the other, otherwise returns - ``False``. - - .. method:: overlaps(other) - - Returns ``True`` if this geometry overlaps the other, otherwise returns - ``False``. - - .. method:: boundary - - The boundary of this geometry, as a new :class:`OGRGeometry` object. - - .. attribute:: convex_hull - - The smallest convex polygon that contains this geometry, as a new - :class:`OGRGeometry` object. - - .. method:: difference - - Returns the region consisting of the difference of this geometry and - the other, as a new :class:`OGRGeometry` object. - - .. method:: intersection - - Returns the region consisting of the intersection of this geometry and - the other, as a new :class:`OGRGeometry` object. - - .. method:: sym_difference - - Returns the region consisting of the symmetric difference of this - geometry and the other, as a new :class:`OGRGeometry` object. - - .. method:: union - - Returns the region consisting of the union of this geometry and - the other, as a new :class:`OGRGeometry` object. - - .. attribute:: tuple - - Returns the coordinates of a point geometry as a tuple, the - coordinates of a line geometry as a tuple of tuples, and so forth:: - - >>> OGRGeometry('POINT (1 2)').tuple - (1.0, 2.0) - >>> OGRGeometry('LINESTRING (1 2,3 4)').tuple - ((1.0, 2.0), (3.0, 4.0)) - - .. attribute:: coords - - An alias for :attr:`tuple`. - -.. class:: Point - - .. attribute:: x - - Returns the X coordinate of this point:: - - >>> OGRGeometry('POINT (1 2)').x - 1.0 - - .. attribute:: y - - Returns the Y coordinate of this point:: - - >>> OGRGeometry('POINT (1 2)').y - 2.0 - - .. attribute:: z - - Returns the Z coordinate of this point, or ``None`` if the - the point does not have a Z coordinate:: - - >>> OGRGeometry('POINT (1 2 3)').z - 3.0 - -.. class:: LineString - - .. attribute:: x - - Returns a list of X coordinates in this line:: - - >>> OGRGeometry('LINESTRING (1 2,3 4)').x - [1.0, 3.0] - - .. attribute:: y - - Returns a list of Y coordinates in this line:: - - >>> OGRGeometry('LINESTRING (1 2,3 4)').y - [2.0, 4.0] - - .. attribute:: z - - Returns a list of Z coordinates in this line, or ``None`` if the - line does not have Z coordinates:: - - >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z - [3.0, 6.0] - - -.. class:: Polygon - - .. attribute:: shell - - Returns the shell or exterior ring of this polygon, as a ``LinearRing`` - geometry. - - .. attribute:: exterior_ring - - An alias for :attr:`shell`. - - .. attribute:: centroid - - Returns a :class:`Point` representing the centroid of this polygon. - -.. class:: GeometryCollection - - .. method:: add(geom) - - Adds a geometry to this geometry collection. Not applicable to other - geometry types. - - -``OGRGeomType`` ---------------- - -.. class:: OGRGeomType(type_input) - - This class allows for the representation of an OGR geometry type - in any of several ways:: - - >>> from django.contrib.gis.gdal import OGRGeomType - >>> gt1 = OGRGeomType(3) # Using an integer for the type - >>> gt2 = OGRGeomType('Polygon') # Using a string - >>> gt3 = OGRGeomType('POLYGON') # It's case-insensitive - >>> print gt1 == 3, gt1 == 'Polygon' # Equivalence works w/non-OGRGeomType objects - True True - - .. attribute:: name - - Returns a short-hand string form of the OGR Geometry type:: - - >>> gt1.name - 'Polygon' - - .. attribute:: num - - Returns the number corresponding to the OGR geometry type:: - - >>> gt1.num - 3 - - .. attribute:: django - - Returns the Django field type (a subclass of GeometryField) to use for - storing this OGR type, or ``None`` if there is no appropriate Django - type:: - - >>> gt1.django - 'PolygonField' - -``Envelope`` ------------- - -.. class:: Envelope(*args) - - Represents an OGR Envelope structure that contains the - minimum and maximum X, Y coordinates for a rectangle bounding box. - The naming of the variables is compatible with the OGR Envelope - C structure. - - .. attribute:: min_x - - The value of the minimum X coordinate. - - .. attribute:: min_y - - The value of the maximum X coordinate. - - .. attribute:: max_x - - The value of the minimum Y coordinate. - - .. attribute:: max_y - - The value of the maximum Y coordinate. - - .. attribute:: ur - - The upper-right coordinate, as a tuple. - - .. attribute:: ll - - The lower-left coordinate, as a tuple. - - .. attribute:: tuple - - A tuple representing the envelope. - - .. attribute:: wkt - - A string representing this envelope as a polygon in WKT format. - - - .. method:: expand_to_include(self, *args) - - .. versionadded:: 1.1 - -Coordinate System Objects -========================= - -``SpatialReference`` --------------------- - -.. class:: SpatialReference(srs_input) - - Spatial reference objects are initialized on the given ``srs_input``, - which may be one of the following: - - * OGC Well Known Text (WKT) (a string) - * EPSG code (integer or string) - * PROJ.4 string - * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, ``'NAD27'``, ``'NAD83'``) - - Example:: - - >>> wgs84 = SpatialReference('WGS84') # shorthand string - >>> wgs84 = SpatialReference(4326) # EPSG code - >>> wgs84 = SpatialReference('EPSG:4326') # EPSG string - >>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ' - >>> wgs84 = SpatialReference(proj4) # PROJ.4 string - >>> wgs84 = SpatialReference("""GEOGCS["WGS 84", - DATUM["WGS_1984", - SPHEROID["WGS 84",6378137,298.257223563, - AUTHORITY["EPSG","7030"]], - AUTHORITY["EPSG","6326"]], - PRIMEM["Greenwich",0, - AUTHORITY["EPSG","8901"]], - UNIT["degree",0.01745329251994328, - AUTHORITY["EPSG","9122"]], - AUTHORITY["EPSG","4326"]]""") # OGC WKT - - .. method:: __getitem__(target) - - Returns the value of the given string attribute node, ``None`` if the node - doesn't exist. Can also take a tuple as a parameter, (target, child), - where child is the index of the attribute in the WKT. For example:: - - >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]') - >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326 - >>> print srs['GEOGCS'] - WGS 84 - >>> print srs['DATUM'] - WGS_1984 - >>> print srs['AUTHORITY'] - EPSG - >>> print srs['AUTHORITY', 1] # The authority value - 4326 - >>> print srs['TOWGS84', 4] # the fourth value in this wkt - 0 - >>> print srs['UNIT|AUTHORITY'] # For the units authority, have to use the pipe symbole. - EPSG - >>> print srs['UNIT|AUTHORITY', 1] # The authority value for the untis - 9122 - - .. method:: attr_value(target, index=0) - - The attribute value for the given target node (e.g. ``'PROJCS'``). - The index keyword specifies an index of the child node to return. - - .. method:: auth_name(target) - - Returns the authority name for the given string target node. - - .. method:: auth_code(target) - - Returns the authority code for the given string target node. - - .. method:: clone() - - Returns a clone of this spatial reference object. - - .. method:: identify_epsg() - - This method inspects the WKT of this SpatialReference, and will - add EPSG authority nodes where an EPSG identifier is applicable. - - .. method:: from_esri() - - Morphs this SpatialReference from ESRI's format to EPSG - - .. method:: to_esri() - - Morphs this SpatialReference to ESRI's format. - - .. method:: validate() - - Checks to see if the given spatial reference is valid, if not - an exception will be raised. - - .. method:: import_epsg(epsg) - - Import spatial reference from EPSG code. - - .. method:: import_proj(proj) - - Import spatial reference from PROJ.4 string. - - .. method:: import_user_input(user_input) - - .. versionadded:: 1.1 - - .. method:: import_wkt(wkt) - - Import spatial reference from WKT. - - .. method:: import_xml(xml) - - Import spatial reference from XML. - - .. attribute:: name - - Returns the name of this Spatial Reference. - - .. attribute:: srid - - Returns the SRID of top-level authority, or ``None`` if undefined. - - .. attribute:: linear_name - - Returns the name of the linear units. - - .. attribute:: linear_units - - Returns the value of the linear units. - - .. attribute:: angular_name - - Returns the name of the angular units." - - .. attribute:: angular_units - - Returns the value of the angular units. - - .. attribute:: units - - Returns a 2-tuple of the units value and the units name, - and will automatically determines whether to return the linear - or angular units. - - .. attribute:: ellisoid - - Returns a tuple of the ellipsoid parameters for this spatial - reference: (semimajor axis, semiminor axis, and inverse flattening) - - .. attribute:: semi_major - - Returns the semi major axis of the ellipsoid for this spatial reference. - - .. attribute:: semi_minor - - Returns the semi minor axis of the ellipsoid for this spatial reference. - - .. attribute:: inverse_flattening - - Returns the inverse flattening of the ellipsoid for this spatial reference. - - .. attribute:: geographic - - Returns ``True`` if this spatial reference is geographic - (root node is ``GEOGCS``). - - .. attribute:: local - - Returns ``True`` if this spatial reference is local - (root node is ``LOCAL_CS``). - - .. attribute:: projected - - Returns ``True`` if this spatial reference is a projected coordinate - system (root node is ``PROJCS``). - - .. attribute:: wkt - - Returns the WKT representation of this spatial reference. - - .. attribute:: pretty_wkt - - Returns the 'pretty' representation of the WKT. - - .. attribute:: proj - - Returns the PROJ.4 representation for this spatial reference. - - .. attribute:: proj4 - - Alias for :attr:`SpatialReference.proj`. - - .. attribute:: xml - - Returns the XML representation of this spatial reference. - - -``CoordTransform`` ------------------- - -.. class:: CoordTransform(source, target) - -Represents a coordinate system transform. It is initialized with two -:class:`SpatialReference`, representing the source and target coordinate -systems, respectively. These objects should be used when performing -the same coordinate transformation repeatedly on different geometries:: - - >>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83')) - >>> for feat in layer: - ... geom = feat.geom # getting clone of feature geometry - ... geom.transform(ct) # transforming - -Settings -======== - -.. setting:: GDAL_LIBRARY_PATH - -GDAL_LIBRARY_PATH ------------------ - -A string specifying the location of the GDAL library. Typically, -this setting is only used if the GDAL library is in a non-standard -location (e.g., ``/home/john/lib/libgdal.so``). diff --git a/parts/django/docs/ref/contrib/gis/geoip.txt b/parts/django/docs/ref/contrib/gis/geoip.txt deleted file mode 100644 index 784d69e..0000000 --- a/parts/django/docs/ref/contrib/gis/geoip.txt +++ /dev/null @@ -1,223 +0,0 @@ -.. _ref-geoip: - -====================== -Geolocation with GeoIP -====================== - -.. module:: django.contrib.gis.utils.geoip - :synopsis: High-level Python interface for MaxMind's GeoIP C library. - -.. currentmodule:: django.contrib.gis.utils - -The :class:`GeoIP` object is a ctypes wrapper for the -`MaxMind GeoIP C API`__. [#]_ This interface is a BSD-licensed alternative -to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind. - -In order to perform IP-based geolocation, the :class:`GeoIP` object requires -the GeoIP C libary and either the GeoIP `Country`__ or `City`__ -datasets in binary format (the CSV files will not work!). These datasets may be -`downloaded from MaxMind`__. Grab the ``GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz`` -and unzip them in a directory corresponding to what you set -``GEOIP_PATH`` with in your settings. See the example and reference below -for more details. - -__ http://www.maxmind.com/app/c -__ http://www.maxmind.com/app/python -__ http://www.maxmind.com/app/country -__ http://www.maxmind.com/app/city -__ http://www.maxmind.com/download/geoip/database/ - -Example -======= - -Assuming you have the GeoIP C library installed, here is an example of its -usage:: - - >>> from django.contrib.gis.utils import GeoIP - >>> g = GeoIP() - >>> g.country('google.com') - {'country_code': 'US', 'country_name': 'United States'} - >>> g.city('72.14.207.99') - {'area_code': 650, - 'city': 'Mountain View', - 'country_code': 'US', - 'country_code3': 'USA', - 'country_name': 'United States', - 'dma_code': 807, - 'latitude': 37.419200897216797, - 'longitude': -122.05740356445312, - 'postal_code': '94043', - 'region': 'CA'} - >>> g.lat_lon('salon.com') - (37.789798736572266, -122.39420318603516) - >>> g.lon_lat('uh.edu') - (-95.415199279785156, 29.77549934387207) - >>> g.geos('24.124.1.80').wkt - 'POINT (-95.2087020874023438 39.0392990112304688)' - -``GeoIP`` Settings -================== - -.. setting:: GEOIP_PATH - -GEOIP_PATH ----------- - -A string specifying the directory where the GeoIP data files are -located. This setting is *required* unless manually specified -with ``path`` keyword when initializing the :class:`GeoIP` object. - -.. setting:: GEOIP_LIBRARY_PATH - -GEOIP_LIBRARY_PATH ------------------- - -A string specifying the location of the GeoIP C library. Typically, -this setting is only used if the GeoIP C library is in a non-standard -location (e.g., ``/home/sue/lib/libGeoIP.so``). - -.. setting:: GEOIP_COUNTRY - -GEOIP_COUNTRY -------------- - -The basename to use for the GeoIP country data file. -Defaults to ``'GeoIP.dat'``. - -.. setting:: GEOIP_CITY - -GEOIP_CITY ----------- - -The basename to use for the GeoIP city data file. -Defaults to ``'GeoLiteCity.dat'``. - -``GeoIP`` API -============= - -.. class:: GeoIP([path=None, cache=0, country=None, city=None]) - -The ``GeoIP`` object does not require any parameters to use the default -settings. However, at the very least the :setting:`GEOIP_PATH` setting -should be set with the path of the location of your GeoIP data sets. The -following intialization keywords may be used to customize any of the -defaults. - -=================== ======================================================= -Keyword Arguments Description -=================== ======================================================= -``path`` Base directory to where GeoIP data is located or the - full path to where the city or country data files - (.dat) are located. Assumes that both the city and - country data sets are located in this directory; - overrides the :setting:`GEOIP_PATH` settings attribute. - -``cache`` The cache settings when opening up the GeoIP datasets, - and may be an integer in (0, 1, 2, 4) corresponding to - the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``, - ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE`` - ``GeoIPOptions`` C API settings, respectively. - Defaults to 0 (``GEOIP_STANDARD``). - -``country`` The name of the GeoIP country data file. Defaults - to ``GeoIP.dat``. Setting this keyword overrides the - :setting:`GEOIP_COUNTRY` settings attribute. - -``city`` The name of the GeoIP city data file. Defaults to - ``GeoLiteCity.dat``. Setting this keyword overrides - the :setting:`GEOIP_CITY` settings attribute. -=================== ======================================================= - -``GeoIP`` Methods -================= - -Querying --------- - -All the following querying routines may take either a string IP address -or a fully qualified domain name (FQDN). For example, both -``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query -parameters. - -.. method:: GeoIP.city(query) - -Returns a dictionary of city information for the given query. Some -of the values in the dictionary may be undefined (``None``). - -.. method:: GeoIPcountry(query) - -Returns a dictionary with the country code and country for the given -query. - -.. method:: GeoIP.country_code(query) - -Returns only the country code corresponding to the query. - -.. method:: GeoIP.country_name(query) - -Returns only the country name corresponding to the query. - -Coordinate Retrieval --------------------- - -.. method:: GeoIP.coords(query) - -Returns a coordinate tuple of (longitude, latitude). - -.. method:: GeoIP.lon_lat(query) - -Returns a coordinate tuple of (longitude, latitude). - -.. method:: GeoIP.lat_lon(query) - -Returns a coordinate tuple of (latitude, longitude), - -.. method:: GeoIP.geos(query) - -Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query. - -Database Information --------------------- - -.. attribute:: GeoIP.country_info - -This property returns information about the GeoIP country database. - -.. attribute:: GeoIP.city_info - -This property returns information about the GeoIP city database. - -.. attribute:: GeoIP.info - -This property returns information about all GeoIP databases (both city -and country). - -GeoIP-Python API compatibility methods ----------------------------------------- - -These methods exist to ease compatibility with any code using MaxMind's -existing Python API. - -.. classmethod:: GeoIP.open(path, cache) - -This classmethod instantiates the GeoIP object from the given database path -and given cache setting. - -.. method:: GeoIP.region_by_addr(query) - -.. method:: GeoIP.region_by_name(query) - -.. method:: GeoIP.record_by_addr(query) - -.. method:: GeoIP.record_by_name(query) - -.. method:: GeoIP.country_code_by_addr(query) - -.. method:: GeoIP.country_code_by_name(query) - -.. method:: GeoIP.country_name_by_addr(query) - -.. method:: GeoIP.country_name_by_name(query) - -.. rubric:: Footnotes -.. [#] GeoIP(R) is a registered trademark of MaxMind, LLC of Boston, Massachusetts. diff --git a/parts/django/docs/ref/contrib/gis/geoquerysets.txt b/parts/django/docs/ref/contrib/gis/geoquerysets.txt deleted file mode 100644 index 69f0c02..0000000 --- a/parts/django/docs/ref/contrib/gis/geoquerysets.txt +++ /dev/null @@ -1,1256 +0,0 @@ -.. _ref-geoquerysets: - -========================= -GeoQuerySet API Reference -========================= - -.. currentmodule:: django.contrib.gis.db.models - -.. class:: GeoQuerySet([model=None]) - - -.. _spatial-lookups: - -Spatial Lookups -=============== - -Just like when using the the :ref:`queryset-api`, interaction -with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`. -Instead of the regular Django :ref:`field-lookups`, the -spatial lookups in this section are available for :class:`GeometryField`. - -For an introduction, see the :ref:`spatial lookups introduction -<spatial-lookups-intro>`. For an overview of what lookups are -compatible with a particular spatial backend, refer to the -:ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`. - -.. fieldlookup:: bbcontains - -bbcontains ----------- - -*Availability*: PostGIS, MySQL, SpatiaLite - -Tests if the geometry field's bounding box completely contains the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__bbcontains=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``poly ~ geom`` -MySQL ``MBRContains(poly, geom)`` -SpatiaLite ``MbrContains(poly, geom)`` -========== ========================== - -.. fieldlookup:: bboverlaps - -bboverlaps ----------- - -*Availability*: PostGIS, MySQL, SpatiaLite - -Tests if the geometry field's bounding box overlaps the lookup geometry's -bounding box. - -Example:: - - Zipcode.objects.filter(poly__bboverlaps=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``poly && geom`` -MySQL ``MBROverlaps(poly, geom)`` -SpatiaLite ``MbrOverlaps(poly, geom)`` -========== ========================== - -.. fieldlookup:: contained - -contained ---------- - -*Availability*: PostGIS, MySQL, SpatiaLite - -Tests if the geometry field's bounding box is completely contained by the -lookup geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__contained=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``poly @ geom`` -MySQL ``MBRWithin(poly, geom)`` -SpatiaLite ``MbrWithin(poly, geom)`` -========== ========================== - -.. fieldlookup:: gis-contains - -contains --------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -Tests if the geometry field spatially contains the lookup geometry. - -Example:: - - Zipcode.objects.filter(poly__contains=geom) - -========== ============================ -Backend SQL Equivalent -========== ============================ -PostGIS ``ST_Contains(poly, geom)`` -Oracle ``SDO_CONTAINS(poly, geom)`` -MySQL ``MBRContains(poly, geom)`` -SpatiaLite ``Contains(poly, geom)`` -========== ============================ - -.. fieldlookup:: contains_properly - -contains_properly ------------------ - -.. versionadded:: 1.2 - -*Availability*: PostGIS - -Returns true if the lookup geometry intersects the interior of the -geometry field, but not the boundary (or exterior). [#fncontainsproperly]_ - -.. note:: - - Requires PostGIS 1.4 and above. - -Example:: - - Zipcode.objects.filter(poly__contains_properly=geom) - -========== =================================== -Backend SQL Equivalent -========== =================================== -PostGIS ``ST_ContainsProperly(poly, geom)`` -========== =================================== - -.. fieldlookup:: coveredby - -coveredby ---------- - -*Availability*: PostGIS, Oracle - -Tests if no point in the geometry field is outside the lookup geometry. -[#fncovers]_ - -Example:: - - Zipcode.objects.filter(poly__coveredby=geom) - -========== ============================= -Backend SQL Equivalent -========== ============================= -PostGIS ``ST_CoveredBy(poly, geom)`` -Oracle ``SDO_COVEREDBY(poly, geom)`` -========== ============================= - -.. fieldlookup:: covers - -covers ------- - -*Availability*: PostGIS, Oracle - -Tests if no point in the lookup geometry is outside the geometry field. -[#fncovers]_ - -Example:: - - Zipcode.objects.filter(poly__covers=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``ST_Covers(poly, geom)`` -Oracle ``SDO_COVERS(poly, geom)`` -========== ========================== - -.. fieldlookup:: crosses - -crosses -------- - -*Availability*: PostGIS, SpatiaLite - -Tests if the geometry field spatially crosses the lookup geometry. - -Example:: - - Zipcode.objects.filter(poly__crosses=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``ST_Crosses(poly, geom)`` -SpatiaLite ``Crosses(poly, geom)`` -========== ========================== - -.. fieldlookup:: disjoint - -disjoint --------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -Tests if the geometry field is spatially disjoint from the lookup geometry. - -Example:: - - Zipcode.objects.filter(poly__disjoint=geom) - -========== ================================================= -Backend SQL Equivalent -========== ================================================= -PostGIS ``ST_Disjoint(poly, geom)`` -Oracle ``SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)`` -MySQL ``MBRDisjoint(poly, geom)`` -SpatiaLite ``Disjoint(poly, geom)`` -========== ================================================= - -equals ------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -.. fieldlookup:: exact -.. fieldlookup:: same_as - -exact, same_as --------------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -.. fieldlookup:: intersects - -intersects ----------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -Tests if the geometry field spatially intersects the lookup geometry. - -Example:: - - Zipcode.objects.filter(poly__intersects=geom) - -========== ================================================= -Backend SQL Equivalent -========== ================================================= -PostGIS ``ST_Intersects(poly, geom)`` -Oracle ``SDO_OVERLAPBDYINTERSECT(poly, geom)`` -MySQL ``MBRIntersects(poly, geom)`` -SpatiaLite ``Intersects(poly, geom)`` -========== ================================================= - -.. fieldlookup:: overlaps - -overlaps --------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -.. fieldlookup:: relate - -relate ------- - -*Availability*: PostGIS, Oracle, SpatiaLite - -Tests if the geometry field is spatially related to the the lookup geometry by -the values given in the given pattern. This lookup requires a tuple parameter, -``(geom, pattern)``; the form of ``pattern`` will depend on the spatial backend: - -PostGIS & SpatiaLite -~~~~~~~~~~~~~~~~~~~~ -On these spatial backends the intersection pattern is a string comprising -nine characters, which define intersections between the interior, boundary, -and exterior of the geometry field and the lookup geometry. -The intersection pattern matrix may only use the following characters: -``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune" -a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_ - -Example:: - - # A tuple lookup parameter is used to specify the geometry and - # the intersection pattern (the pattern here is for 'contains'). - Zipcode.objects.filter(poly__relate(geom, 'T*T***FF*')) - -PostGIS SQL equivalent:: - - SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*') - -SpatiaLite SQL equivalent:: - - SELECT ... WHERE Relate(poly, geom, 'T*T***FF*') - -Oracle -~~~~~~ - -Here the relation pattern is compreised at least one of the nine relation -strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, -``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and -``ANYINTERACT``. Multiple strings may be combined with the logical Boolean -operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation -strings are case-insensitive. - -Example:: - - Zipcode.objects.filter(poly__relate(geom, 'anyinteract')) - -Oracle SQL equivalent:: - - SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract') - -.. fieldlookup:: touches - -touches -------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -Tests if the geometry field spatially touches the lookup geometry. - -Example:: - - Zipcode.objects.filter(poly__touches=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``ST_Touches(poly, geom)`` -MySQL ``MBRTouches(poly, geom)`` -Oracle ``SDO_TOUCH(poly, geom)`` -SpatiaLite ``Touches(poly, geom)`` -========== ========================== - -.. fieldlookup:: within - -within ------- - -*Availability*: PostGIS, Oracle, MySQL, SpatiaLite - -Tests if the geometry field is spatially within the lookup geometry. - -Example:: - - Zipcode.objects.filter(poly__within=geom) - -========== ========================== -Backend SQL Equivalent -========== ========================== -PostGIS ``ST_Within(poly, geom)`` -MySQL ``MBRWithin(poly, geom)`` -Oracle ``SDO_INSIDE(poly, geom)`` -SpatiaLite ``Within(poly, geom)`` -========== ========================== - -.. fieldlookup:: left - -left ----- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box is strictly to the left of the -lookup geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__left=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly << geom - -.. fieldlookup:: right - -right ------ - -*Availability*: PostGIS - -Tests if the geometry field's bounding box is strictly to the right of the -lookup geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__right=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly >> geom - -.. fieldlookup:: overlaps_left - -overlaps_left -------------- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box overlaps or is to the left of the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__overlaps_left=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly &< geom - - -.. fieldlookup:: overlaps_right - -overlaps_right --------------- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box overlaps or is to the right of the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__overlaps_right=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly &> geom - -.. fieldlookup:: overlaps_above - -overlaps_above --------------- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box overlaps or is above the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__overlaps_above=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly |&> geom - -.. fieldlookup:: overlaps_below - -overlaps_below --------------- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box overlaps or is below the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__overlaps_below=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly &<| geom - -.. fieldlookup:: strictly_above - -strictly_above --------------- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box is strictly above the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__strictly_above=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly |>> geom - -.. fieldlookup:: strictly_below - -strictly_below --------------- - -*Availability*: PostGIS - -Tests if the geometry field's bounding box is strictly above the lookup -geometry's bounding box. - -Example:: - - Zipcode.objects.filter(poly__strictly_above=geom) - -PostGIS equivalent:: - - SELECT ... WHERE poly |>> geom - - -.. _distance-lookups: - -Distance Lookups -================ - -*Availability*: PostGIS, Oracle, SpatiaLite - -For an overview on performing distance queries, please refer to -the :ref:`distance queries introduction <distance-queries>`. - -Distance lookups take the following form:: - - <field>__<distance lookup>=(<geometry>, <distance value>[, 'spheroid']) - -The value passed into a distance lookup is a tuple; the first two -values are mandatory, and are the geometry to calculate distances to, -and a distance value (either a number in units of the field or a -:class:`~django.contrib.gis.measure.Distance` object). On every -distance lookup but :lookup:`dwithin`, an optional -third element, ``'spheroid'``, may be included to tell GeoDjango -to use the more accurate spheroid distance calculation functions on -fields with a geodetic coordinate system (e.g., ``ST_Distance_Spheroid`` -would be used instead of ``ST_Distance_Sphere``). - -.. fieldlookup:: distance_gt - -distance_gt ------------ - -Returns models where the distance to the geometry field from the lookup -geometry is greater than the given distance value. - -Example:: - - Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5))) - -========== =============================================== -Backend SQL Equivalent -========== =============================================== -PostGIS ``ST_Distance(poly, geom) > 5`` -Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5`` -SpatiaLite ``Distance(poly, geom) > 5`` -========== =============================================== - -.. fieldlookup:: distance_gte - -distance_gte ------------- - -Returns models where the distance to the geometry field from the lookup -geometry is greater than or equal to the given distance value. - -Example:: - - Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5))) - -========== ================================================ -Backend SQL Equivalent -========== ================================================ -PostGIS ``ST_Distance(poly, geom) >= 5`` -Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5`` -SpatiaLite ``Distance(poly, geom) >= 5`` -========== ================================================ - -.. fieldlookup:: distance_lt - -distance_lt ------------ - -Returns models where the distance to the geometry field from the lookup -geometry is less than the given distance value. - -Example:: - - Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5))) - -========== =============================================== -Backend SQL Equivalent -========== =============================================== -PostGIS ``ST_Distance(poly, geom) < 5`` -Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5`` -SpatiaLite ``Distance(poly, geom) < 5`` -========== =============================================== - -.. fieldlookup:: distance_lte - -distance_lte ------------- - -Returns models where the distance to the geometry field from the lookup -geometry is less than or equal to the given distance value. - -Example:: - - Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5))) - -========== ================================================ -Backend SQL Equivalent -========== ================================================ -PostGIS ``ST_Distance(poly, geom) <= 5`` -Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5`` -SpatiaLite ``Distance(poly, geom) <= 5`` -========== ================================================ - -.. fieldlookup:: dwithin - -dwithin -------- - -Returns models where the distance to the geometry field from the -lookup geometry are within the given distance from one another. - -Example:: - - Zipcode.objects.filter(poly__dwithin=(geom, D(m=5))) - -========== ====================================== -Backend SQL Equivalent -========== ====================================== -PostGIS ``ST_DWithin(poly, geom, 5)`` -Oracle ``SDO_WITHIN_DISTANCE(poly, geom, 5)`` -========== ====================================== - -.. note:: - - This lookup is not available on SpatiaLite. - -.. fieldlookup:: equals - - -``GeoQuerySet`` Methods -======================= - -``GeoQuerySet`` methods specify that a spatial operation be performed -on each patial operation on each geographic -field in the queryset and store its output in a new attribute on the model -(which is generally the name of the ``GeoQuerySet`` method). - -There are also aggregate ``GeoQuerySet`` methods which return a single value -instead of a queryset. This section will describe the API and availability -of every ``GeoQuerySet`` method available in GeoDjango. - -.. note:: - - What methods are available depend on your spatial backend. See - the :ref:`compatibility table <geoqueryset-method-compatibility>` - for more details. - -With a few exceptions, the following keyword arguments may be used with all -``GeoQuerySet`` methods: - -===================== ===================================================== -Keyword Argument Description -===================== ===================================================== -``field_name`` By default, ``GeoQuerySet`` methods use the first - geographic field encountered in the model. This - keyword should be used to specify another - geographic field (e.g., ``field_name='point2'``) - when there are multiple geographic fields in a model. - - On PostGIS, the ``field_name`` keyword may also be - used on geometry fields in models that are related - via a ``ForeignKey`` relation (e.g., - ``field_name='related__point'``). - -``model_att`` By default, ``GeoQuerySet`` methods typically attach - their output in an attribute with the same name as - the ``GeoQuerySet`` method. Setting this keyword - with the desired attribute name will override this - default behavior. For example, - ``qs = Zipcode.objects.centroid(model_att='c')`` will - attach the centroid of the ``Zipcode`` geometry field - in a ``c`` attribute on every model rather than in a - ``centroid`` attribute. - - This keyword is required if - a method name clashes with an existing - ``GeoQuerySet`` method -- if you wanted to use the - ``area()`` method on model with a ``PolygonField`` - named ``area``, for example. -===================== ===================================================== - -Measurement ------------ -*Availability*: PostGIS, Oracle, SpatiaLite - -``area`` -~~~~~~~~ - -.. method:: GeoQuerySet.area(**kwargs) - -Returns the area of the geographic field in an ``area`` attribute on -each element of this GeoQuerySet. - -``distance`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.distance(geom, **kwargs) - -This method takes a geometry as a parameter, and attaches a ``distance`` -attribute to every model in the returned queryset that contains the -distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry. - -In the following example (taken from the `GeoDjango distance tests`__), -the distance from the `Tasmanian`__ city of Hobart to every other -:class:`PointField` in the ``AustraliaCity`` queryset is calculated:: - - >>> pnt = AustraliaCity.objects.get(name='Hobart').point - >>> for city in AustraliaCity.objects.distance(pnt): print city.name, city.distance - Wollongong 990071.220408 m - Shellharbour 972804.613941 m - Thirroul 1002334.36351 m - Mittagong 975691.632637 m - Batemans Bay 834342.185561 m - Canberra 598140.268959 m - Melbourne 575337.765042 m - Sydney 1056978.87363 m - Hobart 0.0 m - Adelaide 1162031.83522 m - Hillsdale 1049200.46122 m - -.. note:: - - Because the ``distance`` attribute is a - :class:`~django.contrib.gis.measure.Distance` object, you can easily express - the value in the units of your choice. For example, ``city.distance.mi`` is - the distance value in miles and ``city.distance.km`` is the distance value - in kilometers. See the :ref:`ref-measure` for usage details and the list of - :ref:`supported_units`. - -__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py -__ http://en.wikipedia.org/wiki/Tasmania - -``length`` -~~~~~~~~~~ - -.. method:: GeoQuerySet.length(**kwargs) - -Returns the length of the geometry field in a ``length`` attribute -(a :class:`~django.contrib.gis.measure.Distance` object) on each model in -the queryset. - -``perimeter`` -~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.perimeter(**kwargs) - -Returns the perimeter of the geometry field in a ``perimeter`` attribute -(a :class:`~django.contrib.gis.measure.Distance` object) on each model in -the queryset. - -Geometry Relationships ----------------------- - -The following methods take no arguments, and attach geometry objects -each element of the :class:`GeoQuerySet` that is the result of relationship -function evaluated on the the geometry field. - -``centroid`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.centroid(**kwargs) - -*Availability*: PostGIS, Oracle, SpatiaLite - -Returns the ``centroid`` value for the geographic field in a ``centroid`` -attribute on each element of the ``GeoQuerySet``. - -``envelope`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.envelope(**kwargs) - -*Availability*: PostGIS, SpatiaLite - -Returns a geometry representing the bounding box of the geometry field in -an ``envelope`` attribute on each element of the ``GeoQuerySet``. - -``point_on_surface`` -~~~~~~~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.point_on_surface(**kwargs) - -*Availability*: PostGIS, Oracle, SpatiaLite - -Returns a Point geometry guaranteed to lie on the surface of the -geometry field in a ``point_on_surface`` attribute on each element -of the queryset; otherwise sets with None. - -Geometry Editors ----------------- - -``force_rhr`` -~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.force_rhr(**kwargs) - -.. versionadded:: 1.2 - -*Availability*: PostGIS - -Returns a modified version of the polygon/multipolygon in which all -of the vertices follow the Right-Hand-Rule, and attaches as a -``force_rhr`` attribute on each element of the queryset. - -``reverse_geom`` -~~~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.reverse_geom(**kwargs) - -.. versionadded:: 1.2 - -*Availability*: PostGIS, Oracle - -Reverse the coordinate order of the geometry field, and attaches as a -``reverse`` attribute on each element of the queryset. - -``scale`` -~~~~~~~~~ - -.. method:: GeoQuerySet.scale(x, y, z=0.0, **kwargs) - -*Availability*: PostGIS, SpatiaLite - -``snap_to_grid`` -~~~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.snap_to_grid(*args, **kwargs) - -.. versionadded:: 1.1 - -Snap all points of the input geometry to the grid. How the -geometry is snapped to the grid depends on how many numeric -(either float, integer, or long) arguments are given. - -=================== ===================================================== -Number of Arguments Description -=================== ===================================================== -1 A single size to snap bot the X and Y grids to. -2 X and Y sizes to snap the grid to. -4 X, Y sizes and the corresponding X, Y origins. -=================== ===================================================== - -``transform`` -~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.transform(srid=4326, **kwargs) - -*Availability*: PostGIS, Oracle, SpatiaLite - -The ``transform`` method transforms the geometry field of a model to the spatial -reference system specified by the ``srid`` parameter. If no ``srid`` is given, -then 4326 (WGS84) is used by default. - -.. note:: - - Unlike other ``GeoQuerySet`` methods, ``transform`` stores its output - "in-place". In other words, no new attribute for the transformed - geometry is placed on the models. - -.. note:: - - What spatial reference system an integer SRID corresponds to may depend on - the spatial database used. In other words, the SRID numbers used for Oracle - are not necessarily the same as those used by PostGIS. - -Example:: - - >>> qs = Zipcode.objects.all().transform() # Transforms to WGS84 - >>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central" - >>> print qs[0].poly.srid - 32140 - >>> print qs[0].poly - POLYGON ((234055.1698884720099159 4937796.9232223574072123 ... - -``translate`` -~~~~~~~~~~~~~ -.. method:: GeoQuerySet.translate(x, y, z=0.0, **kwargs) - -*Availability*: PostGIS, SpatiaLite - -Translates the geometry field to a new location using the given numeric -parameters as offsets. - -Geometry Operations -------------------- -*Availability*: PostGIS, Oracle, SpatiaLite - -The following methods all take a geometry as a parameter and attach a geometry -to each element of the ``GeoQuerySet`` that is the result of the operation. - -``difference`` -~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.difference(geom) - -Returns the spatial difference of the geographic field with the given -geometry in a ``difference`` attribute on each element of the -``GeoQuerySet``. - - -``intersection`` -~~~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.intersection(geom) - -Returns the spatial intersection of the geographic field with the -given geometry in an ``intersection`` attribute on each element of the -``GeoQuerySet``. - -``sym_difference`` -~~~~~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.sym_difference(geom) - -Returns the symmetric difference of the geographic field with the -given geometry in a ``sym_difference`` attribute on each element of the -``GeoQuerySet``. - -``union`` -~~~~~~~~~ - -.. method:: GeoQuerySet.union(geom) - -Returns the union of the geographic field with the given -geometry in an ``union`` attribute on each element of the -``GeoQuerySet``. - -Geometry Output ---------------- - -The following ``GeoQuerySet`` methods will return an attribute that has the value -of the geometry field in each model converted to the requested output format. - -``geohash`` -~~~~~~~~~~~ - -.. method:: GeoQuerySet.geohash(preceision=20, **kwargs) - -.. versionadded:: 1.2 - -Attaches a ``geohash`` attribute to every model the the queryset -containing the `GeoHash`__ representation of the geometry. - -__ http://geohash.org/ - -``geojson`` -~~~~~~~~~~~ - -.. method:: GeoQuerySet.geojson(**kwargs) - -.. versionadded:: 1.1 - -*Availability*: PostGIS - -Attaches a ``geojson`` attribute to every model in the queryset that contains the -`GeoJSON`__ representation of the geometry. - -===================== ===================================================== -Keyword Argument Description -===================== ===================================================== -``precision`` It may be used to specify the number of significant - digits for the coordinates in the GeoJSON - representation -- the default value is 8. - -``crs`` Set this to ``True`` if you want the coordinate - reference system to be included in the returned - GeoJSON. - -``bbox`` Set this to ``True`` if you want the bounding box - to be included in the returned GeoJSON. -===================== ===================================================== - -__ http://geojson.org/ - -``gml`` -~~~~~~~ - -.. method:: GeoQuerySet.gml(**kwargs) - -*Availability*: PostGIS, Oracle - -Attaches a ``gml`` attribute to every model in the queryset that contains the -`Geographic Markup Language (GML)`__ representation of the geometry. - -Example:: - - >>> qs = Zipcode.objects.all().gml() - >>> print qs[0].gml - <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ... -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon> - -===================== ===================================================== -Keyword Argument Description -===================== ===================================================== -``precision`` This keyword is for PostGIS only. It may be used - to specify the number of significant digits for the - coordinates in the GML representation -- the default - value is 8. - -``version`` This keyword is for PostGIS only. It may be used to - specify the GML version used, and may only be values - of 2 or 3. The default value is 2. -===================== ===================================================== - -__ http://en.wikipedia.org/wiki/Geography_Markup_Language - -``kml`` -~~~~~~~ - -.. method:: GeoQuerySet.kml(**kwargs) - -*Availability*: PostGIS - -Attaches a ``kml`` attribute to every model in the queryset that contains the -`Keyhole Markup Language (KML)`__ representation of the geometry fields. It -should be noted that the contents of the KML are transformed to WGS84 if -necessary. - -Example:: - - >>> qs = Zipcode.objects.all().kml() - >>> print qs[0].kml - <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon> - -===================== ===================================================== -Keyword Argument Description -===================== ===================================================== -``precision`` This keyword may be used to specify the number of - significant digits for the coordinates in the KML - representation -- the default value is 8. -===================== ===================================================== - -__ http://code.google.com/apis/kml/documentation/ - -``svg`` -~~~~~~~ - -.. method:: GeoQuerySet.svg(**kwargs) - -*Availability*: PostGIS, SpatiaLite - -Attaches a ``svg`` attribute to every model in the queryset that contains -the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields. - -===================== ===================================================== -Keyword Argument Description -===================== ===================================================== -``relative`` If set to ``True``, the path data will be implemented - in terms of relative moves. Defaults to ``False``, - meaning that absolute moves are used instead. - -``precision`` This keyword may be used to specify the number of - significant digits for the coordinates in the SVG - representation -- the default value is 8. -===================== ===================================================== - -__ http://www.w3.org/Graphics/SVG/ - -Miscellaneous -------------- - -``mem_size`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.mem_size(**kwargs) - -*Availability*: PostGIS - -Returns the memory size (number of bytes) that the geometry field takes -in a ``mem_size`` attribute on each element of the ``GeoQuerySet``. - -``num_geom`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.num_geom(**kwargs) - -*Availability*: PostGIS, Oracle, SpatiaLite - -Returns the number of geometries in a ``num_geom`` attribute on -each element of the ``GeoQuerySet`` if the geometry field is a -collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field); -otherwise sets with ``None``. - -``num_points`` -~~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.num_points(**kwargs) - -*Availability*: PostGIS, Oracle, SpatiaLite - -Returns the number of points in the first linestring in the -geometry field in a ``num_points`` attribute on each element of -the ``GeoQuerySet``; otherwise sets with ``None``. - -Spatial Aggregates -================== -.. versionadded:: 1.1 - -Aggregate Methods ------------------ - -``collect`` -~~~~~~~~~~~ - -.. method:: GeoQuerySet.collect(**kwargs) - -.. versionadded:: 1.1 - -*Availability*: PostGIS - -Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry -column. This is analagous to a simplified version of the :meth:`GeoQuerySet.unionagg` method, -except it can be several orders of magnitude faster than peforming a union because -it simply rolls up geometries into a collection or multi object, not caring about -dissolving boundaries. - -``extent`` -~~~~~~~~~~ - -.. method:: GeoQuerySet.extent(**kwargs) - -*Availability*: PostGIS, Oracle - -Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the -lower left coordinate and the upper right coordinate. - -Example:: - - >>> qs = City.objects.filter(name__in=('Houston', 'Dallas')) - >>> print qs.extent() - (-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820) - -``extent3d`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.extent3d(**kwargs) - -.. versionadded:: 1.2 - -*Availability*: PostGIS - -Returns the 3D extent of the ``GeoQuerySet`` as a six-tuple, comprising -the lower left coordinate and upper right coordinate. - -Example:: - - >>> qs = City.objects.filter(name__in=('Houston', 'Dallas')) - >>> print qs.extent3d() - (-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0) - -``make_line`` -~~~~~~~~~~~~~ - -.. method:: GeoQuerySet.make_line(**kwargs) - -*Availability*: PostGIS - -Returns a ``LineString`` constructed from the point field geometries in the -``GeoQuerySet``. Currently, ordering the queryset has no effect. - -Example:: - - >>> print City.objects.filter(name__in=('Houston', 'Dallas')).make_line() - LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018) - -``unionagg`` -~~~~~~~~~~~~ - -.. method:: GeoQuerySet.unionagg(**kwargs) - -*Availability*: PostGIS, Oracle, SpatiaLite - -This method returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object -comprising the union of every geometry in the queryset. Please note that -use of ``unionagg`` is processor intensive and may take a significant amount -of time on large querysets. - -.. note:: - - If the computation time for using this method is too expensive, - consider using :meth:`GeoQuerySet.collect` instead. - -Example:: - - >>> u = Zipcode.objects.unionagg() # This may take a long time. - >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach. - -===================== ===================================================== -Keyword Argument Description -===================== ===================================================== -``tolerance`` This keyword is for Oracle only. It is for the - tolerance value used by the ``SDOAGGRTYPE`` - procedure; the `Oracle documentation`__ has more - details. -===================== ===================================================== - -__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 - -Aggregate Functions -------------------- - -Example:: - - >>> from django.contrib.gis.db.models import Extent, Union - >>> WorldBorders.objects.aggregate(Extent('mpoly'), Union('mpoly')) - -``Collect`` -~~~~~~~~~~~ - -.. class:: Collect(geo_field) - -Returns the same as the :meth:`GeoQuerySet.collect` aggregate method. - -``Extent`` -~~~~~~~~~~ -.. class:: Extent(geo_field) - - -Returns the same as the :meth:`GeoQuerySet.extent` aggregate method. - -``Extent3D`` -~~~~~~~~~~~~ - -.. class:: Extent3D(geo_field) - -.. versionadded:: 1.2 - -Returns the same as the :meth:`GeoQuerySet.extent3d` aggregate method. - -``MakeLine`` -~~~~~~~~~~~~ - -.. class:: MakeLine(geo_field) - -Returns the same as the :meth:`GeoQuerySet.make_line` aggregate method. - -``Union`` -~~~~~~~~~ - -.. class:: Union(geo_field) - -Returns the same as the :meth:`GeoQuerySet.union` aggregate method. - -.. rubric:: Footnotes -.. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model). -.. [#fnsdorelate] *See* `SDO_RELATE documentation <http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_, from Ch. 11 of the Oracle Spatial User's Guide and Manual. -.. [#fncovers] For an explanation of this routine, read `Quirks of the "Contains" Spatial Predicate <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ by Martin Davis (a PostGIS developer). -.. [#fncontainsproperly] Refer to the PostGIS ``ST_ContainsProperly`` `documentation <http://postgis.refractions.net/documentation/manual-1.4/ST_ContainsProperly.html>`_ for more details. diff --git a/parts/django/docs/ref/contrib/gis/geos.txt b/parts/django/docs/ref/contrib/gis/geos.txt deleted file mode 100644 index 06a88a8..0000000 --- a/parts/django/docs/ref/contrib/gis/geos.txt +++ /dev/null @@ -1,911 +0,0 @@ -.. _ref-geos: - -======== -GEOS API -======== - -.. module:: django.contrib.gis.geos - :synopsis: GeoDjango's high-level interface to the GEOS library. - -Background -========== - -What is GEOS? -------------- - -`GEOS`__ stands for **G**\ eometry **E**\ ngine - **O**\ pen **S**\ ource, -and is a C++ library, ported from the `Java Topology Suite`__. GEOS -implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions -and spatial operators. GEOS, now an OSGeo project, was initially developed and -maintained by `Refractions Research`__ of Victoria, Canada. - -__ http://trac.osgeo.org/geos/ -__ http://sourceforge.net/projects/jts-topo-suite/ -__ http://www.opengeospatial.org/standards/sfs -__ http://www.refractions.net/ - -Features --------- - -GeoDjango implements a high-level Python wrapper for the GEOS library, its -features include: - -* A BSD-licensed interface to the GEOS geometry routines, implemented purely - in Python using ``ctypes``. -* Loosely-coupled to GeoDjango. For example, :class:`GEOSGeometry` objects - may be used outside of a django project/application. In other words, - no need to have ``DJANGO_SETTINGS_MODULE`` set or use a database, etc. -* Mutability: :class:`GEOSGeometry` objects may be modified. -* Cross-platform and tested; compatible with Windows, Linux, Solaris, and Mac - OS X platforms. - -.. _geos-tutorial: - -Tutorial -======== - -This section contains a brief introduction and tutorial to using -:class:`GEOSGeometry` objects. - -Creating a Geometry -------------------- - -:class:`GEOSGeometry` objects may be created in a few ways. The first is -to simply instantiate the object on some spatial input -- the following -are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON:: - - >>> from django.contrib.gis.geos import GEOSGeometry - >>> pnt = GEOSGeometry('POINT(5 23)') # WKT - >>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX - >>> pnt = GEOSGeometry(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@')) - >>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON - -Another option is to use the constructor for the specific geometry type -that you wish to create. For example, a :class:`Point` object may be -created by passing in the X and Y coordinates into its constructor:: - - >>> from django.contrib.gis.geos import Point - >>> pnt = Point(5, 23) - -Finally, there are :func:`fromstr` and :func:`fromfile` factory methods, which -return a :class:`GEOSGeometry` object from an input string or a file:: - - >>> from django.contrib.gis.geos import fromstr, fromfile - >>> pnt = fromstr('POINT(5 23)') - >>> pnt = fromfile('/path/to/pnt.wkt') - >>> pnt = fromfile(open('/path/to/pnt.wkt')) - -Geometries are Pythonic ------------------------ -:class:`GEOSGeometry` objects are 'Pythonic', in other words components may -be accessed, modified, and iterated over using standard Python conventions. -For example, you can iterate over the coordinates in a :class:`Point`:: - - >>> pnt = Point(5, 23) - >>> [coord for coord in pnt] - [5.0, 23.0] - -With any geometry object, the :attr:`GEOSGeometry.coords` property -may be used to get the geometry coordinates as a Python tuple:: - - >>> pnt.coords - (5.0, 23.0) - -You can get/set geometry components using standard Python indexing -techniques. However, what is returned depends on the geometry type -of the object. For example, indexing on a :class:`LineString` -returns a coordinate tuple:: - - >>> from django.contrib.gis.geos import LineString - >>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0)) - >>> line[0] - (0.0, 0.0) - >>> line[-2] - (50.0, 0.0) - -Whereas indexing on a :class:`Polygon` will return the ring -(a :class:`LinearRing` object) corresponding to the index:: - - >>> from django.contrib.gis.geos import Polygon - >>> poly = Polygon( ((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)) ) - >>> poly[0] - <LinearRing object at 0x1044395b0> - >>> poly[0][-2] # second-to-last coordinate of external ring - (50.0, 0.0) - -In addition, coordinates/components of the geometry may added or modified, -just like a Python list:: - - >>> line[0] = (1.0, 1.0) - >>> line.pop() - (0.0, 0.0) - >>> line.append((1.0, 1.0)) - >>> line.coords - ((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0)) - -Geometry Objects -================ - -``GEOSGeometry`` ----------------- - -.. class:: GEOSGeometry(geo_input[, srid=None]) - - :param geo_input: Geometry input value - :type geo_input: string or buffer - :param srid: spatial reference identifier - :type srid: integer - -This is the base class for all GEOS geometry objects. It initializes on the -given ``geo_input`` argument, and then assumes the proper geometry subclass -(e.g., ``GEOSGeometry('POINT(1 1)')`` will create a :class:`Point` object). - -The following input formats, along with their corresponding Python types, -are accepted: - -============= ====================== -Format Input Type -============= ====================== -WKT / EWKT ``str`` or ``unicode`` -HEX / HEXEWKB ``str`` or ``unicode`` -WKB / EWKB ``buffer`` -GeoJSON ``str`` or ``unicode`` -============= ====================== - -Properties -~~~~~~~~~~ - -.. attribute:: GEOSGeometry.coords - -Returns the coordinates of the geometry as a tuple. - -.. attribute:: GEOSGeometry.empty - -Returns whether or not the set of points in the geometry is empty. - -.. attribute:: GEOSGeometry.geom_type - -Returns a string corresponding to the type of geometry. For example:: - - >>> pnt = GEOSGeometry('POINT(5 23)') - >>> pnt.geom_type - 'Point' - -.. attribute:: GEOSGeometry.geom_typeid - -Returns the GEOS geometry type identification number. The following table -shows the value for each geometry type: - -=========================== ======== -Geometry ID -=========================== ======== -:class:`Point` 0 -:class:`LineString` 1 -:class:`LinearRing` 2 -:class:`Polygon` 3 -:class:`MultiPoint` 4 -:class:`MultiLineString` 5 -:class:`MultiPolygon` 6 -:class:`GeometryCollection` 7 -=========================== ======== - -.. attribute:: GEOSGeometry.num_coords - -Returns the number of coordinates in the geometry. - -.. attribute:: GEOSGeometry.num_geom - -Returns the number of geometries in this geometry. In other words, will -return 1 on anything but geometry collections. - -.. attribute:: GEOSGeometry.hasz - -Returns a boolean indicating whether the geometry is three-dimensional. - -.. attribute:: GEOSGeometry.ring - -Returns a boolean indicating whether the geometry is a ``LinearRing``. - -.. attribute:: GEOSGeometry.simple - -Returns a boolean indicating whether the geometry is 'simple'. A geometry -is simple if and only if it does not intersect itself (except at boundary -points). For example, a :class:`LineString` object is not simple if it -intersects itself. Thus, :class:`LinearRing` and :class`Polygon` objects -are always simple because they do cannot intersect themselves, by -definition. - -.. attribute:: GEOSGeometry.valid - -Returns a boolean indicating whether the geometry is valid. - -.. attribute:: GEOSGeometry.srid - -Property that may be used to retrieve or set the SRID associated with the -geometry. For example:: - - >>> pnt = Point(5, 23) - >>> print pnt.srid - None - >>> pnt.srid = 4326 - >>> pnt.srid - 4326 - -Output Properties -~~~~~~~~~~~~~~~~~ - -The properties in this section export the :class:`GEOSGeometry` object into -a different. This output may be in the form of a string, buffer, or even -another object. - -.. attribute:: GEOSGeometry.ewkt - -Returns the "extended" Well-Known Text of the geometry. This representation -is specific to PostGIS and is a super set of the OGC WKT standard. [#fnogc]_ -Essentially the SRID is prepended to the WKT representation, for example -``SRID=4326;POINT(5 23)``. - -.. note:: - - The output from this property does not include the 3dm, 3dz, and 4d - information that PostGIS supports in its EWKT representations. - -.. attribute:: GEOSGeometry.hex - -Returns the WKB of this Geometry in hexadecimal form. Please note -that the SRID and Z values are not included in this representation -because it is not a part of the OGC specification (use the -:attr:`GEOSGeometry.hexewkb` property instead). - -.. attribute:: GEOSGeometry.hexewkb - -.. versionadded:: 1.2 - -Returns the EWKB of this Geometry in hexadecimal form. This is an -extension of the WKB specification that includes SRID and Z values -that are a part of this geometry. - -.. note:: - - GEOS 3.1 is *required* if you want valid 3D HEXEWKB. - -.. attribute:: GEOSGeometry.json - -Returns the GeoJSON representation of the geometry. - -.. note:: - - Requires GDAL. - -.. attribute:: GEOSGeometry.geojson - -Alias for :attr:`GEOSGeometry.json`. - -.. attribute:: GEOSGeometry.kml - -Returns a `KML`__ (Keyhole Markup Language) representation of the -geometry. This should only be used for geometries with an SRID of -4326 (WGS84), but this restriction is not enforced. - -.. attribute:: GEOSGeometry.ogr - -Returns an :class:`~django.contrib.gis.gdal.OGRGeometry` object -correspondg to the GEOS geometry. - -.. note:: - - Requires GDAL. - -.. _wkb: - -.. attribute:: GEOSGeometry.wkb - -Returns the WKB (Well-Known Binary) representation of this Geometry -as a Python buffer. SRID and Z values are not included, use the -:attr:`GEOSGeometry.ewkb` property instead. - -.. _ewkb: - -.. attribute:: GEOSGeometry.ewkb - -.. versionadded:: 1.2 - -Return the EWKB representation of this Geometry as a Python buffer. -This is an extension of the WKB specification that includes any SRID -and Z values that are a part of this geometry. - -.. note:: - - GEOS 3.1 is *required* if you want valid 3D EWKB. - -.. attribute:: GEOSGeometry.wkt - -Returns the Well-Known Text of the geometry (an OGC standard). - -__ http://code.google.com/apis/kml/documentation/ - -Spatial Predicate Methods -~~~~~~~~~~~~~~~~~~~~~~~~~ - -All of the following spatial predicate methods take another -:class:`GEOSGeometry` instance (``other``) as a parameter, and -return a boolean. - -.. method:: GEOSGeometry.contains(other) - -Returns ``True`` if :meth:`GEOSGeometry.within` is ``False``. - -.. method:: GEOSGeometry.crosses(other) - -Returns ``True`` if the DE-9IM intersection matrix for the two Geometries -is ``T*T******`` (for a point and a curve,a point and an area or a line -and an area) ``0********`` (for two curves). - -.. method:: GEOSGeometry.disjoint(other) - -Returns ``True`` if the DE-9IM intersection matrix for the two geometries -is ``FF*FF****``. - -.. method:: GEOSGeometry.equals(other) - -Returns ``True`` if the DE-9IM intersection matrix for the two geometries -is ``T*F**FFF*``. - -.. method:: GEOSGeometry.equals_exact(other, tolerance=0) - -Returns true if the two geometries are exactly equal, up to a -specified tolerance. The ``tolerance`` value should be a floating -point number representing the error tolerance in the comparison, e.g., -``poly1.equals_exact(poly2, 0.001)`` will compare equality to within -one thousandth of a unit. - -.. method:: GEOSGeometry.intersects(other) - -Returns ``True`` if :meth:`GEOSGeometry.disjoint` is ``False``. - -.. method:: GEOSGeometry.overlaps(other) - -Returns true if the DE-9IM intersection matrix for the two geometries -is ``T*T***T**`` (for two points or two surfaces) ``1*T***T**`` -(for two curves). - -.. method:: GEOSGeometry.relate_pattern(other, pattern) - -Returns ``True`` if the elements in the DE-9IM intersection matrix -for this geometry and the other matches the given ``pattern`` -- -a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}. - -.. method:: GEOSGeometry.touches(other) - -Returns ``True`` if the DE-9IM intersection matrix for the two geometries -is ``FT*******``, ``F**T*****`` or ``F***T****``. - -.. method:: GEOSGeometry.within(other) - -Returns ``True`` if the DE-9IM intersection matrix for the two geometries -is ``T*F**F***``. - -Topological Methods -~~~~~~~~~~~~~~~~~~~ - -.. method:: GEOSGeometry.buffer(width, quadsegs=8) - -Returns a :class:`GEOSGeometry` that represents all points whose distance -from this geometry is less than or equal to the given ``width``. The optional -``quadsegs`` keyword sets the number of segments used to approximate a -quarter circle (defaults is 8). - -.. method:: GEOSGeometry.difference(other) - -Returns a :class:`GEOSGeometry` representing the points making up this -geometry that do not make up other. - -.. method:: GEOSGeometry:intersection(other) - -Returns a :class:`GEOSGeometry` representing the points shared by this -geometry and other. - -.. method:: GEOSGeometry.relate(other) - -Returns the DE-9IM intersection matrix (a string) representing the -topological relationship between this geometry and the other. - -.. method:: GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False) - -Returns a new :class:`GEOSGeometry`, simplified using the Douglas-Peucker -algorithm to the specified tolerance. A higher tolerance value implies -less points in the output. If no tolerance is tolerance provided, -it defaults to 0. - -By default, this function does not preserve topology - e.g., -:class:`Polygon` objects can be split, collapsed into lines or disappear. -:class:`Polygon` holes can be created or disappear, and lines can cross. -By specifying ``preserve_topology=True``, the result will have the same -dimension and number of components as the input, however, this is -significantly slower. - -.. method:: GEOSGeometry.sym_difference(other) - -Returns a :class:`GEOSGeometry` combining the points in this geometry -not in other, and the points in other not in this geometry. - -.. method:: GEOSGeometry.union(other) - -Returns a :class:`GEOSGeometry` representing all the points in this -geometry and the other. - -Topological Properties -~~~~~~~~~~~~~~~~~~~~~~ - -.. attribute:: GEOSGeometry.boundary - -Returns the boundary as a newly allocated Geometry object. - -.. attribute:: GEOSGeometry.centroid - -Returns a :class:`Point` object representing the geometric center of -the geometry. The point is not guaranteed to be on the interior -of the geometry. - -.. attribute:: GEOSGeometry.convex_hull - -Returns the smallest :class:`Polygon` that contains all the points in -the geometry. - -.. attribute:: GEOSGeometry.envelope - -Returns a :class:`Polygon` that represents the bounding envelope of -this geometry. - -.. attribute:: GEOSGeometry.point_on_surface - -Computes and returns a :class:`Point` guaranteed to be on the interior -of this geometry. - -Other Properties & Methods -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. attribute:: GEOSGeometry.area - -This property returns the area of the Geometry. - -.. attribute:: GEOSGeometry.extent - -This property returns the extent of this geometry as a 4-tuple, -consisting of (xmin, ymin, xmax, ymax). - -.. method:: GEOSGeometry.clone() - -This method returns a :class:`GEOSGeometry` that is a clone of the original. - -.. method:: GEOSGeometry.distance(geom) - -Returns the distance between the closest points on this geometry and the given -``geom`` (another :class:`GEOSGeometry` object). - -.. note:: - - GEOS distance calculations are linear -- in other words, GEOS does not - perform a spherical calculation even if the SRID specifies a geographic - coordinate system. - -.. attribute:: GEOSGeometry.length - -Returns the length of this geometry (e.g., 0 for a :class:`Point`, -the length of a :class:`LineString`, or the circumference of -a :class:`Polygon`). - -.. attribute:: GEOSGeometry.prepared - -.. versionadded:: 1.1 - -.. note:: - - Support for prepared geometries requires GEOS 3.1. - -Returns a GEOS ``PreparedGeometry`` for the contents of this geometry. -``PreparedGeometry`` objects are optimized for the contains, intersects, -and covers operations. Refer to the :ref:`prepared-geometries` documentation -for more information. - -.. attribute:: GEOSGeometry.srs - -Returns a :class:`~django.contrib.gis.gdal.SpatialReference` object -corresponding to the SRID of the geometry or ``None``. - -.. note:: - - Requires GDAL. - -.. method:: transform(ct, clone=False) - -Transforms the geometry according to the given coordinate transformation paramter -(``ct``), which may be an integer SRID, spatial reference WKT string, -a PROJ.4 string, a :class:`~django.contrib.gis.gdal.SpatialReference` object, or a -:class:`~django.contrib.gis.gdal.CoordTransform` object. By default, the geometry -is transformed in-place and nothing is returned. However if the ``clone`` keyword -is set, then the geometry is not modified and a transformed clone of the geometry -is returned instead. - -.. note:: - - Requires GDAL. - -``Point`` ---------- - -.. class:: Point(x, y, z=None, srid=None) - - ``Point`` objects are instantiated using arguments that represent - the component coordinates of the point or with a single sequence - coordinates. For example, the following are equivalent:: - - >>> pnt = Point(5, 23) - >>> pnt = Point([5, 23]) - -``LineString`` --------------- - -.. class:: LineString(*args, **kwargs) - - ``LineString`` objects are instantiated using arguments that are - either a sequence of coordinates or :class:`Point` objects. - For example, the following are equivalent:: - - >>> ls = LineString((0, 0), (1, 1)) - >>> ls = LineString(Point(0, 0), Point(1, 1)) - - In addition, ``LineString`` objects may also be created by passing - in a single sequence of coordinate or :class:`Point` objects:: - - >>> ls = LineString( ((0, 0), (1, 1)) ) - >>> ls = LineString( [Point(0, 0), Point(1, 1)] ) - -``LinearRing`` --------------- - -.. class:: LinearRing(*args, **kwargs) - - ``LinearRing`` objects are constructed in the exact same way as - :class:`LineString` objects, however the coordinates must be - *closed*, in other words, the first coordinates must be the - same as the last coordinates. For example:: - - >>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0)) - - Notice that ``(0, 0)`` is the first and last coordinate -- if - they were not equal, an error would be raised. - -``Polygon`` ------------ - -.. class:: Polygon(*args, **kwargs) - - ``Polygon`` objects may be instantiated by passing in one or - more parameters that represent the rings of the polygon. The - parameters must either be :class:`LinearRing` instances, or - a sequence that may be used to construct a :class:`LinearRing`:: - - >>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) - >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) - >>> poly = Polygon(ext_coords, int_coords) - >>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords)) - - .. classmethod:: from_bbox(bbox) - - .. versionadded:: 1.1 - - Returns a polygon object from the given bounding-box, a 4-tuple - comprising (xmin, ymin, xmax, ymax). - - .. attribute:: num_interior_rings - - Returns the number of interior rings in this geometry. - -Geometry Collections -==================== - -``MultiPoint`` --------------- - -.. class:: MultiPoint(*args, **kwargs) - - ``MultiPoint`` objects may be instantiated by passing in one - or more :class:`Point` objects as arguments, or a single - sequence of :class:`Point` objects:: - - >>> mp = MultiPoint(Point(0, 0), Point(1, 1)) - >>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) ) - -``MultiLineString`` -------------------- - -.. class:: MultiLineString(*args, **kwargs) - - ``MultiLineString`` objects may be instantiated by passing in one - or more :class:`LineString` objects as arguments, or a single - sequence of :class:`LineString` objects:: - - >>> ls1 = LineString((0, 0), (1, 1)) - >>> ls2 = LineString((2, 2), (3, 3)) - >>> mls = MultiLineString(ls1, ls2) - >>> mls = MultiLineString([ls1, ls2]) - - .. attribute:: merged - - .. versionadded:: 1.1 - - Returns a :class:`LineString` representing the line merge of - all the components in this ``MultiLineString``. - - -``MultiPolygon`` ----------------- - -.. class:: MultiPolygon(*args, **kwargs) - - ``MultiPolygon`` objects may be instantiated by passing one or - more :class:`Polygon` objects as arguments, or a single sequence - of :class:`Polygon` objects:: - - >>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) - >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) ) - >>> mp = MultiPolygon(p1, p2) - >>> mp = MultiPolygon([p1, p2]) - - .. attribute:: cascaded_union - - .. versionadded:: 1.1 - - Returns a :class:`Polygon` that is the union of all of the component - polygons in this collection. The algorithm employed is significantly - more efficient (faster) than trying to union the geometries together - individually. [#fncascadedunion]_ - - .. note:: - - GEOS 3.1 is *required* to peform cascaded unions. - -``GeometryCollection`` ----------------------- - -.. class:: GeometryCollection(*args, **kwargs) - - ``GeometryCollection`` objects may be instantiated by passing in - one or more other :class:`GEOSGeometry` as arguments, or a single - sequence of :class:`GEOSGeometry` objects:: - - >>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) - >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) - >>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)) - -.. _prepared-geometries: - -Prepared Geometries -=================== - -.. versionadded: 1.1 - -In order to obtain a prepared geometry, just access the -:attr:`GEOSGeometry.prepared` property. Once you have a -``PreparedGeometry`` instance its spatial predicate methods, listed below, -may be used with other ``GEOSGeometry`` objects. An operation with a prepared -geometry can be orders of magnitude faster -- the more complex the geometry -that is prepared, the larger the speedup in the operation. For more information, -please consult the `GEOS wiki page on prepared geometries <http://trac.osgeo.org/geos/wiki/PreparedGeometry>`_. - -.. note:: - - GEOS 3.1 is *required* in order to use prepared geometries. - -For example:: - - >>> from django.contrib.gis.geos import Point, Polygon - >>> poly = Polygon.from_bbox((0, 0, 5, 5)) - >>> prep_poly = poly.prepared - >>> prep_poly.contains(Point(2.5, 2.5)) - True - -``PreparedGeometry`` --------------------- - -.. class:: PreparedGeometry - - All methods on ``PreparedGeometry`` take an ``other`` argument, which - must be a :class:`GEOSGeometry` instance. - - .. method:: contains(other) - - .. method:: contains_properly(other) - - .. method:: covers(other) - - .. method:: intersects(other) - -Geometry Factories -================== - -.. function:: fromfile(file_h) - - :param file_h: input file that contains spatial data - :type file_h: a Python ``file`` object or a string path to the file - :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file - -Example:: - - >>> from django.contrib.gis.geos import fromfile - >>> g = fromfile('/home/bob/geom.wkt') - -.. function:: fromstr(string, [,srid=None]) - - :param string: string that contains spatial data - :type string: string - :param srid: spatial reference identifier - :type srid: integer - :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string - -Example:: - - >>> from django.contrib.gis.geos import fromstr - >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326) - -I/O Objects -=========== - -.. versionadded: 1.1 - -Reader Objects --------------- - -The reader I/O classes simply return a :class:`GEOSGeometry` instance from the -WKB and/or WKT input given to their ``read(geom)`` method. - -.. class:: WKBReader - -Example:: - - >>> from django.contrib.gis.geos import WKBReader - >>> wkb_r = WKBReader() - >>> wkb_r.read('0101000000000000000000F03F000000000000F03F') - <Point object at 0x103a88910> - -.. class:: WKTReader - -Example:: - - >>> from django.contrib.gis.geos import WKTReader - >>> wkt_r = WKTReader() - >>> wkt_r.read('POINT(1 1)') - <Point object at 0x103a88b50> - -Writer Objects --------------- - -All writer objects have a ``write(geom)`` method that returns either the -WKB or WKT of the given geometry. In addition, :class:`WKBWriter` objects -also have properties that may be used to change the byte order, and or -include the SRID and 3D values (in other words, EWKB). - -.. class:: WKBWriter - -``WKBWriter`` provides the most control over its output. By default it -returns OGC-compliant WKB when it's ``write`` method is called. However, -it has properties that allow for the creation of EWKB, a superset of the -WKB standard that includes additional information. - -.. method:: WKBWriter.write(geom) - -Returns the WKB of the given geometry as a Python ``buffer`` object. -Example:: - - >>> from django.contrib.gis.geos import Point, WKBWriter - >>> pnt = Point(1, 1) - >>> wkb_w = WKBWriter() - >>> wkb_w.write(pnt) - <read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930> - -.. method:: WKBWriter.write_hex(geom) - -Returns WKB of the geometry in hexadecimal. Example:: - - >>> from django.contrib.gis.geos import Point, WKBWriter - >>> pnt = Point(1, 1) - >>> wkb_w = WKBWriter() - >>> wkb_w.write_hex(pnt) - '0101000000000000000000F03F000000000000F03F' - -.. attribute:: WKBWriter.byteorder - -This property may be be set to change the byte-order of the geometry -representation. - -=============== ================================================= -Byteorder Value Description -=============== ================================================= -0 Big Endian (e.g., compatible with RISC systems) -1 Little Endian (e.g., compatible with x86 systems) -=============== ================================================= - -Example:: - - >>> from django.contrib.gis.geos import Point, WKBWriter - >>> wkb_w = WKBWriter() - >>> pnt = Point(1, 1) - >>> wkb_w.write_hex(pnt) - '0101000000000000000000F03F000000000000F03F' - >>> wkb_w.byteorder = 0 - '00000000013FF00000000000003FF0000000000000' - -.. attribute:: WKBWriter.outdim - -This property may be set to change the output dimension of the geometry -representation. In other words, if you have a 3D geometry then set to 3 -so that the Z value is included in the WKB. - -============ =========================== -Outdim Value Description -============ =========================== -2 The default, output 2D WKB. -3 Output 3D EWKB. -============ =========================== - -Example:: - - >>> from django.contrib.gis.geos import Point, WKBWriter - >>> wkb_w = WKBWriter() - >>> wkb_w.outdim - 2 - >>> pnt = Point(1, 1, 1) - >>> wkb_w.write_hex(pnt) # By default, no Z value included: - '0101000000000000000000F03F000000000000F03F' - >>> wkb_w.outdim = 3 # Tell writer to include Z values - >>> wkb_w.write_hex(pnt) - '0101000080000000000000F03F000000000000F03F000000000000F03F' - -.. attribute:: WKBWriter.srid - -Set this property with a boolean to indicate whether the SRID of the -geometry should be included with the WKB representation. Example:: - - >>> from django.contrib.gis.geos import Point, WKBWriter - >>> wkb_w = WKBWriter() - >>> pnt = Point(1, 1, srid=4326) - >>> wkb_w.write_hex(pnt) # By default, no SRID included: - '0101000000000000000000F03F000000000000F03F' - >>> wkb_w.srid = True # Tell writer to include SRID - >>> wkb_w.write_hex(pnt) - '0101000020E6100000000000000000F03F000000000000F03F' - -.. class:: WKTWriter - -.. method:: WKTWriter.write(geom) - -Returns the WKT of the given geometry. Example:: - - >>> from django.contrib.gis.geos import Point, WKTWriter - >>> pnt = Point(1, 1) - >>> wkt_w = WKTWriter() - >>> wkt_w.write(pnt) - 'POINT (1.0000000000000000 1.0000000000000000)' - - -.. rubric:: Footnotes -.. [#fnogc] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/docs/ch04.html#id2591381>`_, PostGIS documentation at Ch. 4.1.2. -.. [#fncascadedunion] For more information, read Paul Ramsey's blog post about `(Much) Faster Unions in PostGIS 1.4 <http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html>`_ and Martin Davis' blog post on `Fast polygon merging in JTS using Cascaded Union <http://lin-ear-th-inking.blogspot.com/2007/11/fast-polygon-merging-in-jts-using.html>`_. - -Settings -======== - -.. setting:: GEOS_LIBRARY_PATH - -GEOS_LIBRARY_PATH ------------------ - -A string specifying the location of the GEOS C library. Typically, -this setting is only used if the GEOS C library is in a non-standard -location (e.g., ``/home/bob/lib/libgeos_c.so``). - -.. note:: - - The setting must be the *full* path to the **C** shared library; in - other words you want to use ``libgeos_c.so``, not ``libgeos.so``. diff --git a/parts/django/docs/ref/contrib/gis/index.txt b/parts/django/docs/ref/contrib/gis/index.txt deleted file mode 100644 index c4959e0..0000000 --- a/parts/django/docs/ref/contrib/gis/index.txt +++ /dev/null @@ -1,33 +0,0 @@ -.. _ref-contrib-gis: - -========= -GeoDjango -========= - -.. versionadded:: 1.0 - -.. module:: django.contrib.gis - :synopsis: Geographic Information System (GIS) extensions for Django - -GeoDjango intends to be a world-class geographic Web framework. Its goal is to -make it as easy as possible to build GIS Web applications and harness the power -of spatially enabled data. - -.. toctree:: - :maxdepth: 2 - - tutorial - install - model-api - db-api - geoquerysets - measure - geos - gdal - utils - commands - admin - feeds - sitemaps - testing - deployment diff --git a/parts/django/docs/ref/contrib/gis/install.txt b/parts/django/docs/ref/contrib/gis/install.txt deleted file mode 100644 index fa8e34c..0000000 --- a/parts/django/docs/ref/contrib/gis/install.txt +++ /dev/null @@ -1,1190 +0,0 @@ -.. _ref-gis-install: - -====================== -GeoDjango Installation -====================== - -Overview -======== -In general, GeoDjango installation requires: - -1. :ref:`python24` and :ref:`django` -2. :ref:`spatial_database` -3. :ref:`geospatial_libs` - -Details for each of the requirements and installation instructions -are provided in the sections below. In addition, platform-specific -instructions are available for: - -* :ref:`macosx` -* :ref:`ubuntudebian` -* :ref:`windows` - -.. admonition:: Use the Source - - Because GeoDjango takes advantage of the latest in the open source geospatial - software technology, recent versions of the libraries are necessary. - If binary packages aren't available for your platform, - :ref:`installation from source <build_from_source>` - may be required. When compiling the libraries from source, please follow the - directions closely, especially if you're a beginner. - -Requirements -============ - -.. _python24: - -Python 2.4+ ------------ - -Python 2.4 is the minimum version supported by Django, however Python 2.5+ is -recommended because the `ctypes`__ module comes included; otherwise, 2.4 users -will need to `download and install ctypes`__. - -__ http://docs.python.org/lib/module-ctypes.html -__ http://sourceforge.net/projects/ctypes/files/ - -.. _django: - -Django ------- - -Because GeoDjango is included with Django, please refer to Django's -:doc:`installation instructions </intro/install>` for details on how to install. - -.. _spatial_database: - -Spatial Database ----------------- -PostgreSQL (with PostGIS), MySQL, Oracle, and SQLite (with SpatiaLite) are -the spatial databases currently supported. - -.. note:: - - PostGIS is recommended, because it is the most mature and feature-rich - open source spatial database. - -The geospatial libraries required for a GeoDjango installation depends -on the spatial database used. The following lists the library requirements, -supported versions, and any notes for each of the supported database backends: - -================== ============================== ================== ========================================================== -Database Library Requirements Supported Versions Notes -================== ============================== ================== ========================================================== -PostgreSQL GEOS, PROJ.4, PostGIS 8.1+ Requires PostGIS. -MySQL GEOS 5.x Not OGC-compliant; limited functionality. -Oracle GEOS 10.2, 11 XE not supported; not tested with 9. -SQLite GEOS, GDAL, PROJ.4, SpatiaLite 3.6.+ Requires SpatiaLite 2.3+, pysqlite2 2.5+, and Django 1.1. -================== ============================== ================== ========================================================== - -.. _geospatial_libs: - -Geospatial Libraries --------------------- -GeoDjango uses and/or provides interfaces for the the following open source -geospatial libraries: - -======================== ==================================== ================================ ========================== -Program Description Required Supported Versions -======================== ==================================== ================================ ========================== -:ref:`GEOS <ref-geos>` Geometry Engine Open Source Yes 3.2, 3.1, 3.0 -`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.7, 4.6, 4.5, 4.4 -:ref:`GDAL <ref-gdal>` Geospatial Data Abstraction Library No (but, required for SQLite) 1.7, 1.6, 1.5, 1.4 -:ref:`GeoIP <ref-geoip>` IP-based geolocation library No 1.4 -`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 1.5, 1.4, 1.3 -`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 2.4, 2.3 -======================== ==================================== ================================ ========================== - -.. admonition:: Install GDAL - - While :ref:`gdalbuild` is technically not required, it is *recommended*. - Some features of GeoDjango (including the :ref:`ref-layermapping` and the geographic - admin) depend on its functionality. - -.. note:: - - The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used - independently of Django. In other words, no database or settings file - required -- just import them as normal from :mod:`django.contrib.gis`. - -.. _PROJ.4: http://trac.osgeo.org/proj/ -__ http://postgis.refractions.net/ -__ http://www.gaia-gis.it/spatialite/index.html - -.. _build_from_source: - -Building from Source -==================== - -When installing from source on UNIX and GNU/Linux systems, please follow -the installation instructions carefully, and install the libraries in the -given order. If using MySQL or Oracle as the spatial database, only GEOS -is required. - -.. note:: - - On Linux platforms, it may be necessarry to run the ``ldconfig`` - command after installing each library. For example:: - - $ sudo make install - $ sudo ldconfig - -.. note:: - - OS X users are required to install `Apple Developer Tools`_ in order - to compile software from source. This is typically included on your - OS X installation DVDs. - -.. _Apple Developer Tools: http://developer.apple.com/tools/xcode/ - -.. _geosbuild: - -GEOS ----- - -GEOS is a C++ library for performing geometric operations, and is the default -internal geometry representation used by GeoDjango (it's behind the "lazy" -geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``) -directly from Python using ctypes. - -First, download GEOS 3.2 from the refractions Web site and untar the source -archive:: - - $ wget http://download.osgeo.org/geos/geos-3.2.2.tar.bz2 - $ tar xjf geos-3.2.2.tar.bz2 - -Next, change into the directory where GEOS was unpacked, run the configure -script, compile, and install:: - - $ cd geos-3.2.2 - $ ./configure - $ make - $ sudo make install - $ cd .. - -Troubleshooting -^^^^^^^^^^^^^^^ - -Can't find GEOS Library -~~~~~~~~~~~~~~~~~~~~~~~ - -When GeoDjango can't find GEOS, this error is raised:: - - ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings. - -The most common solution is to properly configure your :ref:`libsettings` *or* set -:ref:`geoslibrarypath` in your settings. - -If using a binary package of GEOS (e.g., on Ubuntu 8.10), you may need to :ref:`binutils`. - -.. _geoslibrarypath: - -``GEOS_LIBRARY_PATH`` -~~~~~~~~~~~~~~~~~~~~~ - -If your GEOS library is in a non-standard location, or you don't want to -modify the system's library path then the :setting:`GEOS_LIBRARY_PATH` setting -may be added to your Django settings file with the full path to the GEOS -C library. For example:: - - GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so' - -.. note:: - - The setting must be the *full* path to the **C** shared library; in - other words you want to use ``libgeos_c.so``, not ``libgeos.so``. - -.. _proj4: - -PROJ.4 ------- - -`PROJ.4`_ is a library for converting geospatial data to different coordinate -reference systems. - -First, download the PROJ.4 source code and datum shifting files [#]_:: - - $ wget http://download.osgeo.org/proj/proj-4.7.0.tar.gz - $ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.zip - -Next, untar the source code archive, and extract the datum shifting files in the -``nad`` subdirectory. This must be done *prior* to configuration:: - - $ tar xzf proj-4.7.0.tar.gz - $ cd proj-4.7.0/nad - $ unzip ../../proj-datumgrid-1.5.zip - $ cd .. - -Finally, configure, make and install PROJ.4:: - - $ ./configure - $ make - $ sudo make install - $ cd .. - -.. _postgis: - -PostGIS -------- - -`PostGIS`__ adds geographic object support to PostgreSQL, turning it -into a spatial database. :ref:`geosbuild` and :ref:`proj4` should be -installed prior to building PostGIS. - -.. note:: - - The `psycopg2`_ module is required for use as the database adaptor - when using GeoDjango with PostGIS. - -.. _psycopg2: http://initd.org/projects/psycopg2 - -First download the source archive, and extract:: - - $ wget http://postgis.refractions.net/download/postgis-1.5.2.tar.gz - $ tar xzf postgis-1.5.2.tar.gz - $ cd postgis-1.5.2 - -Next, configure, make and install PostGIS:: - - $ ./configure - -Finally, make and install:: - - $ make - $ sudo make install - $ cd .. - -.. note:: - - GeoDjango does not automatically create a spatial database. Please - consult the section on :ref:`spatialdb_template` for more information. - -__ http://postgis.refractions.net/ - -.. _gdalbuild: - -GDAL ----- - -`GDAL`__ is an excellent open source geospatial library that has support for -reading most vector and raster spatial data formats. Currently, GeoDjango only -supports :ref:`GDAL's vector data <ref-gdal>` capabilities [#]_. -:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL. - -First download the latest GDAL release version and untar the archive:: - - $ wget http://download.osgeo.org/gdal/gdal-1.7.2.tar.gz - $ tar xzf gdal-1.7.2.tar.gz - $ cd gdal-1.7.2 - -Configure, make and install:: - - $ ./configure - $ make # Go get some coffee, this takes a while. - $ sudo make install - $ cd .. - -.. note:: - - Because GeoDjango has it's own Python interface, the preceding instructions - do not build GDAL's own Python bindings. The bindings may be built by - adding the ``--with-python`` flag when running ``configure``. See - `GDAL/OGR In Python`__ for more information on GDAL's bindings. - -If you have any problems, please see the troubleshooting section below for -suggestions and solutions. - -__ http://trac.osgeo.org/gdal/ -__ http://trac.osgeo.org/gdal/wiki/GdalOgrInPython - -.. _gdaltrouble: - -Troubleshooting -^^^^^^^^^^^^^^^ - -Can't find GDAL Library -~~~~~~~~~~~~~~~~~~~~~~~ - -When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag -will be false:: - - >>> from django.contrib.gis import gdal - >>> gdal.HAS_GDAL - False - -The solution is to properly configure your :ref:`libsettings` *or* set -:ref:`gdallibrarypath` in your settings. - -.. _gdallibrarypath: - -``GDAL_LIBRARY_PATH`` -~~~~~~~~~~~~~~~~~~~~~ - -If your GDAL library is in a non-standard location, or you don't want to -modify the system's library path then the :setting:`GDAL_LIBRARY_PATH` -setting may be added to your Django settings file with the full path to -the GDAL library. For example:: - - GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so' - -.. _gdaldata: - -Can't find GDAL data files (``GDAL_DATA``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When installed from source, GDAL versions 1.5.1 and below have an autoconf bug -that places data in the wrong location. [#]_ This can lead to error messages -like this:: - - ERROR 4: Unable to open EPSG support file gcs.csv. - ... - OGRException: OGR failure. - -The solution is to set the ``GDAL_DATA`` environment variable to the location of the -GDAL data files before invoking Python (typically ``/usr/local/share``; use -``gdal-config --datadir`` to find out). For example:: - - $ export GDAL_DATA=`gdal-config --datadir` - $ python manage.py shell - -If using Apache, you may need to add this environment variable to your configuration -file:: - - SetEnv GDAL_DATA /usr/local/share - -.. _spatialite: - -SpatiaLite ----------- -.. versionadded:: 1.1 - -.. note:: - - Mac OS X users should follow the instructions in the :ref:`kyngchaos` section, - as it is much easier than building from source. - -`SpatiaLite`__ adds spatial support to SQLite, turning it into a full-featured -spatial database. Because SpatiaLite has special requirements, it typically -requires SQLite and pysqlite2 (the Python SQLite DB-API adaptor) to be built from -source. :ref:`geosbuild` and :ref:`proj4` should be installed prior to building -SpatiaLite. - -After installation is complete, don't forget to read the post-installation -docs on :ref:`create_spatialite_db`. - -__ http://www.gaia-gis.it/spatialite/index.html - -.. _sqlite: - -SQLite -^^^^^^ - -Typically, SQLite packages are not compiled to include the `R*Tree module`__ -- -thus it must be compiled from source. First download the latest amalgamation -source archive from the `SQLite download page`__, and extract:: - - $ wget http://sqlite.org/sqlite-amalgamation-3.6.23.1.tar.gz - $ tar xzf sqlite-amalgamation-3.6.23.1.tar.gz - $ cd sqlite-3.6.23.1 - -Next, run the ``configure`` script -- however the ``CFLAGS`` environment variable -needs to be customized so that SQLite knows to build the R*Tree module:: - - $ CFLAGS="-DSQLITE_ENABLE_RTREE=1" ./configure - $ make - $ sudo make install - $ cd .. - -.. note:: - - If using Ubuntu, installing a newer SQLite from source can be very difficult - because it links to the existing ``libsqlite3.so`` in ``/usr/lib`` which - many other packages depend on. Unfortunately, the best solution at this time - is to overwrite the existing library by adding ``--prefix=/usr`` to the - ``configure`` command. - -__ http://www.sqlite.org/rtree.html -__ http://www.sqlite.org/download.html - -.. _spatialitebuild : - -SpatiaLite Library (``libspatialite``) and Tools (``spatialite``) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After SQLite has been built with the R*Tree module enabled, get the latest -SpatiaLite library source and tools bundle from the `download page`__:: - - $ wget http://www.gaia-gis.it/spatialite/libspatialite-amalgamation-2.3.1.tar.gz - $ wget http://www.gaia-gis.it/spatialite/spatialite-tools-2.3.1.tar.gz - $ tar xzf libspatialite-amalgamation-2.3.1.tar.gz - $ tar xzf spatialite-tools-2.3.1.tar.gz - -Prior to attempting to build, please read the important notes below to see if -customization of the ``configure`` command is necessary. If not, then run the -``configure`` script, make, and install for the SpatiaLite library:: - - $ cd libspatialite-amalgamation-2.3.1 - $ ./configure # May need to modified, see notes below. - $ make - $ sudo make install - $ cd .. - -Finally, do the same for the SpatiaLite tools:: - - $ cd spatialite-tools-2.3.1 - $ ./configure # May need to modified, see notes below. - $ make - $ sudo make install - $ cd .. - -.. note:: - - If you've installed GEOS and PROJ.4 from binary packages, you will have to specify - their paths when running the ``configure`` scripts for *both* the library and the - tools (the configure scripts look, by default, in ``/usr/local``). For example, - on Debian/Ubuntu distributions that have GEOS and PROJ.4 packages, the command would be:: - - $ ./configure --with-proj-include=/usr/include --with-proj-lib=/usr/lib --with-geos-include=/usr/include --with-geos-lib=/usr/lib - -.. note:: - - For Mac OS X users building from source, the SpatiaLite library *and* tools - need to have their ``target`` configured:: - - $ ./configure --target=macosx - -__ http://www.gaia-gis.it/spatialite/sources.html - -.. _pysqlite2: - -pysqlite2 -^^^^^^^^^ - -Because SpatiaLite must be loaded as an external extension, it requires the -``enable_load_extension`` method, which is only available in versions 2.5+. -Thus, download pysqlite2 2.6, and untar:: - - $ wget http://pysqlite.googlecode.com/files/pysqlite-2.6.0.tar.gz - $ tar xzf pysqlite-2.6.0.tar.gz - $ cd pysqlite-2.6.0 - -Next, use a text editor (e.g., ``emacs`` or ``vi``) to edit the ``setup.cfg`` file -to look like the following:: - - [build_ext] - #define= - include_dirs=/usr/local/include - library_dirs=/usr/local/lib - libraries=sqlite3 - #define=SQLITE_OMIT_LOAD_EXTENSION - -.. note:: - - The important thing here is to make sure you comment out the the - ``define=SQLITE_OMIT_LOAD_EXTENSION`` flag and that the ``include_dirs`` - and ``library_dirs`` settings are uncommented and set to the appropriate - path if the SQLite header files and libraries are not in ``/usr/include`` - and ``/usr/lib``, respectively. - -After modifying ``setup.cfg`` appropriately, then run the ``setup.py`` script -to build and install:: - - $ sudo python setup.py install - -Post-Installation -================= - -.. _spatialdb_template: - -Creating a Spatial Database Template for PostGIS ------------------------------------------------- - -Creating a spatial database with PostGIS is different than normal because -additional SQL must be loaded to enable spatial functionality. Because of -the steps in this process, it's better to create a database template that -can be reused later. - -First, you need to be able to execute the commands as a privileged database -user. For example, you can use the following to become the ``postgres`` user:: - - $ sudo su - postgres - -.. note:: - - The location *and* name of the PostGIS SQL files (e.g., from - ``POSTGIS_SQL_PATH`` below) depends on the version of PostGIS. - PostGIS versions 1.3 and below use ``<pg_sharedir>/contrib/lwpostgis.sql``; - whereas version 1.4 uses ``<sharedir>/contrib/postgis.sql`` and - version 1.5 uses ``<sharedir>/contrib/postgis-1.5/postgis.sql``. - - The example below assumes PostGIS 1.5, thus you may need to modify - ``POSTGIS_SQL_PATH`` and the name of the SQL file for the specific - version of PostGIS you are using. - -Once you're a database super user, then you may execute the following commands -to create a PostGIS spatial database template. If running Ubuntu :ref:`ibex` -or Debian :ref:`lenny`, please refer to their specific documentation for -modifications to these commands:: - - $ POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5 - # Creating the template spatial database. - $ createdb -E UTF8 template_postgis - $ createlang -d template_postgis plpgsql # Adding PLPGSQL language support. - # Allows non-superusers the ability to create from this template - $ psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';" - # Loading the PostGIS SQL routines - $ psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql - $ psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql - # Enabling users to alter spatial tables. - $ psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" - $ psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;" - $ psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;" - -These commands may be placed in a shell script for later use; for convenience -the following scripts are available: - -=============== ========================================== -PostGIS Version Shell Script -=============== ========================================== -1.3 `create_template_postgis-1.3.sh`_ -1.4 `create_template_postgis-1.4.sh`_ -1.5 `create_template_postgis-1.5.sh`_ -=============== ========================================== - -Afterwards, you may create a spatial database by simply specifying -``template_postgis`` as the template to use (via the ``-T`` option):: - - $ createdb -T template_postgis <db name> - -.. note:: - - While the ``createdb`` command does not require database super-user privileges, - it must be executed by a database user that has permissions to create databases. - You can create such a user with the following command:: - - $ createuser --createdb <user> - -.. _create_template_postgis-1.3.sh: http://geodjango.org/docs/create_template_postgis-1.3.sh -.. _create_template_postgis-1.4.sh: http://geodjango.org/docs/create_template_postgis-1.4.sh -.. _create_template_postgis-1.5.sh: http://geodjango.org/docs/create_template_postgis-1.5.sh -.. _create_template_postgis-debian.sh: http://geodjango.org/docs/create_template_postgis-debian.sh - -.. _create_spatialite_db: - -Creating a Spatial Database for SpatiaLite -------------------------------------------- - -After the SpatiaLite library and tools have been installed, it is now possible -to create spatial database for use with GeoDjango. In order to do this, download -the spatial database initialization SQL from the `SpatiaLite Resources`__ page:: - - $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.sql.gz - $ gunzip init_spatialite-2.3.sql.gz - -Now, the ``spatialite`` command can be used to initialize a spatial database:: - - $ spatialite geodjango.db < init_spatialite-2.3.sql - -.. note:: - - The parameter ``geodjango.db`` is the *filename* of the SQLite database - you want to use. Use the same in the :setting:`DATABASE_NAME` - inside your ``settings.py``. - - -__ http://www.gaia-gis.it/spatialite/resources.html - - -Add ``django.contrib.gis`` to ``INSTALLED_APPS`` ------------------------------------------------- - -Like other Django contrib applications, you will *only* need to add -:mod:`django.contrib.gis` to :setting:`INSTALLED_APPS` in your settings. -This is the so that ``gis`` templates can be located -- if not done, then -features such as the geographic admin or KML sitemaps will not function properly. - -.. _addgoogleprojection: - -Add Google Projection to ``spatial_ref_sys`` table --------------------------------------------------- - -.. versionchanged:: 1.2 - -.. note:: - - If running PostGIS 1.4 and above, the entry is already included in the - default ``spatial_ref_sys`` table. You can skip this step. - -In order to conduct database transformations to the so-called "Google" -projection (a spherical mercator projection used by Google Maps), -an entry must be added to your spatial database's ``spatial_ref_sys`` table. -Invoke the Django shell from your project and execute the -``add_srs_entry`` function:: - - $ python manage shell - >>> from django.contrib.gis.utils import add_srs_entry - >>> add_srs_entry(900913) - -.. note:: - - In Django 1.1 the name of this function is ``add_postgis_srs``. - -This adds an entry for the 900913 SRID to the ``spatial_ref_sys`` (or equivalent) -table, making it possible for the spatial database to transform coordinates in -this projection. You only need to execute this command *once* per spatial database. - -Troubleshooting -=============== - -If you can't find the solution to your problem here then participate in the -community! You can: - -* Join the ``#geodjango`` IRC channel on FreeNode (may be accessed on the - Web via `Mibbit`__). Please be patient and polite -- while you may not - get an immediate response, someone will attempt to answer your question - as soon as they see it. -* Ask your question on the `GeoDjango`__ mailing list. -* File a ticket on the `Django trac`__ if you think there's a bug. Make - sure to provide a complete description of the problem, versions used, - and specify the component as "GIS". - -__ http://www.mibbit.com/?server=irc.freenode.net&channel=%23geodjango -__ http://groups.google.com/group/geodjango -__ http://code.djangoproject.com/simpleticket - -.. _libsettings: - -Library Environment Settings ----------------------------- - -By far, the most common problem when installing GeoDjango is that the -external shared libraries (e.g., for GEOS and GDAL) cannot be located. [#]_ -Typically, the cause of this problem is that the operating system isn't aware -of the directory where the libraries built from source were installed. - -In general, the library path may be set on a per-user basis by setting -an environment variable, or by configuring the library path for the entire -system. - -``LD_LIBRARY_PATH`` environment variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A user may set this environment variable to customize the library paths -they want to use. The typical library directory for software -built from source is ``/usr/local/lib``. Thus, ``/usr/local/lib`` needs -to be included in the ``LD_LIBRARY_PATH`` variable. For example, the user -could place the following in their bash profile:: - - export LD_LIBRARY_PATH=/usr/local/lib - -Setting System Library Path -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include -additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. -As the root user, add the custom library path (like ``/usr/local/lib``) on a -new line in ``ld.so.conf``. This is *one* example of how to do so:: - - $ sudo echo /usr/local/lib >> /etc/ld.so.conf - $ sudo ldconfig - -For OpenSolaris users, the system library path may be modified using the -``crle`` utility. Run ``crle`` with no options to see the current configuration -and use ``crle -l`` to set with the new library path. Be *very* careful when -modifying the system library path:: - - # crle -l $OLD_PATH:/usr/local/lib - -.. _binutils: - -Install ``binutils`` -^^^^^^^^^^^^^^^^^^^^ - -GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python -module) to discover libraries. The ``find_library`` routine uses a program -called ``objdump`` (part of the ``binutils`` package) to verify a shared -library on GNU/Linux systems. Thus, if ``binutils`` is not installed on your -Linux system then Python's ctypes may not be able to find your library even if -your library path is set correctly and geospatial libraries were built perfectly. - -The ``binutils`` package may be installed on Debian and Ubuntu systems using the -following command:: - - $ sudo apt-get install binutils - -Similarly, on Red Hat and CentOS systems:: - - $ sudo yum install binutils - -Platform Specific Instructions -============================== - -.. _macosx: - -Mac OS X --------- - -Because of the variety of packaging systems available for OS X, users have -several different options for installing GeoDjango. These options are: - -* :ref:`kyngchaos` -* :ref:`fink` -* :ref:`macports` -* :ref:`build_from_source` - -.. note:: - - Currently, the easiest and recommended approach for installing GeoDjango - on OS X is to use the KyngChaos packages. - -This section also includes instructions for installing an upgraded version -of :ref:`macosx_python` from packages provided by the Python Software -Foundation, however, this is not required. - -.. _macosx_python: - -Python -^^^^^^ - -Although OS X comes with Python installed, users can use framework -installers (`2.5`__ and `2.6`__ are available) provided by -the Python Software Foundation. An advantage to using the installer is -that OS X's Python will remain "pristine" for internal operating system -use. - -__ http://python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg -__ http://python.org/ftp/python/2.6.2/python-2.6.2-macosx2009-04-16.dmg - -.. note:: - - You will need to modify the ``PATH`` environment variable in your - ``.profile`` file so that the new version of Python is used when - ``python`` is entered at the command-line:: - - export PATH=/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH - -.. _kyngchaos: - -KyngChaos Packages -^^^^^^^^^^^^^^^^^^ - -William Kyngesburye provides a number of `geospatial library binary packages`__ -that make it simple to get GeoDjango installed on OS X without compiling -them from source. However, the `Apple Developer Tools`_ are still necessary -for compiling the Python database adapters :ref:`psycopg2_kyngchaos` (for PostGIS) -and :ref:`pysqlite2_kyngchaos` (for SpatiaLite). - -.. note:: - - SpatiaLite users should consult the :ref:`spatialite_kyngchaos` section - after installing the packages for additional instructions. - -Download the framework packages for: - -* UnixImageIO -* PROJ -* GEOS -* SQLite3 (includes the SpatiaLite library) -* GDAL - -Install the packages in the order they are listed above, as the GDAL and SQLite -packages require the packages listed before them. Afterwards, you can also -install the KyngChaos binary packages for `PostgreSQL and PostGIS`__. - -After installing the binary packages, you'll want to add the following to -your ``.profile`` to be able to run the package programs from the command-line:: - - export PATH=/Library/Frameworks/UnixImageIO.framework/Programs:$PATH - export PATH=/Library/Frameworks/PROJ.framework/Programs:$PATH - export PATH=/Library/Frameworks/GEOS.framework/Programs:$PATH - export PATH=/Library/Frameworks/SQLite3.framework/Programs:$PATH - export PATH=/Library/Frameworks/GDAL.framework/Programs:$PATH - export PATH=/usr/local/pgsql/bin:$PATH - -__ http://www.kyngchaos.com/software/frameworks -__ http://www.kyngchaos.com/software/postgres - -.. note:: - - Use of these binaries requires Django 1.0.3 and above. If you are - using a previous version of Django (like 1.0.2), then you will have - to add the the following in your settings:: - - GEOS_LIBRARY_PATH='/Library/Frameworks/GEOS.framework/GEOS' - GDAL_LIBRARY_PATH='/Library/Frameworks/GDAL.framework/GDAL' - -.. _psycopg2_kyngchaos: - -psycopg2 -~~~~~~~~ - -After you've installed the KyngChaos binaries and modified your ``PATH``, as -described above, ``psycopg2`` may be installed using the following command:: - - $ sudo python easy_install psycopg2 - -.. note:: - - To use ``easy_install`` you'll need to install Python's `setuptools`_. - -.. _setuptools: http://pypi.python.org/pypi/setuptools - -.. _pysqlite2_kyngchaos: - -pysqlite2 -~~~~~~~~~ - -Follow the :ref:`pysqlite2` source install instructions, however, -when editing the ``setup.cfg`` use the following instead:: - - [build_ext] - #define= - include_dirs=/Library/Frameworks/SQLite3.framework/unix/include - library_dirs=/Library/Frameworks/SQLite3.framework/unix/lib - libraries=sqlite3 - #define=SQLITE_OMIT_LOAD_EXTENSION - -.. _spatialite_kyngchaos: - -SpatiaLite -~~~~~~~~~~ - -When :ref:`create_spatialite_db`, the ``spatialite`` program is required. -However, instead of attempting to compile the SpatiaLite tools from source, -download the `SpatiaLite Binaries`__ for OS X, and install ``spatialite`` in a -location available in your ``PATH``. For example:: - - $ curl -O http://www.gaia-gis.it/spatialite/spatialite-tools-osx-x86-2.3.1.tar.gz - $ tar xzf spatialite-tools-osx-x86-2.3.1.tar.gz - $ cd spatialite-tools-osx-x86-2.3.1/bin - $ sudo cp spatialite /Library/Frameworks/SQLite3.framework/Programs - -Finally, for GeoDjango to be able to find the KyngChaos SpatiaLite library, -add the following to your ``settings.py``:: - - SPATIALITE_LIBRARY_PATH='/Library/Frameworks/SQLite3.framework/SQLite3' - -__ http://www.gaia-gis.it/spatialite/binaries.html - -.. _fink: - -Fink -^^^^ - -`Kurt Schwehr`__ has been gracious enough to create GeoDjango packages for users -of the `Fink`__ package system. The following packages are available, depending -on which version of Python you want to use: - -* ``django-gis-py26`` -* ``django-gis-py25`` -* ``django-gis-py24`` - -__ http://schwehr.org/blog/ -__ http://www.finkproject.org/ - -.. _macports: - -MacPorts -^^^^^^^^ - -`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh -computers running OS X. Because MacPorts still builds the software from source, -the `Apple Developer Tools`_ are required. - -Summary:: - - $ sudo port install postgresql83-server - $ sudo port install geos - $ sudo port install proj - $ sudo port install postgis - $ sudo port install gdal - $ sudo port install libgeoip - -.. note:: - - You will also have to modify the ``PATH`` in your ``.profile`` so - that the MacPorts programs are accessible from the command-line:: - - export PATH=/opt/local/bin:/opt/local/lib/postgresql83/bin - - In addition, add the ``FALLBACK_DYLD_LIBRARY_PATH`` setting so that - the libraries can be found by Python:: - - export FALLBACK_DYLD_LIBRARY_PATH=/opt/local/lib:/opt/local/lib/postgresql83 - -__ http://www.macports.org/ - -.. _ubuntudebian: - -Ubuntu & Debian GNU/Linux -------------------------- - -.. _ubuntu: - -Ubuntu -^^^^^^ - -.. _heron: - -8.04 and lower -~~~~~~~~~~~~~~ - -The 8.04 (and lower) versions of Ubuntu use GEOS v2.2.3 in their binary packages, -which is incompatible with GeoDjango. Thus, do *not* use the binary packages -for GEOS or PostGIS and build some prerequisites from source, per the instructions -in this document; however, it is okay to use the PostgreSQL binary packages. - -For more details, please see the Debian instructions for :ref:`etch` below. - -.. _ibex: - -8.10 -~~~~ - -Use the synaptic package manager to install the following packages:: - - $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools - -Afterwards, you may install Django with Python's ``easy_install`` script (the -Ubuntu package ``python-django`` uses an older version missing several -important bug fixes for GeoDjango):: - - $ sudo easy_install Django - -That's it! For the curious, the required binary prerequisites packages are: - -* ``binutils``: for ctypes to find libraries -* ``postgresql-8.3`` -* ``postgresql-server-dev-8.3``: for ``pg_config`` -* ``postgresql-8.3-postgis``: for PostGIS 1.3.3 -* ``libgeos-3.0.0``, and ``libgeos-c1``: for GEOS 3.0.0 -* ``libgdal1-1.5.0``: for GDAL 1.5.0 library -* ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below -* ``python-psycopg2`` -* ``python-setuptools``: for ``easy_install`` - -Optional packages to consider: - -* ``libgeoip1``: for :ref:`GeoIP <ref-geoip>` support -* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr`` -* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation - -.. note:: - - The Ubuntu ``proj`` package does not come with the datum shifting files - installed, which will cause problems with the geographic admin because - the ``null`` datum grid is not available for transforming geometries to the - spherical mercator projection. A solution is to download the - datum-shifting files, create the grid file, and install it yourself:: - - $ wget http://download.osgeo.org/proj/proj-datumgrid-1.4.tar.gz - $ mkdir nad - $ cd nad - $ tar xzf ../proj-datumgrid-1.4.tar.gz - $ nad2bin null < null.lla - $ sudo cp null /usr/share/proj - - Otherwise, the Ubuntu ``proj`` package is fine for general use as long as you - do not plan on doing any database transformation of geometries to the - Google projection (900913). - -.. note:: - - The PostGIS SQL files are not placed the PostgreSQL share directory in the - Ubuntu packages. Use the `create_template_postgis-debian.sh`_ script - instead when :ref:`spatialdb_template`. - -.. _debian: - -Debian ------- - -.. _etch: - -4.0 (Etch) -^^^^^^^^^^ -The situation here is the same as that of Ubuntu :ref:`heron` -- in other words, -some packages must be built from source to work properly with GeoDjango. - -Binary Packages -~~~~~~~~~~~~~~~ -The following command will install acceptable binary packages, as well as -the development tools necessary to build the rest of the requirements:: - - $ sudo apt-get install binutils bzip2 gcc g++ flex make postgresql-8.1 postgresql-server-dev-8.1 python-ctypes python-psycopg2 python-setuptools - -Required package information: - -* ``binutils``: for ctypes to find libraries -* ``bzip2``: for decompressing the source packages -* ``gcc``, ``g++``, ``make``: GNU developer tools used to compile the libraries -* ``flex``: required to build PostGIS -* ``postgresql-8.1`` -* ``postgresql-server-dev-8.1``: for ``pg_config`` -* ``python-ctypes``: Python 2.4 needs to have ctypes installed separately -* ``python-psycopg2`` -* ``python-setuptools``: for ``easy_install`` - -Optional packages: - -* ``libgeoip``: for :ref:`GeoIP <ref-geoip>` support - -Source Packages -~~~~~~~~~~~~~~~ -You will still have to install :ref:`geosbuild`, :ref:`proj4`, -:ref:`postgis`, and :ref:`gdalbuild` from source. Please follow the -directions carefully. - -.. _lenny: - -5.0 (Lenny) -^^^^^^^^^^^ -This version is comparable to Ubuntu :ref:`ibex`, so the command -is very similar:: - - $ sudo apt-get install binutils libgdal1-1.5.0 postgresql-8.3 postgresql-8.3-postgis postgresql-server-dev-8.3 python-psycopg2 python-setuptools - -This assumes that you are using PostgreSQL version 8.3. Else, replace ``8.3`` -in the above command with the appropriate PostgreSQL version. - -.. note:: - - Please read the note in the Ubuntu :ref:`ibex` install documentation - about the ``proj`` package -- it also applies here because the package does - not include the datum shifting files. - -.. _post_install: - -Post-installation Notes -~~~~~~~~~~~~~~~~~~~~~~~ - -If the PostgreSQL database cluster was not initiated after installing, then it -can be created (and started) with the following command:: - - $ sudo pg_createcluster --start 8.3 main - -Afterwards, the ``/etc/init.d/postgresql-8.3`` script should be used to manage -the starting and stopping of PostgreSQL. - -In addition, the SQL files for PostGIS are placed in a different location on -Debian 5.0 . Thus when :ref:`spatialdb_template` either: - -* Create a symbolic link to these files:: - - $ sudo ln -s /usr/share/postgresql-8.3-postgis/{lwpostgis,spatial_ref_sys}.sql /usr/share/postgresql/8.3 - - If not running PostgreSQL 8.3, then replace ``8.3`` in the command above with the correct version. - -* Or use the `create_template_postgis-debian.sh`_ to create the spatial database. - -.. _windows: - -Windows XP ----------- - -Python -^^^^^^ - -First, download the `Python 2.6 installer`__ from the Python Web site. Next, -execute the installer and use defaults, e.g., keep 'Install for all users' -checked and the installation path set as ``C:\Python26``. - -.. note:: - - You may already have a version of Python installed in ``C:\python`` as ESRI - products sometimes install a copy there. *You should still install a - fresh version of Python 2.6.* - -__ http://python.org/ftp/python/2.6.2/python-2.6.2.msi - -PostgreSQL -^^^^^^^^^^ - -First, select a mirror and download the latest `PostgreSQL 8.3 installer`__ from -the EnterpriseDB Web site. - -.. note:: - - PostgreSQL 8.3 is required because PostGIS is not available yet for 8.4. - -After downloading, simply click on the installer, follow the -on-screen directions, and keep the default options (e.g., keep the installation -path as ``C:\Program Files\PostgreSQL\8.3``). - -.. note:: - - This PostgreSQL installation process will create both a new windows user to be the - 'postgres service account' and a special 'postgres superuser' to own the database - cluster. You will be prompted to set a password for both users (make sure to write - them down!). To see basic details on the 'service user' account right click on - 'My Computer' and select 'Manage' or go to: Control Panel -> Administrative Tools -> - Computer Management -> System Tools -> Local Users and Groups. - -If installed successfully, the PostgreSQL server will run in the background each time -the system as started as a Windows service. When finished, the installer should launch -the Application Stack Builder (ASB) -- use this to install PostGIS, see instructions -below for more details. A 'PostgreSQL 8.3' start menu group should be created that -contains shortcuts for the ASB and 'Command Prompt', which launches a terminal window -in the PostgreSQL directory. - -__ http://www.enterprisedb.com/products/pgdownload.do#windows - -PostGIS -^^^^^^^ - -From the Application Stack Builder (Programs -> PostgreSQL 8.3), select -'PostgreSQL Database Server 8.3 on port 5432' from the drop down menu. Next, -select 'PostGIS 1.3.6 for PostgreSQL 8.3' from the 'Spatial Extensions' tree -in the list. Select only the default options during install (do not uncheck -the option to create a default PostGIS database). - -.. note:: - - You will be prompted to enter your 'postgres superuser' password in the - 'Database Connection Information' dialog. - -psycopg2 -^^^^^^^^ - -The ``psycopg2`` Python module provides the interface between Python and the -PostgreSQL database. Download the `Windows installer`__ (v2.0.10) and run -using the default settings. [#]_ - -__ http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.0.10.win32-py2.6-pg8.3.7-release.exe - -GeoDjango Installer -^^^^^^^^^^^^^^^^^^^ - -Download the `GeoDjango Installer`__; this was created [#]_ to simplify the rest -of the process for installing GeoDjango on Windows platforms. The installer -automatically installs Django 1.1, GDAL 1.6.0, PROJ 4.6.1 (including datum grid -files), and configures the necessary environment variables. - -Once the installer has completed, log out and log back in so that the -modifications to the system environment variables take effect, and you -should be good to go. - -.. note:: - - The installer modifies the system ``Path`` environment variable to - include ``C:\Program Files\PostgreSQL\8.3\bin`` and - ``C:\Program Files\GeoDjango\bin``. This is required so that Python - may find the GEOS DLL provided by PostGIS and the GDAL DLL provided - by the installer. The installer also sets the ``GDAL_DATA`` and - ``PROJ_LIB`` environment variables. - -__ http://geodjango.org/windows/GeoDjango_Installer.exe - -.. rubric:: Footnotes -.. [#] The datum shifting files are needed for converting data to and from certain projections. - For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ - requires the ``null`` grid file only included in the extra datum shifting files. - It is easier to install the shifting files now, then to have debug a problem caused by their absence later. -.. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL. -.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_. -.. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_ - routine from ``ctypes.util`` to locate shared libraries. -.. [#] The ``psycopg2`` Windows installers are packaged and maintained by - `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. -.. [#] The source code for the installer is available in the `nsis_installer <http://geodjango.org/hg/nsis_installer/>`_ - GeoDjango mercurial repository. diff --git a/parts/django/docs/ref/contrib/gis/layermapping.txt b/parts/django/docs/ref/contrib/gis/layermapping.txt deleted file mode 100644 index 0b09e17..0000000 --- a/parts/django/docs/ref/contrib/gis/layermapping.txt +++ /dev/null @@ -1,220 +0,0 @@ -.. _ref-layermapping: - -==================================== -``LayerMapping`` data import utility -==================================== - -.. module:: django.contrib.gis.utils.layermapping - :synopsis: Spatial data import utility for GeoDjango models. - -.. currentmodule:: django.contrib.gis.utils - -The :class:`LayerMapping` class provides a way to map the contents of -vector spatial data files (e.g. shapefiles) intoto GeoDjango models. - -This utility grew out of the author's personal needs to eliminate -the code repetition that went into pulling geometries and fields out of -a vector layer, converting to another coordinate system (e.g. WGS84), and -then inserting into a GeoDjango model. - -.. note:: - - Use of :class:`LayerMapping` requires GDAL. - -.. warning :: - - GIS data sources, like shapefiles, may be very large. If you find - that :class:`LayerMapping` is using too much memory, set - :setting:`DEBUG` to ``False`` in your settings. When :setting:`DEBUG` - is set to ``True``, Django :ref:`automatically logs <faq-see-raw-sql-queries>` - *every* SQL query -- thus, when SQL statements contain geometries, it is - easy to consume more memory than is typical. - -Example -======= - -1. You need a GDAL-supported data source, like a shapefile (here we're using - a simple polygon shapefile, ``test_poly.shp``, with three features):: - - >>> from django.contrib.gis.gdal import DataSource - >>> ds = DataSource('test_poly.shp') - >>> layer = ds[0] - >>> print layer.fields # Exploring the fields in the layer, we only want the 'str' field. - ['float', 'int', 'str'] - >>> print len(layer) # getting the number of features in the layer (should be 3) - 3 - >>> print layer.geom_type # Should be 'Polygon' - Polygon - >>> print layer.srs # WGS84 in WKT - GEOGCS["GCS_WGS_1984", - DATUM["WGS_1984", - SPHEROID["WGS_1984",6378137,298.257223563]], - PRIMEM["Greenwich",0], - UNIT["Degree",0.017453292519943295]] - -2. Now we define our corresponding Django model (make sure to use ``syncdb``):: - - from django.contrib.gis.db import models - - class TestGeo(models.Model): - name = models.CharField(max_length=25) # corresponds to the 'str' field - poly = models.PolygonField(srid=4269) # we want our model in a different SRID - objects = models.GeoManager() - def __unicode__(self): - return 'Name: %s' % self.name - -3. Use :class:`LayerMapping` to extract all the features and place them in the - database:: - - >>> from django.contrib.gis.utils import LayerMapping - >>> from geoapp.models import TestGeo - >>> mapping = {'name' : 'str', # The 'name' model field maps to the 'str' layer field. - 'poly' : 'POLYGON', # For geometry fields use OGC name. - } # The mapping is a dictionary - >>> lm = LayerMapping(TestGeo, 'test_poly.shp', mapping) - >>> lm.save(verbose=True) # Save the layermap, imports the data. - Saved: Name: 1 - Saved: Name: 2 - Saved: Name: 3 - -Here, :class:`LayerMapping` just transformed the three geometries from the -shapefile in their original spatial reference system (WGS84) to the spatial -reference system of the GeoDjango model (NAD83). If no spatial reference -system is defined for the layer, use the ``source_srs`` keyword with a -:class:`~django.contrib.gis.gdal.SpatialReference` object to specify one. - -``LayerMapping`` API -==================== - -.. class:: LayerMapping(model, data_source, mapping[, layer=0, source_srs=None, encoding=None, transaction_mode='commit_on_success', transform=True, unique=True, using='default']) - -The following are the arguments and keywords that may be used during -instantiation of ``LayerMapping`` objects. - -================= ========================================================= -Argument Description -================= ========================================================= -``model`` The geographic model, *not* an instance. - -``data_source`` The path to the OGR-supported data source file - (e.g., a shapefile). Also accepts - :class:`django.contrib.gis.gdal.DataSource` instances. - -``mapping`` A dictionary: keys are strings corresponding to - the model field, and values correspond to - string field names for the OGR feature, or if the - model field is a geographic then it should - correspond to the OGR geometry type, - e.g., ``'POINT'``, ``'LINESTRING'``, ``'POLYGON'``. -================= ========================================================= - -===================== ===================================================== -Keyword Arguments -===================== ===================================================== -``layer`` The index of the layer to use from the Data Source - (defaults to 0) - -``source_srs`` Use this to specify the source SRS manually (for - example, some shapefiles don't come with a '.prj' - file). An integer SRID, WKT or PROJ.4 strings, and - :class:`django.contrib.gis.gdal.SpatialReference` - objects are accepted. - -``encoding`` Specifies the character set encoding of the strings - in the OGR data source. For example, ``'latin-1'``, - ``'utf-8'``, and ``'cp437'`` are all valid encoding - parameters. - -``transaction_mode`` May be ``'commit_on_success'`` (default) or - ``'autocommit'``. - -``transform`` Setting this to False will disable coordinate - transformations. In other words, geometries will - be inserted into the database unmodified from their - original state in the data source. - -``unique`` Setting this to the name, or a tuple of names, - from the given model will create models unique - only to the given name(s). Geometries will from - each feature will be added into the collection - associated with the unique model. Forces - the transaction mode to be ``'autocommit'``. - -``using`` New in version 1.2. Sets the database to use when - importing spatial data. Default is ``'default'`` -===================== ===================================================== - -``save()`` Keyword Arguments ----------------------------- - -.. method:: LayerMapping.save([verbose=False, fid_range=False, step=False, progress=False, silent=False, stream=sys.stdout, strict=False]) - -The ``save()`` method also accepts keywords. These keywords are -used for controlling output logging, error handling, and for importing -specific feature ranges. - -=========================== ================================================= -Save Keyword Arguments Description -=========================== ================================================= -``fid_range`` May be set with a slice or tuple of - (begin, end) feature ID's to map from - the data source. In other words, this - keyword enables the user to selectively - import a subset range of features in the - geographic data source. - -``progress`` When this keyword is set, status information - will be printed giving the number of features - processed and successfully saved. By default, - progress information will be printed every 1000 - features processed, however, this default may - be overridden by setting this keyword with an - integer for the desired interval. - -``silent`` By default, non-fatal error notifications are - printed to ``sys.stdout``, but this keyword may - be set to disable these notifications. - -``step`` If set with an integer, transactions will - occur at every step interval. For example, if - ``step=1000``, a commit would occur after the - 1,000th feature, the 2,000th feature etc. - - -``stream`` Status information will be written to this file - handle. Defaults to using ``sys.stdout``, but - any object with a ``write`` method is supported. - -``strict`` Execution of the model mapping will cease upon - the first error encountered. The default value - (``False``) - behavior is to attempt to continue. - -``verbose`` If set, information will be printed - subsequent to each model save - executed on the database. -=========================== ================================================= - -Troubleshooting -=============== - -Running out of memory ---------------------- - -As noted in the warning at the top of this section, Django stores all SQL -queries when ``DEBUG=True``. Set ``DEBUG=False`` in your settings, and this -should stop excessive memory use when running ``LayerMapping`` scripts. - -MySQL: ``max_allowed_packet`` error ------------------------------------ - -If you encounter the following error when using ``LayerMapping`` and MySQL:: - - OperationalError: (1153, "Got a packet bigger than 'max_allowed_packet' bytes") - -Then the solution is to increase the value of the ``max_allowed_packet`` -setting in your MySQL configuration. For example, the default value may -be something low like one megabyte -- the setting may be modified in MySQL's -configuration file (``my.cnf``) in the ``[mysqld]`` section:: - - max_allowed_packet = 10M diff --git a/parts/django/docs/ref/contrib/gis/measure.txt b/parts/django/docs/ref/contrib/gis/measure.txt deleted file mode 100644 index 6971788..0000000 --- a/parts/django/docs/ref/contrib/gis/measure.txt +++ /dev/null @@ -1,180 +0,0 @@ -.. _ref-measure: - -=================== -Measurement Objects -=================== - -.. module:: django.contrib.gis.measure - :synopsis: GeoDjango's distance and area measurment objects. - -The :mod:`django.contrib.gis.measure` module contains objects that allow -for convenient representation of distance and area units of measure. [#]_ -Specifically, it implements two objects, :class:`Distance` and -:class:`Area` -- both of which may be accessed via the -:class:`D` and :class:`A` convenience aliases, respectively. - -Example -======= - -:class:`Distance` objects may be instantiated using a keyword argument indicating the -context of the units. In the example below, two different distance objects are -instantiated in units of kilometers (``km``) and miles (``mi``):: - - >>> from django.contrib.gis.measure import Distance, D - >>> d1 = Distance(km=5) - >>> print d1 - 5.0 km - >>> d2 = D(mi=5) # `D` is an alias for `Distance` - >>> print d2 - 5.0 mi - -Conversions are easy, just access the preferred unit attribute to get a -converted distance quantity:: - - >>> print d1.mi # Converting 5 kilometers to miles - 3.10685596119 - >>> print d2.km # Converting 5 miles to kilometers - 8.04672 - -Moreover, arithmetic operations may be performed between the distance -objects:: - - >>> print d1 + d2 # Adding 5 miles to 5 kilometers - 13.04672 km - >>> print d2 - d1 # Subtracting 5 kilometers from 5 miles - 1.89314403881 mi - -Two :class:`Distance` objects multiplied together will yield an :class:`Area` -object, which uses squared units of measure:: - - >>> a = d1 * d2 # Returns an Area object. - >>> print a - 40.2336 sq_km - -To determine what the attribute abbreviation of a unit is, the ``unit_attname`` -class method may be used:: - - >>> print Distance.unit_attname('US Survey Foot') - survey_ft - >>> print Distance.unit_attname('centimeter') - cm - -.. _supported_units: - -Supported units -=============== - -================================= ======================================== -Unit Attribute Full name or alias(es) -================================= ======================================== -``km`` Kilometre, Kilometer -``mi`` Mile -``m`` Meter, Metre -``yd`` Yard -``ft`` Foot, Foot (International) -``survey_ft`` U.S. Foot, US survey foot -``inch`` Inches -``cm`` Centimeter -``mm`` Millimetre, Millimeter -``um`` Micrometer, Micrometre -``british_ft`` British foot (Sears 1922) -``british_yd`` British yard (Sears 1922) -``british_chain_sears`` British chain (Sears 1922) -``indian_yd`` Indian yard, Yard (Indian) -``sears_yd`` Yard (Sears) -``clarke_ft`` Clarke's Foot -``chain`` Chain -``chain_benoit`` Chain (Benoit) -``chain_sears`` Chain (Sears) -``british_chain_benoit`` British chain (Benoit 1895 B) -``british_chain_sears_truncated`` British chain (Sears 1922 truncated) -``gold_coast_ft`` Gold Coast foot -``link`` Link -``link_benoit`` Link (Benoit) -``link_sears`` Link (Sears) -``clarke_link`` Clarke's link -``fathom`` Fathom -``rod`` Rod -``nm`` Nautical Mile -``nm_uk`` Nautical Mile (UK) -``german_m`` German legal metre -================================= ======================================== - -.. note:: - - :class:`Area` attributes are the same as :class:`Distance` attributes, - except they are prefixed with ``sq_`` (area units are square in nature). - For example, ``Area(sq_m=2)`` creates an :class:`Area` object - representing two square meters. - -Measurement API -=============== - -``Distance`` ------------- - -.. class:: Distance(**kwargs) - - To initialize a distance object, pass in a keyword corresponding to - the desired :ref:`unit attribute name <supported_units>` set with - desired value. For example, the following creates a distance - object representing 5 miles:: - - >>> dist = Distance(mi=5) - - .. method:: __getattr__(unit_att) - - Returns the distance value in units corresponding to the given unit - attribute. For example:: - - >>> print dist.km - 8.04672 - - .. classmethod:: unit_attname(unit_name) - - Returns the distance unit attribute name for the given full unit name. - For example:: - - >>> Distance.unit_attname('Mile') - 'mi' - -.. class:: D - - Alias for :class:`Distance` class. - -``Area`` --------- - -.. class:: Area(**kwargs) - - To initialize a distance object, pass in a keyword corresponding to - the desired :ref:`unit attribute name <supported_units>` set with - desired value. For example, the following creates a distance - object representing 5 square miles:: - - >>> a = Area(sq_mi=5) - - .. method:: __getattr__(unit_att) - - Returns the area value in units corresponding to the given unit - attribute. For example:: - - >>> print a.sq_km - 12.949940551680001 - - .. classmethod:: unit_attname(unit_name) - - Returns the area unit attribute name for the given full unit name. - For example:: - - >>> Area.unit_attname('Kilometer') - 'sq_km' - -.. class:: A - - Alias for :class:`Area` class. - -.. rubric:: Footnotes -.. [#] `Robert Coup <http://koordinates.com/>`_ is the initial author of the measure objects, - and was inspired by Brian Beck's work in `geopy <http://code.google.com/p/geopy/>`_ - and Geoff Biggs' PhD work on dimensioned units for robotics. diff --git a/parts/django/docs/ref/contrib/gis/model-api.txt b/parts/django/docs/ref/contrib/gis/model-api.txt deleted file mode 100644 index 6b50cf3..0000000 --- a/parts/django/docs/ref/contrib/gis/model-api.txt +++ /dev/null @@ -1,265 +0,0 @@ -.. _ref-gis-model-api: - -=================== -GeoDjango Model API -=================== - -.. module:: django.contrib.gis.db.models - :synopsis: GeoDjango model and field API. - -This document explores the details of the GeoDjango Model API. Throughout this -section, we'll be using the following geographic model of a `ZIP code`__ as our -example:: - - from django.contrib.gis.db import models - - class Zipcode(models.Model): - code = models.CharField(max_length=5) - poly = models.PolygonField() - objects = models.GeoManager() - -__ http://en.wikipedia.org/wiki/ZIP_code - -Geometry Field Types -==================== - -Each of the following geometry field types correspond with the -OpenGIS Simple Features specification [#fnogc]_. - -``GeometryField`` ------------------ - -.. class:: GeometryField - -``PointField`` --------------- - -.. class:: PointField - -``LineStringField`` -------------------- - -.. class:: LineStringField - -``PolygonField`` ----------------- - -.. class:: PolygonField - -``MultiPointField`` -------------------- - -.. class:: MultiPointField - -``MultiLineStringField`` ------------------------- - -.. class:: MultiLineStringField - -``MultiPolygonField`` ---------------------- - -.. class:: MultiPolygonField - -``GeometryCollectionField`` ---------------------------- - -.. class:: GeometryCollectionField - -.. _geometry-field-options: - -Geometry Field Options -====================== - -In addition to the regular :ref:`common-model-field-options` available for -Django model fields, geometry fields have the following additional options. -All are optional. - -``srid`` --------- - -.. attribute:: GeometryField.srid - -Sets the SRID [#fnogcsrid]_ (Spatial Reference System Identity) of the geometry field to -the given value. Defaults to 4326 (also known as `WGS84`__, units are in degrees -of longitude and latitude). - -__ http://en.wikipedia.org/wiki/WGS84 - -.. _selecting-an-srid: - -Selecting an SRID -^^^^^^^^^^^^^^^^^ - -Choosing an appropriate SRID for your model is an important decision that the -developer should consider carefully. The SRID is an integer specifier that -corresponds to the projection system that will be used to interpret the data -in the spatial database. [#fnsrid]_ Projection systems give the context to the -coordinates that specify a location. Although the details of `geodesy`__ are -beyond the scope of this documentation, the general problem is that the earth -is spherical and representations of the earth (e.g., paper maps, Web maps) -are not. - -Most people are familiar with using latitude and longitude to reference a -location on the earth's surface. However, latitude and longitude are angles, -not distances. [#fnharvard]_ In other words, while the shortest path between two points on -a flat surface is a straight line, the shortest path between two points on a curved -surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_ Thus, -additional computation is required to obtain distances in planar units (e.g., -kilometers and miles). Using a geographic coordinate system may introduce -complications for the developer later on. For example, PostGIS versions 1.4 -and below do not have the capability to perform distance calculations between -non-point geometries using geographic coordinate systems, e.g., constructing a -query to find all points within 5 miles of a county boundary stored as WGS84. -[#fndist]_ - -Portions of the earth's surface may projected onto a two-dimensional, or -Cartesian, plane. Projected coordinate systems are especially convenient -for region-specific applications, e.g., if you know that your database will -only cover geometries in `North Kansas`__, then you may consider using projection -system specific to that region. Moreover, projected coordinate systems are -defined in Cartesian units (such as meters or feet), easing distance -calculations. - -.. note:: - - If you wish to peform arbitrary distance queries using non-point - geometries in WGS84, consider upgrading to PostGIS 1.5. For - better performance, enable the :attr:`GeometryField.geography` - keyword so that :ref:`geography database type <geography-type>` - is used instead. - -Additional Resources: - -* `spatialreference.org`__: A Django-powered database of spatial reference - systems. -* `The State Plane Coordinate System`__: A Web site covering the various - projection systems used in the United States. Much of the U.S. spatial - data encountered will be in one of these coordinate systems rather than - in a geographic coordinate system such as WGS84. - -__ http://en.wikipedia.org/wiki/Geodesy -__ http://en.wikipedia.org/wiki/Great_circle -__ http://www.spatialreference.org/ref/epsg/2796/ -__ http://spatialreference.org/ -__ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html - -``spatial_index`` ------------------ - -.. attribute:: GeometryField.spatial_index - -Defaults to ``True``. Creates a spatial index for the given geometry -field. - -.. note:: - - This is different from the ``db_index`` field option because spatial - indexes are created in a different manner than regular database - indexes. Specifically, spatial indexes are typically created using - a variant of the R-Tree, while regular database indexes typically - use B-Trees. - -``dim`` -------- - -.. versionadded:: 1.2 - -.. attribute:: GeometryField.dim - -This option may be used for customizing the coordinate dimension of the -geometry field. By default, it is set to 2, for representing two-dimensional -geometries. For spatial backends that support it, it may be set to 3 for -three-dimensonal support. - -.. note:: - - At this time 3D support requires that GEOS 3.1 be installed, and is - limited only to the PostGIS spatial backend. - -``geography`` -------------- - -.. versionadded:: 1.2 - -.. attribute:: GeometryField.geography - -If set to ``True``, this option will create a database column of -type geography, rather than geometry. Please refer to the -:ref:`geography type <geography-type>` section below for more -details. - -.. note:: - - Geography support is limited only to PostGIS 1.5+, and will - force the SRID to be 4326. - -.. _geography-type: - -Geography Type -^^^^^^^^^^^^^^ - -In PostGIS 1.5, the geography type was introduced -- it provides -provides native support for spatial features represented with geographic -coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_ -Unlike the plane used by a geometry type, the geography type uses a spherical -representation of its data. Distance and measurement operations -performed on a geography column automatically employ great circle arc -calculations and return linear units. In other words, when ``ST_Distance`` -is called on two geographies, a value in meters is returned (as opposed -to degrees if called on a geometry column in WGS84). - -Because geography calculations involve more mathematics, only a subset of the -PostGIS spatial lookups are available for the geography type. Practically, -this means that in addition to the :ref:`distance lookups <distance-lookups>` -only the following additional :ref:`spatial lookups <spatial-lookups>` are -available for geography columns: - -* :lookup:`bboverlaps` -* :lookup:`coveredby` -* :lookup:`covers` -* :lookup:`intersects` - -For more information, the PostGIS documentation contains a helpful section on -determining `when to use geography data type over geometry data type -<http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_GeographyVSGeometry>`_. - -``GeoManager`` -============== - -.. currentmodule:: django.contrib.gis.db.models -.. class:: GeoManager - -In order to conduct geographic queries, each geographic model requires -a ``GeoManager`` model manager. This manager allows for the proper SQL -construction for geographic queries; thus, without it, all geographic filters -will fail. It should also be noted that ``GeoManager`` is required even if the -model does not have a geographic field itself, e.g., in the case of a -``ForeignKey`` relation to a model with a geographic field. For example, -if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` -model:: - - from django.contrib.gis.db import models - from django.contrib.localflavor.us.models import USStateField - - class Address(models.Model): - num = models.IntegerField() - street = models.CharField(max_length=100) - city = models.CharField(max_length=100) - state = USStateField() - zipcode = models.ForeignKey(Zipcode) - objects = models.GeoManager() - -The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, -for example:: - - qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)') - -.. rubric:: Footnotes -.. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999). -.. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems). -.. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table. -.. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems. -.. [#fnthematic] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3. -.. [#fndist] This limitation does not apply to PostGIS 1.5. It should be noted that even in previous versions of PostGIS, this isn't impossible using GeoDjango; you could for example, take a known point in a projected coordinate system, buffer it to the appropriate radius, and then perform an intersection operation with the buffer transformed to the geographic coordinate system. -.. [#fngeography] Please refer to the `PostGIS Geography Type <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_Geography>`_ documentation for more details. diff --git a/parts/django/docs/ref/contrib/gis/ogrinspect.txt b/parts/django/docs/ref/contrib/gis/ogrinspect.txt deleted file mode 100644 index ed285e0..0000000 --- a/parts/django/docs/ref/contrib/gis/ogrinspect.txt +++ /dev/null @@ -1,21 +0,0 @@ -.. _ref-ogrinspect: - -============== -OGR Inspection -============== - -.. module:: django.contrib.gis.utils.ogrinspect - :synopsis: Utilities for inspecting OGR data sources. - -.. currentmodule:: django.contrib.gis.utils - -``ogrinspect`` -============== - -.. function:: ogrinspect(data_source, model_name[, **kwargs]) - :noindex: - -``mapping`` -=========== - -.. function:: mapping(data_source, [geom_name='geom', layer_key=0, multi_geom=False]) diff --git a/parts/django/docs/ref/contrib/gis/sitemaps.txt b/parts/django/docs/ref/contrib/gis/sitemaps.txt deleted file mode 100644 index 75bddd3..0000000 --- a/parts/django/docs/ref/contrib/gis/sitemaps.txt +++ /dev/null @@ -1,27 +0,0 @@ -=================== -Geographic Sitemaps -=================== - -Google's sitemap protocol has been recently extended to support geospatial -content. [#]_ This includes the addition of the ``<url>`` child element -``<geo:geo>``, which tells Google that the content located at the URL is -geographic in nature. [#]_ - -Example -======= - -Reference -========= - -``KMLSitemap`` --------------- - -``KMZSitemap`` --------------- - -``GeoRSSSitemap`` ------------------ - -.. rubric:: Footnotes -.. [#] Google, Inc., `What is a Geo Sitemap? <http://www.google.com/support/webmasters/bin/answer.py?answer=94554>`_. -.. [#] Google, Inc., `Submit Your Geo Content to Google <http://code.google.com/apis/kml/documentation/kmlSearch.html>`_. diff --git a/parts/django/docs/ref/contrib/gis/testing.txt b/parts/django/docs/ref/contrib/gis/testing.txt deleted file mode 100644 index 889b43a..0000000 --- a/parts/django/docs/ref/contrib/gis/testing.txt +++ /dev/null @@ -1,268 +0,0 @@ -====================== -Testing GeoDjango Apps -====================== - -.. versionchanged:: 1.2 - -In Django 1.2, the addition of :ref:`spatial-backends` -simplified the process of testing GeoDjango applications. Specifically, testing -GeoDjango applications is now the same as :doc:`/topics/testing`. - -Included in this documentation are some additional notes and settings -for :ref:`testing-postgis` and :ref:`testing-spatialite` users. - -.. note:: - - Django 1.1 users are still required to use a custom :setting:`TEST_RUNNER`. - See the :ref:`testing-1.1` section for more details. - -.. _testing-postgis: - -PostGIS -======= - -Settings --------- - -.. note:: - - The settings below have sensible defaults, and shouldn't require manual setting. - -.. setting:: POSTGIS_TEMPLATE - -``POSTGIS_TEMPLATE`` -^^^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 1.1 - -.. versionchanged:: 1.2 - -This setting may be used to customize the name of the PostGIS template -database to use. In Django versions 1.2 and above, it automatically -defaults to ``'template_postgis'`` (the same name used in the -:ref:`installation documentation <spatialdb_template>`). - -.. note:: - - Django 1.1 users will still have to define the :setting:`POSTGIS_TEMPLATE` - with a value, for example:: - - POSTGIS_TEMPLATE='template_postgis' - -.. setting:: POSTGIS_VERSION - -``POSTGIS_VERSION`` -^^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 1.1 - -When GeoDjango's spatial backend initializes on PostGIS, it has to perform -a SQL query to determine the version in order to figure out what -features are available. Advanced users wishing to prevent this additional -query may set the version manually using a 3-tuple of integers specifying -the major, minor, and subminor version numbers for PostGIS. For example, -to configure for PostGIS 1.5.2 you would use:: - - POSTGIS_VERSION = (1, 5, 2) - -Obtaining Sufficient Privileges -------------------------------- - -Depending on your configuration, this section describes several methods to -configure a database user with sufficient privileges to run tests for -GeoDjango applications on PostgreSQL. If your -:ref:`spatial database template <spatialdb_template>` -was created like in the instructions, then your testing database user -only needs to have the ability to create databases. In other configurations, -you may be required to use a database superuser. - -Create Database User -^^^^^^^^^^^^^^^^^^^^ - -To make database user with the ability to create databases, use the -following command:: - - $ createuser --createdb -R -S <user_name> - -The ``-R -S`` flags indicate that we do not want the user to have the ability -to create additional users (roles) or to be a superuser, respectively. - -Alternatively, you may alter an existing user's role from the SQL shell -(assuming this is done from an existing superuser account):: - - postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE; - -Create Database Superuser -^^^^^^^^^^^^^^^^^^^^^^^^^ - -This may be done at the time the user is created, for example:: - - $ createuser --superuser <user_name> - -Or you may alter the user's role from the SQL shell (assuming this -is done from an existing superuser account):: - - postgres# ALTER ROLE <user_name> SUPERUSER; - - -Create Local PostgreSQL Database -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. Initialize database: ``initdb -D /path/to/user/db`` - -2. If there's already a Postgres instance on the machine, it will need - to use a different TCP port than 5432. Edit ``postgresql.conf`` (in - ``/path/to/user/db``) to change the database port (e.g. ``port = 5433``). - -3. Start this database ``pg_ctl -D /path/to/user/db start`` - -Windows -------- - -On Windows platforms the pgAdmin III utility may also be used as -a simple way to add superuser privileges to your database user. - -By default, the PostGIS installer on Windows includes a template -spatial database entitled ``template_postgis``. - -.. _testing-spatialite: - -SpatiaLite -========== - -.. versionadded:: 1.1 - -You will need to download the `initialization SQL`__ script for SpatiaLite:: - - $ wget http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip - $ unzip init_spatialite-2.3.zip - -If ``init_spatialite-2.3.sql`` is in the same path as your project's ``manage.py``, -then all you have to do is:: - - $ python manage.py test - -Settings --------- - -.. setting:: SPATIALITE_SQL - -``SPATIALITE_SQL`` -^^^^^^^^^^^^^^^^^^ - -.. versionadded:: 1.1 - -By default, the GeoDjango test runner looks for the SpatiaLite SQL in the -same directory where it was invoked (by default the same directory where -``manage.py`` is located). If you want to use a different location, then -you may add the following to your settings:: - - SPATIALITE_SQL='/path/to/init_spatialite-2.3.sql' - -__ http://www.gaia-gis.it/spatialite/init_spatialite-2.3.zip - -.. _testing-1.1: - -Testing GeoDjango Applications in 1.1 -===================================== - -In Django 1.1, to accommodate the extra steps required to scaffalod a -spatial database automatically, a test runner customized for GeoDjango -must be used. To use this runner, configure :setting:`TEST_RUNNER` as follows:: - - TEST_RUNNER='django.contrib.gis.tests.run_tests' - -.. note:: - - In order to create a spatial database, the :setting:`USER` setting - (or :setting:`TEST_USER`, if optionally defined on Oracle) requires - elevated privileges. When using PostGIS or MySQL, the database user - must have at least the ability to create databases. When testing on Oracle, - the user should be a superuser. - -.. _geodjango-tests: - -GeoDjango Tests -=============== - -.. versionchanged:: 1.2.4 - -GeoDjango's test suite may be run in one of two ways, either by itself or -with the rest of Django's :ref:`unit-tests`. - -.. note:: - - The :setting:`TEST_RUNNER` previously used to execute the GeoDjango - test suite,:func:`django.contrib.gis.tests.run_gis_tests`, was deprecated - in favor of the :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner` - class. - -Run only GeoDjango tests ------------------------- - -To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER` -setting must be changed to use the -:class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`:: - - TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner' - -Example -^^^^^^^ - -First, you'll need a bare-bones settings file, like below, that is -customized with your spatial database name and user:: - - TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner' - - DATABASES = { - 'default': { - 'ENGINE': 'django.contrib.gis.db.backends.postgis', - 'NAME': 'a_spatial_database', - 'USER': 'db_user' - } - } - -Assuming the above is in a file called ``postgis.py`` that is in the -the same directory as ``manage.py`` of your Django project, then -you may run the tests with the following command:: - - $ python manage.py test --settings=postgis - -Run with ``runtests.py`` ------------------------- - -To have the GeoDjango tests executed when -:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py`` -all of the databases in the settings file must be using one of the -:ref:`spatial database backends <spatial-backends>`. - -.. warning:: - - Do not change the :setting:`TEST_RUNNER` setting - when running the GeoDjango tests with ``runtests.py``. - -Example -^^^^^^^ - -The following is an example bare-bones settings file with spatial backends -that can be used to run the entire Django test suite, including those -in :mod:`django.contrib.gis`:: - - DATABASES = { - 'default': { - 'ENGINE': 'django.contrib.gis.db.backends.postgis', - 'NAME': 'geodjango', - 'USER': 'geodjango', - }, - 'other': { - 'ENGINE': 'django.contrib.gis.db.backends.postgis', - 'NAME': 'other', - 'USER': 'geodjango', - } - } - -Assuming the settings above were in a ``postgis.py`` file in the same -directory as ``runtests.py``, then all Django and GeoDjango tests would -be performed when executing the command:: - - $ ./runtests.py --settings=postgis diff --git a/parts/django/docs/ref/contrib/gis/tutorial.txt b/parts/django/docs/ref/contrib/gis/tutorial.txt deleted file mode 100644 index 9deeb78..0000000 --- a/parts/django/docs/ref/contrib/gis/tutorial.txt +++ /dev/null @@ -1,758 +0,0 @@ -================== -GeoDjango Tutorial -================== - -Introduction -============ - -GeoDjango is an add-on for Django that turns it into a world-class geographic -Web framework. GeoDjango strives to make at as simple as possible to create -geographic Web applications, like location-based services. Some features include: - -* Django model fields for `OGC`_ geometries. -* Extensions to Django's ORM for the querying and manipulation of spatial data. -* Loosely-coupled, high-level Python interfaces for GIS geometry operations and - data formats. -* Editing of geometry fields inside the admin. - -This tutorial assumes a familiarity with Django; thus, if you're brand new to -Django please read through the :doc:`regular tutorial </intro/tutorial01>` to introduce -yourself with basic Django concepts. - -.. note:: - - GeoDjango has special prerequisites overwhat is required by Django -- - please consult the :ref:`installation documentation <ref-gis-install>` - for more details. - -This tutorial will guide you through the creation of a geographic Web -application for viewing the `world borders`_. [#]_ Some of the code -used in this tutorial is taken from and/or inspired by the `GeoDjango -basic apps`_ project. [#]_ - -.. note:: - - Proceed through the tutorial sections sequentially for step-by-step - instructions. - -.. _OGC: http://www.opengeospatial.org/ -.. _world borders: http://thematicmapping.org/downloads/world_borders.php -.. _GeoDjango basic apps: http://code.google.com/p/geodjango-basic-apps/ - -Setting Up -========== - -Create a Spatial Database -------------------------- - -.. note:: - - MySQL and Oracle users can skip this section because spatial types - are already built into the database. - -First, a spatial database needs to be created for our project. If using -PostgreSQL and PostGIS, then the following commands will -create the database from a :ref:`spatial database template <spatialdb_template>`:: - - $ createdb -T template_postgis geodjango - -.. note:: - - This command must be issued by a database user that has permissions to - create a database. Here is an example set of commands to create such - a user:: - - $ sudo su - postgres - $ createuser --createdb geo - $ exit - - Replace ``geo`` to correspond to the system login user name will be - connecting to the database. For example, ``johndoe`` if that is the - system user that will be running GeoDjango. - -Users of SQLite and SpatiaLite should consult the instructions on how -to create a :ref:`SpatiaLite database <create_spatialite_db>`. - -Create GeoDjango Project ------------------------- - -Use the ``django-admin.py`` script like normal to create a ``geodjango`` project:: - - $ django-admin.py startproject geodjango - -With the project initialized, now create a ``world`` Django application within -the ``geodjango`` project:: - - $ cd geodjango - $ python manage.py startapp world - -Configure ``settings.py`` -------------------------- - -The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit -the database connection settings appropriately:: - - DATABASES = { - 'default': { - 'ENGINE': 'django.contrib.gis.db.backends.postgis', - 'NAME': 'geodjango', - 'USER': 'geo', - } - } - -.. note:: - - These database settings are for Django 1.2 and above. - -In addition, modify the :setting:`INSTALLED_APPS` setting to include -:mod:`django.contrib.admin`, :mod:`django.contrib.gis`, -and ``world`` (our newly created application):: - - INSTALLED_APPS = ( - 'django.contrib.auth', - 'django.contrib.contenttypes', - 'django.contrib.sessions', - 'django.contrib.sites', - 'django.contrib.admin', - 'django.contrib.gis', - 'world' - ) - -Geographic Data -=============== - -.. _worldborders: - -World Borders -------------- - -The world borders data is available in this `zip file`__. Create a data directory -in the ``world`` application, download the world borders data, and unzip. -On GNU/Linux platforms the following commands should do it:: - - $ mkdir world/data - $ cd world/data - $ wget http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip - $ unzip TM_WORLD_BORDERS-0.3.zip - $ cd ../.. - -The world borders ZIP file contains a set of data files collectively known as -an `ESRI Shapefile`__, one of the most popular geospatial data formats. When -unzipped the world borders data set includes files with the following extensions: - -* ``.shp``: Holds the vector data for the world borders geometries. -* ``.shx``: Spatial index file for geometries stored in the ``.shp``. -* ``.dbf``: Database file for holding non-geometric attribute data - (e.g., integer and character fields). -* ``.prj``: Contains the spatial reference information for the geographic - data stored in the shapefile. - -__ http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip -__ http://en.wikipedia.org/wiki/Shapefile - -Use ``ogrinfo`` to examine spatial data ---------------------------------------- - -The GDAL ``ogrinfo`` utility is excellent for examining metadata about -shapefiles (or other vector data sources):: - - $ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp - INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp' - using driver `ESRI Shapefile' successful. - 1: TM_WORLD_BORDERS-0.3 (Polygon) - -Here ``ogrinfo`` is telling us that the shapefile has one layer, and that -layer contains polygon data. To find out more we'll specify the layer name -and use the ``-so`` option to get only important summary information:: - - $ ogrinfo -so world/data/TM_WORLD_BORDERS-0.3.shp TM_WORLD_BORDERS-0.3 - INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp' - using driver `ESRI Shapefile' successful. - - Layer name: TM_WORLD_BORDERS-0.3 - Geometry: Polygon - Feature Count: 246 - Extent: (-180.000000, -90.000000) - (180.000000, 83.623596) - Layer SRS WKT: - GEOGCS["GCS_WGS_1984", - DATUM["WGS_1984", - SPHEROID["WGS_1984",6378137.0,298.257223563]], - PRIMEM["Greenwich",0.0], - UNIT["Degree",0.0174532925199433]] - FIPS: String (2.0) - ISO2: String (2.0) - ISO3: String (3.0) - UN: Integer (3.0) - NAME: String (50.0) - AREA: Integer (7.0) - POP2005: Integer (10.0) - REGION: Integer (3.0) - SUBREGION: Integer (3.0) - LON: Real (8.3) - LAT: Real (7.3) - -This detailed summary information tells us the number of features in the layer -(246), the geographical extent, the spatial reference system ("SRS WKT"), -as well as detailed information for each attribute field. For example, -``FIPS: String (2.0)`` indicates that there's a ``FIPS`` character field -with a maximum length of 2; similarly, ``LON: Real (8.3)`` is a floating-point -field that holds a maximum of 8 digits up to three decimal places. Although -this information may be found right on the `world borders`_ Web site, this shows -you how to determine this information yourself when such metadata is not -provided. - -Geographic Models -================= - -Defining a Geographic Model ---------------------------- - -Now that we've examined our world borders data set using ``ogrinfo``, we can -create a GeoDjango model to represent this data:: - - from django.contrib.gis.db import models - - class WorldBorders(models.Model): - # Regular Django fields corresponding to the attributes in the - # world borders shapefile. - name = models.CharField(max_length=50) - area = models.IntegerField() - pop2005 = models.IntegerField('Population 2005') - fips = models.CharField('FIPS Code', max_length=2) - iso2 = models.CharField('2 Digit ISO', max_length=2) - iso3 = models.CharField('3 Digit ISO', max_length=3) - un = models.IntegerField('United Nations Code') - region = models.IntegerField('Region Code') - subregion = models.IntegerField('Sub-Region Code') - lon = models.FloatField() - lat = models.FloatField() - - # GeoDjango-specific: a geometry field (MultiPolygonField), and - # overriding the default manager with a GeoManager instance. - mpoly = models.MultiPolygonField() - objects = models.GeoManager() - - # So the model is pluralized correctly in the admin. - class Meta: - verbose_name_plural = "World Borders" - - # Returns the string representation of the model. - def __unicode__(self): - return self.name - -Two important things to note: - -1. The ``models`` module is imported from :mod:`django.contrib.gis.db`. -2. The model overrides its default manager with - :class:`~django.contrib.gis.db.models.GeoManager`; this is *required* - to perform spatial queries. - -When declaring a geometry field on your model the default spatial reference system -is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in -longitude/latitude pairs in units of degrees. If you want the coordinate system to be -different, then SRID of the geometry field may be customized by setting the ``srid`` -with an integer corresponding to the coordinate system of your choice. - -__ http://en.wikipedia.org/wiki/SRID - -Run ``syncdb`` --------------- - -After you've defined your model, it needs to be synced with the spatial database. -First, let's look at the SQL that will generate the table for the ``WorldBorders`` -model:: - - $ python manage.py sqlall world - -This management command should produce the following output:: - - BEGIN; - CREATE TABLE "world_worldborders" ( - "id" serial NOT NULL PRIMARY KEY, - "name" varchar(50) NOT NULL, - "area" integer NOT NULL, - "pop2005" integer NOT NULL, - "fips" varchar(2) NOT NULL, - "iso2" varchar(2) NOT NULL, - "iso3" varchar(3) NOT NULL, - "un" integer NOT NULL, - "region" integer NOT NULL, - "subregion" integer NOT NULL, - "lon" double precision NOT NULL, - "lat" double precision NOT NULL - ) - ; - SELECT AddGeometryColumn('world_worldborders', 'mpoly', 4326, 'MULTIPOLYGON', 2); - ALTER TABLE "world_worldborders" ALTER "mpoly" SET NOT NULL; - CREATE INDEX "world_worldborders_mpoly_id" ON "world_worldborders" USING GIST ( "mpoly" GIST_GEOMETRY_OPS ); - COMMIT; - -If satisfied, you may then create this table in the database by running the -``syncdb`` management command:: - - $ python manage.py syncdb - Creating table world_worldborders - Installing custom SQL for world.WorldBorders model - -The ``syncdb`` command may also prompt you to create an admin user; go ahead and -do so (not required now, may be done at any point in the future using the -``createsuperuser`` management command). - -Importing Spatial Data -====================== - -This section will show you how to take the data from the world borders -shapefile and import it into GeoDjango models using the :ref:`ref-layermapping`. -There are many different different ways to import data in to a -spatial database -- besides the tools included within GeoDjango, you -may also use the following to populate your spatial database: - -* `ogr2ogr`_: Command-line utility, included with GDAL, that - supports loading a multitude of vector data formats into - the PostGIS, MySQL, and Oracle spatial databases. -* `shp2pgsql`_: This utility is included with PostGIS and only supports - ESRI shapefiles. - -.. _ogr2ogr: http://www.gdal.org/ogr2ogr.html -.. _shp2pgsql: http://postgis.refractions.net/documentation/manual-1.5/ch04.html#shp2pgsql_usage - -.. _gdalinterface: - -GDAL Interface --------------- - -Earlier we used the the ``ogrinfo`` to explore the contents of the world borders -shapefile. Included within GeoDjango is an interface to GDAL's powerful OGR -library -- in other words, you'll be able explore all the vector data sources -that OGR supports via a Pythonic API. - -First, invoke the Django shell:: - - $ python manage.py shell - -If the :ref:`worldborders` data was downloaded like earlier in the -tutorial, then we can determine the path using Python's built-in -``os`` module:: - - >>> import os - >>> from geodjango import world - >>> world_shp = os.path.abspath(os.path.join(os.path.dirname(world.__file__), - ... 'data/TM_WORLD_BORDERS-0.3.shp')) - -Now, the world borders shapefile may be opened using GeoDjango's -:class:`~django.contrib.gis.gdal.DataSource` interface:: - - >>> from django.contrib.gis.gdal import * - >>> ds = DataSource(world_shp) - >>> print ds - / ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile) - -Data source objects can have different layers of geospatial features; however, -shapefiles are only allowed to have one layer:: - - >>> print len(ds) - 1 - >>> lyr = ds[0] - >>> print lyr - TM_WORLD_BORDERS-0.3 - -You can see what the geometry type of the layer is and how many features it -contains:: - - >>> print lyr.geom_type - Polygon - >>> print len(lyr) - 246 - -.. note:: - - Unfortunately the shapefile data format does not allow for greater - specificity with regards to geometry types. This shapefile, like - many others, actually includes ``MultiPolygon`` geometries in its - features. You need to watch out for this when creating your models - as a GeoDjango ``PolygonField`` will not accept a ``MultiPolygon`` - type geometry -- thus a ``MultiPolygonField`` is used in our model's - definition instead. - -The :class:`~django.contrib.gis.gdal.Layer` may also have a spatial reference -system associated with it -- if it does, the ``srs`` attribute will return a -:class:`~django.contrib.gis.gdal.SpatialReference` object:: - - >>> srs = lyr.srs - >>> print srs - GEOGCS["GCS_WGS_1984", - DATUM["WGS_1984", - SPHEROID["WGS_1984",6378137.0,298.257223563]], - PRIMEM["Greenwich",0.0], - UNIT["Degree",0.0174532925199433]] - >>> srs.proj4 # PROJ.4 representation - '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ' - -Here we've noticed that the shapefile is in the popular WGS84 spatial reference -system -- in other words, the data uses units of degrees longitude and latitude. - -In addition, shapefiles also support attribute fields that may contain -additional data. Here are the fields on the World Borders layer: - - >>> print lyr.fields - ['FIPS', 'ISO2', 'ISO3', 'UN', 'NAME', 'AREA', 'POP2005', 'REGION', 'SUBREGION', 'LON', 'LAT'] - -Here we are examining the OGR types (e.g., whether a field is an integer or -a string) associated with each of the fields: - - >>> [fld.__name__ for fld in lyr.field_types] - ['OFTString', 'OFTString', 'OFTString', 'OFTInteger', 'OFTString', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTReal', 'OFTReal'] - -You can iterate over each feature in the layer and extract information from both -the feature's geometry (accessed via the ``geom`` attribute) as well as the -feature's attribute fields (whose **values** are accessed via ``get()`` -method):: - - >>> for feat in lyr: - ... print feat.get('NAME'), feat.geom.num_points - ... - Guernsey 18 - Jersey 26 - South Georgia South Sandwich Islands 338 - Taiwan 363 - -:class:`~django.contrib.gis.gdal.Layer` objects may be sliced:: - - >>> lyr[0:2] - [<django.contrib.gis.gdal.feature.Feature object at 0x2f47690>, <django.contrib.gis.gdal.feature.Feature object at 0x2f47650>] - -And individual features may be retrieved by their feature ID:: - - >>> feat = lyr[234] - >>> print feat.get('NAME') - San Marino - -Here the boundary geometry for San Marino is extracted and looking -exported to WKT and GeoJSON:: - - >>> geom = feat.geom - >>> print geom.wkt - POLYGON ((12.415798 43.957954,12.450554 ... - >>> print geom.json - { "type": "Polygon", "coordinates": [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ... - - -``LayerMapping`` ----------------- - -We're going to dive right in -- create a file called ``load.py`` inside the -``world`` application, and insert the following:: - - import os - from django.contrib.gis.utils import LayerMapping - from models import WorldBorders - - world_mapping = { - 'fips' : 'FIPS', - 'iso2' : 'ISO2', - 'iso3' : 'ISO3', - 'un' : 'UN', - 'name' : 'NAME', - 'area' : 'AREA', - 'pop2005' : 'POP2005', - 'region' : 'REGION', - 'subregion' : 'SUBREGION', - 'lon' : 'LON', - 'lat' : 'LAT', - 'mpoly' : 'MULTIPOLYGON', - } - - world_shp = os.path.abspath(os.path.join(os.path.dirname(__file__), 'data/TM_WORLD_BORDERS-0.3.shp')) - - def run(verbose=True): - lm = LayerMapping(WorldBorders, world_shp, world_mapping, - transform=False, encoding='iso-8859-1') - - lm.save(strict=True, verbose=verbose) - -A few notes about what's going on: - -* Each key in the ``world_mapping`` dictionary corresponds to a field in the - ``WorldBorders`` model, and the value is the name of the shapefile field - that data will be loaded from. -* The key ``mpoly`` for the geometry field is ``MULTIPOLYGON``, the - geometry type we wish to import as. Even if simple polygons are encountered - in the shapefile they will automatically be converted into collections prior - to insertion into the database. -* The path to the shapefile is not absolute -- in other words, if you move the - ``world`` application (with ``data`` subdirectory) to a different location, - then the script will still work. -* The ``transform`` keyword is set to ``False`` because the data in the - shapefile does not need to be converted -- it's already in WGS84 (SRID=4326). -* The ``encoding`` keyword is set to the character encoding of string values in - the shapefile. This ensures that string values are read and saved correctly - from their original encoding system. - -Afterwards, invoke the Django shell from the ``geodjango`` project directory:: - - $ python manage.py shell - -Next, import the ``load`` module, call the ``run`` routine, and watch ``LayerMapping`` -do the work:: - - >>> from world import load - >>> load.run() - - -.. _ogrinspect-intro: - -Try ``ogrinspect`` ------------------- -Now that you've seen how to define geographic models and import data with the -:ref:`ref-layermapping`, it's possible to further automate this process with -use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect` -command introspects a GDAL-supported vector data source (e.g., a shapefile) and -generates a model definition and ``LayerMapping`` dictionary automatically. - -The general usage of the command goes as follows:: - - $ python manage.py ogrinspect [options] <data_source> <model_name> [options] - -Where ``data_source`` is the path to the GDAL-supported data source and -``model_name`` is the name to use for the model. Command-line options may -be used to further define how the model is generated. - -For example, the following command nearly reproduces the ``WorldBorders`` model -and mapping dictionary created above, automatically:: - - $ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp WorldBorders --srid=4326 --mapping --multi - -A few notes about the command-line options given above: - -* The ``--srid=4326`` option sets the SRID for the geographic field. -* The ``--mapping`` option tells ``ogrinspect`` to also generate a - mapping dictionary for use with :class:`~django.contrib.gis.utils.LayerMapping`. -* The ``--multi`` option is specified so that the geographic field is a - :class:`~django.contrib.gis.db.models.MultiPolygonField` instead of just a - :class:`~django.contrib.gis.db.models.PolygonField`. - -The command produces the following output, which may be copied -directly into the ``models.py`` of a GeoDjango application:: - - # This is an auto-generated Django model module created by ogrinspect. - from django.contrib.gis.db import models - - class WorldBorders(models.Model): - fips = models.CharField(max_length=2) - iso2 = models.CharField(max_length=2) - iso3 = models.CharField(max_length=3) - un = models.IntegerField() - name = models.CharField(max_length=50) - area = models.IntegerField() - pop2005 = models.IntegerField() - region = models.IntegerField() - subregion = models.IntegerField() - lon = models.FloatField() - lat = models.FloatField() - geom = models.MultiPolygonField(srid=4326) - objects = models.GeoManager() - - # Auto-generated `LayerMapping` dictionary for WorldBorders model - worldborders_mapping = { - 'fips' : 'FIPS', - 'iso2' : 'ISO2', - 'iso3' : 'ISO3', - 'un' : 'UN', - 'name' : 'NAME', - 'area' : 'AREA', - 'pop2005' : 'POP2005', - 'region' : 'REGION', - 'subregion' : 'SUBREGION', - 'lon' : 'LON', - 'lat' : 'LAT', - 'geom' : 'MULTIPOLYGON', - } - -Spatial Queries -=============== - -Spatial Lookups ---------------- -GeoDjango extends the Django ORM and allows the use of spatial lookups. -Let's do an example where we find the ``WorldBorder`` model that contains -a point. First, fire up the management shell:: - - $ python manage.py shell - -Now, define a point of interest [#]_:: - - >>> pnt_wkt = 'POINT(-95.3385 29.7245)' - -The ``pnt_wkt`` string represents the point at -95.3385 degrees longitude, -and 29.7245 degrees latitude. The geometry is in a format known as -Well Known Text (WKT), an open standard issued by the Open Geospatial -Consortium (OGC). [#]_ Import the ``WorldBorders`` model, and perform -a ``contains`` lookup using the ``pnt_wkt`` as the parameter:: - - >>> from world.models import WorldBorders - >>> qs = WorldBorders.objects.filter(mpoly__contains=pnt_wkt) - >>> qs - [<WorldBorders: United States>] - -Here we retrieved a ``GeoQuerySet`` that has only one model: the one -for the United States (which is what we would expect). Similarly, -a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the ``intersects`` -spatial lookup is combined with the ``get`` method to retrieve -only the ``WorldBorders`` instance for San Marino instead of a queryset:: - - >>> from django.contrib.gis.geos import Point - >>> pnt = Point(12.4604, 43.9420) - >>> sm = WorldBorders.objects.get(mpoly__intersects=pnt) - >>> sm - <WorldBorders: San Marino> - -The ``contains`` and ``intersects`` lookups are just a subset of what's -available -- the :ref:`ref-gis-db-api` documentation has more. - -Automatic Spatial Transformations ---------------------------------- -When querying the spatial database GeoDjango automatically transforms -geometries if they're in a different coordinate system. In the following -example, the coordinate will be expressed in terms of `EPSG SRID 32140`__, -a coordinate system specific to south Texas **only** and in units of -**meters** and not degrees:: - - >>> from django.contrib.gis.geos import * - >>> pnt = Point(954158.1, 4215137.1, srid=32140) - -Note that ``pnt`` may also constructed with EWKT, an "extended" form of -WKT that includes the SRID:: - - >>> pnt = GEOSGeometry('SRID=32140;POINT(954158.1 4215137.1)') - -When using GeoDjango's ORM, it will automatically wrap geometry values -in transformation SQL, allowing the developer to work at a higher level -of abstraction:: - - >>> qs = WorldBorders.objects.filter(mpoly__intersects=pnt) - >>> qs.query.as_sql() # Generating the SQL - ('SELECT "world_worldborders"."id", "world_worldborders"."name", "world_worldborders"."area", - "world_worldborders"."pop2005", "world_worldborders"."fips", "world_worldborders"."iso2", - "world_worldborders"."iso3", "world_worldborders"."un", "world_worldborders"."region", - "world_worldborders"."subregion", "world_worldborders"."lon", "world_worldborders"."lat", - "world_worldborders"."mpoly" FROM "world_worldborders" - WHERE ST_Intersects("world_worldborders"."mpoly", ST_Transform(%s, 4326))', - (<django.contrib.gis.db.backend.postgis.adaptor.PostGISAdaptor object at 0x25641b0>,)) - >>> qs # printing evaluates the queryset - [<WorldBorders: United States>] - -__ http://spatialreference.org/ref/epsg/32140/ - -Lazy Geometries ---------------- -Geometries come to GeoDjango in a standardized textual representation. Upon -access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`, -exposing powerful functionality, such as serialization properties for -popular geospatial formats:: - - >>> sm = WorldBorders.objects.get(name='San Marino') - >>> sm.mpoly - <MultiPolygon object at 0x24c6798> - >>> sm.mpoly.wkt # WKT - MULTIPOLYGON (((12.4157980000000006 43.9579540000000009, 12.4505540000000003 43.9797209999999978, ... - >>> sm.mpoly.wkb # WKB (as Python binary buffer) - <read-only buffer for 0x1fe2c70, size -1, offset 0 at 0x2564c40> - >>> sm.mpoly.geojson # GeoJSON (requires GDAL) - '{ "type": "MultiPolygon", "coordinates": [ [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ... - -This includes access to all of the advanced geometric operations provided by -the GEOS library:: - - >>> pnt = Point(12.4604, 43.9420) - >>> sm.mpoly.contains(pnt) - True - >>> pnt.contains(sm.mpoly) - False - -``GeoQuerySet`` Methods ------------------------ - - -Putting your data on the map -============================ - -Google ------- - -Geographic Admin ----------------- - -GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>` -to enable support for editing geometry fields. - -Basics -^^^^^^ - -GeoDjango also supplements the Django admin by allowing users to create -and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_). - -Let's dive in again -- create a file called ``admin.py`` inside the -``world`` application, and insert the following:: - - from django.contrib.gis import admin - from models import WorldBorders - - admin.site.register(WorldBorders, admin.GeoModelAdmin) - -Next, edit your ``urls.py`` in the ``geodjango`` project folder to look -as follows:: - - from django.conf.urls.defaults import * - from django.contrib.gis import admin - - admin.autodiscover() - - urlpatterns = patterns('', - (r'^admin/', include(admin.site.urls)), - ) - -Start up the Django development server:: - - $ python manage.py runserver - -Finally, browse to ``http://localhost:8000/admin/``, and log in with the admin -user created after running ``syncdb``. Browse to any of the ``WorldBorders`` -entries -- the borders may be edited by clicking on a polygon and dragging -the vertexes to the desired position. - -.. _OpenLayers: http://openlayers.org/ -.. _Open Street Map: http://openstreetmap.org/ -.. _Vector Map Level 0: http://earth-info.nga.mil/publications/vmap0.html -.. _Metacarta: http://metacarta.com - -.. _osmgeoadmin-intro: - -``OSMGeoAdmin`` -^^^^^^^^^^^^^^^ - -With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses -a `Open Street Map`_ layer in the admin. -This provides more context (including street and thoroughfare details) than -available with the :class:`~django.contrib.gis.admin.GeoModelAdmin` -(which uses the `Vector Map Level 0`_ WMS data set hosted at `Metacarta`_). - -First, there are some important requirements and limitations: - -* :class:`~django.contrib.gis.admin.OSMGeoAdmin` requires that the - :ref:`spherical mercator projection be added <addgoogleprojection>` - to the to be added to the ``spatial_ref_sys`` table (PostGIS 1.3 and - below, only). -* The PROJ.4 datum shifting files must be installed (see the - :ref:`PROJ.4 installation instructions <proj4>` for more details). - -If you meet these requirements, then just substitute in the ``OSMGeoAdmin`` -option class in your ``admin.py`` file:: - - admin.site.register(WorldBorders, admin.OSMGeoAdmin) - -.. rubric:: Footnotes - -.. [#] Special thanks to Bjørn Sandvik of `thematicmapping.org <http://thematicmapping.org>`_ for providing and maintaining this data set. -.. [#] GeoDjango basic apps was written by Dane Springmeyer, Josh Livni, and Christopher Schmidt. -.. [#] Here the point is for the `University of Houston Law Center <http://www.law.uh.edu/>`_ . -.. [#] Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049. diff --git a/parts/django/docs/ref/contrib/gis/utils.txt b/parts/django/docs/ref/contrib/gis/utils.txt deleted file mode 100644 index 9f8e518..0000000 --- a/parts/django/docs/ref/contrib/gis/utils.txt +++ /dev/null @@ -1,32 +0,0 @@ -.. _ref-gis-utils: - -=================== -GeoDjango Utilities -=================== - -.. module:: django.contrib.gis.utils - :synopsis: GeoDjango's collection of utilities. - -The :mod:`django.contrib.gis.utils` module contains various utilities that are -useful in creating geospatial Web applications. - -.. toctree:: - :maxdepth: 2 - - geoip - layermapping - ogrinspect - -GeoIP -===== - -Interface to the MaxMind GeoIP library for performing IP-based geolocation -from GeoDjango. See :ref:`GeoIP reference <ref-geoip>` documentation for -more information. - -LayerMapping -============ - -The :class:`~django.contrib.gis.utils.LayerMapping` simplifies the process -of importing spatial data and attributes into your GeoDjango models. - diff --git a/parts/django/docs/ref/contrib/humanize.txt b/parts/django/docs/ref/contrib/humanize.txt deleted file mode 100644 index b5ec518..0000000 --- a/parts/django/docs/ref/contrib/humanize.txt +++ /dev/null @@ -1,100 +0,0 @@ -======================== -django.contrib.humanize -======================== - -.. module:: django.contrib.humanize - :synopsis: A set of Django template filters useful for adding a "human - touch" to data. - -A set of Django template filters useful for adding a "human touch" to data. - -To activate these filters, add ``'django.contrib.humanize'`` to your -:setting:`INSTALLED_APPS` setting. Once you've done that, use -``{% load humanize %}`` in a template, and you'll have access to the following -filters. - -.. templatefilter:: apnumber - -apnumber --------- - -For numbers 1-9, returns the number spelled out. Otherwise, returns the -number. This follows Associated Press style. - -Examples: - - * ``1`` becomes ``one``. - * ``2`` becomes ``two``. - * ``10`` becomes ``10``. - -You can pass in either an integer or a string representation of an integer. - -.. templatefilter:: intcomma - -intcomma --------- - -Converts an integer to a string containing commas every three digits. - -Examples: - - * ``4500`` becomes ``4,500``. - * ``45000`` becomes ``45,000``. - * ``450000`` becomes ``450,000``. - * ``4500000`` becomes ``4,500,000``. - -You can pass in either an integer or a string representation of an integer. - -.. templatefilter:: intword - -intword -------- - -Converts a large integer to a friendly text representation. Works best for -numbers over 1 million. - -Examples: - - * ``1000000`` becomes ``1.0 million``. - * ``1200000`` becomes ``1.2 million``. - * ``1200000000`` becomes ``1.2 billion``. - -Values up to 1000000000000000 (one quadrillion) are supported. - -You can pass in either an integer or a string representation of an integer. - -.. templatefilter:: naturalday - -naturalday ----------- - -.. versionadded:: 1.0 - -For dates that are the current day or within one day, return "today", -"tomorrow" or "yesterday", as appropriate. Otherwise, format the date using -the passed in format string. - -**Argument:** Date formatting string as described in the :tfilter:`date` tag. - -Examples (when 'today' is 17 Feb 2007): - - * ``16 Feb 2007`` becomes ``yesterday``. - * ``17 Feb 2007`` becomes ``today``. - * ``18 Feb 2007`` becomes ``tomorrow``. - * Any other day is formatted according to given argument or the - :setting:`DATE_FORMAT` setting if no argument is given. - -.. templatefilter:: ordinal - -ordinal -------- - -Converts an integer to its ordinal as a string. - -Examples: - - * ``1`` becomes ``1st``. - * ``2`` becomes ``2nd``. - * ``3`` becomes ``3rd``. - -You can pass in either an integer or a string representation of an integer. diff --git a/parts/django/docs/ref/contrib/index.txt b/parts/django/docs/ref/contrib/index.txt deleted file mode 100644 index 90edf72..0000000 --- a/parts/django/docs/ref/contrib/index.txt +++ /dev/null @@ -1,207 +0,0 @@ -==================== -``contrib`` packages -==================== - -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. This document -gives a rundown of the packages in ``contrib``, along with any dependencies -those packages have. - -.. admonition:: Note - - For most of these add-ons -- specifically, the add-ons that include either - models or template tags -- you'll need to add the package name (e.g., - ``'django.contrib.admin'``) to your ``INSTALLED_APPS`` setting and re-run - ``manage.py syncdb``. - -.. _"batteries included" philosophy: http://docs.python.org/tutorial/stdlib.html#batteries-included - -.. toctree:: - :maxdepth: 1 - - admin/index - auth - comments/index - contenttypes - csrf - databrowse - flatpages - formtools/index - gis/index - humanize - localflavor - markup - messages - redirects - sitemaps - sites - syndication - webdesign - -admin -===== - -The automatic Django administrative interface. For more information, see -:doc:`Tutorial 2 </intro/tutorial02>` and the -:doc:`admin documentation </ref/contrib/admin/index>`. - -Requires the auth_ and contenttypes_ contrib packages to be installed. - -auth -==== - -Django's authentication framework. - -See :doc:`/topics/auth`. - -comments -======== - -.. versionchanged:: 1.0 - The comments application has been rewriten. See :doc:`/ref/contrib/comments/upgrade` - for information on howto upgrade. - -A simple yet flexible comments system. See :doc:`/ref/contrib/comments/index`. - -contenttypes -============ - -A light framework for hooking into "types" of content, where each installed -Django model is a separate content type. - -See the :doc:`contenttypes documentation </ref/contrib/contenttypes>`. - -csrf -==== - -A middleware for preventing Cross Site Request Forgeries - -See the :doc:`csrf documentation </ref/contrib/csrf>`. - -flatpages -========= - -A framework for managing simple "flat" HTML content in a database. - -See the :doc:`flatpages documentation </ref/contrib/flatpages>`. - -Requires the sites_ contrib package to be installed as well. - -formtools -========= - -A set of high-level abstractions for Django forms (django.forms). - -django.contrib.formtools.preview --------------------------------- - -An abstraction of the following workflow: - -"Display an HTML form, force a preview, then do something with the submission." - -See the :doc:`form preview documentation </ref/contrib/formtools/form-preview>`. - -django.contrib.formtools.wizard --------------------------------- - -Splits forms across multiple Web pages. - -See the :doc:`form wizard documentation </ref/contrib/formtools/form-wizard>`. - -gis -==== - -A world-class geospatial framework built on top of Django, that enables -storage, manipulation and display of spatial data. - -See the :doc:`/ref/contrib/gis/index` documentation for more. - -humanize -======== - -A set of Django template filters useful for adding a "human touch" to data. - -See the :doc:`humanize documentation </ref/contrib/humanize>`. - -localflavor -=========== - -A collection of various Django snippets that are useful only for a particular -country or culture. For example, ``django.contrib.localflavor.us.forms`` -contains a ``USZipCodeField`` that you can use to validate U.S. zip codes. - -See the :doc:`localflavor documentation </ref/contrib/localflavor>`. - -markup -====== - -A collection of template filters that implement common markup languages - -See the :doc:`markup documentation </ref/contrib/markup>`. - -messages -======== - -.. versionchanged:: 1.2 - The messages framework was added. - -A framework for storing and retrieving temporary cookie- or session-based -messages - -See the :doc:`messages documentation </ref/contrib/messages>`. - -redirects -========= - -A framework for managing redirects. - -See the :doc:`redirects documentation </ref/contrib/redirects>`. - -sessions -======== - -A framework for storing data in anonymous sessions. - -See the :doc:`sessions documentation </topics/http/sessions>`. - -sites -===== - -A light framework that lets you operate multiple Web sites off of the same -database and Django installation. It gives you hooks for associating objects to -one or more sites. - -See the :doc:`sites documentation </ref/contrib/sites>`. - -sitemaps -======== - -A framework for generating Google sitemap XML files. - -See the :doc:`sitemaps documentation </ref/contrib/sitemaps>`. - -syndication -=========== - -A framework for generating syndication feeds, in RSS and Atom, quite easily. - -See the :doc:`syndication documentation </ref/contrib/syndication>`. - -webdesign -========= - -Helpers and utilities targeted primarily at Web *designers* rather than -Web *developers*. - -See the :doc:`Web design helpers documentation </ref/contrib/webdesign>`. - -Other add-ons -============= - -If you have an idea for functionality to include in ``contrib``, let us know! -Code it up, and post it to the `django-users mailing list`_. - -.. _django-users mailing list: http://groups.google.com/group/django-users diff --git a/parts/django/docs/ref/contrib/localflavor.txt b/parts/django/docs/ref/contrib/localflavor.txt deleted file mode 100644 index 2eb731d..0000000 --- a/parts/django/docs/ref/contrib/localflavor.txt +++ /dev/null @@ -1,842 +0,0 @@ -========================== -The "local flavor" add-ons -========================== - -.. module:: django.contrib.localflavor - :synopsis: A collection of various Django snippets that are useful only for - a particular country or culture. - -Following its "batteries included" philosophy, Django comes with assorted -pieces of code that are useful for particular countries or cultures. These are -called the "local flavor" add-ons and live in the -:mod:`django.contrib.localflavor` package. - -Inside that package, country- or culture-specific code is organized into -subpackages, named using `ISO 3166 country codes`_. - -Most of the ``localflavor`` add-ons are localized form components deriving -from the :doc:`forms </topics/forms/index>` framework -- for example, a -:class:`~django.contrib.localflavor.us.forms.USStateField` that knows how to -validate U.S. state abbreviations, and a -:class:`~django.contrib.localflavor.fi.forms.FISocialSecurityNumber` that -knows how to validate Finnish social security numbers. - -To use one of these localized components, just import the relevant subpackage. -For example, here's how you can create a form with a field representing a -French telephone number:: - - from django import forms - from django.contrib.localflavor.fr.forms import FRPhoneNumberField - - class MyForm(forms.Form): - my_french_phone_no = FRPhoneNumberField() - -Supported countries -=================== - -Countries currently supported by :mod:`~django.contrib.localflavor` are: - - * Argentina_ - * Australia_ - * Austria_ - * Brazil_ - * Canada_ - * Chile_ - * Czech_ - * Finland_ - * France_ - * Germany_ - * Iceland_ - * India_ - * Indonesia_ - * Ireland_ - * Italy_ - * Japan_ - * Kuwait_ - * Mexico_ - * `The Netherlands`_ - * Norway_ - * Peru_ - * Poland_ - * Portugal_ - * Romania_ - * Slovakia_ - * `South Africa`_ - * Spain_ - * Sweden_ - * Switzerland_ - * `United Kingdom`_ - * `United States of America`_ - * Uruguay_ - -The ``django.contrib.localflavor`` package also includes a ``generic`` subpackage, -containing useful code that is not specific to one particular country or culture. -Currently, it defines date, datetime and split datetime input fields based on -those from :doc:`forms </topics/forms/index>`, but with non-US default formats. -Here's an example of how to use them:: - - from django import forms - from django.contrib.localflavor import generic - - class MyForm(forms.Form): - my_date_field = generic.forms.DateField() - -.. _ISO 3166 country codes: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm -.. _Argentina: `Argentina (ar)`_ -.. _Australia: `Australia (au)`_ -.. _Austria: `Austria (at)`_ -.. _Brazil: `Brazil (br)`_ -.. _Canada: `Canada (ca)`_ -.. _Chile: `Chile (cl)`_ -.. _Czech: `Czech (cz)`_ -.. _Finland: `Finland (fi)`_ -.. _France: `France (fr)`_ -.. _Germany: `Germany (de)`_ -.. _The Netherlands: `The Netherlands (nl)`_ -.. _Iceland: `Iceland (is\_)`_ -.. _India: `India (in\_)`_ -.. _Indonesia: `Indonesia (id)`_ -.. _Ireland: `Ireland (ie)`_ -.. _Italy: `Italy (it)`_ -.. _Japan: `Japan (jp)`_ -.. _Kuwait: `Kuwait (kw)`_ -.. _Mexico: `Mexico (mx)`_ -.. _Norway: `Norway (no)`_ -.. _Peru: `Peru (pe)`_ -.. _Poland: `Poland (pl)`_ -.. _Portugal: `Portugal (pt)`_ -.. _Romania: `Romania (ro)`_ -.. _Slovakia: `Slovakia (sk)`_ -.. _South Africa: `South Africa (za)`_ -.. _Spain: `Spain (es)`_ -.. _Sweden: `Sweden (se)`_ -.. _Switzerland: `Switzerland (ch)`_ -.. _United Kingdom: `United Kingdom (uk)`_ -.. _United States of America: `United States of America (us)`_ -.. _Uruguay: `Uruguay (uy)`_ - -Adding flavors -============== - -We'd love to add more of these to Django, so please `create a ticket`_ with -any code you'd like to contribute. One thing we ask is that you please use -Unicode objects (``u'mystring'``) for strings, rather than setting the encoding -in the file. See any of the existing flavors for examples. - -.. _create a ticket: http://code.djangoproject.com/simpleticket - -Argentina (``ar``) -============================================= - -.. class:: ar.forms.ARPostalCodeField - - A form field that validates input as either a classic four-digit Argentinian - postal code or a CPA_. - -.. _CPA: http://www.correoargentino.com.ar/consulta_cpa/home.php - -.. class:: ar.forms.ARDNIField - - A form field that validates input as a Documento Nacional de Identidad (DNI) - number. - -.. class:: ar.forms.ARCUITField - - A form field that validates input as a Codigo Unico de Identificacion - Tributaria (CUIT) number. - -.. class:: ar.forms.ARProvinceSelect - - A ``Select`` widget that uses a list of Argentina's provinces and autonomous - cities as its choices. - -Australia (``au``) -============================================= - -.. class:: au.forms.AUPostCodeField - - A form field that validates input as an Australian postcode. - -.. class:: au.forms.AUPhoneNumberField - - A form field that validates input as an Australian phone number. Valid numbers - have ten digits. - -.. class:: au.forms.AUStateSelect - - A ``Select`` widget that uses a list of Australian states/territories as its - choices. - -Austria (``at``) -================ - -.. class:: at.forms.ATZipCodeField - - A form field that validates its input as an Austrian zip code. - -.. class:: at.forms.ATStateSelect - - A ``Select`` widget that uses a list of Austrian states as its choices. - -.. class:: at.forms.ATSocialSecurityNumberField - - A form field that validates its input as an Austrian social security number. - -Brazil (``br``) -=============== - -.. class:: br.forms.BRPhoneNumberField - - A form field that validates input as a Brazilian phone number, with the format - XX-XXXX-XXXX. - -.. class:: br.forms.BRZipCodeField - - A form field that validates input as a Brazilian zip code, with the format - XXXXX-XXX. - -.. class:: br.forms.BRStateSelect - - A ``Select`` widget that uses a list of Brazilian states/territories as its - choices. - -.. class:: br.forms.BRCPFField - - A form field that validates input as `Brazilian CPF`_. - - Input can either be of the format XXX.XXX.XXX-VD or be a group of 11 digits. - -.. _Brazilian CPF: http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas - -.. class:: br.forms.BRCNPJField - - A form field that validates input as `Brazilian CNPJ`_. - - Input can either be of the format XX.XXX.XXX/XXXX-XX or be a group of 14 - digits. - -.. _Brazilian CNPJ: http://en.wikipedia.org/wiki/National_identification_number#Brazil - -Canada (``ca``) -=============== - -.. class:: ca.forms.CAPhoneNumberField - - A form field that validates input as a Canadian phone number, with the format - XXX-XXX-XXXX. - -.. class:: ca.forms.CAPostalCodeField - - A form field that validates input as a Canadian postal code, with the format - XXX XXX. - -.. class:: ca.forms.CAProvinceField - - A form field that validates input as a Canadian province name or abbreviation. - -.. class:: ca.forms.CASocialInsuranceNumberField - - A form field that validates input as a Canadian Social Insurance Number (SIN). - A valid number must have the format XXX-XXX-XXX and pass a `Luhn mod-10 - checksum`_. - -.. _Luhn mod-10 checksum: http://en.wikipedia.org/wiki/Luhn_algorithm - -.. class:: ca.forms.CAProvinceSelect - - A ``Select`` widget that uses a list of Canadian provinces and territories as - its choices. - -Chile (``cl``) -============== - -.. class:: cl.forms.CLRutField - - A form field that validates input as a Chilean national identification number - ('Rol Unico Tributario' or RUT). The valid format is XX.XXX.XXX-X. - -.. class:: cl.forms.CLRegionSelect - - A ``Select`` widget that uses a list of Chilean regions (Regiones) as its - choices. - -Czech (``cz``) -============== - -.. class:: cz.forms.CZPostalCodeField - - A form field that validates input as a Czech postal code. Valid formats - are XXXXX or XXX XX, where X is a digit. - -.. class:: cz.forms.CZBirthNumberField - - A form field that validates input as a Czech Birth Number. - A valid number must be in format XXXXXX/XXXX (slash is optional). - -.. class:: cz.forms.CZICNumberField - - A form field that validates input as a Czech IC number field. - -.. class:: cz.forms.CZRegionSelect - - A ``Select`` widget that uses a list of Czech regions as its choices. - -Finland (``fi``) -================ - -.. class:: fi.forms.FISocialSecurityNumber - - A form field that validates input as a Finnish social security number. - -.. class:: fi.forms.FIZipCodeField - - A form field that validates input as a Finnish zip code. Valid codes - consist of five digits. - -.. class:: fi.forms.FIMunicipalitySelect - - A ``Select`` widget that uses a list of Finnish municipalities as its - choices. - -France (``fr``) -=============== - -.. class:: fr.forms.FRPhoneNumberField - - A form field that validates input as a French local phone number. The - correct format is 0X XX XX XX XX. 0X.XX.XX.XX.XX and 0XXXXXXXXX validate - but are corrected to 0X XX XX XX XX. - -.. class:: fr.forms.FRZipCodeField - - A form field that validates input as a French zip code. Valid codes - consist of five digits. - -.. class:: fr.forms.FRDepartmentSelect - - A ``Select`` widget that uses a list of French departments as its choices. - -Germany (``de``) -================ - -.. class:: de.forms.DEIdentityCardNumberField - - A form field that validates input as a German identity card number - (Personalausweis_). Valid numbers have the format - XXXXXXXXXXX-XXXXXXX-XXXXXXX-X, with no group consisting entirely of zeroes. - -.. _Personalausweis: http://de.wikipedia.org/wiki/Personalausweis - -.. class:: de.forms.DEZipCodeField - - A form field that validates input as a German zip code. Valid codes - consist of five digits. - -.. class:: de.forms.DEStateSelect - - A ``Select`` widget that uses a list of German states as its choices. - -The Netherlands (``nl``) -======================== - -.. class:: nl.forms.NLPhoneNumberField - - A form field that validates input as a Dutch telephone number. - -.. class:: nl.forms.NLSofiNumberField - - A form field that validates input as a Dutch social security number - (SoFI/BSN). - -.. class:: nl.forms.NLZipCodeField - - A form field that validates input as a Dutch zip code. - -.. class:: nl.forms.NLProvinceSelect - - A ``Select`` widget that uses a list of Dutch provinces as its list of - choices. - -Iceland (``is_``) -================= - -.. class:: is_.forms.ISIdNumberField - - A form field that validates input as an Icelandic identification number - (kennitala). The format is XXXXXX-XXXX. - -.. class:: is_.forms.ISPhoneNumberField - - A form field that validates input as an Icelandtic phone number (seven - digits with an optional hyphen or space after the first three digits). - -.. class:: is_.forms.ISPostalCodeSelect - - A ``Select`` widget that uses a list of Icelandic postal codes as its - choices. - -India (``in_``) -=============== - -.. class:: in.forms.INStateField - - A form field that validates input as an Indian state/territory name or - abbreviation. Input is normalized to the standard two-letter vehicle - registration abbreviation for the given state or territory. - -.. class:: in.forms.INZipCodeField - - A form field that validates input as an Indian zip code, with the - format XXXXXXX. - -.. class:: in.forms.INStateSelect - - A ``Select`` widget that uses a list of Indian states/territories as its - choices. - -Ireland (``ie``) -================ - -.. class:: ie.forms.IECountySelect - - A ``Select`` widget that uses a list of Irish Counties as its choices. - -Indonesia (``id``) -================== - -.. class:: id.forms.IDPostCodeField - - A form field that validates input as an Indonesian post code field. - -.. class:: id.forms.IDProvinceSelect - - A ``Select`` widget that uses a list of Indonesian provinces as its choices. - -.. class:: id.forms.IDPhoneNumberField - - A form field that validates input as an Indonesian telephone number. - -.. class:: id.forms.IDLicensePlatePrefixSelect - - A ``Select`` widget that uses a list of Indonesian license plate - prefix code as its choices. - -.. class:: id.forms.IDLicensePlateField - - A form field that validates input as an Indonesian vehicle license plate. - -.. class:: id.forms.IDNationalIdentityNumberField - - A form field that validates input as an Indonesian national identity - number (`NIK`_/KTP). The output will be in the format of - 'XX.XXXX.DDMMYY.XXXX'. Dots or spaces can be used in the input to break - down the numbers. - -.. _NIK: http://en.wikipedia.org/wiki/Indonesian_identity_card - -Italy (``it``) -============== - -.. class:: it.forms.ITSocialSecurityNumberField - - A form field that validates input as an Italian social security number - (`codice fiscale`_). - -.. _codice fiscale: http://www.agenziaentrate.it/ilwwcm/connect/Nsi/Servizi/Codice+fiscale+-+tessera+sanitaria/NSI+Informazioni+sulla+codificazione+delle+persone+fisiche - -.. class:: it.forms.ITVatNumberField - - A form field that validates Italian VAT numbers (partita IVA). - -.. class:: it.forms.ITZipCodeField - - A form field that validates input as an Italian zip code. Valid codes - must have five digits. - -.. class:: it.forms.ITProvinceSelect - - A ``Select`` widget that uses a list of Italian provinces as its choices. - -.. class:: it.forms.ITRegionSelect - - A ``Select`` widget that uses a list of Italian regions as its choices. - -Japan (``jp``) -============== - -.. class:: jp.forms.JPPostalCodeField - - A form field that validates input as a Japanese postcode. It accepts seven - digits, with or without a hyphen. - -.. class:: jp.forms.JPPrefectureSelect - - A ``Select`` widget that uses a list of Japanese prefectures as its choices. - -Kuwait (``kw``) -=============== - -.. class:: kw.forms.KWCivilIDNumberField - - A form field that validates input as a Kuwaiti Civil ID number. A valid - Civil ID number must obey the following rules: - - * The number consist of 12 digits. - * The birthdate of the person is a valid date. - * The calculated checksum equals to the last digit of the Civil ID. - -Mexico (``mx``) -=============== - -.. class:: mx.forms.MXStateSelect - - A ``Select`` widget that uses a list of Mexican states as its choices. - -Norway (``no``) -=============== - -.. class:: no.forms.NOSocialSecurityNumber - - A form field that validates input as a Norwegian social security number - (personnummer_). - -.. _personnummer: http://no.wikipedia.org/wiki/Personnummer - -.. class:: no.forms.NOZipCodeField - - A form field that validates input as a Norwegian zip code. Valid codes - have four digits. - -.. class:: no.forms.NOMunicipalitySelect - - A ``Select`` widget that uses a list of Norwegian municipalities (fylker) as - its choices. - -Peru (``pe``) -============= - -.. class:: pe.forms.PEDNIField - - A form field that validates input as a DNI (Peruvian national identity) - number. - -.. class:: pe.forms.PERUCField - - A form field that validates input as an RUC (Registro Unico de - Contribuyentes) number. Valid RUC numbers have 11 digits. - -.. class:: pe.forms.PEDepartmentSelect - - A ``Select`` widget that uses a list of Peruvian Departments as its choices. - -Poland (``pl``) -=============== - -.. class:: pl.forms.PLPESELField - - A form field that validates input as a Polish national identification number - (PESEL_). - -.. _PESEL: http://en.wikipedia.org/wiki/PESEL - -.. class:: pl.forms.PLREGONField - - A form field that validates input as a Polish National Official Business - Register Number (REGON_), having either seven or nine digits. The checksum - algorithm used for REGONs is documented at - http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. - -.. _REGON: http://www.stat.gov.pl/bip/regon_ENG_HTML.htm - -.. class:: pl.forms.PLPostalCodeField - - A form field that validates input as a Polish postal code. The valid format - is XX-XXX, where X is a digit. - -.. class:: pl.forms.PLNIPField - - A form field that validates input as a Polish Tax Number (NIP). Valid - formats are XXX-XXX-XX-XX or XX-XX-XXX-XXX. The checksum algorithm used - for NIPs is documented at http://wipos.p.lodz.pl/zylla/ut/nip-rego.html. - -.. class:: pl.forms.PLCountySelect - - A ``Select`` widget that uses a list of Polish administrative units as its - choices. - -.. class:: pl.forms.PLProvinceSelect - - A ``Select`` widget that uses a list of Polish voivodeships (administrative - provinces) as its choices. - -Portugal (``pt``) -================= - -.. class:: pt.forms.PTZipCodeField - - A form field that validates input as a Portuguese zip code. - -.. class:: pt.forms.PTPhoneNumberField - - A form field that validates input as a Portuguese phone number. - Valid numbers have 9 digits (may include spaces) or start by 00 - or + (international). - -Romania (``ro``) -================ - -.. class:: ro.forms.ROCIFField - - A form field that validates Romanian fiscal identification codes (CIF). The - return value strips the leading RO, if given. - -.. class:: ro.forms.ROCNPField - - A form field that validates Romanian personal numeric codes (CNP). - -.. class:: ro.forms.ROCountyField - - A form field that validates its input as a Romanian county (judet) name or - abbreviation. It normalizes the input to the standard vehicle registration - abbreviation for the given county. This field will only accept names written - with diacritics; consider using ROCountySelect as an alternative. - -.. class:: ro.forms.ROCountySelect - - A ``Select`` widget that uses a list of Romanian counties (judete) as its - choices. - -.. class:: ro.forms.ROIBANField - - A form field that validates its input as a Romanian International Bank - Account Number (IBAN). The valid format is ROXX-XXXX-XXXX-XXXX-XXXX-XXXX, - with or without hyphens. - -.. class:: ro.forms.ROPhoneNumberField - - A form field that validates Romanian phone numbers, short special numbers - excluded. - -.. class:: ro.forms.ROPostalCodeField - - A form field that validates Romanian postal codes. - -Slovakia (``sk``) -================= - -.. class:: sk.forms.SKPostalCodeField - - A form field that validates input as a Slovak postal code. Valid formats - are XXXXX or XXX XX, where X is a digit. - -.. class:: sk.forms.SKDistrictSelect - - A ``Select`` widget that uses a list of Slovak districts as its choices. - -.. class:: sk.forms.SKRegionSelect - - A ``Select`` widget that uses a list of Slovak regions as its choices. - -South Africa (``za``) -===================== - -.. class:: za.forms.ZAIDField - - A form field that validates input as a South African ID number. Validation - uses the Luhn checksum and a simplistic (i.e., not entirely accurate) check - for birth date. - -.. class:: za.forms.ZAPostCodeField - - A form field that validates input as a South African postcode. Valid - postcodes must have four digits. - -Spain (``es``) -============== - -.. class:: es.forms.ESIdentityCardNumberField - - A form field that validates input as a Spanish NIF/NIE/CIF (Fiscal - Identification Number) code. - -.. class:: es.forms.ESCCCField - - A form field that validates input as a Spanish bank account number (Codigo - Cuenta Cliente or CCC). A valid CCC number has the format - EEEE-OOOO-CC-AAAAAAAAAA, where the E, O, C and A digits denote the entity, - office, checksum and account, respectively. The first checksum digit - validates the entity and office. The second checksum digit validates the - account. It is also valid to use a space as a delimiter, or to use no - delimiter. - -.. class:: es.forms.ESPhoneNumberField - - A form field that validates input as a Spanish phone number. Valid numbers - have nine digits, the first of which is 6, 8 or 9. - -.. class:: es.forms.ESPostalCodeField - - A form field that validates input as a Spanish postal code. Valid codes - have five digits, the first two being in the range 01 to 52, representing - the province. - -.. class:: es.forms.ESProvinceSelect - - A ``Select`` widget that uses a list of Spanish provinces as its choices. - -.. class:: es.forms.ESRegionSelect - - A ``Select`` widget that uses a list of Spanish regions as its choices. - -Sweden (``se``) -=============== - -.. class:: se.forms.SECountySelect - - A Select form widget that uses a list of the Swedish counties (län) as its - choices. - - The cleaned value is the official county code -- see - http://en.wikipedia.org/wiki/Counties_of_Sweden for a list. - -.. class:: se.forms.SEOrganisationNumber - - A form field that validates input as a Swedish organisation number - (organisationsnummer). - - It accepts the same input as SEPersonalIdentityField (for sole - proprietorships (enskild firma). However, co-ordination numbers are not - accepted. - - It also accepts ordinary Swedish organisation numbers with the format - NNNNNNNNNN. - - The return value will be YYYYMMDDXXXX for sole proprietors, and NNNNNNNNNN - for other organisations. - -.. class:: se.forms.SEPersonalIdentityNumber - - A form field that validates input as a Swedish personal identity number - (personnummer). - - The correct formats are YYYYMMDD-XXXX, YYYYMMDDXXXX, YYMMDD-XXXX, - YYMMDDXXXX and YYMMDD+XXXX. - - A \+ indicates that the person is older than 100 years, which will be taken - into consideration when the date is validated. - - The checksum will be calculated and checked. The birth date is checked - to be a valid date. - - By default, co-ordination numbers (samordningsnummer) will be accepted. To - only allow real personal identity numbers, pass the keyword argument - coordination_number=False to the constructor. - - The cleaned value will always have the format YYYYMMDDXXXX. - -.. class:: se.forms.SEPostalCodeField - - A form field that validates input as a Swedish postal code (postnummer). - Valid codes consist of five digits (XXXXX). The number can optionally be - formatted with a space after the third digit (XXX XX). - - The cleaned value will never contain the space. - -Switzerland (``ch``) -==================== - -.. class:: ch.forms.CHIdentityCardNumberField - - A form field that validates input as a Swiss identity card number. - A valid number must confirm to the X1234567<0 or 1234567890 format and - have the correct checksums -- see http://adi.kousz.ch/artikel/IDCHE.htm. - -.. class:: ch.forms.CHPhoneNumberField - - A form field that validates input as a Swiss phone number. The correct - format is 0XX XXX XX XX. 0XX.XXX.XX.XX and 0XXXXXXXXX validate but are - corrected to 0XX XXX XX XX. - -.. class:: ch.forms.CHZipCodeField - - A form field that validates input as a Swiss zip code. Valid codes - consist of four digits. - -.. class:: ch.forms.CHStateSelect - - A ``Select`` widget that uses a list of Swiss states as its choices. - -United Kingdom (``uk``) -======================= - -.. class:: uk.forms.UKPostcodeField - - A form field that validates input as a UK postcode. The regular - expression used is sourced from the schema for British Standard BS7666 - address types at http://www.cabinetoffice.gov.uk/media/291293/bs7666-v2-0.xml. - -.. class:: uk.forms.UKCountySelect - - A ``Select`` widget that uses a list of UK counties/regions as its choices. - -.. class:: uk.forms.UKNationSelect - - A ``Select`` widget that uses a list of UK nations as its choices. - -United States of America (``us``) -================================= - -.. class:: us.forms.USPhoneNumberField - - A form field that validates input as a U.S. phone number. - -.. class:: us.forms.USSocialSecurityNumberField - - A form field that validates input as a U.S. Social Security Number (SSN). - A valid SSN must obey the following rules: - - * Format of XXX-XX-XXXX - * No group of digits consisting entirely of zeroes - * Leading group of digits cannot be 666 - * Number not in promotional block 987-65-4320 through 987-65-4329 - * Number not one known to be invalid due to widespread promotional - use or distribution (e.g., the Woolworth's number or the 1962 - promotional number) - -.. class:: us.forms.USStateField - - A form field that validates input as a U.S. state name or abbreviation. It - normalizes the input to the standard two-letter postal service abbreviation - for the given state. - -.. class:: us.forms.USZipCodeField - - A form field that validates input as a U.S. ZIP code. Valid formats are - XXXXX or XXXXX-XXXX. - -.. class:: us.forms.USStateSelect - - A form ``Select`` widget that uses a list of U.S. states/territories as its - choices. - -.. class:: us.models.PhoneNumberField - - A :class:`CharField` that checks that the value is a valid U.S.A.-style phone - number (in the format ``XXX-XXX-XXXX``). - -.. class:: us.models.USStateField - - A model field that forms represent as a ``forms.USStateField`` field and - stores the two-letter U.S. state abbreviation in the database. - -Uruguay (``uy``) -================ - -.. class:: uy.forms.UYCIField - - A field that validates Uruguayan 'Cedula de identidad' (CI) numbers. - -.. class:: uy.forms.UYDepartamentSelect - - A ``Select`` widget that uses a list of Uruguayan departaments as its - choices. diff --git a/parts/django/docs/ref/contrib/markup.txt b/parts/django/docs/ref/contrib/markup.txt deleted file mode 100644 index 9282313..0000000 --- a/parts/django/docs/ref/contrib/markup.txt +++ /dev/null @@ -1,42 +0,0 @@ -===================== -django.contrib.markup -===================== - -.. module:: django.contrib.markup - :synopsis: A collection of template filters that implement common markup languages. - -Django provides template filters that implement the following markup -languages: - - * ``textile`` -- implements `Textile`_ -- requires `PyTextile`_ - * ``markdown`` -- implements `Markdown`_ -- requires `Python-markdown`_ - * ``restructuredtext`` -- implements `reST (reStructured Text)`_ - -- requires `doc-utils`_ - -In each case, the filter expects formatted markup as a string and -returns a string representing the marked-up text. For example, the -``textile`` filter converts text that is marked-up in Textile format -to HTML. - -To activate these filters, add ``'django.contrib.markup'`` to your -:setting:`INSTALLED_APPS` setting. Once you've done that, use -``{% load markup %}`` in a template, and you'll have access to these filters. -For more documentation, read the source code in -:file:`django/contrib/markup/templatetags/markup.py`. - -.. _Textile: http://en.wikipedia.org/wiki/Textile_%28markup_language%29 -.. _Markdown: http://en.wikipedia.org/wiki/Markdown -.. _reST (reStructured Text): http://en.wikipedia.org/wiki/ReStructuredText -.. _PyTextile: http://loopcore.com/python-textile/ -.. _Python-markdown: http://www.freewisdom.org/projects/python-markdown -.. _doc-utils: http://docutils.sf.net/ - -reStructured Text ------------------ - -When using the ``restructuredtext`` markup filter you can define a -:setting:`RESTRUCTUREDTEXT_FILTER_SETTINGS` in your django settings to -override the default writer settings. See the `restructuredtext writer -settings`_ for details on what these settings are. - -.. _restructuredtext writer settings: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer diff --git a/parts/django/docs/ref/contrib/messages.txt b/parts/django/docs/ref/contrib/messages.txt deleted file mode 100644 index 3081f27..0000000 --- a/parts/django/docs/ref/contrib/messages.txt +++ /dev/null @@ -1,411 +0,0 @@ -====================== -The messages framework -====================== - -.. module:: django.contrib.messages - :synopsis: Provides cookie- and session-based temporary message storage. - -Django provides full support for cookie- and session-based messaging, for -both anonymous and authenticated clients. The messages framework allows you -to temporarily store messages in one request and retrieve them for display -in a subsequent request (usually the next one). Every message is tagged -with a specific ``level`` that determines its priority (e.g., ``info``, -``warning``, or ``error``). - -.. versionadded:: 1.2 - The messages framework was added. - -Enabling messages -================= - -Messages are implemented through a :doc:`middleware </ref/middleware>` -class and corresponding :doc:`context processor </ref/templates/api>`. - -To enable message functionality, do the following: - - * Edit the :setting:`MIDDLEWARE_CLASSES` setting and make sure - it contains ``'django.contrib.messages.middleware.MessageMiddleware'``. - - If you are using a :ref:`storage backend <message-storage-backends>` that - relies on :doc:`sessions </topics/http/sessions>` (the default), - ``'django.contrib.sessions.middleware.SessionMiddleware'`` must be - enabled and appear before ``MessageMiddleware`` in your - :setting:`MIDDLEWARE_CLASSES`. - - * Edit the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting and make sure - it contains ``'django.contrib.messages.context_processors.messages'``. - - * Add ``'django.contrib.messages'`` to your :setting:`INSTALLED_APPS` - setting - -The default ``settings.py`` created by ``django-admin.py startproject`` has -``MessageMiddleware`` activated and the ``django.contrib.messages`` app -installed. Also, the default value for :setting:`TEMPLATE_CONTEXT_PROCESSORS` -contains ``'django.contrib.messages.context_processors.messages'``. - -If you don't want to use messages, you can remove the -``MessageMiddleware`` line from :setting:`MIDDLEWARE_CLASSES`, the ``messages`` -context processor from :setting:`TEMPLATE_CONTEXT_PROCESSORS` and -``'django.contrib.messages'`` from your :setting:`INSTALLED_APPS`. - -Configuring the message engine -============================== - -.. _message-storage-backends: - -Storage backends ----------------- - -The messages framework can use different backends to store temporary messages. -To change which backend is being used, add a `MESSAGE_STORAGE`_ to your -settings, referencing the module and class of the storage class. For -example:: - - MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage' - -The value should be the full path of the desired storage class. - -Four storage classes are included: - -``'django.contrib.messages.storage.session.SessionStorage'`` - This class stores all messages inside of the request's session. It - requires Django's ``contrib.sessions`` application. - -``'django.contrib.messages.storage.cookie.CookieStorage'`` - This class stores the message data in a cookie (signed with a secret hash - to prevent manipulation) to persist notifications across requests. Old - messages are dropped if the cookie data size would exceed 4096 bytes. - -``'django.contrib.messages.storage.fallback.FallbackStorage'`` - This class first uses CookieStorage for all messages, falling back to using - SessionStorage for the messages that could not fit in a single cookie. - - Since it is uses SessionStorage, it also requires Django's - ``contrib.session`` application. - -``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'`` - This is the default temporary storage class. - - This class extends FallbackStorage and adds compatibility methods to - to retrieve any messages stored in the user Message model by code that - has not yet been updated to use the new API. This storage is temporary - (because it makes use of code that is pending deprecation) and will be - removed in Django 1.4. At that time, the default storage will become - ``django.contrib.messages.storage.fallback.FallbackStorage``. For more - information, see `LegacyFallbackStorage`_ below. - -To write your own storage class, subclass the ``BaseStorage`` class in -``django.contrib.messages.storage.base`` and implement the ``_get`` and -``_store`` methods. - -LegacyFallbackStorage -^^^^^^^^^^^^^^^^^^^^^ - -The ``LegacyFallbackStorage`` is a temporary tool to facilitate the transition -from the deprecated ``user.message_set`` API and will be removed in Django 1.4 -according to Django's standard deprecation policy. For more information, see -the full :doc:`release process documentation </internals/release-process>`. - -In addition to the functionality in the ``FallbackStorage``, it adds a custom, -read-only storage class that retrieves messages from the user ``Message`` -model. Any messages that were stored in the ``Message`` model (e.g., by code -that has not yet been updated to use the messages framework) will be retrieved -first, followed by those stored in a cookie and in the session, if any. Since -messages stored in the ``Message`` model do not have a concept of levels, they -will be assigned the ``INFO`` level by default. - -Message levels --------------- - -The messages framework is based on a configurable level architecture similar -to that of the Python logging module. Message levels allow you to group -messages by type so they can be filtered or displayed differently in views and -templates. - -The built-in levels (which can be imported from ``django.contrib.messages`` -directly) are: - -=========== ======== -Constant Purpose -=========== ======== -``DEBUG`` Development-related messages that will be ignored (or removed) in a production deployment -``INFO`` Informational messages for the user -``SUCCESS`` An action was successful, e.g. "Your profile was updated successfully" -``WARNING`` A failure did not occur but may be imminent -``ERROR`` An action was **not** successful or some other failure occurred -=========== ======== - -The `MESSAGE_LEVEL`_ setting can be used to change the minimum recorded level -(or it can be `changed per request`_). Attempts to add messages of a level less -than this will be ignored. - -.. _`changed per request`: `Changing the minimum recorded level per-request`_ - -Message tags ------------- - -Message tags are a string representation of the message level plus any -extra tags that were added directly in the view (see -`Adding extra message tags`_ below for more details). Tags are stored in a -string and are separated by spaces. Typically, message tags -are used as CSS classes to customize message style based on message type. By -default, each level has a single tag that's a lowercase version of its own -constant: - -============== =========== -Level Constant Tag -============== =========== -``DEBUG`` ``debug`` -``INFO`` ``info`` -``SUCCESS`` ``success`` -``WARNING`` ``warning`` -``ERROR`` ``error`` -============== =========== - -To change the default tags for a message level (either built-in or custom), -set the `MESSAGE_TAGS`_ setting to a dictionary containing the levels -you wish to change. As this extends the default tags, you only need to provide -tags for the levels you wish to override:: - - from django.contrib.messages import constants as messages - MESSAGE_TAGS = { - messages.INFO: '', - 50: 'critical', - } - -Using messages in views and templates -===================================== - -Adding a message ----------------- - -To add a message, call:: - - from django.contrib import messages - messages.add_message(request, messages.INFO, 'Hello world.') - -Some shortcut methods provide a standard way to add messages with commonly -used tags (which are usually represented as HTML classes for the message):: - - messages.debug(request, '%s SQL statements were executed.' % count) - messages.info(request, 'Three credits remain in your account.') - messages.success(request, 'Profile details updated.') - messages.warning(request, 'Your account expires in three days.') - messages.error(request, 'Document deleted.') - -Displaying messages -------------------- - -In your template, use something like:: - - {% if messages %} - <ul class="messages"> - {% for message in messages %} - <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li> - {% endfor %} - </ul> - {% endif %} - -If you're using the context processor, your template should be rendered with a -``RequestContext``. Otherwise, ensure ``messages`` is available to -the template context. - -Creating custom message levels ------------------------------- - -Messages levels are nothing more than integers, so you can define your own -level constants and use them to create more customized user feedback, e.g.:: - - CRITICAL = 50 - - def my_view(request): - messages.add_message(request, CRITICAL, 'A serious error occurred.') - -When creating custom message levels you should be careful to avoid overloading -existing levels. The values for the built-in levels are: - -.. _message-level-constants: - -============== ===== -Level Constant Value -============== ===== -``DEBUG`` 10 -``INFO`` 20 -``SUCCESS`` 25 -``WARNING`` 30 -``ERROR`` 40 -============== ===== - -If you need to identify the custom levels in your HTML or CSS, you need to -provide a mapping via the `MESSAGE_TAGS`_ setting. - -.. note:: - If you are creating a reusable application, it is recommended to use - only the built-in `message levels`_ and not rely on any custom levels. - -Changing the minimum recorded level per-request ------------------------------------------------ - -The minimum recorded level can be set per request via the ``set_level`` -method:: - - from django.contrib import messages - - # Change the messages level to ensure the debug message is added. - messages.set_level(request, messages.DEBUG) - messages.debug(request, 'Test message...') - - # In another request, record only messages with a level of WARNING and higher - messages.set_level(request, messages.WARNING) - messages.success(request, 'Your profile was updated.') # ignored - messages.warning(request, 'Your account is about to expire.') # recorded - - # Set the messages level back to default. - messages.set_level(request, None) - -Similarly, the current effective level can be retrieved with ``get_level``:: - - from django.contrib import messages - current_level = messages.get_level(request) - -For more information on how the minimum recorded level functions, see -`Message levels`_ above. - -Adding extra message tags -------------------------- - -For more direct control over message tags, you can optionally provide a string -containing extra tags to any of the add methods:: - - messages.add_message(request, messages.INFO, 'Over 9000!', - extra_tags='dragonball') - messages.error(request, 'Email box full', extra_tags='email') - -Extra tags are added before the default tag for that level and are space -separated. - -Failing silently when the message framework is disabled -------------------------------------------------------- - -If you're writing a reusable app (or other piece of code) and want to include -messaging functionality, but don't want to require your users to enable it -if they don't want to, you may pass an additional keyword argument -``fail_silently=True`` to any of the ``add_message`` family of methods. For -example:: - - messages.add_message(request, messages.SUCCESS, 'Profile details updated.', - fail_silently=True) - messages.info(request, 'Hello world.', fail_silently=True) - -Internally, Django uses this functionality in the create, update, and delete -:doc:`generic views </topics/http/generic-views>` so that they work even if the -message framework is disabled. - -.. note:: - Setting ``fail_silently=True`` only hides the ``MessageFailure`` that would - otherwise occur when the messages framework disabled and one attempts to - use one of the ``add_message`` family of methods. It does not hide failures - that may occur for other reasons. - -Expiration of messages -====================== - -The messages are marked to be cleared when the storage instance is iterated -(and cleared when the response is processed). - -To avoid the messages being cleared, you can set the messages storage to -``False`` after iterating:: - - storage = messages.get_messages(request) - for message in storage: - do_something_with(message) - storage.used = False - -Behavior of parallel requests -============================= - -Due to the way cookies (and hence sessions) work, **the behavior of any -backends that make use of cookies or sessions is undefined when the same -client makes multiple requests that set or get messages in parallel**. For -example, if a client initiates a request that creates a message in one window -(or tab) and then another that fetches any uniterated messages in another -window, before the first window redirects, the message may appear in the -second window instead of the first window where it may be expected. - -In short, when multiple simultaneous requests from the same client are -involved, messages are not guaranteed to be delivered to the same window that -created them nor, in some cases, at all. Note that this is typically not a -problem in most applications and will become a non-issue in HTML5, where each -window/tab will have its own browsing context. - -Settings -======== - -A few :doc:`Django settings </ref/settings>` give you control over message -behavior: - -MESSAGE_LEVEL -------------- - -Default: ``messages.INFO`` - -This sets the minimum message that will be saved in the message storage. See -`Message levels`_ above for more details. - -.. admonition:: Important - - If you override ``MESSAGE_LEVEL`` in your settings file and rely on any of - the built-in constants, you must import the constants module directly to - avoid the potential for circular imports, e.g.:: - - from django.contrib.messages import constants as message_constants - MESSAGE_LEVEL = message_constants.DEBUG - - If desired, you may specify the numeric values for the constants directly - according to the values in the above :ref:`constants table - <message-level-constants>`. - -MESSAGE_STORAGE ---------------- - -Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'`` - -Controls where Django stores message data. Valid values are: - - * ``'django.contrib.messages.storage.fallback.FallbackStorage'`` - * ``'django.contrib.messages.storage.session.SessionStorage'`` - * ``'django.contrib.messages.storage.cookie.CookieStorage'`` - * ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'`` - -See `Storage backends`_ for more details. - -MESSAGE_TAGS ------------- - -Default:: - - {messages.DEBUG: 'debug', - messages.INFO: 'info', - messages.SUCCESS: 'success', - messages.WARNING: 'warning', - messages.ERROR: 'error',} - -This sets the mapping of message level to message tag, which is typically -rendered as a CSS class in HTML. If you specify a value, it will extend -the default. This means you only have to specify those values which you need -to override. See `Displaying messages`_ above for more details. - -.. admonition:: Important - - If you override ``MESSAGE_TAGS`` in your settings file and rely on any of - the built-in constants, you must import the ``constants`` module directly to - avoid the potential for circular imports, e.g.:: - - from django.contrib.messages import constants as message_constants - MESSAGE_TAGS = {message_constants.INFO: ''} - - If desired, you may specify the numeric values for the constants directly - according to the values in the above :ref:`constants table - <message-level-constants>`. - -.. _Django settings: ../settings/ diff --git a/parts/django/docs/ref/contrib/redirects.txt b/parts/django/docs/ref/contrib/redirects.txt deleted file mode 100644 index f1a58cb..0000000 --- a/parts/django/docs/ref/contrib/redirects.txt +++ /dev/null @@ -1,70 +0,0 @@ -================= -The redirects app -================= - -.. module:: django.contrib.redirects - :synopsis: A framework for managing redirects. - -Django comes with an optional redirects application. It lets you store simple -redirects in a database and handles the redirecting for you. - -Installation -============ - -To install the redirects app, follow these steps: - - 1. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` - setting. - 2. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'`` - to your :setting:`MIDDLEWARE_CLASSES` setting. - 3. Run the command :djadmin:`manage.py syncdb <syncdb>`. - -How it works -============ - -``manage.py syncdb`` creates a ``django_redirect`` table in your database. This -is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields. - -The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django -application raises a 404 error, this middleware checks the redirects database -for the requested URL as a last resort. Specifically, it checks for a redirect -with the given ``old_path`` with a site ID that corresponds to the -:setting:`SITE_ID` setting. - - * If it finds a match, and ``new_path`` is not empty, it redirects to - ``new_path``. - * If it finds a match, and ``new_path`` is empty, it sends a 410 ("Gone") - HTTP header and empty (content-less) response. - * If it doesn't find a match, the request continues to be processed as - usual. - -The middleware only gets activated for 404s -- not for 500s or responses of any -other status code. - -Note that the order of :setting:`MIDDLEWARE_CLASSES` matters. Generally, you -can put ``RedirectFallbackMiddleware`` at the end of the list, because it's a -last resort. - -For more on middleware, read the :doc:`middleware docs -</topics/http/middleware>`. - -How to add, change and delete redirects -======================================= - -Via the admin interface ------------------------ - -If you've activated the automatic Django admin interface, you should see a -"Redirects" section on the admin index page. Edit redirects as you edit any -other object in the system. - -Via the Python API ------------------- - -.. class:: models.Redirect - - Redirects are represented by a standard :doc:`Django model </topics/db/models>`, - which lives in `django/contrib/redirects/models.py`_. You can access redirect - objects via the :doc:`Django database API </topics/db/queries>`. - -.. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py diff --git a/parts/django/docs/ref/contrib/sitemaps.txt b/parts/django/docs/ref/contrib/sitemaps.txt deleted file mode 100644 index eb29c6c..0000000 --- a/parts/django/docs/ref/contrib/sitemaps.txt +++ /dev/null @@ -1,351 +0,0 @@ -===================== -The sitemap framework -===================== - -.. module:: django.contrib.sitemaps - :synopsis: A framework for generating Google sitemap XML files. - -Django comes with a high-level sitemap-generating framework that makes -creating sitemap_ XML files easy. - -.. _sitemap: http://www.sitemaps.org/ - -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 :doc:`syndication framework -</ref/contrib/syndication>`. To create a sitemap, just write a -:class:`~django.contrib.sitemaps.Sitemap` class and point to it in your -:doc:`URLconf </topics/http/urls>`. - -Installation -============ - -To install the sitemap app, follow these steps: - - 1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` - setting. - - 2. Make sure ``'django.template.loaders.app_directories.Loader'`` - is in your :setting:`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 - :mod:`sites framework <django.contrib.sites>`. - -(Note: The sitemap application doesn't install any database tables. The only -reason it needs to go into :setting:`INSTALLED_APPS` is so that the -:func:`~django.template.loaders.app_directories.Loader` template -loader can find the default templates.) - -Initialization -============== - -To activate sitemap generation on your Django site, add this line to your -:doc:`URLconf </topics/http/urls>`:: - - (r'^sitemap\.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps}) - -This tells Django to build a sitemap when a client accesses :file:`/sitemap.xml`. - -The name of the sitemap file is not important, but the location is. Search -engines will only index links in your sitemap for the current URL level and -below. For instance, if :file:`sitemap.xml` lives in your root directory, it may -reference any URL in your site. However, if your sitemap lives at -:file:`/content/sitemap.xml`, it may only reference URLs that begin with -:file:`/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 :class:`~django.contrib.sitemaps.Sitemap` class -(e.g., ``BlogSitemap`` or ``NewsSitemap``). It may also map to an *instance* of -a :class:`~django.contrib.sitemaps.Sitemap` class (e.g., -``BlogSitemap(some_var)``). - -Sitemap classes -=============== - -A :class:`~django.contrib.sitemaps.Sitemap` class is a simple Python -class that represents a "section" of entries in your sitemap. For example, -one :class:`~django.contrib.sitemaps.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 -:file:`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.) - -:class:`~django.contrib.sitemaps.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 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: - - * :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` are class - attributes corresponding to ``<changefreq>`` and ``<priority>`` elements, - respectively. They can be made callable as functions, as - :attr:`~Sitemap.lastmod` was in the example. - * :attr:`~Sitemap.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 (:attr:`~Sitemap.location`, - :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and - :attr:`~Sitemap.priority`). - * :attr:`~Sitemap.lastmod` should return a Python ``datetime`` object. - * There is no :attr:`~Sitemap.location` method in this example, but you - can provide it in order to specify the URL for your object. By default, - :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object - and returns the result. - -Sitemap class reference -======================= - -.. class:: Sitemap - - A ``Sitemap`` class can define the following methods/attributes: - - .. attribute:: Sitemap.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 :attr:`~Sitemap.location()`, - :attr:`~Sitemap.lastmod()`, :attr:`~Sitemap.changefreq()` and - :attr:`~Sitemap.priority()` methods. - - .. attribute:: Sitemap.location - - **Optional.** Either a method or attribute. - - If it's a method, it should return the absolute path for a given object - as returned by :attr:`~Sitemap.items()`. - - If it's an attribute, its value should be a string representing an - absolute path to use for *every* object returned by - :attr:`~Sitemap.items()`. - - In both cases, "absolute path" means a URL that doesn't include the - protocol or domain. Examples: - - * Good: :file:`'/foo/bar/'` - * Bad: :file:`'example.com/foo/bar/'` - * Bad: :file:`'http://example.com/foo/bar/'` - - If :attr:`~Sitemap.location` isn't provided, the framework will call - the ``get_absolute_url()`` method on each object as returned by - :attr:`~Sitemap.items()`. - - .. attribute:: Sitemap.lastmod - - **Optional.** Either a method or attribute. - - If it's a method, it should take one argument -- an object as returned by - :attr:`~Sitemap.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 - :attr:`~Sitemap.items()`. - - .. attribute:: Sitemap.changefreq - - **Optional.** Either a method or attribute. - - If it's a method, it should take one argument -- an object as returned by - :attr:`~Sitemap.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 :attr:`~Sitemap.items()`. - - Possible values for :attr:`~Sitemap.changefreq`, whether you use a method or attribute, are: - - * ``'always'`` - * ``'hourly'`` - * ``'daily'`` - * ``'weekly'`` - * ``'monthly'`` - * ``'yearly'`` - * ``'never'`` - - .. method:: Sitemap.priority - - **Optional.** Either a method or attribute. - - If it's a method, it should take one argument -- an object as returned by - :attr:`~Sitemap.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 :attr:`~Sitemap.items()`. - - Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The default priority of a - page is ``0.5``. See the `sitemaps.org documentation`_ for more. - - .. _sitemaps.org documentation: http://www.sitemaps.org/protocol.html#prioritydef - -Shortcuts -========= - -The sitemap framework provides a couple convenience classes for common cases: - -.. class:: FlatPageSitemap - - The :class:`django.contrib.sitemaps.FlatPageSitemap` class looks at all - publicly visible :mod:`flatpages <django.contrib.flatpages>` - defined for the current :setting:`SITE_ID` (see the - :mod:`sites documentation <django.contrib.sites>`) and - creates an entry in the sitemap. These entries include only the - :attr:`~Sitemap.location` attribute -- not :attr:`~Sitemap.lastmod`, - :attr:`~Sitemap.changefreq` or :attr:`~Sitemap.priority`. - -.. class:: GenericSitemap - - The :class:`django.contrib.sitemaps.GenericSitemap` class works with any - :doc:`generic views </ref/generic-views>` you already have. - To use it, create an instance, passing in the same :data:`info_dict` you pass to - the generic views. The only requirement is that the dictionary have a - :data:`queryset` entry. It may also have a :data:`date_field` entry that specifies a - date field for objects retrieved from the :data:`queryset`. This will be used for - the :attr:`~Sitemap.lastmod` attribute in the generated sitemap. You may - also pass :attr:`~Sitemap.priority` and :attr:`~Sitemap.changefreq` - keyword arguments to the :class:`~django.contrib.sitemaps.GenericSitemap` - constructor to specify these attributes for all URLs. - -Example -------- - -Here's an example of a :doc:`URLconf </topics/http/urls>` using both:: - - from django.conf.urls.defaults import * - from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap - from 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: ../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 -:data:`sitemaps` dictionary. The only differences in usage are: - - * You use two views in your URLconf: :func:`django.contrib.sitemaps.views.index` - and :func:`django.contrib.sitemaps.views.sitemap`. - * The :func:`django.contrib.sitemaps.views.sitemap` view should take a - :data:`section` keyword argument. - -Here's 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 :file:`sitemap.xml` file that references both -:file:`sitemap-flatpages.xml` and :file:`sitemap-blog.xml`. The -:class:`~django.contrib.sitemaps.Sitemap` classes and the :data:`sitemaps` dict -don't change at all. - -You should create an index file if one of your sitemaps has more than 50,000 -URLs. In this case, Django will automatically paginate the sitemap, and the -index will reflect that. - -Pinging Google -============== - -You may want to "ping" Google when your sitemap changes, to let it know to -reindex your site. The sitemaps framework provides a function to do just -that: :func:`django.contrib.sitemaps.ping_google()`. - -.. function:: ping_google - - :func:`ping_google` takes an optional argument, :data:`sitemap_url`, - which should be the absolute path to your site's sitemap (e.g., - :file:`'/sitemap.xml'`). If this argument isn't provided, - :func:`ping_google` will attempt to figure out your - sitemap by performing a reverse looking in your URLconf. - - :func:`ping_google` raises the exception - :exc:`django.contrib.sitemaps.SitemapNotFound` if it cannot determine your - sitemap URL. - -.. admonition:: Register with Google first! - - The :func:`ping_google` command only works if you have registered your - site with `Google Webmaster Tools`_. - -.. _`Google Webmaster Tools`: http://www.google.com/webmasters/tools/ - -One useful way to call :func:`ping_google` is from a model's ``save()`` -method:: - - from django.contrib.sitemaps import ping_google - - class Entry(models.Model): - # ... - def save(self, force_insert=False, force_update=False): - super(Entry, self).save(force_insert, force_update) - 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 :func:`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()``. - -Pinging Google via `manage.py` ------------------------------- - -.. django-admin:: ping_google - -.. versionadded:: 1.0 - -Once the sitemaps application is added to your project, you may also -ping Google using the ``ping_google`` management command:: - - python manage.py ping_google [/sitemap.xml] diff --git a/parts/django/docs/ref/contrib/sites.txt b/parts/django/docs/ref/contrib/sites.txt deleted file mode 100644 index 6d795d0..0000000 --- a/parts/django/docs/ref/contrib/sites.txt +++ /dev/null @@ -1,415 +0,0 @@ -===================== -The "sites" framework -===================== - -.. module:: django.contrib.sites - :synopsis: Lets you operate multiple Web sites from the same database and - Django project - -Django comes with an optional "sites" framework. It's a hook for associating -objects and functionality to particular Web sites, and it's a holding place for -the domain names and "verbose" names of your Django-powered sites. - -Use it if your single Django installation powers more than one site and you -need to differentiate between those sites in some way. - -The whole sites framework is based on a simple model: - -.. class:: django.contrib.sites.models.Site - -This model has :attr:`~django.contrib.sites.models.Site.domain` and -:attr:`~django.contrib.sites.models.Site.name` fields. The :setting:`SITE_ID` -setting specifies the database ID of the -:class:`~django.contrib.sites.models.Site` object associated with that -particular settings file. - -How you use this is up to you, but Django uses it in a couple of ways -automatically via simple conventions. - -Example usage -============= - -Why would you use sites? It's best explained through examples. - -Associating content with multiple sites ---------------------------------------- - -The Django-powered sites LJWorld.com_ and Lawrence.com_ are operated by the -same news organization -- the Lawrence Journal-World newspaper in Lawrence, -Kansas. LJWorld.com focuses on news, while Lawrence.com focuses on local -entertainment. But sometimes editors want to publish an article on *both* -sites. - -The brain-dead way of solving the problem would be to require site producers to -publish the same story twice: once for LJWorld.com and again for Lawrence.com. -But that's inefficient for site producers, and it's redundant to store -multiple copies of the same story in the database. - -The better solution is simple: Both sites use the same article database, and an -article is associated with one or more sites. In Django model terminology, -that's represented by a :class:`~django.db.models.ManyToManyField` in the -``Article`` model:: - - from django.db import models - from django.contrib.sites.models import Site - - class Article(models.Model): - headline = models.CharField(max_length=200) - # ... - sites = models.ManyToManyField(Site) - -This accomplishes several things quite nicely: - - * It lets the site producers edit all content -- on both sites -- in a - single interface (the Django admin). - - * It means the same story doesn't have to be published twice in the - database; it only has a single record in the database. - - * It lets the site developers use the same Django view code for both sites. - The view code that displays a given story just checks to make sure the - requested story is on the current site. It looks something like this:: - - from django.conf import settings - - def article_detail(request, article_id): - try: - a = Article.objects.get(id=article_id, sites__id__exact=settings.SITE_ID) - except Article.DoesNotExist: - raise Http404 - # ... - -.. _ljworld.com: http://www.ljworld.com/ -.. _lawrence.com: http://www.lawrence.com/ - -Associating content with a single site --------------------------------------- - -Similarly, you can associate a model to the :class:`~django.contrib.sites.models.Site` -model in a many-to-one relationship, using -:class:`~django.db.models.fields.related.ForeignKey`. - -For example, if an article is only allowed on a single site, you'd use a model -like this:: - - from django.db import models - from django.contrib.sites.models import Site - - class Article(models.Model): - headline = models.CharField(max_length=200) - # ... - site = models.ForeignKey(Site) - -This has the same benefits as described in the last section. - -Hooking into the current site from views ----------------------------------------- - -You can use the sites framework in your Django views to do -particular things based on the site in which the view is being called. -For example:: - - from django.conf import settings - - def my_view(request): - if settings.SITE_ID == 3: - # Do something. - else: - # Do something else. - -Of course, it's ugly to hard-code the site IDs like that. This sort of -hard-coding is best for hackish fixes that you need done quickly. A slightly -cleaner way of accomplishing the same thing is to check the current site's -domain:: - - from django.conf import settings - from django.contrib.sites.models import Site - - def my_view(request): - current_site = Site.objects.get(id=settings.SITE_ID) - if current_site.domain == 'foo.com': - # Do something - else: - # Do something else. - -The idiom of retrieving the :class:`~django.contrib.sites.models.Site` object -for the value of :setting:`settings.SITE_ID <SITE_ID>` is quite common, so -the :class:`~django.contrib.sites.models.Site` model's manager has a -``get_current()`` method. This example is equivalent to the previous one:: - - from django.contrib.sites.models import Site - - def my_view(request): - current_site = Site.objects.get_current() - if current_site.domain == 'foo.com': - # Do something - else: - # Do something else. - -.. versionchanged:: 1.3 - -For code which relies on getting the current domain but cannot be certain -that the sites framework will be installed for any given project, there is a -utility function :func:`~django.contrib.sites.models.get_current_site` that -takes a request object as an argument and returns either a Site instance (if -the sites framework is installed) or a RequestSite instance (if it is not). -This allows loose coupling with the sites framework and provides a usable -fallback for cases where it is not installed. - -Getting the current domain for display --------------------------------------- - -LJWorld.com and Lawrence.com both have e-mail alert functionality, which lets -readers sign up to get notifications when news happens. It's pretty basic: A -reader signs up on a Web form, and he immediately gets an e-mail saying, -"Thanks for your subscription." - -It'd be inefficient and redundant to implement this signup-processing code -twice, so the sites use the same code behind the scenes. But the "thank you for -signing up" notice needs to be different for each site. By using -:class:`~django.contrib.sites.models.Site` -objects, we can abstract the "thank you" notice to use the values of the -current site's :attr:`~django.contrib.sites.models.Site.name` and -:attr:`~django.contrib.sites.models.Site.domain`. - -Here's an example of what the form-handling view looks like:: - - from django.contrib.sites.models import Site - from django.core.mail import send_mail - - def register_for_newsletter(request): - # Check form values, etc., and subscribe the user. - # ... - - current_site = Site.objects.get_current() - send_mail('Thanks for subscribing to %s alerts' % current_site.name, - 'Thanks for your subscription. We appreciate it.\n\n-The %s team.' % current_site.name, - 'editor@%s' % current_site.domain, - [user.email]) - - # ... - -On Lawrence.com, this e-mail has the subject line "Thanks for subscribing to -lawrence.com alerts." On LJWorld.com, the e-mail has the subject "Thanks for -subscribing to LJWorld.com alerts." Same goes for the e-mail's message body. - -Note that an even more flexible (but more heavyweight) way of doing this would -be to use Django's template system. Assuming Lawrence.com and LJWorld.com have -different template directories (:setting:`TEMPLATE_DIRS`), you could simply farm out -to the template system like so:: - - from django.core.mail import send_mail - from django.template import loader, Context - - def register_for_newsletter(request): - # Check form values, etc., and subscribe the user. - # ... - - subject = loader.get_template('alerts/subject.txt').render(Context({})) - message = loader.get_template('alerts/message.txt').render(Context({})) - send_mail(subject, message, 'editor@ljworld.com', [user.email]) - - # ... - -In this case, you'd have to create :file:`subject.txt` and :file:`message.txt` template -files for both the LJWorld.com and Lawrence.com template directories. That -gives you more flexibility, but it's also more complex. - -It's a good idea to exploit the :class:`~django.contrib.sites.models.Site` -objects as much as possible, to remove unneeded complexity and redundancy. - -Getting the current domain for full URLs ----------------------------------------- - -Django's ``get_absolute_url()`` convention is nice for getting your objects' -URL without the domain name, but in some cases you might want to display the -full URL -- with ``http://`` and the domain and everything -- for an object. -To do this, you can use the sites framework. A simple example:: - - >>> from django.contrib.sites.models import Site - >>> obj = MyModel.objects.get(id=3) - >>> obj.get_absolute_url() - '/mymodel/objects/3/' - >>> Site.objects.get_current().domain - 'example.com' - >>> 'http://%s%s' % (Site.objects.get_current().domain, obj.get_absolute_url()) - 'http://example.com/mymodel/objects/3/' - -Caching the current ``Site`` object -=================================== - -.. versionadded:: 1.0 - -As the current site is stored in the database, each call to -``Site.objects.get_current()`` could result in a database query. But Django is a -little cleverer than that: on the first request, the current site is cached, and -any subsequent call returns the cached data instead of hitting the database. - -If for any reason you want to force a database query, you can tell Django to -clear the cache using ``Site.objects.clear_cache()``:: - - # First call; current site fetched from database. - current_site = Site.objects.get_current() - # ... - - # Second call; current site fetched from cache. - current_site = Site.objects.get_current() - # ... - - # Force a database query for the third call. - Site.objects.clear_cache() - current_site = Site.objects.get_current() - -The ``CurrentSiteManager`` -========================== - -.. class:: django.contrib.sites.managers.CurrentSiteManager - -If :class:`~django.contrib.sites.models.Site` plays a key role in your -application, consider using the helpful -:class:`~django.contrib.sites.managers.CurrentSiteManager` in your -model(s). It's a model :doc:`manager </topics/db/managers>` that -automatically filters its queries to include only objects associated -with the current :class:`~django.contrib.sites.models.Site`. - -Use :class:`~django.contrib.sites.managers.CurrentSiteManager` by adding it to -your model explicitly. For example:: - - from django.db import models - from django.contrib.sites.models import Site - from django.contrib.sites.managers import CurrentSiteManager - - class Photo(models.Model): - photo = models.FileField(upload_to='/home/photos') - photographer_name = models.CharField(max_length=100) - pub_date = models.DateField() - site = models.ForeignKey(Site) - objects = models.Manager() - on_site = CurrentSiteManager() - -With this model, ``Photo.objects.all()`` will return all ``Photo`` objects in -the database, but ``Photo.on_site.all()`` will return only the ``Photo`` objects -associated with the current site, according to the :setting:`SITE_ID` setting. - -Put another way, these two statements are equivalent:: - - Photo.objects.filter(site=settings.SITE_ID) - Photo.on_site.all() - -How did :class:`~django.contrib.sites.managers.CurrentSiteManager` -know which field of ``Photo`` was the -:class:`~django.contrib.sites.models.Site`? By default, -:class:`~django.contrib.sites.managers.CurrentSiteManager` looks for a -either a :class:`~django.db.models.fields.related.ForeignKey` called -``site`` or a -:class:`~django.db.models.fields.related.ManyToManyField` called -``sites`` to filter on. If you use a field named something other than -``site`` or ``sites`` to identify which -:class:`~django.contrib.sites.models.Site` objects your object is -related to, then you need to explicitly pass the custom field name as -a parameter to -:class:`~django.contrib.sites.managers.CurrentSiteManager` on your -model. The following model, which has a field called ``publish_on``, -demonstrates this:: - - from django.db import models - from django.contrib.sites.models import Site - from django.contrib.sites.managers import CurrentSiteManager - - class Photo(models.Model): - photo = models.FileField(upload_to='/home/photos') - photographer_name = models.CharField(max_length=100) - pub_date = models.DateField() - publish_on = models.ForeignKey(Site) - objects = models.Manager() - on_site = CurrentSiteManager('publish_on') - -If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager` -and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`. - -Finally, note that you'll probably want to keep a normal -(non-site-specific) ``Manager`` on your model, even if you use -:class:`~django.contrib.sites.managers.CurrentSiteManager`. As -explained in the :doc:`manager documentation </topics/db/managers>`, 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 :class:`~django.contrib.sites.managers.CurrentSiteManager`. - -How Django uses the sites framework -=================================== - -Although it's not required that you use the sites framework, it's strongly -encouraged, because Django takes advantage of it in a few places. Even if your -Django installation is powering only a single site, you should take the two -seconds to create the site object with your ``domain`` and ``name``, and point -to its ID in your :setting:`SITE_ID` setting. - -Here's how Django uses the sites framework: - -* In the :mod:`redirects framework <django.contrib.redirects>`, each - redirect object is associated with a particular site. When Django searches - for a redirect, it takes into account the current :setting:`SITE_ID`. - -* In the comments framework, each comment is associated with a particular - site. When a comment is posted, its - :class:`~django.contrib.sites.models.Site` is set to the current - :setting:`SITE_ID`, and when comments are listed via the appropriate - template tag, only the comments for the current site are displayed. - -* In the :mod:`flatpages framework <django.contrib.flatpages>`, each - flatpage is associated with a particular site. When a flatpage is created, - you specify its :class:`~django.contrib.sites.models.Site`, and the - :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` - checks the current :setting:`SITE_ID` in retrieving flatpages to display. - -* In the :mod:`syndication framework <django.contrib.syndication>`, the - templates for ``title`` and ``description`` automatically have access to a - variable ``{{ site }}``, which is the - :class:`~django.contrib.sites.models.Site` object representing the current - site. Also, the hook for providing item URLs will use the ``domain`` from - the current :class:`~django.contrib.sites.models.Site` object if you don't - specify a fully-qualified domain. - -* In the :mod:`authentication framework <django.contrib.auth>`, the - :func:`django.contrib.auth.views.login` view passes the current - :class:`~django.contrib.sites.models.Site` name to the template as - ``{{ site_name }}``. - -* The shortcut view (:func:`django.views.defaults.shortcut`) uses the domain - of the current :class:`~django.contrib.sites.models.Site` object when - calculating an object's URL. - -* In the admin framework, the "view on site" link uses the current - :class:`~django.contrib.sites.models.Site` to work out the domain for the - site that it will redirect to. - - -``RequestSite`` objects -======================= - -.. _requestsite-objects: - -.. versionadded:: 1.0 - -Some :doc:`django.contrib </ref/contrib/index>` applications take advantage of -the sites framework but are architected in a way that doesn't *require* the -sites framework to be installed in your database. (Some people don't want to, or -just aren't *able* to install the extra database table that the sites framework -requires.) For those cases, the framework provides a -:class:`~django.contrib.sites.models.RequestSite` class, which can be used as a -fallback when the database-backed sites framework is not available. - -A :class:`~django.contrib.sites.models.RequestSite` object has a similar -interface to a normal :class:`~django.contrib.sites.models.Site` object, except -its :meth:`~django.contrib.sites.models.RequestSite.__init__()` method takes an -:class:`~django.http.HttpRequest` object. It's able to deduce the -:attr:`~django.contrib.sites.models.RequestSite.domain` and -:attr:`~django.contrib.sites.models.RequestSite.name` by looking at the -request's domain. It has :meth:`~django.contrib.sites.models.RequestSite.save()` -and :meth:`~django.contrib.sites.models.RequestSite.delete()` methods to match -the interface of :class:`~django.contrib.sites.models.Site`, but the methods -raise :exc:`NotImplementedError`. diff --git a/parts/django/docs/ref/contrib/syndication.txt b/parts/django/docs/ref/contrib/syndication.txt deleted file mode 100644 index 04f14b5..0000000 --- a/parts/django/docs/ref/contrib/syndication.txt +++ /dev/null @@ -1,949 +0,0 @@ -============================== -The syndication feed framework -============================== - -.. module:: django.contrib.syndication - :synopsis: A framework for generating syndication feeds, in RSS and Atom, - quite easily. - -Django comes with a high-level syndication-feed-generating framework -that makes creating RSS_ and Atom_ feeds easy. - -To create any syndication feed, all you have to do is write a short -Python class. You can create as many feeds as you want. - -Django also comes with a lower-level feed-generating API. Use this if -you want to generate feeds outside of a Web context, or in some other -lower-level way. - -.. _RSS: http://www.whatisrss.com/ -.. _Atom: http://www.atomenabled.org/ - -The high-level framework -======================== - -.. versionchanged:: 1.2 - The high-level feeds framework was refactored in Django 1.2. The - pre-1.2 interface still exists, but it has been deprecated, and - will be removed in Django 1.4. If you need to maintain an old-style - Django feed, please consult the Django 1.1 documentation. For - details on updating to use the new high-level feed framework, see - the :ref:`Django 1.2 release notes <1.2-updating-feeds>`. - -Overview --------- - -The high-level feed-generating framework is supplied by the -:class:`~django.contrib.syndication.views.Feed` class. To create a -feed, write a :class:`~django.contrib.syndication.views.Feed` class -and point to an instance of it in your :doc:`URLconf -</topics/http/urls>`. - -Feed classes ------------- - -A :class:`~django.contrib.syndication.views.Feed` class is a Python -class that represents a syndication feed. A feed can be simple (e.g., -a "site news" feed, or a basic feed displaying the latest entries of a -blog) or more complex (e.g., a feed displaying all the blog entries in -a particular category, where the category is variable). - -Feed classes subclass :class:`django.contrib.syndication.views.Feed`. -They can live anywhere in your codebase. - -Instances of :class:`~django.contrib.syndication.views.Feed` classes -are views which can be used in your :doc:`URLconf </topics/http/urls>`. - -A simple example ----------------- - -This simple example, taken from `chicagocrime.org`_, describes a feed of the -latest five news items:: - - from django.contrib.syndication.views import Feed - from chicagocrime.models import NewsItem - - class LatestEntriesFeed(Feed): - title = "Chicagocrime.org site news" - link = "/sitenews/" - description = "Updates on changes and additions to chicagocrime.org." - - def items(self): - return NewsItem.objects.order_by('-pub_date')[:5] - - def item_title(self, item): - return item.title - - def item_description(self, item): - return item.description - -To connect a URL to this feed, put an instance of the Feed object in -your :doc:`URLconf </topics/http/urls>`. For example:: - - from django.conf.urls.defaults import * - from myproject.feeds import LatestEntriesFeed - - urlpatterns = patterns('', - # ... - (r'^latest/feed/$', LatestEntriesFeed()), - # ... - ) - -Note: - -* The Feed class subclasses :class:`django.contrib.syndication.views.Feed`. - -* :attr:`title`, :attr:`link` and :attr:`description` correspond to the - standard RSS ``<title>``, ``<link>`` and ``<description>`` elements, - respectively. - -* :meth:`items()` is, simply, a method that returns a list of objects that - should be included in the feed as ``<item>`` elements. Although this - example returns ``NewsItem`` objects using Django's - :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()` - doesn't have to return model instances. Although you get a few bits of - functionality "for free" by using Django models, :meth:`items()` can - return any type of object you want. - -* If you're creating an Atom feed, rather than an RSS feed, set the - :attr:`subtitle` attribute instead of the :attr:`description` attribute. - See `Publishing Atom and RSS feeds in tandem`_, later, for an example. - -One thing is left to do. In an RSS feed, each ``<item>`` has a ``<title>``, -``<link>`` and ``<description>``. We need to tell the framework what data to put -into those elements. - - * For the contents of ``<title>`` and ``<description>``, Django tries - calling the methods :meth:`item_title()` and :meth:`item_description()` on - the :class:`~django.contrib.syndication.views.Feed` class. They are passed - a single parameter, :attr:`item`, which is the object itself. These are - optional; by default, the unicode representation of the object is used for - both. - - If you want to do any special formatting for either the title or - description, :doc:`Django templates </topics/templates>` can be used - instead. Their paths can be specified with the ``title_template`` and - ``description_template`` attributes on the - :class:`~django.contrib.syndication.views.Feed` class. The templates are - rendered for each item and are passed two template context variables: - - * ``{{ obj }}`` -- The current object (one of whichever objects you - returned in :meth:`items()`). - - * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object - representing the current site. This is useful for ``{{ site.domain - }}`` or ``{{ site.name }}``. If you do *not* have the Django sites - framework installed, this will be set to a - :class:`django.contrib.sites.models.RequestSite` object. See the - :ref:`RequestSite section of the sites framework documentation - <requestsite-objects>` for more. - - See `a complex example`_ below that uses a description template. - - * To specify the contents of ``<link>``, you have two options. For each item - in :meth:`items()`, Django first tries calling the - :meth:`item_link()` method on the - :class:`~django.contrib.syndication.views.Feed` class. In a similar way to - the title and description, it is passed it a single parameter, - :attr:`item`. If that method doesn't exist, Django tries executing a - ``get_absolute_url()`` method on that object. Both - :meth:`get_absolute_url()` and :meth:`item_link()` should return the - item's URL as a normal Python string. As with ``get_absolute_url()``, the - result of :meth:`item_link()` will be included directly in the URL, so you - are responsible for doing all necessary URL quoting and conversion to - ASCII inside the method itself. - -.. _chicagocrime.org: http://www.chicagocrime.org/ - -A complex example ------------------ - -The framework also supports more complex feeds, via arguments. - -For example, `chicagocrime.org`_ offers an RSS feed of recent crimes for every -police beat in Chicago. It'd be silly to create a separate -:class:`~django.contrib.syndication.views.Feed` class for each police beat; that -would violate the :ref:`DRY principle <dry>` and would couple data to -programming logic. Instead, the syndication framework lets you access the -arguments passed from your :doc:`URLconf </topics/http/urls>` so feeds can output -items based on information in the feed's URL. - -On chicagocrime.org, the police-beat feeds are accessible via URLs like this: - - * :file:`/beats/613/rss/` -- Returns recent crimes for beat 613. - * :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424. - -These can be matched with a :doc:`URLconf </topics/http/urls>` line such as:: - - (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()), - -Like a view, the arguments in the URL are passed to the :meth:`get_object()` -method along with the request object. - -.. versionchanged:: 1.2 - Prior to version 1.2, ``get_object()`` only accepted a ``bits`` argument. - -Here's the code for these beat-specific feeds:: - - from django.contrib.syndication.views import FeedDoesNotExist - from django.shortcuts import get_object_or_404 - - class BeatFeed(Feed): - description_template = 'feeds/beat_description.html' - - def get_object(self, request, beat_id): - return get_object_or_404(Beat, pk=beat_id) - - def title(self, obj): - return "Chicagocrime.org: Crimes for beat %s" % obj.beat - - def link(self, obj): - return obj.get_absolute_url() - - def description(self, obj): - return "Crimes recently reported in police beat %s" % obj.beat - - def items(self, obj): - return Crime.objects.filter(beat=obj).order_by('-crime_date')[:30] - -To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django -uses the :meth:`title()`, :meth:`link()` and :meth:`description()` methods. In -the previous example, they were simple string class attributes, but this example -illustrates that they can be either strings *or* methods. For each of -:attr:`title`, :attr:`link` and :attr:`description`, Django follows this -algorithm: - - * First, it tries to call a method, passing the ``obj`` argument, where - ``obj`` is the object returned by :meth:`get_object()`. - - * Failing that, it tries to call a method with no arguments. - - * Failing that, it uses the class attribute. - -Also note that :meth:`items()` also follows the same algorithm -- first, it -tries :meth:`items(obj)`, then :meth:`items()`, then finally an :attr:`items` -class attribute (which should be a list). - -We are using a template for the item descriptions. It can be very simple: - -.. code-block:: html+django - - {{ obj.description }} - -However, you are free to add formatting as desired. - -The ``ExampleFeed`` class below gives full documentation on methods and -attributes of :class:`~django.contrib.syndication.views.Feed` classes. - -Specifying the type of feed ---------------------------- - -By default, feeds produced in this framework use RSS 2.0. - -To change that, add a ``feed_type`` attribute to your -:class:`~django.contrib.syndication.views.Feed` class, like so:: - - from django.utils.feedgenerator import Atom1Feed - - class MyFeed(Feed): - feed_type = Atom1Feed - -Note that you set ``feed_type`` to a class object, not an instance. - -Currently available feed types are: - - * :class:`django.utils.feedgenerator.Rss201rev2Feed` (RSS 2.01. Default.) - * :class:`django.utils.feedgenerator.RssUserland091Feed` (RSS 0.91.) - * :class:`django.utils.feedgenerator.Atom1Feed` (Atom 1.0.) - -Enclosures ----------- - -To specify enclosures, such as those used in creating podcast feeds, use the -:attr:`item_enclosure_url`, :attr:`item_enclosure_length` and -:attr:`item_enclosure_mime_type` hooks. See the ``ExampleFeed`` class below for -usage examples. - -Language --------- - -Feeds created by the syndication framework automatically include the -appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This -comes directly from your :setting:`LANGUAGE_CODE` setting. - -URLs ----- - -The :attr:`link` method/attribute can return either an absolute path (e.g. -:file:`"/blog/"`) or a URL with the fully-qualified domain and protocol (e.g. -``"http://www.example.com/blog/"``). If :attr:`link` doesn't return the domain, -the syndication framework will insert the domain of the current site, according -to your :setting:`SITE_ID setting <SITE_ID>`. - -Atom feeds require a ``<link rel="self">`` that defines the feed's current -location. The syndication framework populates this automatically, using the -domain of the current site according to the :setting:`SITE_ID` setting. - -Publishing Atom and RSS feeds in tandem ---------------------------------------- - -Some developers like to make available both Atom *and* RSS versions of their -feeds. That's easy to do with Django: Just create a subclass of your -:class:`~django.contrib.syndication.views.Feed` -class and set the :attr:`feed_type` to something different. Then update your -URLconf to add the extra versions. - -Here's a full example:: - - from django.contrib.syndication.views import Feed - from chicagocrime.models import NewsItem - from django.utils.feedgenerator import Atom1Feed - - class RssSiteNewsFeed(Feed): - title = "Chicagocrime.org site news" - link = "/sitenews/" - description = "Updates on changes and additions to chicagocrime.org." - - def items(self): - return NewsItem.objects.order_by('-pub_date')[:5] - - class AtomSiteNewsFeed(RssSiteNewsFeed): - feed_type = Atom1Feed - subtitle = RssSiteNewsFeed.description - -.. Note:: - In this example, the RSS feed uses a :attr:`description` while the Atom - feed uses a :attr:`subtitle`. That's because Atom feeds don't provide for - a feed-level "description," but they *do* provide for a "subtitle." - - If you provide a :attr:`description` in your - :class:`~django.contrib.syndication.views.Feed` class, Django will *not* - automatically put that into the :attr:`subtitle` element, because a - subtitle and description are not necessarily the same thing. Instead, you - should define a :attr:`subtitle` attribute. - - In the above example, we simply set the Atom feed's :attr:`subtitle` to the - RSS feed's :attr:`description`, because it's quite short already. - -And the accompanying URLconf:: - - from django.conf.urls.defaults import * - from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed - - urlpatterns = patterns('', - # ... - (r'^sitenews/rss/$', RssSiteNewsFeed()), - (r'^sitenews/atom/$', AtomSiteNewsFeed()), - # ... - ) - -Feed class reference --------------------- - -.. class:: django.contrib.syndication.views.Feed - -This example illustrates all possible attributes and methods for a -:class:`~django.contrib.syndication.views.Feed` class:: - - from django.contrib.syndication.views import Feed - from django.utils import feedgenerator - - class ExampleFeed(Feed): - - # FEED TYPE -- Optional. This should be a class that subclasses - # django.utils.feedgenerator.SyndicationFeed. This designates - # which type of feed this should be: RSS 2.0, Atom 1.0, etc. If - # you don't specify feed_type, your feed will be RSS 2.0. This - # should be a class, not an instance of the class. - - feed_type = feedgenerator.Rss201rev2Feed - - # TEMPLATE NAMES -- Optional. These should be strings - # representing names of Django templates that the system should - # use in rendering the title and description of your feed items. - # Both are optional. If a template is not specified, the - # item_title() or item_description() methods are used instead. - - title_template = None - description_template = None - - # TITLE -- One of the following three is required. The framework - # looks for them in this order. - - def title(self, obj): - """ - Takes the object returned by get_object() and returns the - feed's title as a normal Python string. - """ - - def title(self): - """ - Returns the feed's title as a normal Python string. - """ - - title = 'foo' # Hard-coded title. - - # LINK -- One of the following three is required. The framework - # looks for them in this order. - - def link(self, obj): - """ - # Takes the object returned by get_object() and returns the feed's - # link as a normal Python string. - """ - - def link(self): - """ - Returns the feed's link as a normal Python string. - """ - - link = '/foo/bar/' # Hard-coded link. - - # GUID -- One of the following three is optional. The framework looks - # for them in this order. This property is only used for Atom feeds - # (where it is the feed-level ID element). If not provided, the feed - # link is used as the ID. - - def feed_guid(self, obj): - """ - Takes the object returned by get_object() and returns the globally - unique ID for the feed as a normal Python string. - """ - - def feed_guid(self): - """ - Returns the feed's globally unique ID as a normal Python string. - """ - - feed_guid = '/foo/bar/1234' # Hard-coded guid. - - # DESCRIPTION -- One of the following three is required. The framework - # looks for them in this order. - - def description(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - description as a normal Python string. - """ - - def description(self): - """ - Returns the feed's description as a normal Python string. - """ - - description = 'Foo bar baz.' # Hard-coded description. - - # AUTHOR NAME --One of the following three is optional. The framework - # looks for them in this order. - - def author_name(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - author's name as a normal Python string. - """ - - def author_name(self): - """ - Returns the feed's author's name as a normal Python string. - """ - - author_name = 'Sally Smith' # Hard-coded author name. - - # AUTHOR E-MAIL --One of the following three is optional. The framework - # looks for them in this order. - - def author_email(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - author's e-mail as a normal Python string. - """ - - def author_email(self): - """ - Returns the feed's author's e-mail as a normal Python string. - """ - - author_email = 'test@example.com' # Hard-coded author e-mail. - - # AUTHOR LINK --One of the following three is optional. The framework - # looks for them in this order. In each case, the URL should include - # the "http://" and domain name. - - def author_link(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - author's URL as a normal Python string. - """ - - def author_link(self): - """ - Returns the feed's author's URL as a normal Python string. - """ - - author_link = 'http://www.example.com/' # Hard-coded author URL. - - # CATEGORIES -- One of the following three is optional. The framework - # looks for them in this order. In each case, the method/attribute - # should return an iterable object that returns strings. - - def categories(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - categories as iterable over strings. - """ - - def categories(self): - """ - Returns the feed's categories as iterable over strings. - """ - - categories = ("python", "django") # Hard-coded list of categories. - - # COPYRIGHT NOTICE -- One of the following three is optional. The - # framework looks for them in this order. - - def feed_copyright(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - copyright notice as a normal Python string. - """ - - def feed_copyright(self): - """ - Returns the feed's copyright notice as a normal Python string. - """ - - feed_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice. - - # TTL -- One of the following three is optional. The framework looks - # for them in this order. Ignored for Atom feeds. - - def ttl(self, obj): - """ - Takes the object returned by get_object() and returns the feed's - TTL (Time To Live) as a normal Python string. - """ - - def ttl(self): - """ - Returns the feed's TTL as a normal Python string. - """ - - ttl = 600 # Hard-coded Time To Live. - - # ITEMS -- One of the following three is required. The framework looks - # for them in this order. - - def items(self, obj): - """ - Takes the object returned by get_object() and returns a list of - items to publish in this feed. - """ - - def items(self): - """ - Returns a list of items to publish in this feed. - """ - - items = ('Item 1', 'Item 2') # Hard-coded items. - - # GET_OBJECT -- This is required for feeds that publish different data - # for different URL parameters. (See "A complex example" above.) - - def get_object(self, request, *args, **kwargs): - """ - Takes the current request and the arguments from the URL, and - returns an object represented by this feed. Raises - django.core.exceptions.ObjectDoesNotExist on error. - """ - - # ITEM TITLE AND DESCRIPTION -- If title_template or - # description_template are not defined, these are used instead. Both are - # optional, by default they will use the unicode representation of the - # item. - - def item_title(self, item): - """ - Takes an item, as returned by items(), and returns the item's - title as a normal Python string. - """ - - def item_title(self): - """ - Returns the title for every item in the feed. - """ - - item_title = 'Breaking News: Nothing Happening' # Hard-coded title. - - def item_description(self, item): - """ - Takes an item, as returned by items(), and returns the item's - description as a normal Python string. - """ - - def item_description(self): - """ - Returns the description for every item in the feed. - """ - - item_description = 'A description of the item.' # Hard-coded description. - - # ITEM LINK -- One of these three is required. The framework looks for - # them in this order. - - # First, the framework tries the two methods below, in - # order. Failing that, it falls back to the get_absolute_url() - # method on each item returned by items(). - - def item_link(self, item): - """ - Takes an item, as returned by items(), and returns the item's URL. - """ - - def item_link(self): - """ - Returns the URL for every item in the feed. - """ - - # ITEM_GUID -- The following method is optional. If not provided, the - # item's link is used by default. - - def item_guid(self, obj): - """ - Takes an item, as return by items(), and returns the item's ID. - """ - - # ITEM AUTHOR NAME -- One of the following three is optional. The - # framework looks for them in this order. - - def item_author_name(self, item): - """ - Takes an item, as returned by items(), and returns the item's - author's name as a normal Python string. - """ - - def item_author_name(self): - """ - Returns the author name for every item in the feed. - """ - - item_author_name = 'Sally Smith' # Hard-coded author name. - - # ITEM AUTHOR E-MAIL --One of the following three is optional. The - # framework looks for them in this order. - # - # If you specify this, you must specify item_author_name. - - def item_author_email(self, obj): - """ - Takes an item, as returned by items(), and returns the item's - author's e-mail as a normal Python string. - """ - - def item_author_email(self): - """ - Returns the author e-mail for every item in the feed. - """ - - item_author_email = 'test@example.com' # Hard-coded author e-mail. - - # ITEM AUTHOR LINK -- One of the following three is optional. The - # framework looks for them in this order. In each case, the URL should - # include the "http://" and domain name. - # - # If you specify this, you must specify item_author_name. - - def item_author_link(self, obj): - """ - Takes an item, as returned by items(), and returns the item's - author's URL as a normal Python string. - """ - - def item_author_link(self): - """ - Returns the author URL for every item in the feed. - """ - - item_author_link = 'http://www.example.com/' # Hard-coded author URL. - - # ITEM ENCLOSURE URL -- One of these three is required if you're - # publishing enclosures. The framework looks for them in this order. - - def item_enclosure_url(self, item): - """ - Takes an item, as returned by items(), and returns the item's - enclosure URL. - """ - - def item_enclosure_url(self): - """ - Returns the enclosure URL for every item in the feed. - """ - - item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link. - - # ITEM ENCLOSURE LENGTH -- One of these three is required if you're - # publishing enclosures. The framework looks for them in this order. - # In each case, the returned value should be either an integer, or a - # string representation of the integer, in bytes. - - def item_enclosure_length(self, item): - """ - Takes an item, as returned by items(), and returns the item's - enclosure length. - """ - - def item_enclosure_length(self): - """ - Returns the enclosure length for every item in the feed. - """ - - item_enclosure_length = 32000 # Hard-coded enclosure length. - - # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're - # publishing enclosures. The framework looks for them in this order. - - def item_enclosure_mime_type(self, item): - """ - Takes an item, as returned by items(), and returns the item's - enclosure MIME type. - """ - - def item_enclosure_mime_type(self): - """ - Returns the enclosure MIME type for every item in the feed. - """ - - item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type. - - # ITEM PUBDATE -- It's optional to use one of these three. This is a - # hook that specifies how to get the pubdate for a given item. - # In each case, the method/attribute should return a Python - # datetime.datetime object. - - def item_pubdate(self, item): - """ - Takes an item, as returned by items(), and returns the item's - pubdate. - """ - - def item_pubdate(self): - """ - Returns the pubdate for every item in the feed. - """ - - item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate. - - # ITEM CATEGORIES -- It's optional to use one of these three. This is - # a hook that specifies how to get the list of categories for a given - # item. In each case, the method/attribute should return an iterable - # object that returns strings. - - def item_categories(self, item): - """ - Takes an item, as returned by items(), and returns the item's - categories. - """ - - def item_categories(self): - """ - Returns the categories for every item in the feed. - """ - - item_categories = ("python", "django") # Hard-coded categories. - - # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the - # following three is optional. The framework looks for them in this - # order. - - def item_copyright(self, obj): - """ - Takes an item, as returned by items(), and returns the item's - copyright notice as a normal Python string. - """ - - def item_copyright(self): - """ - Returns the copyright notice for every item in the feed. - """ - - item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice. - - -The low-level framework -======================= - -Behind the scenes, the high-level RSS framework uses a lower-level framework -for generating feeds' XML. This framework lives in a single module: -`django/utils/feedgenerator.py`_. - -You use this framework on your own, for lower-level feed generation. You can -also create custom feed generator subclasses for use with the ``feed_type`` -``Feed`` option. - -``SyndicationFeed`` classes ---------------------------- - -The :mod:`~django.utils.feedgenerator` module contains a base class: - -.. class:: django.utils.feedgenerator.SyndicationFeed - -and several subclasses: - -.. class:: django.utils.feedgenerator.RssUserland091Feed -.. class:: django.utils.feedgenerator.Rss201rev2Feed -.. class:: django.utils.feedgenerator.Atom1Feed - -Each of these three classes knows how to render a certain type of feed as XML. -They share this interface: - -.. method:: SyndicationFeed.__init__(**kwargs) - - Initialize the feed with the given dictionary of metadata, which applies to - the entire feed. Required keyword arguments are: - - * ``title`` - * ``link`` - * ``description`` - - There's also a bunch of other optional keywords: - - * ``language`` - * ``author_email`` - * ``author_name`` - * ``author_link`` - * ``subtitle`` - * ``categories`` - * ``feed_url`` - * ``feed_copyright`` - * ``feed_guid`` - * ``ttl`` - - Any extra keyword arguments you pass to ``__init__`` will be stored in - ``self.feed`` for use with `custom feed generators`_. - - All parameters should be Unicode objects, except ``categories``, which - should be a sequence of Unicode objects. - -.. method:: SyndicationFeed.add_item(**kwargs) - - Add an item to the feed with the given parameters. - - Required keyword arguments are: - - * ``title`` - * ``link`` - * ``description`` - - Optional keyword arguments are: - - * ``author_email`` - * ``author_name`` - * ``author_link`` - * ``pubdate`` - * ``comments`` - * ``unique_id`` - * ``enclosure`` - * ``categories`` - * ``item_copyright`` - * ``ttl`` - - Extra keyword arguments will be stored for `custom feed generators`_. - - All parameters, if given, should be Unicode objects, except: - - * ``pubdate`` should be a `Python datetime object`_. - * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``. - * ``categories`` should be a sequence of Unicode objects. - -.. method:: SyndicationFeed.write(outfile, encoding) - - Outputs the feed in the given encoding to outfile, which is a file-like object. - -.. method:: SyndicationFeed.writeString(encoding) - - Returns the feed as a string in the given encoding. - -For example, to create an Atom 1.0 feed and print it to standard output:: - - >>> from django.utils import feedgenerator - >>> from datetime import datetime - >>> f = feedgenerator.Atom1Feed( - ... title=u"My Weblog", - ... link=u"http://www.example.com/", - ... description=u"In which I write about what I ate today.", - ... language=u"en", - ... author_name=u"Myself", - ... feed_url=u"http://example.com/atom.xml") - >>> f.add_item(title=u"Hot dog today", - ... link=u"http://www.example.com/entries/1/", - ... pubdate=datetime.now(), - ... description=u"<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>") - >>> print f.writeString('UTF-8') - <?xml version="1.0" encoding="UTF-8"?> - <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en"> - ... - </feed> - -.. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py -.. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects - -Custom feed generators ----------------------- - -If you need to produce a custom feed format, you've got a couple of options. - -If the feed format is totally custom, you'll want to subclass -``SyndicationFeed`` and completely replace the ``write()`` and -``writeString()`` methods. - -However, if the feed format is a spin-off of RSS or Atom (i.e. GeoRSS_, Apple's -`iTunes podcast format`_, etc.), you've got a better choice. These types of -feeds typically add extra elements and/or attributes to the underlying format, -and there are a set of methods that ``SyndicationFeed`` calls to get these extra -attributes. Thus, you can subclass the appropriate feed generator class -(``Atom1Feed`` or ``Rss201rev2Feed``) and extend these callbacks. They are: - -.. _georss: http://georss.org/ -.. _itunes podcast format: http://www.apple.com/itunes/podcasts/specs.html - -``SyndicationFeed.root_attributes(self, )`` - Return a ``dict`` of attributes to add to the root feed element - (``feed``/``channel``). - -``SyndicationFeed.add_root_elements(self, handler)`` - Callback to add elements inside the root feed element - (``feed``/``channel``). ``handler`` is an `XMLGenerator`_ from Python's - built-in SAX library; you'll call methods on it to add to the XML - document in process. - -``SyndicationFeed.item_attributes(self, item)`` - Return a ``dict`` of attributes to add to each item (``item``/``entry``) - element. The argument, ``item``, is a dictionary of all the data passed to - ``SyndicationFeed.add_item()``. - -``SyndicationFeed.add_item_elements(self, handler, item)`` - Callback to add elements to each item (``item``/``entry``) element. - ``handler`` and ``item`` are as above. - -.. warning:: - - If you override any of these methods, be sure to call the superclass methods - since they add the required elements for each feed format. - -For example, you might start implementing an iTunes RSS feed generator like so:: - - class iTunesFeed(Rss201rev2Feed): - def root_attributes(self): - attrs = super(iTunesFeed, self).root_attributes() - attrs['xmlns:itunes'] = 'http://www.itunes.com/dtds/podcast-1.0.dtd' - return attrs - - def add_root_elements(self, handler): - super(iTunesFeed, self).add_root_elements(handler) - handler.addQuickElement('itunes:explicit', 'clean') - -Obviously there's a lot more work to be done for a complete custom feed class, -but the above example should demonstrate the basic idea. - -.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator diff --git a/parts/django/docs/ref/contrib/webdesign.txt b/parts/django/docs/ref/contrib/webdesign.txt deleted file mode 100644 index d355d03..0000000 --- a/parts/django/docs/ref/contrib/webdesign.txt +++ /dev/null @@ -1,56 +0,0 @@ -======================== -django.contrib.webdesign -======================== - -.. module:: django.contrib.webdesign - :synopsis: Helpers and utilities targeted primarily at Web *designers* - rather than Web *developers*. - -The ``django.contrib.webdesign`` package, part of the -:doc:`"django.contrib" add-ons </ref/contrib/index>`, provides various Django -helpers that are particularly useful to Web *designers* (as opposed to -developers). - -At present, the package contains only a single template tag. If you have ideas -for Web-designer-friendly functionality in Django, please -:doc:`suggest them </internals/contributing>`. - -Template tags -============= - -To use these template tags, add ``'django.contrib.webdesign'`` to your -:setting:`INSTALLED_APPS` setting. Once you've done that, use -``{% load webdesign %}`` in a template to give your template access to the tags. - - -lorem -===== - -Displays random "lorem ipsum" Latin text. This is useful for providing sample -data in templates. - -Usage:: - - {% lorem [count] [method] [random] %} - -The ``{% lorem %}`` tag can be used with zero, one, two or three arguments. -The arguments are: - - =========== ============================================================= - Argument Description - =========== ============================================================= - ``count`` A number (or variable) containing the number of paragraphs or - words to generate (default is 1). - ``method`` Either ``w`` for words, ``p`` for HTML paragraphs or ``b`` - for plain-text paragraph blocks (default is ``b``). - ``random`` The word ``random``, which if given, does not use the common - paragraph ("Lorem ipsum dolor sit amet...") when generating - text. - =========== ============================================================= - -Examples: - - * ``{% lorem %}`` will output the common "lorem ipsum" paragraph. - * ``{% lorem 3 p %}`` will output the common "lorem ipsum" paragraph - and two random paragraphs each wrapped in HTML ``<p>`` tags. - * ``{% lorem 2 w random %}`` will output two random Latin words. diff --git a/parts/django/docs/ref/databases.txt b/parts/django/docs/ref/databases.txt deleted file mode 100644 index c49a3fc..0000000 --- a/parts/django/docs/ref/databases.txt +++ /dev/null @@ -1,682 +0,0 @@ -========= -Databases -========= - -Django attempts to support as many features as possible on all database -backends. However, not all database backends are alike, and we've had to make -design decisions on which features to support and which assumptions we can make -safely. - -This file describes some of the features that might be relevant to Django -usage. Of course, it is not intended as a replacement for server-specific -documentation or reference manuals. - -.. _postgresql-notes: - -PostgreSQL notes -================ - -PostgreSQL 8.2 to 8.2.4 ------------------------ - -The implementation of the population statistics aggregates ``STDDEV_POP`` and -``VAR_POP`` that shipped with PostgreSQL 8.2 to 8.2.4 are `known to be -faulty`_. Users of these releases of PostgreSQL are advised to upgrade to -`Release 8.2.5`_ or later. Django will raise a ``NotImplementedError`` if you -attempt to use the ``StdDev(sample=False)`` or ``Variance(sample=False)`` -aggregate with a database backend that falls within the affected release range. - -.. _known to be faulty: http://archives.postgresql.org/pgsql-bugs/2007-07/msg00046.php -.. _Release 8.2.5: http://developer.postgresql.org/pgdocs/postgres/release-8-2-5.html - -Transaction handling ---------------------- - -:doc:`By default </topics/db/transactions>`, Django starts a transaction when a -database connection is first used and commits the result at the end of the -request/response handling. The PostgreSQL backends normally operate the same -as any other Django backend in this respect. - -Autocommit mode -~~~~~~~~~~~~~~~ - -.. versionadded:: 1.1 - -If your application is particularly read-heavy and doesn't make many -database writes, the overhead of a constantly open transaction can -sometimes be noticeable. For those situations, if you're using the -``postgresql_psycopg2`` backend, you can configure Django to use -*"autocommit"* behavior for the connection, meaning that each database -operation will normally be in its own transaction, rather than having -the transaction extend over multiple operations. In this case, you can -still manually start a transaction if you're doing something that -requires consistency across multiple database operations. The -autocommit behavior is enabled by setting the ``autocommit`` key in -the :setting:`OPTIONS` part of your database configuration in -:setting:`DATABASES`:: - - 'OPTIONS': { - 'autocommit': True, - } - -In this configuration, Django still ensures that :ref:`delete() -<topics-db-queries-delete>` and :ref:`update() <topics-db-queries-update>` -queries run inside a single transaction, so that either all the affected -objects are changed or none of them are. - -.. admonition:: This is database-level autocommit - - This functionality is not the same as the - :ref:`topics-db-transactions-autocommit` decorator. That decorator - is a Django-level implementation that commits automatically after - data changing operations. The feature enabled using the - :setting:`OPTIONS` option provides autocommit behavior at the - database adapter level. It commits after *every* operation. - -If you are using this feature and performing an operation akin to delete or -updating that requires multiple operations, you are strongly recommended to -wrap you operations in manual transaction handling to ensure data consistency. -You should also audit your existing code for any instances of this behavior -before enabling this feature. It's faster, but it provides less automatic -protection for multi-call operations. - -Indexes for ``varchar`` and ``text`` columns -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. versionadded:: 1.1.2 - -When specifying ``db_index=True`` on your model fields, Django typically -outputs a single ``CREATE INDEX`` statement. However, if the database type -for the field is either ``varchar`` or ``text`` (e.g., used by ``CharField``, -``FileField``, and ``TextField``), then Django will create -an additional index that uses an appropriate `PostgreSQL operator class`_ -for the column. The extra index is necessary to correctly perfrom -lookups that use the ``LIKE`` operator in their SQL, as is done with the -``contains`` and ``startswith`` lookup types. - -.. _PostgreSQL operator class: http://www.postgresql.org/docs/8.4/static/indexes-opclass.html - -.. _mysql-notes: - -MySQL notes -=========== - -Django expects the database to support transactions, referential integrity, and -Unicode (UTF-8 encoding). Fortunately, MySQL_ has all these features as -available as far back as 3.23. While it may be possible to use 3.23 or 4.0, -you'll probably have less trouble if you use 4.1 or 5.0. - -MySQL 4.1 ---------- - -`MySQL 4.1`_ has greatly improved support for character sets. It is possible to -set different default character sets on the database, table, and column. -Previous versions have only a server-wide character set setting. It's also the -first version where the character set can be changed on the fly. 4.1 also has -support for views, but Django currently doesn't use views. - -MySQL 5.0 ---------- - -`MySQL 5.0`_ adds the ``information_schema`` database, which contains detailed -data on all database schema. Django's ``inspectdb`` feature uses this -``information_schema`` if it's available. 5.0 also has support for stored -procedures, but Django currently doesn't use stored procedures. - -.. _MySQL: http://www.mysql.com/ -.. _MySQL 4.1: http://dev.mysql.com/doc/refman/4.1/en/index.html -.. _MySQL 5.0: http://dev.mysql.com/doc/refman/5.0/en/index.html - -Storage engines ---------------- - -MySQL has several `storage engines`_ (previously called table types). You can -change the default storage engine in the server configuration. - -The default engine is MyISAM_ [#]_. The main drawback of MyISAM is that it -doesn't currently support transactions or foreign keys. On the plus side, it's -currently the only engine that supports full-text indexing and searching. - -The InnoDB_ engine is fully transactional and supports foreign key references. - -The BDB_ engine, like InnoDB, is also fully transactional and supports foreign -key references. However, its use seems to be deprecated. - -`Other storage engines`_, including SolidDB_ and Falcon_, are on the horizon. -For now, InnoDB is probably your best choice. - -.. _storage engines: http://dev.mysql.com/doc/refman/5.0/en/storage-engines.html -.. _MyISAM: http://dev.mysql.com/doc/refman/5.0/en/myisam-storage-engine.html -.. _BDB: http://dev.mysql.com/doc/refman/5.0/en/bdb-storage-engine.html -.. _InnoDB: http://dev.mysql.com/doc/refman/5.0/en/innodb.html -.. _Other storage engines: http://dev.mysql.com/doc/refman/5.1/en/storage-engines-other.html -.. _SolidDB: http://forge.mysql.com/projects/project.php?id=139 -.. _Falcon: http://dev.mysql.com/doc/falcon/en/index.html - -.. [#] Unless this was changed by the packager of your MySQL package. We've - had reports that the Windows Community Server installer sets up InnoDB as - the default storage engine, for example. - -MySQLdb -------- - -`MySQLdb`_ is the Python interface to MySQL. Version 1.2.1p2 or later is -required for full MySQL support in Django. - -.. note:: - If you see ``ImportError: cannot import name ImmutableSet`` when trying to - use Django, your MySQLdb installation may contain an outdated ``sets.py`` - file that conflicts with the built-in module of the same name from Python - 2.4 and later. To fix this, verify that you have installed MySQLdb version - 1.2.1p2 or newer, then delete the ``sets.py`` file in the MySQLdb - directory that was left by an earlier version. - -.. _MySQLdb: http://sourceforge.net/projects/mysql-python - -Creating your database ----------------------- - -You can `create your database`_ using the command-line tools and this SQL:: - - CREATE DATABASE <dbname> CHARACTER SET utf8; - -This ensures all tables and columns will use UTF-8 by default. - -.. _create your database: http://dev.mysql.com/doc/refman/5.0/en/create-database.html - -.. _mysql-collation: - -Collation settings -~~~~~~~~~~~~~~~~~~ - -The collation setting for a column controls the order in which data is sorted -as well as what strings compare as equal. It can be set on a database-wide -level and also per-table and per-column. This is `documented thoroughly`_ in -the MySQL documentation. In all cases, you set the collation by directly -manipulating the database tables; Django doesn't provide a way to set this on -the model definition. - -.. _documented thoroughly: http://dev.mysql.com/doc/refman/5.0/en/charset.html - -By default, with a UTF-8 database, MySQL will use the -``utf8_general_ci_swedish`` collation. This results in all string equality -comparisons being done in a *case-insensitive* manner. That is, ``"Fred"`` and -``"freD"`` are considered equal at the database level. If you have a unique -constraint on a field, it would be illegal to try to insert both ``"aa"`` and -``"AA"`` into the same column, since they compare as equal (and, hence, -non-unique) with the default collation. - -In many cases, this default will not be a problem. However, if you really want -case-sensitive comparisons on a particular column or table, you would change -the column or table to use the ``utf8_bin`` collation. The main thing to be -aware of in this case is that if you are using MySQLdb 1.2.2, the database -backend in Django will then return bytestrings (instead of unicode strings) for -any character fields it receive from the database. This is a strong variation -from Django's normal practice of *always* returning unicode strings. It is up -to you, the developer, to handle the fact that you will receive bytestrings if -you configure your table(s) to use ``utf8_bin`` collation. Django itself should -mostly work smoothly with such columns (except for the ``contrib.sessions`` -``Session`` and ``contrib.admin`` ``LogEntry`` tables described below), but -your code must be prepared to call ``django.utils.encoding.smart_unicode()`` at -times if it really wants to work with consistent data -- Django will not do -this for you (the database backend layer and the model population layer are -separated internally so the database layer doesn't know it needs to make this -conversion in this one particular case). - -If you're using MySQLdb 1.2.1p2, Django's standard -:class:`~django.db.models.CharField` class will return unicode strings even -with ``utf8_bin`` collation. However, :class:`~django.db.models.TextField` -fields will be returned as an ``array.array`` instance (from Python's standard -``array`` module). There isn't a lot Django can do about that, since, again, -the information needed to make the necessary conversions isn't available when -the data is read in from the database. This problem was `fixed in MySQLdb -1.2.2`_, so if you want to use :class:`~django.db.models.TextField` with -``utf8_bin`` collation, upgrading to version 1.2.2 and then dealing with the -bytestrings (which shouldn't be too difficult) as described above is the -recommended solution. - -Should you decide to use ``utf8_bin`` collation for some of your tables with -MySQLdb 1.2.1p2 or 1.2.2, you should still use ``utf8_collation_ci_swedish`` -(the default) collation for the :class:`django.contrib.sessions.models.Session` -table (usually called ``django_session``) and the -:class:`django.contrib.admin.models.LogEntry` table (usually called -``django_admin_log``). Those are the two standard tables that use -:class:`~django.db.model.TextField` internally. - -.. _fixed in MySQLdb 1.2.2: http://sourceforge.net/tracker/index.php?func=detail&aid=1495765&group_id=22307&atid=374932 - -Connecting to the database --------------------------- - -Refer to the :doc:`settings documentation </ref/settings>`. - -Connection settings are used in this order: - - 1. :setting:`OPTIONS`. - 2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`, - :setting:`HOST`, :setting:`PORT` - 3. MySQL option files. - -In other words, if you set the name of the database in ``OPTIONS``, -this will take precedence over ``NAME``, which would override -anything in a `MySQL option file`_. - -Here's a sample configuration which uses a MySQL option file:: - - # settings.py - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.mysql', - 'OPTIONS': { - 'read_default_file': '/path/to/my.cnf', - }, - } - } - - - # my.cnf - [client] - database = NAME - user = USER - password = PASSWORD - default-character-set = utf8 - -Several other MySQLdb connection options may be useful, such as ``ssl``, -``use_unicode``, ``init_command``, and ``sql_mode``. Consult the -`MySQLdb documentation`_ for more details. - -.. _MySQL option file: http://dev.mysql.com/doc/refman/5.0/en/option-files.html -.. _MySQLdb documentation: http://mysql-python.sourceforge.net/ - -Creating your tables --------------------- - -When Django generates the schema, it doesn't specify a storage engine, so -tables will be created with whatever default storage engine your database -server is configured for. The easiest solution is to set your database server's -default storage engine to the desired engine. - -If you're using a hosting service and can't change your server's default -storage engine, you have a couple of options. - - * After the tables are created, execute an ``ALTER TABLE`` statement to - convert a table to a new storage engine (such as InnoDB):: - - ALTER TABLE <tablename> ENGINE=INNODB; - - This can be tedious if you have a lot of tables. - - * Another option is to use the ``init_command`` option for MySQLdb prior to - creating your tables:: - - 'OPTIONS': { - 'init_command': 'SET storage_engine=INNODB', - } - - This sets the default storage engine upon connecting to the database. - After your tables have been created, you should remove this option. - - * Another method for changing the storage engine is described in - AlterModelOnSyncDB_. - -.. _AlterModelOnSyncDB: http://code.djangoproject.com/wiki/AlterModelOnSyncDB - -Notes on specific fields ------------------------- - -Boolean fields -~~~~~~~~~~~~~~ - -.. versionchanged:: 1.2 - -In previous versions of Django when running under MySQL ``BooleanFields`` would -return their data as ``ints``, instead of true ``bools``. See the release -notes for a complete description of the change. - -Character fields -~~~~~~~~~~~~~~~~ - -Any fields that are stored with ``VARCHAR`` column types have their -``max_length`` restricted to 255 characters if you are using ``unique=True`` -for the field. This affects :class:`~django.db.models.CharField`, -:class:`~django.db.models.SlugField` and -:class:`~django.db.models.CommaSeparatedIntegerField`. - -Furthermore, if you are using a version of MySQL prior to 5.0.3, all of those -column types have a maximum length restriction of 255 characters, regardless -of whether ``unique=True`` is specified or not. - -.. _sqlite-notes: - -SQLite notes -============ - -SQLite_ provides an excellent development alternative for applications that -are predominantly read-only or require a smaller installation footprint. As -with all database servers, though, there are some differences that are -specific to SQLite that you should be aware of. - -.. _SQLite: http://www.sqlite.org/ - -.. _sqlite-string-matching: - -String matching for non-ASCII strings --------------------------------------- - -SQLite doesn't support case-insensitive matching for non-ASCII strings. Some -possible workarounds for this are `documented at sqlite.org`_, but they are -not utilised by the default SQLite backend in Django. Therefore, if you are -using the ``iexact`` lookup type in your queryset filters, be aware that it -will not work as expected for non-ASCII strings. - -.. _documented at sqlite.org: http://www.sqlite.org/faq.html#q18 - -SQLite 3.3.6 or newer strongly recommended ------------------------------------------- - -Versions of SQLite 3.3.5 and older contains the following bugs: - - * A bug when `handling`_ ``ORDER BY`` parameters. This can cause problems when - you use the ``select`` parameter for the ``extra()`` QuerySet method. The bug - can be identified by the error message ``OperationalError: ORDER BY terms - must not be non-integer constants``. - - * A bug when handling `aggregation`_ together with DateFields and - DecimalFields. - -.. _handling: http://www.sqlite.org/cvstrac/tktview?tn=1768 -.. _aggregation: http://code.djangoproject.com/ticket/10031 - -SQLite 3.3.6 was released in April 2006, so most current binary distributions -for different platforms include newer version of SQLite usable from Python -through either the ``pysqlite2`` or the ``sqlite3`` modules. - -However, some platform/Python version combinations include older versions of -SQLite (e.g. the official binary distribution of Python 2.5 for Windows, 2.5.4 -as of this writing, includes SQLite 3.3.4). There are (as of Django 1.1) even -some tests in the Django test suite that will fail when run under this setup. - -As described :ref:`below<using-newer-versions-of-pysqlite>`, this can be solved -by downloading and installing a newer version of ``pysqlite2`` -(``pysqlite-2.x.x.win32-py2.5.exe`` in the described case) that includes and -uses a newer version of SQLite. Python 2.6 for Windows ships with a version of -SQLite that is not affected by these issues. - -Version 3.5.9 -------------- - -The Ubuntu "Intrepid Ibex" (8.10) SQLite 3.5.9-3 package contains a bug that -causes problems with the evaluation of query expressions. If you are using -Ubuntu "Intrepid Ibex", you will need to update the package to version -3.5.9-3ubuntu1 or newer (recommended) or find an alternate source for SQLite -packages, or install SQLite from source. - -At one time, Debian Lenny shipped with the same malfunctioning SQLite 3.5.9-3 -package. However the Debian project has subsequently issued updated versions -of the SQLite package that correct these bugs. If you find you are getting -unexpected results under Debian, ensure you have updated your SQLite package -to 3.5.9-5 or later. - -The problem does not appear to exist with other versions of SQLite packaged -with other operating systems. - -Version 3.6.2 --------------- - -SQLite version 3.6.2 (released August 30, 2008) introduced a bug into ``SELECT -DISTINCT`` handling that is triggered by, amongst other things, Django's -``DateQuerySet`` (returned by the ``dates()`` method on a queryset). - -You should avoid using this version of SQLite with Django. Either upgrade to -3.6.3 (released September 22, 2008) or later, or downgrade to an earlier -version of SQLite. - -.. _using-newer-versions-of-pysqlite: - -Using newer versions of the SQLite DB-API 2.0 driver ----------------------------------------------------- - -.. versionadded:: 1.1 - -For versions of Python 2.5 or newer that include ``sqlite3`` in the standard -library Django will now use a ``pysqlite2`` interface in preference to -``sqlite3`` if it finds one is available. - -This provides the ability to upgrade both the DB-API 2.0 interface or SQLite 3 -itself to versions newer than the ones included with your particular Python -binary distribution, if needed. - -"Database is locked" errors ------------------------------------------------ - -SQLite is meant to be a lightweight database, and thus can't support a high -level of concurrency. ``OperationalError: database is locked`` errors indicate -that your application is experiencing more concurrency than ``sqlite`` can -handle in default configuration. This error means that one thread or process has -an exclusive lock on the database connection and another thread timed out -waiting for the lock the be released. - -Python's SQLite wrapper has -a default timeout value that determines how long the second thread is allowed to -wait on the lock before it times out and raises the ``OperationalError: database -is locked`` error. - -If you're getting this error, you can solve it by: - - * Switching to another database backend. At a certain point SQLite becomes - too "lite" for real-world applications, and these sorts of concurrency - errors indicate you've reached that point. - - * Rewriting your code to reduce concurrency and ensure that database - transactions are short-lived. - - * Increase the default timeout value by setting the ``timeout`` database - option option:: - - 'OPTIONS': { - # ... - 'timeout': 20, - # ... - } - - This will simply make SQLite wait a bit longer before throwing "database - is locked" errors; it won't really do anything to solve them. - -.. _oracle-notes: - -Oracle notes -============ - -Django supports `Oracle Database Server`_ versions 9i and -higher. Oracle version 10g or later is required to use Django's -``regex`` and ``iregex`` query operators. You will also need at least -version 4.3.1 of the `cx_Oracle`_ Python driver. - -Note that due to a Unicode-corruption bug in ``cx_Oracle`` 5.0, that -version of the driver should **not** be used with Django; -``cx_Oracle`` 5.0.1 resolved this issue, so if you'd like to use a -more recent ``cx_Oracle``, use version 5.0.1. - -``cx_Oracle`` 5.0.1 or greater can optionally be compiled with the -``WITH_UNICODE`` environment variable. This is recommended but not -required. - -.. _`Oracle Database Server`: http://www.oracle.com/ -.. _`cx_Oracle`: http://cx-oracle.sourceforge.net/ - -In order for the ``python manage.py syncdb`` command to work, your Oracle -database user must have privileges to run the following commands: - - * CREATE TABLE - * CREATE SEQUENCE - * CREATE PROCEDURE - * CREATE TRIGGER - -To run Django's test suite, the user needs these *additional* privileges: - - * CREATE USER - * DROP USER - * CREATE TABLESPACE - * DROP TABLESPACE - * CONNECT WITH ADMIN OPTION - * RESOURCE WITH ADMIN OPTION - -Connecting to the database --------------------------- - -Your Django settings.py file should look something like this for Oracle:: - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.oracle', - 'NAME': 'xe', - 'USER': 'a_user', - 'PASSWORD': 'a_password', - 'HOST': '', - 'PORT': '', - } - } - - -If you don't use a ``tnsnames.ora`` file or a similar naming method that -recognizes the SID ("xe" in this example), then fill in both -``HOST`` and ``PORT`` like so:: - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.oracle', - 'NAME': 'xe', - 'USER': 'a_user', - 'PASSWORD': 'a_password', - 'HOST': 'dbprod01ned.mycompany.com', - 'PORT': '1540', - } - } - -You should supply both ``HOST`` and ``PORT``, or leave both -as empty strings. - -Threaded option ----------------- - -If you plan to run Django in a multithreaded environment (e.g. Apache in Windows -using the default MPM module), then you **must** set the ``threaded`` option of -your Oracle database configuration to True:: - - 'OPTIONS': { - 'threaded': True, - }, - -Failure to do this may result in crashes and other odd behavior. - -Tablespace options ------------------- - -A common paradigm for optimizing performance in Oracle-based systems is the -use of `tablespaces`_ to organize disk layout. The Oracle backend supports -this use case by adding ``db_tablespace`` options to the ``Meta`` and -``Field`` classes. (When you use a backend that lacks support for tablespaces, -Django ignores these options.) - -.. _`tablespaces`: http://en.wikipedia.org/wiki/Tablespace - -A tablespace can be specified for the table(s) generated by a model by -supplying the ``db_tablespace`` option inside the model's ``class Meta``. -Additionally, you can pass the ``db_tablespace`` option to a ``Field`` -constructor to specify an alternate tablespace for the ``Field``'s column -index. If no index would be created for the column, the ``db_tablespace`` -option is ignored:: - - class TablespaceExample(models.Model): - name = models.CharField(max_length=30, db_index=True, db_tablespace="indexes") - data = models.CharField(max_length=255, db_index=True) - edges = models.ManyToManyField(to="self", db_tablespace="indexes") - - class Meta: - db_tablespace = "tables" - -In this example, the tables generated by the ``TablespaceExample`` model -(i.e., the model table and the many-to-many table) would be stored in the -``tables`` tablespace. The index for the name field and the indexes on the -many-to-many table would be stored in the ``indexes`` tablespace. The ``data`` -field would also generate an index, but no tablespace for it is specified, so -it would be stored in the model tablespace ``tables`` by default. - -.. versionadded:: 1.0 - -Use the :setting:`DEFAULT_TABLESPACE` and :setting:`DEFAULT_INDEX_TABLESPACE` -settings to specify default values for the db_tablespace options. -These are useful for setting a tablespace for the built-in Django apps and -other applications whose code you cannot control. - -Django does not create the tablespaces for you. Please refer to `Oracle's -documentation`_ for details on creating and managing tablespaces. - -.. _`Oracle's documentation`: http://download.oracle.com/docs/cd/B19306_01/server.102/b14200/statements_7003.htm#SQLRF01403 - -Naming issues -------------- - -Oracle imposes a name length limit of 30 characters. To accommodate this, the -backend truncates database identifiers to fit, replacing the final four -characters of the truncated name with a repeatable MD5 hash value. - -When running syncdb, an ``ORA-06552`` error may be encountered if -certain Oracle keywords are used as the name of a model field or the -value of a ``db_column`` option. Django quotes all identifiers used -in queries to prevent most such problems, but this error can still -occur when an Oracle datatype is used as a column name. In -particular, take care to avoid using the names ``date``, -``timestamp``, ``number`` or ``float`` as a field name. - -NULL and empty strings ----------------------- - -Django generally prefers to use the empty string ('') rather than -NULL, but Oracle treats both identically. To get around this, the -Oracle backend coerces the ``null=True`` option on fields that have -the empty string as a possible value. When fetching from the database, -it is assumed that a NULL value in one of these fields really means -the empty string, and the data is silently converted to reflect this -assumption. - -``TextField`` limitations -------------------------- - -The Oracle backend stores ``TextFields`` as ``NCLOB`` columns. Oracle imposes -some limitations on the usage of such LOB columns in general: - - * LOB columns may not be used as primary keys. - - * LOB columns may not be used in indexes. - - * LOB columns may not be used in a ``SELECT DISTINCT`` list. This means that - attempting to use the ``QuerySet.distinct`` method on a model that - includes ``TextField`` columns will result in an error when run against - Oracle. As a workaround, use the ``QuerySet.defer`` method in conjunction - with ``distinct()`` to prevent ``TextField`` columns from being included in - the ``SELECT DISTINCT`` list. - -.. _third-party-notes: - -Using a 3rd-party database backend -================================== - -In addition to the officially supported databases, there are backends provided -by 3rd parties that allow you to use other databases with Django: - -* `Sybase SQL Anywhere`_ -* `IBM DB2`_ -* `Microsoft SQL Server 2005`_ -* Firebird_ -* ODBC_ - -The Django versions and ORM features supported by these unofficial backends -vary considerably. Queries regarding the specific capabilities of these -unofficial backends, along with any support queries, should be directed to -the support channels provided by each 3rd party project. - -.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/ -.. _IBM DB2: http://code.google.com/p/ibm-db/ -.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/ -.. _Firebird: http://code.google.com/p/django-firebird/ -.. _ODBC: http://code.google.com/p/django-pyodbc/ diff --git a/parts/django/docs/ref/django-admin.txt b/parts/django/docs/ref/django-admin.txt deleted file mode 100644 index 70faa3c..0000000 --- a/parts/django/docs/ref/django-admin.txt +++ /dev/null @@ -1,1293 +0,0 @@ -============================= -django-admin.py and manage.py -============================= - -``django-admin.py`` is Django's command-line utility for administrative tasks. -This document outlines all it can do. - -In addition, ``manage.py`` is automatically created in each Django project. -``manage.py`` is a thin wrapper around ``django-admin.py`` that takes care of -two things for you before delegating to ``django-admin.py``: - - * It puts your project's package on ``sys.path``. - - * It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that - it points to your project's ``settings.py`` file. - -The ``django-admin.py`` script should be on your system path if you installed -Django via its ``setup.py`` utility. If it's not on your path, you can find it -in ``site-packages/django/bin`` within your Python installation. Consider -symlinking it from some place on your path, such as ``/usr/local/bin``. - -For Windows users, who do not have symlinking functionality available, you can -copy ``django-admin.py`` to a location on your existing path or edit the -``PATH`` settings (under ``Settings - Control Panel - System - Advanced - -Environment...``) to point to its installed location. - -Generally, when working on a single Django project, it's easier to use -``manage.py``. Use ``django-admin.py`` with ``DJANGO_SETTINGS_MODULE``, or the -``--settings`` command line option, if you need to switch between multiple -Django settings files. - -The command-line examples throughout this document use ``django-admin.py`` to -be consistent, but any example can use ``manage.py`` just as well. - -Usage -===== - -.. code-block:: bash - - django-admin.py <command> [options] - manage.py <command> [options] - -``command`` should be one of the commands listed in this document. -``options``, which is optional, should be zero or more of the options available -for the given command. - -Getting runtime help --------------------- - -.. django-admin-option:: --help - -Run ``django-admin.py help`` to display a list of all available commands. -Run ``django-admin.py help <command>`` to display a description of the -given command and a list of its available options. - -App names ---------- - -Many commands take a list of "app names." An "app name" is the basename of -the package containing your models. For example, if your ``INSTALLED_APPS`` -contains the string ``'mysite.blog'``, the app name is ``blog``. - -Determining the version ------------------------ - -.. django-admin-option:: --version - -Run ``django-admin.py --version`` to display the current Django version. - -Examples of output:: - - 0.95 - 0.96 - 0.97-pre-SVN-6069 - -Displaying debug output ------------------------ - -Use :djadminopt:`--verbosity` to specify the amount of notification and debug information -that ``django-admin.py`` should print to the console. For more details, see the -documentation for the :djadminopt:`--verbosity` option. - -Available commands -================== - -cleanup -------- - -.. django-admin:: cleanup - -.. versionadded:: 1.0 - -Can be run as a cronjob or directly to clean out old data from the database -(only expired sessions at the moment). - -compilemessages ---------------- - -.. django-admin:: compilemessages - -.. versionchanged:: 1.0 - Before 1.0 this was the "bin/compile-messages.py" command. - -Compiles .po files created with ``makemessages`` to .mo files for use with -the builtin gettext support. See :doc:`/topics/i18n/index`. - -Use the :djadminopt:`--locale` option to specify the locale to process. -If not provided, all locales are processed. - -Example usage:: - - django-admin.py compilemessages --locale=br_PT - -createcachetable ----------------- - -.. django-admin:: createcachetable - -Creates a cache table named ``tablename`` for use with the database cache -backend. See :doc:`/topics/cache` for more information. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database -onto which the cachetable will be installed. - -dbshell -------- - -.. django-admin:: dbshell - -Runs the command-line client for the database engine specified in your -``ENGINE`` setting, with the connection parameters specified in your -``USER``, ``PASSWORD``, etc., settings. - - * For PostgreSQL, this runs the ``psql`` command-line client. - * For MySQL, this runs the ``mysql`` command-line client. - * For SQLite, this runs the ``sqlite3`` command-line client. - -This command assumes the programs are on your ``PATH`` so that a simple call to -the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in -the right place. There's no way to specify the location of the program -manually. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database -onto which to open a shell. - -diffsettings ------------- - -.. django-admin:: diffsettings - -Displays differences between the current settings file and Django's default -settings. - -Settings that don't appear in the defaults are followed by ``"###"``. For -example, the default settings don't define ``ROOT_URLCONF``, so -``ROOT_URLCONF`` is followed by ``"###"`` in the output of ``diffsettings``. - -Note that Django's default settings live in ``django/conf/global_settings.py``, -if you're ever curious to see the full list of defaults. - -dumpdata <appname appname appname.Model ...> --------------------------------------------- - -.. django-admin:: dumpdata - -Outputs to standard output all data in the database associated with the named -application(s). - -If no application name is provided, all installed applications will be dumped. - -The output of ``dumpdata`` can be used as input for ``loaddata``. - -Note that ``dumpdata`` uses the default manager on the model for selecting the -records to dump. If you're using a :ref:`custom manager <custom-managers>` as -the default manager and it filters some of the available records, not all of the -objects will be dumped. - -.. django-admin-option:: --format <fmt> - -By default, ``dumpdata`` will format its output in JSON, but you can use the -``--format`` option to specify another format. Currently supported formats -are listed in :ref:`serialization-formats`. - -.. django-admin-option:: --indent <num> - -By default, ``dumpdata`` will output all data on a single line. This isn't -easy for humans to read, so you can use the ``--indent`` option to -pretty-print the output with a number of indentation spaces. - -.. versionadded:: 1.0 - -The :djadminopt:`--exclude` option may be provided to prevent specific -applications from being dumped. - -.. versionadded:: 1.1 - -In addition to specifying application names, you can provide a list of -individual models, in the form of ``appname.Model``. If you specify a model -name to ``dumpdata``, the dumped output will be restricted to that model, -rather than the entire application. You can also mix application names and -model names. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database -onto which the data will be loaded. - -.. django-admin-option:: --natural - -.. versionadded:: 1.2 - -Use :ref:`natural keys <topics-serialization-natural-keys>` to represent -any foreign key and many-to-many relationship with a model that provides -a natural key definition. If you are dumping ``contrib.auth`` ``Permission`` -objects or ``contrib.contenttypes`` ``ContentType`` objects, you should -probably be using this flag. - -flush ------ - -.. django-admin:: flush - -Returns the database to the state it was in immediately after syncdb was -executed. This means that all data will be removed from the database, any -post-synchronization handlers will be re-executed, and the ``initial_data`` -fixture will be re-installed. - -The :djadminopt:`--noinput` option may be provided to suppress all user -prompts. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option may be used to specify the database -to flush. - - -inspectdb ---------- - -.. django-admin:: inspectdb - -Introspects the database tables in the database pointed-to by the -``NAME`` setting and outputs a Django model module (a ``models.py`` -file) to standard output. - -Use this if you have a legacy database with which you'd like to use Django. -The script will inspect the database and create a model for each table within -it. - -As you might expect, the created models will have an attribute for every field -in the table. Note that ``inspectdb`` has a few special cases in its field-name -output: - - * If ``inspectdb`` cannot map a column's type to a model field type, it'll - use ``TextField`` and will insert the Python comment - ``'This field type is a guess.'`` next to the field in the generated - model. - - * If the database column name is a Python reserved word (such as - ``'pass'``, ``'class'`` or ``'for'``), ``inspectdb`` will append - ``'_field'`` to the attribute name. For example, if a table has a column - ``'for'``, the generated model will have a field ``'for_field'``, with - the ``db_column`` attribute set to ``'for'``. ``inspectdb`` will insert - the Python comment - ``'Field renamed because it was a Python reserved word.'`` next to the - field. - -This feature is meant as a shortcut, not as definitive model generation. After -you run it, you'll want to look over the generated models yourself to make -customizations. In particular, you'll need to rearrange models' order, so that -models that refer to other models are ordered properly. - -Primary keys are automatically introspected for PostgreSQL, MySQL and -SQLite, in which case Django puts in the ``primary_key=True`` where -needed. - -``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection -only works in PostgreSQL and with certain types of MySQL tables. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option may be used to specify the -database to introspect. - -loaddata <fixture fixture ...> ------------------------------- - -.. django-admin:: loaddata - -Searches for and loads the contents of the named fixture into the database. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database -onto which the data will be loaded. - -What's a "fixture"? -~~~~~~~~~~~~~~~~~~~ - -A *fixture* is a collection of files that contain the serialized contents of -the database. Each fixture has a unique name, and the files that comprise the -fixture can be distributed over multiple directories, in multiple applications. - -Django will search in three locations for fixtures: - - 1. In the ``fixtures`` directory of every installed application - 2. In any directory named in the ``FIXTURE_DIRS`` setting - 3. In the literal path named by the fixture - -Django will load any and all fixtures it finds in these locations that match -the provided fixture names. - -If the named fixture has a file extension, only fixtures of that type -will be loaded. For example:: - - django-admin.py loaddata mydata.json - -would only load JSON fixtures called ``mydata``. The fixture extension -must correspond to the registered name of a -:ref:`serializer <serialization-formats>` (e.g., ``json`` or ``xml``). - -If you omit the extensions, Django will search all available fixture types -for a matching fixture. For example:: - - django-admin.py loaddata mydata - -would look for any fixture of any fixture type called ``mydata``. If a fixture -directory contained ``mydata.json``, that fixture would be loaded -as a JSON fixture. - -The fixtures that are named can include directory components. These -directories will be included in the search path. For example:: - - django-admin.py loaddata foo/bar/mydata.json - -would search ``<appname>/fixtures/foo/bar/mydata.json`` for each installed -application, ``<dirname>/foo/bar/mydata.json`` for each directory in -``FIXTURE_DIRS``, and the literal path ``foo/bar/mydata.json``. - -When fixture files are processed, the data is saved to the database as is. -Model defined ``save`` methods and ``pre_save`` signals are not called. - -Note that the order in which fixture files are processed is undefined. However, -all fixture data is installed as a single transaction, so data in -one fixture can reference data in another fixture. If the database backend -supports row-level constraints, these constraints will be checked at the -end of the transaction. - -The ``dumpdata`` command can be used to generate input for ``loaddata``. - -Compressed fixtures -~~~~~~~~~~~~~~~~~~~ - -Fixtures may be compressed in ``zip``, ``gz``, or ``bz2`` format. For example:: - - django-admin.py loaddata mydata.json - -would look for any of ``mydata.json``, ``mydata.json.zip``, -``mydata.json.gz``, or ``mydata.json.bz2``. The first file contained within a -zip-compressed archive is used. - -Note that if two fixtures with the same name but different -fixture type are discovered (for example, if ``mydata.json`` and -``mydata.xml.gz`` were found in the same fixture directory), fixture -installation will be aborted, and any data installed in the call to -``loaddata`` will be removed from the database. - -.. admonition:: MySQL and Fixtures - - Unfortunately, MySQL isn't capable of completely supporting all the - features of Django fixtures. If you use MyISAM tables, MySQL doesn't - support transactions or constraints, so you won't get a rollback if - multiple transaction files are found, or validation of fixture data. - If you use InnoDB tables, you won't be able to have any forward - references in your data files - MySQL doesn't provide a mechanism to - defer checking of row constraints until a transaction is committed. - -Database-specific fixtures -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you are in a multi-database setup, you may have fixture data that -you want to load onto one database, but not onto another. In this -situation, you can add database identifier into . If your -:setting:`DATABASES` setting has a 'master' database defined, you can -define the fixture ``mydata.master.json`` or -``mydata.master.json.gz``. This fixture will only be loaded if you -have specified that you want to load data onto the ``master`` -database. - -makemessages ------------- - -.. django-admin:: makemessages - -.. versionchanged:: 1.0 - Before 1.0 this was the ``bin/make-messages.py`` command. - -Runs over the entire source tree of the current directory and pulls out all -strings marked for translation. It creates (or updates) a message file in the -conf/locale (in the django tree) or locale (for project and application) -directory. After making changes to the messages files you need to compile them -with ``compilemessages`` for use with the builtin gettext support. See the -:ref:`i18n documentation <how-to-create-language-files>` for details. - -.. django-admin-option:: --all - -Use the ``--all`` or ``-a`` option to update the message files for all -available languages. - -Example usage:: - - django-admin.py makemessages --all - -.. django-admin-option:: --extension - -Use the ``--extension`` or ``-e`` option to specify a list of file extensions -to examine (default: ".html"). - -Example usage:: - - django-admin.py makemessages --locale=de --extension xhtml - -Separate multiple extensions with commas or use -e or --extension multiple times:: - - django-admin.py makemessages --locale=de --extension=html,txt --extension xml - -Use the :djadminopt:`--locale` option to specify the locale to process. - -Example usage:: - - django-admin.py makemessages --locale=br_PT - -.. django-admin-option:: --domain - -Use the ``--domain`` or ``-d`` option to change the domain of the messages files. -Currently supported: - - * ``django`` for all ``*.py`` and ``*.html`` files (default) - * ``djangojs`` for ``*.js`` files - -.. django-admin-option:: --symlinks - -.. versionadded:: 1.2 - -Use the ``--symlinks`` or ``-s`` option to follow symlinks to directories when -looking for new translation strings. - -Example usage:: - - django-admin.py makemessages --locale=de --symlinks - -.. django-admin-option:: --ignore - -Use the ``--ignore`` or ``-i`` option to ignore files or directories matching -the given `glob-style pattern`_. Use multiple times to ignore more. - -These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'`` - -Example usage:: - - django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html - -.. _`glob-style pattern`: http://docs.python.org/library/glob.html - -.. django-admin-option:: --no-default-ignore - -Use the ``--no-default-ignore`` option to disable the default values of -:djadminopt:`--ignore`. - -reset <appname appname ...> ---------------------------- - -.. django-admin:: reset - -Executes the equivalent of ``sqlreset`` for the given app name(s). - -The :djadminopt:`--noinput` option may be provided to suppress all user -prompts. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the alias -of the database to reset. - -runfcgi [options] ------------------ - -.. django-admin:: runfcgi - -Starts a set of FastCGI processes suitable for use with any Web server that -supports the FastCGI protocol. See the :doc:`FastCGI deployment documentation -</howto/deployment/fastcgi>` for details. Requires the Python FastCGI module from -`flup`_. - -.. _flup: http://www.saddi.com/software/flup/ - -The options accepted by this command are passed to the FastCGI library and -don't use the ``'--'`` prefix as is usual for other Django management commands. - -.. django-admin-option:: protocol - -``protocol=PROTOCOL`` - -Protocol to use. *PROTOCOL* can be ``fcgi``, ``scgi``, ``ajp``, etc. -(default is ``fcgi``) - -.. django-admin-option:: host - -``host=HOSTNAME`` - -Hostname to listen on. - -.. django-admin-option:: port - -``port=PORTNUM`` - -Port to listen on. - -.. django-admin-option:: socket - -``socket=FILE`` - -UNIX socket to listen on. - -.. django-admin-option:: method - -``method=IMPL`` - -Possible values: ``prefork`` or ``threaded`` (default ``prefork``) - -.. django-admin-option:: maxrequests - -``maxrequests=NUMBER`` - -Number of requests a child handles before it is killed and a new child is -forked (0 means no limit). - -.. django-admin-option:: maxspare - -``maxspare=NUMBER`` - -Max number of spare processes / threads. - -.. django-admin-option:: minspare - -``minspare=NUMBER`` - -Min number of spare processes / threads. - -.. django-admin-option:: maxchildren - -``maxchildren=NUMBER`` - -Hard limit number of processes / threads. - -.. django-admin-option:: daemonize - -``daemonize=BOOL`` - -Whether to detach from terminal. - -.. django-admin-option:: pidfile - -``pidfile=FILE`` - -Write the spawned process-id to file *FILE*. - -.. django-admin-option:: workdir - -``workdir=DIRECTORY`` - -Change to directory *DIRECTORY* when daemonizing. - -.. django-admin-option:: debug - -``debug=BOOL`` - -Set to true to enable flup tracebacks. - -.. django-admin-option:: outlog - -``outlog=FILE`` - -Write stdout to the *FILE* file. - -.. django-admin-option:: errlog - -``errlog=FILE`` - -Write stderr to the *FILE* file. - -.. django-admin-option:: umask - -``umask=UMASK`` - -Umask to use when daemonizing. The value is interpeted as an octal number -(default value is ``022``). - -Example usage:: - - django-admin.py runfcgi socket=/tmp/fcgi.sock method=prefork daemonize=true \ - pidfile=/var/run/django-fcgi.pid - -Run a FastCGI server as a daemon and write the spawned PID in a file. - -runserver [port or ipaddr:port] -------------------------------- - -.. django-admin:: runserver - -Starts a lightweight development Web server on the local machine. By default, -the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an -IP address and port number explicitly. - -If you run this script as a user with normal privileges (recommended), you -might not have access to start a port on a low port number. Low port numbers -are reserved for the superuser (root). - -DO NOT USE THIS SERVER IN A PRODUCTION SETTING. It has not gone through -security audits or performance tests. (And that's how it's gonna stay. We're in -the business of making Web frameworks, not Web servers, so improving this -server to be able to handle a production environment is outside the scope of -Django.) - -The development server automatically reloads Python code for each request, as -needed. You don't need to restart the server for code changes to take effect. - -When you start the server, and each time you change Python code while the -server is running, the server will validate all of your installed models. (See -the ``validate`` command below.) If the validator finds errors, it will print -them to standard output, but it won't stop the server. - -You can run as many servers as you want, as long as they're on separate ports. -Just execute ``django-admin.py runserver`` more than once. - -Note that the default IP address, 127.0.0.1, is not accessible from other -machines on your network. To make your development server viewable to other -machines on the network, use its own IP address (e.g. ``192.168.2.1``) or -``0.0.0.0``. - -.. django-admin-option:: --adminmedia - -Use the ``--adminmedia`` option to tell Django where to find the various CSS -and JavaScript files for the Django admin interface. Normally, the development -server serves these files out of the Django source tree magically, but you'd -want to use this if you made any changes to those files for your own site. - -Example usage:: - - django-admin.py runserver --adminmedia=/tmp/new-admin-style/ - -.. django-admin-option:: --noreload - -Use the ``--noreload`` option to disable the use of the auto-reloader. This -means any Python code changes you make while the server is running will *not* -take effect if the particular Python modules have already been loaded into -memory. - -Example usage:: - - django-admin.py runserver --noreload - -Examples of using different ports and addresses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Port 8000 on IP address 127.0.0.1:: - - django-admin.py runserver - -Port 8000 on IP address 1.2.3.4:: - - django-admin.py runserver 1.2.3.4:8000 - -Port 7000 on IP address 127.0.0.1:: - - django-admin.py runserver 7000 - -Port 7000 on IP address 1.2.3.4:: - - django-admin.py runserver 1.2.3.4:7000 - -Serving static files with the development server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the development server doesn't serve any static files for your site -(such as CSS files, images, things under ``MEDIA_URL`` and so forth). If -you want to configure Django to serve static media, read :doc:`/howto/static-files`. - -shell ------ - -.. django-admin:: shell - -Starts the Python interactive interpreter. - -Django will use IPython_, if it's installed. If you have IPython installed and -want to force use of the "plain" Python interpreter, use the ``--plain`` -option, like so:: - - django-admin.py shell --plain - -.. _IPython: http://ipython.scipy.org/ - -sql <appname appname ...> -------------------------- - -.. django-admin:: sql - -Prints the CREATE TABLE SQL statements for the given app name(s). - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlall <appname appname ...> ----------------------------- - -.. django-admin:: sqlall - -Prints the CREATE TABLE and initial-data SQL statements for the given app name(s). - -Refer to the description of ``sqlcustom`` for an explanation of how to -specify initial data. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlclear <appname appname ...> ------------------------------- - -.. django-admin:: sqlclear - -Prints the DROP TABLE SQL statements for the given app name(s). - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlcustom <appname appname ...> -------------------------------- - -.. django-admin:: sqlcustom - -Prints the custom SQL statements for the given app name(s). - -For each model in each specified app, this command looks for the file -``<appname>/sql/<modelname>.sql``, where ``<appname>`` is the given app name and -``<modelname>`` is the model's name in lowercase. For example, if you have an -app ``news`` that includes a ``Story`` model, ``sqlcustom`` will attempt -to read a file ``news/sql/story.sql`` and append it to the output of this -command. - -Each of the SQL files, if given, is expected to contain valid SQL. The SQL -files are piped directly into the database after all of the models' -table-creation statements have been executed. Use this SQL hook to make any -table modifications, or insert any SQL functions into the database. - -Note that the order in which the SQL files are processed is undefined. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlflush --------- - -.. django-admin:: sqlflush - -Prints the SQL statements that would be executed for the :djadmin:`flush` -command. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlindexes <appname appname ...> --------------------------------- - -.. django-admin:: sqlindexes - -Prints the CREATE INDEX SQL statements for the given app name(s). - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlreset <appname appname ...> ------------------------------- - -.. django-admin:: sqlreset - -Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s). - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -sqlsequencereset <appname appname ...> --------------------------------------- - -.. django-admin:: sqlsequencereset - -Prints the SQL statements for resetting sequences for the given app name(s). - -Sequences are indexes used by some database engines to track the next available -number for automatically incremented fields. - -Use this command to generate SQL which will fix cases where a sequence is out -of sync with its automatically incremented field data. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database for -which to print the SQL. - -startapp <appname> ------------------- - -.. django-admin:: startapp - -Creates a Django app directory structure for the given app name in the current -directory. - -startproject <projectname> --------------------------- - -.. django-admin:: startproject - -Creates a Django project directory structure for the given project name in the -current directory. - -This command is disabled when the ``--settings`` option to -``django-admin.py`` is used, or when the environment variable -``DJANGO_SETTINGS_MODULE`` has been set. To re-enable it in these -situations, either omit the ``--settings`` option or unset -``DJANGO_SETTINGS_MODULE``. - -syncdb ------- - -.. django-admin:: syncdb - -Creates the database tables for all apps in ``INSTALLED_APPS`` whose tables -have not already been created. - -Use this command when you've added new applications to your project and want to -install them in the database. This includes any apps shipped with Django that -might be in ``INSTALLED_APPS`` by default. When you start a new project, run -this command to install the default apps. - -.. admonition:: Syncdb will not alter existing tables - - ``syncdb`` will only create tables for models which have not yet been - installed. It will *never* issue ``ALTER TABLE`` statements to match - changes made to a model class after installation. Changes to model classes - and database schemas often involve some form of ambiguity and, in those - cases, Django would have to guess at the correct changes to make. There is - a risk that critical data would be lost in the process. - - If you have made changes to a model and wish to alter the database tables - to match, use the ``sql`` command to display the new SQL structure and - compare that to your existing table schema to work out the changes. - -If you're installing the ``django.contrib.auth`` application, ``syncdb`` will -give you the option of creating a superuser immediately. - -``syncdb`` will also search for and install any fixture named ``initial_data`` -with an appropriate extension (e.g. ``json`` or ``xml``). See the -documentation for ``loaddata`` for details on the specification of fixture -data files. - ---noinput -~~~~~~~~~ -The :djadminopt:`--noinput` option may be provided to suppress all user -prompts. - -.. versionadded:: 1.2 - -The :djadminopt:`--database` option can be used to specify the database to -synchronize. - -test <app or test identifier> ------------------------------ - -.. django-admin:: test - -Runs tests for all installed models. See :doc:`/topics/testing` for more -information. - -.. versionadded:: 1.2 -.. django-admin-option:: --failfast - -Use the :djadminopt:`--failfast` option to stop running tests and report the failure -immediately after a test fails. - -testserver <fixture fixture ...> --------------------------------- - -.. django-admin:: testserver - -.. versionadded:: 1.0 - -Runs a Django development server (as in ``runserver``) using data from the -given fixture(s). - -For example, this command:: - - django-admin.py testserver mydata.json - -...would perform the following steps: - - 1. Create a test database, as described in :doc:`/topics/testing`. - 2. Populate the test database with fixture data from the given fixtures. - (For more on fixtures, see the documentation for ``loaddata`` above.) - 3. Runs the Django development server (as in ``runserver``), pointed at - this newly created test database instead of your production database. - -This is useful in a number of ways: - - * When you're writing :doc:`unit tests </topics/testing>` of how your views - act with certain fixture data, you can use ``testserver`` to interact with - the views in a Web browser, manually. - - * Let's say you're developing your Django application and have a "pristine" - copy of a database that you'd like to interact with. You can dump your - database to a fixture (using the ``dumpdata`` command, explained above), - then use ``testserver`` to run your Web application with that data. With - this arrangement, you have the flexibility of messing up your data - in any way, knowing that whatever data changes you're making are only - being made to a test database. - -Note that this server does *not* automatically detect changes to your Python -source code (as ``runserver`` does). It does, however, detect changes to -templates. - -.. django-admin-option:: --addrport [port number or ipaddr:port] - -Use ``--addrport`` to specify a different port, or IP address and port, from -the default of 127.0.0.1:8000. This value follows exactly the same format and -serves exactly the same function as the argument to the ``runserver`` command. - -Examples: - -To run the test server on port 7000 with ``fixture1`` and ``fixture2``:: - - django-admin.py testserver --addrport 7000 fixture1 fixture2 - django-admin.py testserver fixture1 fixture2 --addrport 7000 - -(The above statements are equivalent. We include both of them to demonstrate -that it doesn't matter whether the options come before or after the fixture -arguments.) - -To run on 1.2.3.4:7000 with a ``test`` fixture:: - - django-admin.py testserver --addrport 1.2.3.4:7000 test - -validate --------- - -.. django-admin:: validate - -Validates all installed models (according to the ``INSTALLED_APPS`` setting) -and prints validation errors to standard output. - -Commands provided by applications -================================= - -Some commands are only available when the ``django.contrib`` application that -:doc:`implements </howto/custom-management-commands>` them has been -:setting:`enabled <INSTALLED_APPS>`. This section describes them grouped by -their application. - -``django.contrib.auth`` ------------------------ - -changepassword -~~~~~~~~~~~~~~ - -.. django-admin:: changepassword - -.. versionadded:: 1.2 - -This command is only available if Django's :doc:`authentication system -</topics/auth>` (``django.contrib.auth``) is installed. - -Allows changing a user's password. It prompts you to enter twice the password of -the user given as parameter. If they both match, the new password will be -changed immediately. If you do not supply a user, the command will attempt to -change the password whose username matches the current user. - -Example usage:: - - django-admin.py changepassword ringo - -createsuperuser -~~~~~~~~~~~~~~~ - -.. django-admin:: createsuperuser - -.. versionadded:: 1.0 - -This command is only available if Django's :doc:`authentication system -</topics/auth>` (``django.contrib.auth``) is installed. - -Creates a superuser account (a user who has all permissions). This is -useful if you need to create an initial superuser account but did not -do so during ``syncdb``, or if you need to programmatically generate -superuser accounts for your site(s). - -When run interactively, this command will prompt for a password for -the new superuser account. When run non-interactively, no password -will be set, and the superuser account will not be able to log in until -a password has been manually set for it. - -.. django-admin-option:: --username -.. django-admin-option:: --email - -The username and e-mail address for the new account can be supplied by -using the ``--username`` and ``--email`` arguments on the command -line. If either of those is not supplied, ``createsuperuser`` will prompt for -it when running interactively. - -``django.contrib.gis`` ----------------------- - -ogrinspect -~~~~~~~~~~ - -This command is only available if :doc:`GeoDjango </ref/contrib/gis/index>` -(``django.contrib.gis``) is installed. - -Please refer to its :djadmin:`description <ogrinspect>` in the GeoDjango -documentation. - -``django.contrib.sitemaps`` ---------------------------- - -ping_google -~~~~~~~~~~~ - -This command is only available if the :doc:`Sitemaps framework -</ref/contrib/sitemaps>` (``django.contrib.sitemaps``) is installed. - -Please refer to its :djadmin:`description <ping_google>` in the Sitemaps -documentation. - -Default options -=============== - -Although some commands may allow their own custom options, every command -allows for the following options: - -.. django-admin-option:: --pythonpath - -Example usage:: - - django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject' - -Adds the given filesystem path to the Python `import search path`_. If this -isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment -variable. - -Note that this option is unnecessary in ``manage.py``, because it takes care of -setting the Python path for you. - -.. _import search path: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html - -.. django-admin-option:: --settings - -Example usage:: - - django-admin.py syncdb --settings=mysite.settings - -Explicitly specifies the settings module to use. The settings module should be -in Python package syntax, e.g. ``mysite.settings``. If this isn't provided, -``django-admin.py`` will use the ``DJANGO_SETTINGS_MODULE`` environment -variable. - -Note that this option is unnecessary in ``manage.py``, because it uses -``settings.py`` from the current project by default. - -.. django-admin-option:: --traceback - -Example usage:: - - django-admin.py syncdb --traceback - -By default, ``django-admin.py`` will show a simple error message whenever an -error occurs. If you specify ``--traceback``, ``django-admin.py`` will -output a full stack trace whenever an exception is raised. - -.. django-admin-option:: --verbosity - -Example usage:: - - django-admin.py syncdb --verbosity 2 - -Use ``--verbosity`` to specify the amount of notification and debug information -that ``django-admin.py`` should print to the console. - - * ``0`` means no output. - * ``1`` means normal output (default). - * ``2`` means verbose output. - -Common options -============== - -The following options are not available on every commands, but they are -common to a number of commands. - -.. django-admin-option:: --database - -.. versionadded:: 1.2 - -Used to specify the database on which a command will operate. If not -specified, this option will default to an alias of ``default``. - -For example, to dump data from the database with the alias ``master``:: - - django-admin.py dumpdata --database=master - -.. django-admin-option:: --exclude - -Exclude a specific application from the applications whose contents is -output. For example, to specifically exclude the `auth` application from -the output of dumpdata, you would call:: - - django-admin.py dumpdata --exclude=auth - -If you want to exclude multiple applications, use multiple ``--exclude`` -directives:: - - django-admin.py dumpdata --exclude=auth --exclude=contenttypes - -.. django-admin-option:: --locale - -Use the ``--locale`` or ``-l`` option to specify the locale to process. -If not provided all locales are processed. - -.. django-admin-option:: --noinput - -Use the ``--noinput`` option to suppress all user prompting, such as "Are -you sure?" confirmation messages. This is useful if ``django-admin.py`` is -being executed as an unattended, automated script. - -Extra niceties -============== - -.. _syntax-coloring: - -Syntax coloring ---------------- - -The ``django-admin.py`` / ``manage.py`` commands will use pretty -color-coded output if your terminal supports ANSI-colored output. It -won't use the color codes if you're piping the command's output to -another program. - -The colors used for syntax highlighting can be customized. Django -ships with three color palettes: - - * ``dark``, suited to terminals that show white text on a black - background. This is the default palette. - - * ``light``, suited to terminals that show black text on a white - background. - - * ``nocolor``, which disables syntax highlighting. - -You select a palette by setting a ``DJANGO_COLORS`` environment -variable to specify the palette you want to use. For example, to -specify the ``light`` palette under a Unix or OS/X BASH shell, you -would run the following at a command prompt:: - - export DJANGO_COLORS="light" - -You can also customize the colors that are used. Django specifies a -number of roles in which color is used: - - * ``error`` - A major error. - * ``notice`` - A minor error. - * ``sql_field`` - The name of a model field in SQL. - * ``sql_coltype`` - The type of a model field in SQL. - * ``sql_keyword`` - A SQL keyword. - * ``sql_table`` - The name of a model in SQL. - * ``http_info`` - A 1XX HTTP Informational server response. - * ``http_success`` - A 2XX HTTP Success server response. - * ``http_not_modified`` - A 304 HTTP Not Modified server response. - * ``http_redirect`` - A 3XX HTTP Redirect server response other than 304. - * ``http_not_found`` - A 404 HTTP Not Found server response. - * ``http_bad_request`` - A 4XX HTTP Bad Request server response other than 404. - * ``http_server_error`` - A 5XX HTTP Server Error response. - -Each of these roles can be assigned a specific foreground and -background color, from the following list: - - * ``black`` - * ``red`` - * ``green`` - * ``yellow`` - * ``blue`` - * ``magenta`` - * ``cyan`` - * ``white`` - -Each of these colors can then be modified by using the following -display options: - - * ``bold`` - * ``underscore`` - * ``blink`` - * ``reverse`` - * ``conceal`` - -A color specification follows one of the the following patterns: - - * ``role=fg`` - * ``role=fg/bg`` - * ``role=fg,option,option`` - * ``role=fg/bg,option,option`` - -where ``role`` is the name of a valid color role, ``fg`` is the -foreground color, ``bg`` is the background color and each ``option`` -is one of the color modifying options. Multiple color specifications -are then separated by semicolon. For example:: - - export DJANGO_COLORS="error=yellow/blue,blink;notice=magenta" - -would specify that errors be displayed using blinking yellow on blue, -and notices displayed using magenta. All other color roles would be -left uncolored. - -Colors can also be specified by extending a base palette. If you put -a palette name in a color specification, all the colors implied by that -palette will be loaded. So:: - - export DJANGO_COLORS="light;error=yellow/blue,blink;notice=magenta" - -would specify the use of all the colors in the light color palette, -*except* for the colors for errors and notices which would be -overridden as specified. - -Bash completion ---------------- - -If you use the Bash shell, consider installing the Django bash completion -script, which lives in ``extras/django_bash_completion`` in the Django -distribution. It enables tab-completion of ``django-admin.py`` and -``manage.py`` commands, so you can, for instance... - - * Type ``django-admin.py``. - * Press [TAB] to see all available options. - * Type ``sql``, then [TAB], to see all available options whose names start - with ``sql``. - - -See :doc:`/howto/custom-management-commands` for how to add customized actions. - - -========================================== -Running management commands from your code -========================================== - -.. function:: django.core.management.call_command(name, *args, **options) - -To call a management command from code use ``call_command``. - -``name`` - the name of the command to call. - -``*args`` - a list of arguments accepted by the command. - -``**options`` - named options accepted on the command-line. - -Examples:: - - from django.core import management - management.call_command('flush', verbosity=0, interactive=False) - management.call_command('loaddata', 'test_data', verbosity=0) diff --git a/parts/django/docs/ref/exceptions.txt b/parts/django/docs/ref/exceptions.txt deleted file mode 100644 index f1246bf..0000000 --- a/parts/django/docs/ref/exceptions.txt +++ /dev/null @@ -1,128 +0,0 @@ -================= -Django Exceptions -================= - - -Django raises some Django specific exceptions as well as many standard -Python exceptions. - -Django-specific Exceptions -========================== - -.. module:: django.core.exceptions - :synopsis: Django specific exceptions - -ObjectDoesNotExist and DoesNotExist ------------------------------------ -.. exception:: DoesNotExist -.. exception:: ObjectDoesNotExist - - The :exc:`DoesNotExist` exception is raised when an object is not found - for the given parameters of a query. - - :exc:`ObjectDoesNotExist` is defined in :mod:`django.core.exceptions`. - :exc:`DoesNotExist` is a subclass of the base :exc:`ObjectDoesNotExist` - exception that is provided on every model class as a way of - identifying the specific type of object that could not be found. - - See :meth:`~django.db.models.QuerySet.get()` for further information - on :exc:`ObjectDoesNotExist` and :exc:`DoesNotExist`. - -MultipleObjectsReturned ------------------------ -.. exception:: MultipleObjectsReturned - - The :exc:`MultipleObjectsReturned` exception is raised by a query if only - one object is expected, but multiple objects are returned. A base version - of this exception is provided in :mod:`django.core.exceptions`; each model - class contains a subclassed version that can be used to identify the - specific object type that has returned multiple objects. - - See :meth:`~django.db.models.QuerySet.get()` for further information. - -SuspiciousOperation -------------------- -.. exception:: SuspiciousOperation - - The :exc:`SuspiciousOperation` exception is raised when a user has performed - an operation that should be considered suspicious from a security perspective, - such as tampering with a session cookie. - -PermissionDenied ----------------- -.. exception:: PermissionDenied - - The :exc:`PermissionDenied` exception is raised when a user does not have - permission to perform the action requested. - -ViewDoesNotExist ----------------- -.. exception:: ViewDoesNotExist - - The :exc:`ViewDoesNotExist` exception is raised by - :mod:`django.core.urlresolvers` when a requested view does not exist. - -MiddlewareNotUsed ------------------ -.. exception:: MiddlewareNotUsed - - The :exc:`MiddlewareNotUsed` exception is raised when a middleware is not - used in the server configuration. - -ImproperlyConfigured --------------------- -.. exception:: ImproperlyConfigured - - The :exc:`ImproperlyConfigured` exception is raised when Django is - somehow improperly configured -- for example, if a value in ``settings.py`` - is incorrect or unparseable. - -FieldError ----------- -.. exception:: FieldError - - The :exc:`FieldError` exception is raised when there is a problem with a - model field. This can happen for several reasons: - - - A field in a model clashes with a field of the same name from an - abstract base class - - An infinite loop is caused by ordering - - A keyword cannot be parsed from the filter parameters - - A field cannot be determined from a keyword in the query - parameters - - A join is not permitted on the specified field - - A field name is invalid - - A query contains invalid order_by arguments - -ValidationError ---------------- -.. exception:: ValidationError - - The :exc:`ValidationError` exception is raised when data fails form or - model field validation. For more information about validation, see - :doc:`Form and Field Validation </ref/forms/validation>`, - :ref:`Model Field Validation <validating-objects>` and the - :doc:`Validator Reference </ref/validators>`. - -Database Exceptions -=================== - -Django wraps the standard database exceptions :exc:`DatabaseError` and -:exc:`IntegrityError` so that your Django code has a guaranteed common -implementation of these classes. These database exceptions are -provided in :mod:`django.db`. - -The Django wrappers for database exceptions behave exactly the same as -the underlying database exceptions. See `PEP 249 - Python Database API -Specification v2.0`_ for further information. - -.. _`PEP 249 - Python Database API Specification v2.0`: http://www.python.org/dev/peps/pep-0249/ - -Python Exceptions -================= - -Django raises built-in Python exceptions when appropriate as well. See -the Python `documentation`_ for further information on the built-in -exceptions. - -.. _`documentation`: http://docs.python.org/lib/module-exceptions.html diff --git a/parts/django/docs/ref/files/file.txt b/parts/django/docs/ref/files/file.txt deleted file mode 100644 index 1374d01..0000000 --- a/parts/django/docs/ref/files/file.txt +++ /dev/null @@ -1,152 +0,0 @@ -The ``File`` object -=================== - -The :mod:`django.core.files` module and its submodules contain built-in classes -for basic file handling in Django. - -.. currentmodule:: django.core.files - -The ``File`` Class ------------------- - -.. class:: File(file_object) - - The :class:`File` is a thin wrapper around Python's built-in file object - with some Django-specific additions. Internally, Django uses this class - any time it needs to represent a file. - - :class:`File` objects have the following attributes and methods: - - .. attribute:: name - - The name of file including the relative path from - :setting:`MEDIA_ROOT`. - - .. attribute:: size - - The size of the file in bytes. - - .. attribute:: file - - The underlying Python ``file`` object passed to - :class:`~django.core.files.File`. - - .. attribute:: mode - - The read/write mode for the file. - - .. method:: open([mode=None]) - - Open or reopen the file (which by definition also does - ``File.seek(0)``). The ``mode`` argument allows the same values - as Python's standard ``open()``. - - When reopening a file, ``mode`` will override whatever mode the file - was originally opened with; ``None`` means to reopen with the original - mode. - - .. method:: read([num_bytes=None]) - - Read content from the file. The optional ``size`` is the number of - bytes to read; if not specified, the file will be read to the end. - - .. method:: __iter__() - - Iterate over the file yielding one line at a time. - - .. method:: chunks([chunk_size=None]) - - Iterate over the file yielding "chunks" of a given size. ``chunk_size`` - defaults to 64 KB. - - This is especially useful with very large files since it allows them to - be streamed off disk and avoids storing the whole file in memory. - - .. method:: multiple_chunks([chunk_size=None]) - - Returns ``True`` if the file is large enough to require multiple chunks - to access all of its content give some ``chunk_size``. - - .. method:: write([content]) - - Writes the specified content string to the file. Depending on the - storage system behind the scenes, this content might not be fully - committed until ``close()`` is called on the file. - - .. method:: close() - - Close the file. - - In addition to the listed methods, :class:`~django.core.files.File` exposes - the following attributes and methods of the underlying ``file`` object: - ``encoding``, ``fileno``, ``flush``, ``isatty``, ``newlines``, - ``read``, ``readinto``, ``readlines``, ``seek``, ``softspace``, ``tell``, - ``truncate``, ``writelines``, ``xreadlines``. - -.. currentmodule:: django.core.files.base - -The ``ContentFile`` Class -------------------------- - -.. class:: ContentFile(File) - - The ``ContentFile`` class inherits from :class:`~django.core.files.File`, - but unlike :class:`~django.core.files.File` it operates on string content, - rather than an actual file. For example:: - - from django.core.files.base import ContentFile - - f1 = ContentFile("my string content") - f2 = ContentFile(u"my unicode content encoded as UTF-8".encode('UTF-8')) - -.. currentmodule:: django.core.files.images - -The ``ImageFile`` Class ------------------------ - -.. class:: ImageFile(file_object) - - Django provides a built-in class specifically for images. - :class:`django.core.files.images.ImageFile` inherits all the attributes - and methods of :class:`~django.core.files.File`, and additionally - provides the following: - - .. attribute:: width - - Width of the image in pixels. - - .. attribute:: height - - Height of the image in pixels. - -.. currentmodule:: django.core.files - -Additional methods on files attached to objects ------------------------------------------------ - -Any :class:`File` that's associated with an object (as with ``Car.photo``, -below) will also have a couple of extra methods: - -.. method:: File.save(name, content, [save=True]) - - Saves a new file with the file name and contents provided. This will not - replace the existing file, but will create a new file and update the object - to point to it. If ``save`` is ``True``, the model's ``save()`` method will - be called once the file is saved. That is, these two lines:: - - >>> car.photo.save('myphoto.jpg', contents, save=False) - >>> car.save() - - are the same as this one line:: - - >>> car.photo.save('myphoto.jpg', contents, save=True) - - Note that the ``content`` argument must be an instance of either - :class:`File` or of a subclass of :class:`File`, such as - :class:`ContentFile`. - -.. method:: File.delete([save=True]) - - Removes the file from the model instance and deletes the underlying file. - If ``save`` is ``True``, the model's ``save()`` method will be called once - the file is deleted. diff --git a/parts/django/docs/ref/files/index.txt b/parts/django/docs/ref/files/index.txt deleted file mode 100644 index 552559d..0000000 --- a/parts/django/docs/ref/files/index.txt +++ /dev/null @@ -1,12 +0,0 @@ -============= -File handling -============= - -.. module:: django.core.files - :synopsis: File handling and storage - -.. toctree:: - :maxdepth: 2 - - file - storage diff --git a/parts/django/docs/ref/files/storage.txt b/parts/django/docs/ref/files/storage.txt deleted file mode 100644 index 84ef00c..0000000 --- a/parts/django/docs/ref/files/storage.txt +++ /dev/null @@ -1,119 +0,0 @@ -File storage API -================ - -.. module:: django.core.files.storage - -Getting the current storage class ---------------------------------- - -Django provides two convenient ways to access the current storage class: - -.. class:: DefaultStorage - - :class:`~django.core.files.storage.DefaultStorage` provides - lazy access to the current default storage system as defined by - :setting:`DEFAULT_FILE_STORAGE`. :class:`DefaultStorage` uses - :func:`~django.core.files.storage.get_storage_class` internally. - -.. function:: get_storage_class([import_path=None]) - - Returns a class or module which implements the storage API. - - When called without the ``import_path`` parameter ``get_storage_class`` - will return the current default storage system as defined by - :setting:`DEFAULT_FILE_STORAGE`. If ``import_path`` is provided, - ``get_storage_class`` will attempt to import the class or module from the - given path and will return it if successful. An exception will be - raised if the import is unsuccessful. - -The FileSystemStorage Class ---------------------------- - -.. class:: FileSystemStorage - - The :class:`~django.core.files.storage.FileSystemStorage` class implements - basic file storage on a local filesystem. It inherits from - :class:`~django.core.files.storage.Storage` and provides implementations - for all the public methods thereof. - - .. note:: - - The :class:`FileSystemStorage.delete` method will not raise - raise an exception if the given file name does not exist. - -The Storage Class ------------------ - -.. class:: Storage - - The :class:`~django.core.files.storage.Storage` class provides a - standardized API for storing files, along with a set of default - behaviors that all other storage systems can inherit or override - as necessary. - - .. method:: delete(name) - - Deletes the file referenced by ``name``. If deletion is not supported - on the targest storage system this will raise ``NotImplementedError`` - instead - - .. method:: exists(name) - - Returns ``True`` if a file referened by the given name already exists - in the storage system, or ``False`` if the name is available for a new - file. - - .. method:: get_available_name(name) - - Returns a filename based on the ``name`` parameter that's free and - available for new content to be written to on the target storage - system. - - - .. method:: get_valid_name(name) - - Returns a filename based on the ``name`` parameter that's suitable - for use on the target storage system. - - .. method:: listdir(path) - - Lists the contents of the specified path, returning a 2-tuple of lists; - the first item being directories, the second item being files. For - storage systems that aren't able to provide such a listing, this will - raise a ``NotImplementedError`` instead. - - .. method:: open(name, mode='rb') - - Opens the file given by ``name``. Note that although the returned file - is guaranteed to be a ``File`` object, it might actually be some - subclass. In the case of remote file storage this means that - reading/writing could be quite slow, so be warned. - - .. method:: path(name) - - The local filesystem path where the file can be opened using Python's - standard ``open()``. For storage systems that aren't accessible from - the local filesystem, this will raise ``NotImplementedError`` instead. - - .. method:: save(name, content) - - Saves a new file using the storage system, preferably with the name - specified. If there already exists a file with this name ``name``, the - storage system may modify the filename as necessary to get a unique - name. The actual name of the stored file will be returned. - - The ``content`` argument must be an instance of - :class:`django.core.files.File` or of a subclass of - :class:`~django.core.files.File`. - - .. method:: size(name) - - Returns the total size, in bytes, of the file referenced by ``name``. - For storage systems that aren't able to return the file size this will - raise ``NotImplementedError`` instead. - - .. method:: url(name) - - Returns the URL where the contents of the file referenced by ``name`` - can be accessed. For storage systems that don't support access by URL - this will raise ``NotImplementedError`` instead. diff --git a/parts/django/docs/ref/forms/api.txt b/parts/django/docs/ref/forms/api.txt deleted file mode 100644 index 613d754..0000000 --- a/parts/django/docs/ref/forms/api.txt +++ /dev/null @@ -1,791 +0,0 @@ -============= -The Forms API -============= - -.. module:: django.forms.forms - -.. currentmodule:: django.forms - -.. admonition:: About this document - - This document covers the gritty details of Django's forms API. You should - read the :doc:`introduction to working with forms </topics/forms/index>` - first. - -.. _ref-forms-api-bound-unbound: - -Bound and unbound forms ------------------------ - -A :class:`Form` instance is either **bound** to a set of data, or **unbound**. - - * If it's **bound** to a set of data, it's capable of validating that data - and rendering the form as HTML with the data displayed in the HTML. - - * If it's **unbound**, it cannot do validation (because there's no data to - validate!), but it can still render the blank form as HTML. - -.. class:: Form - -To create an unbound :class:`Form` instance, simply instantiate the class:: - - >>> f = ContactForm() - -To bind data to a form, pass the data as a dictionary as the first parameter to -your :class:`Form` class constructor:: - - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True} - >>> f = ContactForm(data) - -In this dictionary, the keys are the field names, which correspond to the -attributes in your :class:`Form` class. The values are the data you're trying to -validate. These will usually be strings, but there's no requirement that they be -strings; the type of data you pass depends on the :class:`Field`, as we'll see -in a moment. - -.. attribute:: Form.is_bound - -If you need to distinguish between bound and unbound form instances at runtime, -check the value of the form's :attr:`~Form.is_bound` attribute:: - - >>> f = ContactForm() - >>> f.is_bound - False - >>> f = ContactForm({'subject': 'hello'}) - >>> f.is_bound - True - -Note that passing an empty dictionary creates a *bound* form with empty data:: - - >>> f = ContactForm({}) - >>> f.is_bound - True - -If you have a bound :class:`Form` instance and want to change the data somehow, -or if you want to bind an unbound :class:`Form` instance to some data, create -another :class:`Form` instance. There is no way to change data in a -:class:`Form` instance. Once a :class:`Form` instance has been created, you -should consider its data immutable, whether it has data or not. - -Using forms to validate data ----------------------------- - -.. method:: Form.is_valid() - -The primary task of a :class:`Form` object is to validate data. With a bound -:class:`Form` instance, call the :meth:`~Form.is_valid` method to run validation -and return a boolean designating whether the data was valid:: - - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True} - >>> f = ContactForm(data) - >>> f.is_valid() - True - -Let's try with some invalid data. In this case, ``subject`` is blank (an error, -because all fields are required by default) and ``sender`` is not a valid -e-mail address:: - - >>> data = {'subject': '', - ... 'message': 'Hi there', - ... 'sender': 'invalid e-mail address', - ... 'cc_myself': True} - >>> f = ContactForm(data) - >>> f.is_valid() - False - -.. attribute:: Form.errors - -Access the :attr:`~Form.errors` attribute to get a dictionary of error -messages:: - - >>> f.errors - {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']} - -In this dictionary, the keys are the field names, and the values are lists of -Unicode strings representing the error messages. The error messages are stored -in lists because a field can have multiple error messages. - -You can access :attr:`~Form.errors` without having to call -:meth:`~Form.is_valid` first. The form's data will be validated the first time -either you call :meth:`~Form.is_valid` or access :attr:`~Form.errors`. - -The validation routines will only get called once, regardless of how many times -you access :attr:`~Form.errors` or call :meth:`~Form.is_valid`. This means that -if validation has side effects, those side effects will only be triggered once. - -Behavior of unbound forms -~~~~~~~~~~~~~~~~~~~~~~~~~ - -It's meaningless to validate a form with no data, but, for the record, here's -what happens with unbound forms:: - - >>> f = ContactForm() - >>> f.is_valid() - False - >>> f.errors - {} - -Dynamic initial values ----------------------- - -.. attribute:: Form.initial - -Use :attr:`~Form.initial` to declare the initial value of form fields at -runtime. For example, you might want to fill in a ``username`` field with the -username of the current session. - -To accomplish this, use the :attr:`~Form.initial` argument to a :class:`Form`. -This argument, if given, should be a dictionary mapping field names to initial -values. Only include the fields for which you're specifying an initial value; -it's not necessary to include every field in your form. For example:: - - >>> f = ContactForm(initial={'subject': 'Hi there!'}) - -These values are only displayed for unbound forms, and they're not used as -fallback values if a particular value isn't provided. - -Note that if a :class:`~django.forms.fields.Field` defines -:attr:`~Form.initial` *and* you include ``initial`` when instantiating the -``Form``, then the latter ``initial`` will have precedence. In this example, -``initial`` is provided both at the field level and at the form instance level, -and the latter gets precedence:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='class') - ... url = forms.URLField() - ... comment = forms.CharField() - >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) - >>> print f - <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr> - <tr><th>Url:</th><td><input type="text" name="url" /></td></tr> - <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> - -Accessing "clean" data ----------------------- - -.. attribute:: Form.cleaned_data - -Each field in a :class:`Form` class is responsible not only for validating -data, but also for "cleaning" it -- normalizing it to a consistent format. This -is a nice feature, because it allows data for a particular field to be input in -a variety of ways, always resulting in consistent output. - -For example, :class:`~django.forms.DateField` normalizes input into a -Python ``datetime.date`` object. Regardless of whether you pass it a string in -the format ``'1994-07-15'``, a ``datetime.date`` object, or a number of other -formats, ``DateField`` will always normalize it to a ``datetime.date`` object -as long as it's valid. - -Once you've created a :class:`~Form` instance with a set of data and validated -it, you can access the clean data via its ``cleaned_data`` attribute:: - - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True} - >>> f = ContactForm(data) - >>> f.is_valid() - True - >>> f.cleaned_data - {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} - -.. versionchanged:: 1.0 - The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases. - -Note that any text-based field -- such as ``CharField`` or ``EmailField`` -- -always cleans the input into a Unicode string. We'll cover the encoding -implications later in this document. - -If your data does *not* validate, your ``Form`` instance will not have a -``cleaned_data`` attribute:: - - >>> data = {'subject': '', - ... 'message': 'Hi there', - ... 'sender': 'invalid e-mail address', - ... 'cc_myself': True} - >>> f = ContactForm(data) - >>> f.is_valid() - False - >>> f.cleaned_data - Traceback (most recent call last): - ... - AttributeError: 'ContactForm' object has no attribute 'cleaned_data' - -``cleaned_data`` will always *only* contain a key for fields defined in the -``Form``, even if you pass extra data when you define the ``Form``. In this -example, we pass a bunch of extra fields to the ``ContactForm`` constructor, -but ``cleaned_data`` contains only the form's fields:: - - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True, - ... 'extra_field_1': 'foo', - ... 'extra_field_2': 'bar', - ... 'extra_field_3': 'baz'} - >>> f = ContactForm(data) - >>> f.is_valid() - True - >>> f.cleaned_data # Doesn't contain extra_field_1, etc. - {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} - -``cleaned_data`` will include a key and value for *all* fields defined in the -``Form``, even if the data didn't include a value for fields that are not -required. In this example, the data dictionary doesn't include a value for the -``nick_name`` field, but ``cleaned_data`` includes it, with an empty value:: - - >>> class OptionalPersonForm(Form): - ... first_name = CharField() - ... last_name = CharField() - ... nick_name = CharField(required=False) - >>> data = {'first_name': u'John', 'last_name': u'Lennon'} - >>> f = OptionalPersonForm(data) - >>> f.is_valid() - True - >>> f.cleaned_data - {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'} - -In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an -empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat -empty values as an empty string. Each field type knows what its "blank" value -is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For -full details on each field's behavior in this case, see the "Empty value" note -for each field in the "Built-in ``Field`` classes" section below. - -You can write code to perform validation for particular form fields (based on -their name) or for the form as a whole (considering combinations of various -fields). More information about this is in :doc:`/ref/forms/validation`. - -Outputting forms as HTML ------------------------- - -The second task of a ``Form`` object is to render itself as HTML. To do so, -simply ``print`` it:: - - >>> f = ContactForm() - >>> print f - <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr> - <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr> - <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr> - <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr> - -If the form is bound to data, the HTML output will include that data -appropriately. For example, if a field is represented by an -``<input type="text">``, the data will be in the ``value`` attribute. If a -field is represented by an ``<input type="checkbox">``, then that HTML will -include ``checked="checked"`` if appropriate:: - - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True} - >>> f = ContactForm(data) - >>> print f - <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" /></td></tr> - <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr> - <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></td></tr> - <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr> - -This default output is a two-column HTML table, with a ``<tr>`` for each field. -Notice the following: - - * For flexibility, the output does *not* include the ``<table>`` and - ``</table>`` tags, nor does it include the ``<form>`` and ``</form>`` - tags or an ``<input type="submit">`` tag. It's your job to do that. - - * Each field type has a default HTML representation. ``CharField`` and - ``EmailField`` are represented by an ``<input type="text">``. - ``BooleanField`` is represented by an ``<input type="checkbox">``. Note - these are merely sensible defaults; you can specify which HTML to use for - a given field by using widgets, which we'll explain shortly. - - * The HTML ``name`` for each tag is taken directly from its attribute name - in the ``ContactForm`` class. - - * The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and - ``'Cc myself:'`` is generated from the field name by converting all - underscores to spaces and upper-casing the first letter. Again, note - these are merely sensible defaults; you can also specify labels manually. - - * Each text label is surrounded in an HTML ``<label>`` tag, which points - to the appropriate form field via its ``id``. Its ``id``, in turn, is - generated by prepending ``'id_'`` to the field name. The ``id`` - attributes and ``<label>`` tags are included in the output by default, to - follow best practices, but you can change that behavior. - -Although ``<table>`` output is the default output style when you ``print`` a -form, other output styles are available. Each style is available as a method on -a form object, and each rendering method returns a Unicode object. - -``as_p()`` -~~~~~~~~~~ - -.. method:: Form.as_p - - ``as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>`` - containing one field:: - - >>> f = ContactForm() - >>> f.as_p() - u'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>' - >>> print f.as_p() - <p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p> - <p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p> - <p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p> - <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p> - -``as_ul()`` -~~~~~~~~~~~ - -.. method:: Form.as_ul - - ``as_ul()`` renders the form as a series of ``<li>`` tags, with each - ``<li>`` containing one field. It does *not* include the ``<ul>`` or - ``</ul>``, so that you can specify any HTML attributes on the ``<ul>`` for - flexibility:: - - >>> f = ContactForm() - >>> f.as_ul() - u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>' - >>> print f.as_ul() - <li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li> - <li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li> - <li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li> - <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li> - -``as_table()`` -~~~~~~~~~~~~~~ - -.. method:: Form.as_table - - Finally, ``as_table()`` outputs the form as an HTML ``<table>``. This is - exactly the same as ``print``. In fact, when you ``print`` a form object, - it calls its ``as_table()`` method behind the scenes:: - - >>> f = ContactForm() - >>> f.as_table() - u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>' - >>> print f.as_table() - <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr> - <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr> - <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr> - <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr> - -Styling required or erroneous form rows -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.2 - -It's pretty common to style form rows and fields that are required or have -errors. For example, you might want to present required form rows in bold and -highlight errors in red. - -The :class:`Form` class has a couple of hooks you can use to add ``class`` -attributes to required rows or to rows with errors: simple set the -:attr:`Form.error_css_class` and/or :attr:`Form.required_css_class` -attributes:: - - class ContactForm(Form): - error_css_class = 'error' - required_css_class = 'required' - - # ... and the rest of your fields here - -Once you've done that, rows will be given ``"error"`` and/or ``"required"`` -classes, as needed. The HTML will look something like:: - - >>> f = ContactForm(data) - >>> print f.as_table() - <tr class="required"><th><label for="id_subject">Subject:</label> ... - <tr class="required"><th><label for="id_message">Message:</label> ... - <tr class="required error"><th><label for="id_sender">Sender:</label> ... - <tr><th><label for="id_cc_myself">Cc myself:<label> ... - -.. _ref-forms-api-configuring-label: - -Configuring HTML ``<label>`` tags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An HTML ``<label>`` tag designates which label text is associated with which -form element. This small enhancement makes forms more usable and more accessible -to assistive devices. It's always a good idea to use ``<label>`` tags. - -By default, the form rendering methods include HTML ``id`` attributes on the -form elements and corresponding ``<label>`` tags around the labels. The ``id`` -attribute values are generated by prepending ``id_`` to the form field names. -This behavior is configurable, though, if you want to change the ``id`` -convention or remove HTML ``id`` attributes and ``<label>`` tags entirely. - -Use the ``auto_id`` argument to the ``Form`` constructor to control the label -and ``id`` behavior. This argument must be ``True``, ``False`` or a string. - -If ``auto_id`` is ``False``, then the form output will not include ``<label>`` -tags nor ``id`` attributes:: - - >>> f = ContactForm(auto_id=False) - >>> print f.as_table() - <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /></td></tr> - <tr><th>Message:</th><td><input type="text" name="message" /></td></tr> - <tr><th>Sender:</th><td><input type="text" name="sender" /></td></tr> - <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr> - >>> print f.as_ul() - <li>Subject: <input type="text" name="subject" maxlength="100" /></li> - <li>Message: <input type="text" name="message" /></li> - <li>Sender: <input type="text" name="sender" /></li> - <li>Cc myself: <input type="checkbox" name="cc_myself" /></li> - >>> print f.as_p() - <p>Subject: <input type="text" name="subject" maxlength="100" /></p> - <p>Message: <input type="text" name="message" /></p> - <p>Sender: <input type="text" name="sender" /></p> - <p>Cc myself: <input type="checkbox" name="cc_myself" /></p> - -If ``auto_id`` is set to ``True``, then the form output *will* include -``<label>`` tags and will simply use the field name as its ``id`` for each form -field:: - - >>> f = ContactForm(auto_id=True) - >>> print f.as_table() - <tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" /></td></tr> - <tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr> - <tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></td></tr> - <tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr> - >>> print f.as_ul() - <li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></li> - <li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li> - <li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></li> - <li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li> - >>> print f.as_p() - <p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></p> - <p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p> - <p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></p> - <p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p> - -If ``auto_id`` is set to a string containing the format character ``'%s'``, -then the form output will include ``<label>`` tags, and will generate ``id`` -attributes based on the format string. For example, for a format string -``'field_%s'``, a field named ``subject`` will get the ``id`` value -``'field_subject'``. Continuing our example:: - - >>> f = ContactForm(auto_id='id_for_%s') - >>> print f.as_table() - <tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" /></td></tr> - <tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" /></td></tr> - <tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></td></tr> - <tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr> - >>> print f.as_ul() - <li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> - <li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li> - <li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></li> - <li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> - >>> print f.as_p() - <p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></p> - <p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p> - <p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></p> - <p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p> - -If ``auto_id`` is set to any other true value -- such as a string that doesn't -include ``%s`` -- then the library will act as if ``auto_id`` is ``True``. - -By default, ``auto_id`` is set to the string ``'id_%s'``. - -Normally, a colon (``:``) will be appended after any label name when a form is -rendered. It's possible to change the colon to another character, or omit it -entirely, using the ``label_suffix`` parameter:: - - >>> f = ContactForm(auto_id='id_for_%s', label_suffix='') - >>> print f.as_ul() - <li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> - <li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li> - <li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li> - <li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> - >>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->') - >>> print f.as_ul() - <li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> - <li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li> - <li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li> - <li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> - -Note that the label suffix is added only if the last character of the -label isn't a punctuation character (``.``, ``!``, ``?`` or ``:``) - -Notes on field ordering -~~~~~~~~~~~~~~~~~~~~~~~ - -In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are -displayed in the order in which you define them in your form class. For -example, in the ``ContactForm`` example, the fields are defined in the order -``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML -output, just change the order in which those fields are listed in the class. - -How errors are displayed -~~~~~~~~~~~~~~~~~~~~~~~~ - -If you render a bound ``Form`` object, the act of rendering will automatically -run the form's validation if it hasn't already happened, and the HTML output -will include the validation errors as a ``<ul class="errorlist">`` near the -field. The particular positioning of the error messages depends on the output -method you're using:: - - >>> data = {'subject': '', - ... 'message': 'Hi there', - ... 'sender': 'invalid e-mail address', - ... 'cc_myself': True} - >>> f = ContactForm(data, auto_id=False) - >>> print f.as_table() - <tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr> - <tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr> - <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid e-mail address" /></td></tr> - <tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr> - >>> print f.as_ul() - <li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" /></li> - <li>Message: <input type="text" name="message" value="Hi there" /></li> - <li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid e-mail address" /></li> - <li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li> - >>> print f.as_p() - <p><ul class="errorlist"><li>This field is required.</li></ul></p> - <p>Subject: <input type="text" name="subject" maxlength="100" /></p> - <p>Message: <input type="text" name="message" value="Hi there" /></p> - <p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p> - <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p> - <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> - -Customizing the error list format -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, forms use ``django.forms.util.ErrorList`` to format validation -errors. If you'd like to use an alternate class for displaying errors, you can -pass that in at construction time:: - - >>> from django.forms.util import ErrorList - >>> class DivErrorList(ErrorList): - ... def __unicode__(self): - ... return self.as_divs() - ... def as_divs(self): - ... if not self: return u'' - ... return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self]) - >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList) - >>> f.as_p() - <div class="errorlist"><div class="error">This field is required.</div></div> - <p>Subject: <input type="text" name="subject" maxlength="100" /></p> - <p>Message: <input type="text" name="message" value="Hi there" /></p> - <div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div> - <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p> - <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> - -More granular output -~~~~~~~~~~~~~~~~~~~~ - -The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for -lazy developers -- they're not the only way a form object can be displayed. - -To display the HTML for a single field in your form, use dictionary lookup -syntax using the field's name as the key, and print the resulting object:: - - >>> f = ContactForm() - >>> print f['subject'] - <input id="id_subject" type="text" name="subject" maxlength="100" /> - >>> print f['message'] - <input type="text" name="message" id="id_message" /> - >>> print f['sender'] - <input type="text" name="sender" id="id_sender" /> - >>> print f['cc_myself'] - <input type="checkbox" name="cc_myself" id="id_cc_myself" /> - -Call ``str()`` or ``unicode()`` on the field to get its rendered HTML as a -string or Unicode object, respectively:: - - >>> str(f['subject']) - '<input id="id_subject" type="text" name="subject" maxlength="100" />' - >>> unicode(f['subject']) - u'<input id="id_subject" type="text" name="subject" maxlength="100" />' - -Form objects define a custom ``__iter__()`` method, which allows you to loop -through their fields:: - - >>> f = ContactForm() - >>> for field in f: print field - <input id="id_subject" type="text" name="subject" maxlength="100" /> - <input type="text" name="message" id="id_message" /> - <input type="text" name="sender" id="id_sender" /> - <input type="checkbox" name="cc_myself" id="id_cc_myself" /> - -The field-specific output honors the form object's ``auto_id`` setting:: - - >>> f = ContactForm(auto_id=False) - >>> print f['message'] - <input type="text" name="message" /> - >>> f = ContactForm(auto_id='id_%s') - >>> print f['message'] - <input type="text" name="message" id="id_message" /> - -For a field's list of errors, access the field's ``errors`` attribute. This -is a list-like object that is displayed as an HTML ``<ul class="errorlist">`` -when printed:: - - >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''} - >>> f = ContactForm(data, auto_id=False) - >>> print f['message'] - <input type="text" name="message" /> - >>> f['message'].errors - [u'This field is required.'] - >>> print f['message'].errors - <ul class="errorlist"><li>This field is required.</li></ul> - >>> f['subject'].errors - [] - >>> print f['subject'].errors - - >>> str(f['subject'].errors) - '' - -.. versionadded:: 1.2 - -When you use Django's rendering shortcuts, CSS classes are used to -indicate required form fields or fields that contain errors. If you're -manually rendering a form, you can access these CSS classes using the -``css_classes`` method:: - - >>> f = ContactForm(data) - >>> f['message'].css_classes() - 'required' - -If you want to provide some additional classes in addition to the -error and required classes that may be required, you can provide -those classes as an argument:: - - >>> f = ContactForm(data) - >>> f['message'].css_classes('foo bar') - 'foo bar required' - -.. _binding-uploaded-files: - -Binding uploaded files to a form --------------------------------- - -.. versionadded:: 1.0 - -Dealing with forms that have ``FileField`` and ``ImageField`` fields -is a little more complicated than a normal form. - -Firstly, in order to upload files, you'll need to make sure that your -``<form>`` element correctly defines the ``enctype`` as -``"multipart/form-data"``:: - - <form enctype="multipart/form-data" method="post" action="/foo/"> - -Secondly, when you use the form, you need to bind the file data. File -data is handled separately to normal form data, so when your form -contains a ``FileField`` and ``ImageField``, you will need to specify -a second argument when you bind your form. So if we extend our -ContactForm to include an ``ImageField`` called ``mugshot``, we -need to bind the file data containing the mugshot image:: - - # Bound form with an image field - >>> from django.core.files.uploadedfile import SimpleUploadedFile - >>> data = {'subject': 'hello', - ... 'message': 'Hi there', - ... 'sender': 'foo@example.com', - ... 'cc_myself': True} - >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)} - >>> f = ContactFormWithMugshot(data, file_data) - -In practice, you will usually specify ``request.FILES`` as the source -of file data (just like you use ``request.POST`` as the source of -form data):: - - # Bound form with an image field, data from the request - >>> f = ContactFormWithMugshot(request.POST, request.FILES) - -Constructing an unbound form is the same as always -- just omit both -form data *and* file data:: - - # Unbound form with a image field - >>> f = ContactFormWithMugshot() - -Testing for multipart forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you're writing reusable views or templates, you may not know ahead of time -whether your form is a multipart form or not. The ``is_multipart()`` method -tells you whether the form requires multipart encoding for submission:: - - >>> f = ContactFormWithMugshot() - >>> f.is_multipart() - True - -Here's an example of how you might use this in a template:: - - {% if form.is_multipart %} - <form enctype="multipart/form-data" method="post" action="/foo/"> - {% else %} - <form method="post" action="/foo/"> - {% endif %} - {{ form }} - </form> - -Subclassing forms ------------------ - -If you have multiple ``Form`` classes that share fields, you can use -subclassing to remove redundancy. - -When you subclass a custom ``Form`` class, the resulting subclass will -include all fields of the parent class(es), followed by the fields you define -in the subclass. - -In this example, ``ContactFormWithPriority`` contains all the fields from -``ContactForm``, plus an additional field, ``priority``. The ``ContactForm`` -fields are ordered first:: - - >>> class ContactFormWithPriority(ContactForm): - ... priority = forms.CharField() - >>> f = ContactFormWithPriority(auto_id=False) - >>> print f.as_ul() - <li>Subject: <input type="text" name="subject" maxlength="100" /></li> - <li>Message: <input type="text" name="message" /></li> - <li>Sender: <input type="text" name="sender" /></li> - <li>Cc myself: <input type="checkbox" name="cc_myself" /></li> - <li>Priority: <input type="text" name="priority" /></li> - -It's possible to subclass multiple forms, treating forms as "mix-ins." In this -example, ``BeatleForm`` subclasses both ``PersonForm`` and ``InstrumentForm`` -(in that order), and its field list includes the fields from the parent -classes:: - - >>> class PersonForm(Form): - ... first_name = CharField() - ... last_name = CharField() - >>> class InstrumentForm(Form): - ... instrument = CharField() - >>> class BeatleForm(PersonForm, InstrumentForm): - ... haircut_type = CharField() - >>> b = BeatleForm(auto_id=False) - >>> print b.as_ul() - <li>First name: <input type="text" name="first_name" /></li> - <li>Last name: <input type="text" name="last_name" /></li> - <li>Instrument: <input type="text" name="instrument" /></li> - <li>Haircut type: <input type="text" name="haircut_type" /></li> - -.. _form-prefix: - -Prefixes for forms ------------------- - -.. attribute:: Form.prefix - -You can put several Django forms inside one ``<form>`` tag. To give each -``Form`` its own namespace, use the ``prefix`` keyword argument:: - - >>> mother = PersonForm(prefix="mother") - >>> father = PersonForm(prefix="father") - >>> print mother.as_ul() - <li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li> - <li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li> - >>> print father.as_ul() - <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li> - <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li> diff --git a/parts/django/docs/ref/forms/fields.txt b/parts/django/docs/ref/forms/fields.txt deleted file mode 100644 index 91f245a..0000000 --- a/parts/django/docs/ref/forms/fields.txt +++ /dev/null @@ -1,939 +0,0 @@ -=========== -Form fields -=========== - -.. module:: django.forms.fields - :synopsis: Django's built-in form fields. - -.. currentmodule:: django.forms - -.. class:: Field(**kwargs) - -When you create a ``Form`` class, the most important part is defining the -fields of the form. Each field has custom validation logic, along with a few -other hooks. - -.. method:: Field.clean(value) - -Although the primary way you'll use ``Field`` classes is in ``Form`` classes, -you can also instantiate them and use them directly to get a better idea of -how they work. Each ``Field`` instance has a ``clean()`` method, which takes -a single argument and either raises a ``django.forms.ValidationError`` -exception or returns the clean value:: - - >>> from django import forms - >>> f = forms.EmailField() - >>> f.clean('foo@example.com') - u'foo@example.com' - >>> f.clean(u'foo@example.com') - u'foo@example.com' - >>> f.clean('invalid e-mail address') - Traceback (most recent call last): - ... - ValidationError: [u'Enter a valid e-mail address.'] - -Core field arguments --------------------- - -Each ``Field`` class constructor takes at least these arguments. Some -``Field`` classes take additional, field-specific arguments, but the following -should *always* be accepted: - -``required`` -~~~~~~~~~~~~ - -.. attribute:: Field.required - -By default, each ``Field`` class assumes the value is required, so if you pass -an empty value -- either ``None`` or the empty string (``""``) -- then -``clean()`` will raise a ``ValidationError`` exception:: - - >>> f = forms.CharField() - >>> f.clean('foo') - u'foo' - >>> f.clean('') - Traceback (most recent call last): - ... - ValidationError: [u'This field is required.'] - >>> f.clean(None) - Traceback (most recent call last): - ... - ValidationError: [u'This field is required.'] - >>> f.clean(' ') - u' ' - >>> f.clean(0) - u'0' - >>> f.clean(True) - u'True' - >>> f.clean(False) - u'False' - -To specify that a field is *not* required, pass ``required=False`` to the -``Field`` constructor:: - - >>> f = forms.CharField(required=False) - >>> f.clean('foo') - u'foo' - >>> f.clean('') - u'' - >>> f.clean(None) - u'' - >>> f.clean(0) - u'0' - >>> f.clean(True) - u'True' - >>> f.clean(False) - u'False' - -If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value, -then ``clean()`` will return a *normalized* empty value rather than raising -``ValidationError``. For ``CharField``, this will be a Unicode empty string. -For other ``Field`` classes, it might be ``None``. (This varies from field to -field.) - -``label`` -~~~~~~~~~ - -.. attribute:: Field.label - -The ``label`` argument lets you specify the "human-friendly" label for this -field. This is used when the ``Field`` is displayed in a ``Form``. - -As explained in "Outputting forms as HTML" above, the default label for a -``Field`` is generated from the field name by converting all underscores to -spaces and upper-casing the first letter. Specify ``label`` if that default -behavior doesn't result in an adequate label. - -Here's a full example ``Form`` that implements ``label`` for two of its fields. -We've specified ``auto_id=False`` to simplify the output:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField(label='Your name') - ... url = forms.URLField(label='Your Web site', required=False) - ... comment = forms.CharField() - >>> f = CommentForm(auto_id=False) - >>> print f - <tr><th>Your name:</th><td><input type="text" name="name" /></td></tr> - <tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr> - <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> - -``initial`` -~~~~~~~~~~~ - -.. attribute:: Field.initial - -The ``initial`` argument lets you specify the initial value to use when -rendering this ``Field`` in an unbound ``Form``. - -To specify dynamic initial data, see the :attr:`Form.initial` parameter. - -The use-case for this is when you want to display an "empty" form in which a -field is initialized to a particular value. For example:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='Your name') - ... url = forms.URLField(initial='http://') - ... comment = forms.CharField() - >>> f = CommentForm(auto_id=False) - >>> print f - <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr> - <tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr> - <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> - -You may be thinking, why not just pass a dictionary of the initial values as -data when displaying the form? Well, if you do that, you'll trigger validation, -and the HTML output will include any validation errors:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField() - ... url = forms.URLField() - ... comment = forms.CharField() - >>> default_data = {'name': 'Your name', 'url': 'http://'} - >>> f = CommentForm(default_data, auto_id=False) - >>> print f - <tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr> - <tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr> - <tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr> - -This is why ``initial`` values are only displayed for unbound forms. For bound -forms, the HTML output will use the bound data. - -Also note that ``initial`` values are *not* used as "fallback" data in -validation if a particular field's value is not given. ``initial`` values are -*only* intended for initial form display:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='Your name') - ... url = forms.URLField(initial='http://') - ... comment = forms.CharField() - >>> data = {'name': '', 'url': '', 'comment': 'Foo'} - >>> f = CommentForm(data) - >>> f.is_valid() - False - # The form does *not* fall back to using the initial values. - >>> f.errors - {'url': [u'This field is required.'], 'name': [u'This field is required.']} - -Instead of a constant, you can also pass any callable:: - - >>> import datetime - >>> class DateForm(forms.Form): - ... day = forms.DateField(initial=datetime.date.today) - >>> print DateForm() - <tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" /><td></tr> - -The callable will be evaluated only when the unbound form is displayed, not when it is defined. - -``widget`` -~~~~~~~~~~ - -.. attribute:: Field.widget - -The ``widget`` argument lets you specify a ``Widget`` class to use when -rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information. - -``help_text`` -~~~~~~~~~~~~~ - -.. attribute:: Field.help_text - -The ``help_text`` argument lets you specify descriptive text for this -``Field``. If you provide ``help_text``, it will be displayed next to the -``Field`` when the ``Field`` is rendered by one of the convenience ``Form`` -methods (e.g., ``as_ul()``). - -Here's a full example ``Form`` that implements ``help_text`` for two of its -fields. We've specified ``auto_id=False`` to simplify the output:: - - >>> class HelpTextContactForm(forms.Form): - ... subject = forms.CharField(max_length=100, help_text='100 characters max.') - ... message = forms.CharField() - ... sender = forms.EmailField(help_text='A valid e-mail address, please.') - ... cc_myself = forms.BooleanField(required=False) - >>> f = HelpTextContactForm(auto_id=False) - >>> print f.as_table() - <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr> - <tr><th>Message:</th><td><input type="text" name="message" /></td></tr> - <tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</td></tr> - <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr> - >>> print f.as_ul() - <li>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</li> - <li>Message: <input type="text" name="message" /></li> - <li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li> - <li>Cc myself: <input type="checkbox" name="cc_myself" /></li> - >>> print f.as_p() - <p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p> - <p>Message: <input type="text" name="message" /></p> - <p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p> - <p>Cc myself: <input type="checkbox" name="cc_myself" /></p> - -``error_messages`` -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. attribute:: Field.error_messages - -The ``error_messages`` argument lets you override the default messages that the -field will raise. Pass in a dictionary with keys matching the error messages you -want to override. For example, here is the default error message:: - - >>> generic = forms.CharField() - >>> generic.clean('') - Traceback (most recent call last): - ... - ValidationError: [u'This field is required.'] - -And here is a custom error message:: - - >>> name = forms.CharField(error_messages={'required': 'Please enter your name'}) - >>> name.clean('') - Traceback (most recent call last): - ... - ValidationError: [u'Please enter your name'] - -In the `built-in Field classes`_ section below, each ``Field`` defines the -error message keys it uses. - -``validators`` -~~~~~~~~~~~~~~ - -.. versionadded:: 1.2 - -.. attribute:: Field.validators - -The ``validators`` argument lets you provide a list of validation functions -for this field. - -See the :doc:`validators documentation </ref/validators>` for more information. - -``localize`` -~~~~~~~~~~~~ - -.. versionadded:: 1.2 - -.. attribute:: Field.localize - -The ``localize`` argument enables the localization of form data, input as well -as the rendered output. - -See the :ref:`format localization <format-localization>` documentation for -more information. - - -Built-in ``Field`` classes --------------------------- - -Naturally, the ``forms`` library comes with a set of ``Field`` classes that -represent common validation needs. This section documents each built-in field. - -For each field, we describe the default widget used if you don't specify -``widget``. We also specify the value returned when you provide an empty value -(see the section on ``required`` above to understand what that means). - -``BooleanField`` -~~~~~~~~~~~~~~~~ - -.. class:: BooleanField(**kwargs) - - * Default widget: ``CheckboxInput`` - * Empty value: ``False`` - * Normalizes to: A Python ``True`` or ``False`` value. - * Validates that the value is ``True`` (e.g. the check box is checked) if - the field has ``required=True``. - * Error message keys: ``required`` - -.. versionchanged:: 1.0 - The empty value for a ``CheckboxInput`` (and hence the standard - ``BooleanField``) has changed to return ``False`` instead of ``None`` in - the Django 1.0. - -.. note:: - - Since all ``Field`` subclasses have ``required=True`` by default, the - validation condition here is important. If you want to include a boolean - in your form that can be either ``True`` or ``False`` (e.g. a checked or - unchecked checkbox), you must remember to pass in ``required=False`` when - creating the ``BooleanField``. - -``CharField`` -~~~~~~~~~~~~~ - -.. class:: CharField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates ``max_length`` or ``min_length``, if they are provided. - Otherwise, all inputs are valid. - * Error message keys: ``required``, ``max_length``, ``min_length`` - -Has two optional arguments for validation: - -.. attribute:: CharField.max_length -.. attribute:: CharField.min_length - - If provided, these arguments ensure that the string is at most or at least - the given length. - -``ChoiceField`` -~~~~~~~~~~~~~~~ - -.. class:: ChoiceField(**kwargs) - - * Default widget: ``Select`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value exists in the list of choices. - * Error message keys: ``required``, ``invalid_choice`` - -Takes one extra required argument: - -.. attribute:: ChoiceField.choices - - An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this - field. This argument accepts the same formats as the ``choices`` argument - to a model field. See the :ref:`model field reference documentation on - choices <field-choices>` for more details. - -``TypedChoiceField`` -~~~~~~~~~~~~~~~~~~~~ - -.. class:: TypedChoiceField(**kwargs) - -Just like a :class:`ChoiceField`, except :class:`TypedChoiceField` takes an -extra ``coerce`` argument. - - * Default widget: ``Select`` - * Empty value: Whatever you've given as ``empty_value`` - * Normalizes to: the value returned by the ``coerce`` argument. - * Validates that the given value exists in the list of choices. - * Error message keys: ``required``, ``invalid_choice`` - -Takes extra arguments: - -.. attribute:: TypedChoiceField.coerce - - A function that takes one argument and returns a coerced value. Examples - include the built-in ``int``, ``float``, ``bool`` and other types. Defaults - to an identity function. - -.. attribute:: TypedChoiceField.empty_value - - The value to use to represent "empty." Defaults to the empty string; - ``None`` is another common choice here. - -``DateField`` -~~~~~~~~~~~~~ - -.. class:: DateField(**kwargs) - - * Default widget: ``DateInput`` - * Empty value: ``None`` - * Normalizes to: A Python ``datetime.date`` object. - * Validates that the given value is either a ``datetime.date``, - ``datetime.datetime`` or string formatted in a particular date format. - * Error message keys: ``required``, ``invalid`` - -Takes one optional argument: - -.. attribute:: DateField.input_formats - - A list of formats used to attempt to convert a string to a valid - ``datetime.date`` object. - -If no ``input_formats`` argument is provided, the default input formats are:: - - '%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06' - '%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006' - '%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006' - '%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006' - '%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006' - -.. versionchanged:: 1.1 - The ``DateField`` previously used a ``TextInput`` widget by default. It now - uses a ``DateInput`` widget. - -``DateTimeField`` -~~~~~~~~~~~~~~~~~ - -.. class:: DateTimeField(**kwargs) - - * Default widget: ``DateTimeInput`` - * Empty value: ``None`` - * Normalizes to: A Python ``datetime.datetime`` object. - * Validates that the given value is either a ``datetime.datetime``, - ``datetime.date`` or string formatted in a particular datetime format. - * Error message keys: ``required``, ``invalid`` - -Takes one optional argument: - -.. attribute:: DateTimeField.input_formats - - A list of formats used to attempt to convert a string to a valid - ``datetime.datetime`` object. - -If no ``input_formats`` argument is provided, the default input formats are:: - - '%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59' - '%Y-%m-%d %H:%M', # '2006-10-25 14:30' - '%Y-%m-%d', # '2006-10-25' - '%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59' - '%m/%d/%Y %H:%M', # '10/25/2006 14:30' - '%m/%d/%Y', # '10/25/2006' - '%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59' - '%m/%d/%y %H:%M', # '10/25/06 14:30' - '%m/%d/%y', # '10/25/06' - -.. versionchanged:: 1.0 - The ``DateTimeField`` used to use a ``TextInput`` widget by default. This has now changed. - -``DecimalField`` -~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. class:: DecimalField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``None`` - * Normalizes to: A Python ``decimal``. - * Validates that the given value is a decimal. Leading and trailing - whitespace is ignored. - * Error message keys: ``required``, ``invalid``, ``max_value``, - ``min_value``, ``max_digits``, ``max_decimal_places``, - ``max_whole_digits`` - -Takes four optional arguments: - -.. attribute:: DecimalField.max_value -.. attribute:: DecimalField.min_value - - These attributes define the limits for the fields value. - -.. attribute:: DecimalField.max_digits - - The maximum number of digits (those before the decimal point plus those - after the decimal point, with leading zeros stripped) permitted in the - value. - -.. attribute:: DecimalField.decimal_places - - The maximum number of decimal places permitted. - -``EmailField`` -~~~~~~~~~~~~~~ - -.. class:: EmailField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value is a valid e-mail address, using a - moderately complex regular expression. - * Error message keys: ``required``, ``invalid`` - -Has two optional arguments for validation, ``max_length`` and ``min_length``. -If provided, these arguments ensure that the string is at most or at least the -given length. - -.. versionchanged:: 1.2 - The EmailField previously did not recognize e-mail addresses as valid that - contained an IDN (Internationalized Domain Name; a domain containing - unicode characters) domain part. This has now been corrected. - -``FileField`` -~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. class:: FileField(**kwargs) - - * Default widget: ``FileInput`` - * Empty value: ``None`` - * Normalizes to: An ``UploadedFile`` object that wraps the file content - and file name into a single object. - * Validates that non-empty file data has been bound to the form. - * Error message keys: ``required``, ``invalid``, ``missing``, ``empty`` - -To learn more about the ``UploadedFile`` object, see the :doc:`file uploads -documentation </topics/http/file-uploads>`. - -When you use a ``FileField`` in a form, you must also remember to -:ref:`bind the file data to the form <binding-uploaded-files>`. - -``FilePathField`` -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. class:: FilePathField(**kwargs) - - * Default widget: ``Select`` - * Empty value: ``None`` - * Normalizes to: A unicode object - * Validates that the selected choice exists in the list of choices. - * Error message keys: ``required``, ``invalid_choice`` - -The field allows choosing from files inside a certain directory. It takes three -extra arguments; only ``path`` is required: - -.. attribute:: FilePathField.path - - The absolute path to the directory whose contents you want listed. This - directory must exist. - -.. attribute:: FilePathField.recursive - - If ``False`` (the default) only the direct contents of ``path`` will be - offered as choices. If ``True``, the directory will be descended into - recursively and all descendants will be listed as choices. - -.. attribute:: FilePathField.match - - A regular expression pattern; only files with names matching this expression - will be allowed as choices. - -``FloatField`` -~~~~~~~~~~~~~~ - - * Default widget: ``TextInput`` - * Empty value: ``None`` - * Normalizes to: A Python float. - * Validates that the given value is an float. Leading and trailing - whitespace is allowed, as in Python's ``float()`` function. - * Error message keys: ``required``, ``invalid``, ``max_value``, - ``min_value`` - -Takes two optional arguments for validation, ``max_value`` and ``min_value``. -These control the range of values permitted in the field. - -``ImageField`` -~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. class:: ImageField(**kwargs) - - * Default widget: ``FileInput`` - * Empty value: ``None`` - * Normalizes to: An ``UploadedFile`` object that wraps the file content - and file name into a single object. - * Validates that file data has been bound to the form, and that the - file is of an image format understood by PIL. - * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``, - ``invalid_image`` - -Using an ImageField requires that the `Python Imaging Library`_ is installed. - -When you use an ``ImageField`` on a form, you must also remember to -:ref:`bind the file data to the form <binding-uploaded-files>`. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - -``IntegerField`` -~~~~~~~~~~~~~~~~ - -.. class:: IntegerField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``None`` - * Normalizes to: A Python integer or long integer. - * Validates that the given value is an integer. Leading and trailing - whitespace is allowed, as in Python's ``int()`` function. - * Error message keys: ``required``, ``invalid``, ``max_value``, - ``min_value`` - -Takes two optional arguments for validation: - -.. attribute:: IntegerField.max_value -.. attribute:: IntegerField.min_value - - These control the range of values permitted in the field. - -``IPAddressField`` -~~~~~~~~~~~~~~~~~~ - -.. class:: IPAddressField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value is a valid IPv4 address, using a regular - expression. - * Error message keys: ``required``, ``invalid`` - -``MultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~ - -.. class:: MultipleChoiceField(**kwargs) - - * Default widget: ``SelectMultiple`` - * Empty value: ``[]`` (an empty list) - * Normalizes to: A list of Unicode objects. - * Validates that every value in the given list of values exists in the list - of choices. - * Error message keys: ``required``, ``invalid_choice``, ``invalid_list`` - -Takes one extra argument, ``choices``, as for ``ChoiceField``. - -``NullBooleanField`` -~~~~~~~~~~~~~~~~~~~~ - -.. class:: NullBooleanField(**kwargs) - - * Default widget: ``NullBooleanSelect`` - * Empty value: ``None`` - * Normalizes to: A Python ``True``, ``False`` or ``None`` value. - * Validates nothing (i.e., it never raises a ``ValidationError``). - -``RegexField`` -~~~~~~~~~~~~~~ - -.. class:: RegexField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value matches against a certain regular - expression. - * Error message keys: ``required``, ``invalid`` - -Takes one required argument: - -.. attribute:: RegexField.regex - - A regular expression specified either as a string or a compiled regular - expression object. - -Also takes ``max_length`` and ``min_length``, which work just as they do for -``CharField``. - -The optional argument ``error_message`` is also accepted for backwards -compatibility. The preferred way to provide an error message is to use the -``error_messages`` argument, passing a dictionary with ``'invalid'`` as a key -and the error message as the value. - -``SlugField`` -~~~~~~~~~~~~~ - -.. class:: SlugField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value contains only letters, numbers, - underscores, and hyphens. - * Error messages: ``required``, ``invalid`` - -This field is intended for use in representing a model -:class:`~django.db.models.SlugField` in forms. - -``TimeField`` -~~~~~~~~~~~~~ - -.. class:: TimeField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``None`` - * Normalizes to: A Python ``datetime.time`` object. - * Validates that the given value is either a ``datetime.time`` or string - formatted in a particular time format. - * Error message keys: ``required``, ``invalid`` - -Takes one optional argument: - -.. attribute:: TimeField.input_formats - - A list of formats used to attempt to convert a string to a valid - ``datetime.time`` object. - -If no ``input_formats`` argument is provided, the default input formats are:: - - '%H:%M:%S', # '14:30:59' - '%H:%M', # '14:30' - -``URLField`` -~~~~~~~~~~~~ - -.. class:: URLField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value is a valid URL. - * Error message keys: ``required``, ``invalid``, ``invalid_link`` - -Takes the following optional arguments: - -.. attribute:: URLField.max_length -.. attribute:: URLField.min_length - - Same as ``CharField.max_length`` and ``CharField.min_length``. - -.. attribute:: URLField.verify_exists - - If ``True``, the validator will attempt to load the given URL, raising - ``ValidationError`` if the page gives a 404. Defaults to ``False``. - -.. attribute:: URLField.validator_user_agent - - String used as the user-agent used when checking for a URL's existence. - Defaults to the value of the ``URL_VALIDATOR_USER_AGENT`` setting. - -.. versionchanged:: 1.2 - The URLField previously did not recognize URLs as valid that contained an IDN - (Internationalized Domain Name; a domain name containing unicode characters) - domain name. This has now been corrected. - - -Slightly complex built-in ``Field`` classes -------------------------------------------- - -``ComboField`` -~~~~~~~~~~~~~~ - -.. class:: ComboField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. - * Validates that the given value against each of the fields specified - as an argument to the ``ComboField``. - * Error message keys: ``required``, ``invalid`` - -Takes one extra required argument: - -.. attribute:: ComboField.fields - - The list of fields that should be used to validate the field's value (in - the order in which they are provided). - - >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) - >>> f.clean('test@example.com') - u'test@example.com' - >>> f.clean('longemailaddress@example.com') - Traceback (most recent call last): - ... - ValidationError: [u'Ensure this value has at most 20 characters (it has 28).'] - -``MultiValueField`` -~~~~~~~~~~~~~~~~~~~ - -.. class:: MultiValueField(**kwargs) - - * Default widget: ``TextInput`` - * Empty value: ``''`` (an empty string) - * Normalizes to: the type returned by the ``compress`` method of the subclass. - * Validates that the given value against each of the fields specified - as an argument to the ``MultiValueField``. - * Error message keys: ``required``, ``invalid`` - - This abstract field (must be subclassed) aggregates the logic of multiple - fields. Subclasses should not have to implement clean(). Instead, they must - implement compress(), which takes a list of valid values and returns a - "compressed" version of those values -- a single value. For example, - :class:`SplitDateTimeField` is a subclass which combines a time field and - a date field into a datetime object. - -Takes one extra required argument: - -.. attribute:: MultiValueField.fields - - A list of fields which are cleaned into a single field. Each value in - ``clean`` is cleaned by the corresponding field in ``fields`` -- the first - value is cleaned by the first field, the second value is cleaned by - the second field, etc. Once all fields are cleaned, the list of clean - values is "compressed" into a single value. - -``SplitDateTimeField`` -~~~~~~~~~~~~~~~~~~~~~~ - -.. class:: SplitDateTimeField(**kwargs) - - * Default widget: ``SplitDateTimeWidget`` - * Empty value: ``None`` - * Normalizes to: A Python ``datetime.datetime`` object. - * Validates that the given value is a ``datetime.datetime`` or string - formatted in a particular datetime format. - * Error message keys: ``required``, ``invalid`` - -Takes two optional arguments: - -.. attribute:: SplitDateTimeField.input_date_formats - - A list of formats used to attempt to convert a string to a valid - ``datetime.date`` object. - -If no ``input_date_formats`` argument is provided, the default input formats -for ``DateField`` are used. - -.. attribute:: SplitDateTimeField.input_time_formats - - A list of formats used to attempt to convert a string to a valid - ``datetime.time`` object. - -If no ``input_time_formats`` argument is provided, the default input formats -for ``TimeField`` are used. - -.. versionchanged:: 1.1 - The ``SplitDateTimeField`` previously used two ``TextInput`` widgets by - default. The ``input_date_formats`` and ``input_time_formats`` arguments - are also new. - -Fields which handle relationships ---------------------------------- - -Two fields are available for representing relationships between -models: :class:`ModelChoiceField` and -:class:`ModelMultipleChoiceField`. Both of these fields require a -single ``queryset`` parameter that is used to create the choices for -the field. Upon form validation, these fields will place either one -model object (in the case of ``ModelChoiceField``) or multiple model -objects (in the case of ``ModelMultipleChoiceField``) into the -``cleaned_data`` dictionary of the form. - -``ModelChoiceField`` -~~~~~~~~~~~~~~~~~~~~ - -.. class:: ModelChoiceField(**kwargs) - - * Default widget: ``Select`` - * Empty value: ``None`` - * Normalizes to: A model instance. - * Validates that the given id exists in the queryset. - * Error message keys: ``required``, ``invalid_choice`` - -Allows the selection of a single model object, suitable for -representing a foreign key. A single argument is required: - -.. attribute:: ModelChoiceField.queryset - - A ``QuerySet`` of model objects from which the choices for the - field will be derived, and which will be used to validate the - user's selection. - -``ModelChoiceField`` also takes one optional argument: - -.. attribute:: ModelChoiceField.empty_label - - By default the ``<select>`` widget used by ``ModelChoiceField`` will have a - an empty choice at the top of the list. You can change the text of this - label (which is ``"---------"`` by default) with the ``empty_label`` - attribute, or you can disable the empty label entirely by setting - ``empty_label`` to ``None``:: - - # A custom empty label - field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") - - # No empty label - field2 = forms.ModelChoiceField(queryset=..., empty_label=None) - - Note that if a ``ModelChoiceField`` is required and has a default - initial value, no empty choice is created (regardless of the value - of ``empty_label``). - -The ``__unicode__`` method of the model will be called to generate -string representations of the objects for use in the field's choices; -to provide customized representations, subclass ``ModelChoiceField`` -and override ``label_from_instance``. This method will receive a model -object, and should return a string suitable for representing it. For -example:: - - class MyModelChoiceField(ModelChoiceField): - def label_from_instance(self, obj): - return "My Object #%i" % obj.id - -``ModelMultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. class:: ModelMultipleChoiceField(**kwargs) - - * Default widget: ``SelectMultiple`` - * Empty value: ``[]`` (an empty list) - * Normalizes to: A list of model instances. - * Validates that every id in the given list of values exists in the - queryset. - * Error message keys: ``required``, ``list``, ``invalid_choice``, - ``invalid_pk_value`` - -Allows the selection of one or more model objects, suitable for -representing a many-to-many relation. As with :class:`ModelChoiceField`, -you can use ``label_from_instance`` to customize the object -representations, and ``queryset`` is a required parameter: - -.. attribute:: ModelMultipleChoiceField.queryset - - A ``QuerySet`` of model objects from which the choices for the - field will be derived, and which will be used to validate the - user's selection. - -Creating custom fields ----------------------- - -If the built-in ``Field`` classes don't meet your needs, you can easily create -custom ``Field`` classes. To do this, just create a subclass of -``django.forms.Field``. Its only requirements are that it implement a -``clean()`` method and that its ``__init__()`` method accept the core arguments -mentioned above (``required``, ``label``, ``initial``, ``widget``, -``help_text``). diff --git a/parts/django/docs/ref/forms/index.txt b/parts/django/docs/ref/forms/index.txt deleted file mode 100644 index 866afed..0000000 --- a/parts/django/docs/ref/forms/index.txt +++ /dev/null @@ -1,13 +0,0 @@ -===== -Forms -===== - -Detailed form API reference. For introductory material, see :doc:`/topics/forms/index`. - -.. toctree:: - :maxdepth: 2 - - api - fields - widgets - validation diff --git a/parts/django/docs/ref/forms/validation.txt b/parts/django/docs/ref/forms/validation.txt deleted file mode 100644 index 1c047f2..0000000 --- a/parts/django/docs/ref/forms/validation.txt +++ /dev/null @@ -1,366 +0,0 @@ -Form and field validation -========================= - -.. versionchanged:: 1.2 - -Form validation happens when the data is cleaned. If you want to customize -this process, there are various places you can change, each one serving a -different purpose. Three types of cleaning methods are run during form -processing. These are normally executed when you call the ``is_valid()`` -method on a form. There are other things that can trigger cleaning and -validation (accessing the ``errors`` attribute or calling ``full_clean()`` -directly), but normally they won't be needed. - -In general, any cleaning method can raise ``ValidationError`` if there is a -problem with the data it is processing, passing the relevant error message to -the ``ValidationError`` constructor. If no ``ValidationError`` is raised, the -method should return the cleaned (normalized) data as a Python object. - -If you detect multiple errors during a cleaning method and wish to signal all -of them to the form submitter, it is possible to pass a list of errors to the -``ValidationError`` constructor. - -Most validation can be done using `validators`_ - simple helpers that can be -reused easily. Validators are simple functions (or callables) that take a single -argument and raise ``ValidationError`` on invalid input. Validators are run -after the field's ``to_python`` and ``validate`` methods have been called. - -Validation of a Form is split into several steps, which can be customized or -overridden: - - * The ``to_python()`` method on a Field is the first step in every - validation. It coerces the value to correct datatype and raises - ``ValidationError`` if that is not possible. This method accepts the raw - value from the widget and returns the converted value. For example, a - FloatField will turn the data into a Python ``float`` or raise a - ``ValidationError``. - - * The ``validate()`` method on a Field handles field-specific validation - that is not suitable for a validator, It takes a value that has been - coerced to correct datatype and raises ``ValidationError`` on any error. - This method does not return anything and shouldn't alter the value. You - should override it to handle validation logic that you can't or don't - want to put in a validator. - - * The ``run_validators()`` method on a Field runs all of the field's - validators and aggregates all the errors into a single - ``ValidationError``. You shouldn't need to override this method. - - * The ``clean()`` method on a Field subclass. This is responsible for - running ``to_python``, ``validate`` and ``run_validators`` in the correct - order and propagating their errors. If, at any time, any of the methods - raise ``ValidationError``, the validation stops and that error is raised. - This method returns the clean data, which is then inserted into the - ``cleaned_data`` dictionary of the form. - - * The ``clean_<fieldname>()`` method in a form subclass -- where - ``<fieldname>`` is replaced with the name of the form field attribute. - This method does any cleaning that is specific to that particular - attribute, unrelated to the type of field that it is. This method is not - passed any parameters. You will need to look up the value of the field - in ``self.cleaned_data`` and remember that it will be a Python object - at this point, not the original string submitted in the form (it will be - in ``cleaned_data`` because the general field ``clean()`` method, above, - has already cleaned the data once). - - For example, if you wanted to validate that the contents of a - ``CharField`` called ``serialnumber`` was unique, - ``clean_serialnumber()`` would be the right place to do this. You don't - need a specific field (it's just a ``CharField``), but you want a - formfield-specific piece of validation and, possibly, - cleaning/normalizing the data. - - Just like the general field ``clean()`` method, above, this method - should return the cleaned data, regardless of whether it changed - anything or not. - - * The Form subclass's ``clean()`` method. This method can perform - any validation that requires access to multiple fields from the form at - once. This is where you might put in things to check that if field ``A`` - is supplied, field ``B`` must contain a valid e-mail address and the - like. The data that this method returns is the final ``cleaned_data`` - attribute for the form, so don't forget to return the full list of - cleaned data if you override this method (by default, ``Form.clean()`` - just returns ``self.cleaned_data``). - - Note that any errors raised by your ``Form.clean()`` override will not - be associated with any field in particular. They go into a special - "field" (called ``__all__``), which you can access via the - ``non_field_errors()`` method if you need to. If you want to attach - errors to a specific field in the form, you will need to access the - ``_errors`` attribute on the form, which is `described later`_. - - Also note that there are special considerations when overriding - the ``clean()`` method of a ``ModelForm`` subclass. (see the - :ref:`ModelForm documentation - <overriding-modelform-clean-method>` for more information) - -These methods are run in the order given above, one field at a time. That is, -for each field in the form (in the order they are declared in the form -definition), the ``Field.clean()`` method (or its override) is run, then -``clean_<fieldname>()``. Finally, once those two methods are run for every -field, the ``Form.clean()`` method, or its override, is executed. - -Examples of each of these methods are provided below. - -As mentioned, any of these methods can raise a ``ValidationError``. For any -field, if the ``Field.clean()`` method raises a ``ValidationError``, any -field-specific cleaning method is not called. However, the cleaning methods -for all remaining fields are still executed. - -The ``clean()`` method for the ``Form`` class or subclass is always run. If -that method raises a ``ValidationError``, ``cleaned_data`` will be an empty -dictionary. - -The previous paragraph means that if you are overriding ``Form.clean()``, you -should iterate through ``self.cleaned_data.items()``, possibly considering the -``_errors`` dictionary attribute on the form as well. In this way, you will -already know which fields have passed their individual validation requirements. - -.. _described later: - -Form subclasses and modifying field errors ------------------------------------------- - -Sometimes, in a form's ``clean()`` method, you will want to add an error -message to a particular field in the form. This won't always be appropriate -and the more typical situation is to raise a ``ValidationError`` from -``Form.clean()``, which is turned into a form-wide error that is available -through the ``Form.non_field_errors()`` method. - -When you really do need to attach the error to a particular field, you should -store (or amend) a key in the ``Form._errors`` attribute. This attribute is an -instance of a ``django.forms.util.ErrorDict`` class. Essentially, though, it's -just a dictionary. There is a key in the dictionary for each field in the form -that has an error. Each value in the dictionary is a -``django.forms.util.ErrorList`` instance, which is a list that knows how to -display itself in different ways. So you can treat ``_errors`` as a dictionary -mapping field names to lists. - -If you want to add a new error to a particular field, you should check whether -the key already exists in ``self._errors`` or not. If not, create a new entry -for the given key, holding an empty ``ErrorList`` instance. In either case, -you can then append your error message to the list for the field name in -question and it will be displayed when the form is displayed. - -There is an example of modifying ``self._errors`` in the following section. - -.. admonition:: What's in a name? - - You may be wondering why is this attribute called ``_errors`` and not - ``errors``. Normal Python practice is to prefix a name with an underscore - if it's not for external usage. In this case, you are subclassing the - ``Form`` class, so you are essentially writing new internals. In effect, - you are given permission to access some of the internals of ``Form``. - - Of course, any code outside your form should never access ``_errors`` - directly. The data is available to external code through the ``errors`` - property, which populates ``_errors`` before returning it). - - Another reason is purely historical: the attribute has been called - ``_errors`` since the early days of the forms module and changing it now - (particularly since ``errors`` is used for the read-only property name) - would be inconvenient for a number of reasons. You can use whichever - explanation makes you feel more comfortable. The result is the same. - -Using validation in practice ----------------------------- - -The previous sections explained how validation works in general for forms. -Since it can sometimes be easier to put things into place by seeing each -feature in use, here are a series of small examples that use each of the -previous features. - -.. _validators: - -Using validators -~~~~~~~~~~~~~~~~ -.. versionadded:: 1.2 - -Django's form (and model) fields support use of simple utility functions and -classes known as validators. These can be passed to a field's constructor, via -the field's ``validators`` argument, or defined on the Field class itself with -the ``default_validators`` attribute. - -Simple validators can be used to validate values inside the field, let's have -a look at Django's ``EmailField``:: - - class EmailField(CharField): - default_error_messages = { - 'invalid': _(u'Enter a valid e-mail address.'), - } - default_validators = [validators.validate_email] - -As you can see, ``EmailField`` is just a ``CharField`` with customized error -message and a validator that validates e-mail addresses. This can also be done -on field definition so:: - - email = forms.EmailField() - -is equivalent to:: - - email = forms.CharField(validators=[validators.validate_email], - error_messages={'invalid': _(u'Enter a valid e-mail address.')}) - - -Form field default cleaning -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Let's firstly create a custom form field that validates its input is a string -containing comma-separated e-mail addresses. The full class looks like this:: - - from django import forms - from django.core.validators import validate_email - - class MultiEmailField(forms.Field): - def to_python(self, value): - "Normalize data to a list of strings." - - # Return an empty list if no input was given. - if not value: - return [] - return value.split(',') - - def validate(self, value): - "Check if value consists only of valid emails." - - # Use the parent's handling of required fields, etc. - super(MultiEmailField, self).validate(value) - - for email in value: - validate_email(email) - -Every form that uses this field will have these methods run before anything -else can be done with the field's data. This is cleaning that is specific to -this type of field, regardless of how it is subsequently used. - -Let's create a simple ``ContactForm`` to demonstrate how you'd use this -field:: - - class ContactForm(forms.Form): - subject = forms.CharField(max_length=100) - message = forms.CharField() - sender = forms.EmailField() - recipients = MultiEmailField() - cc_myself = forms.BooleanField(required=False) - -Simply use ``MultiEmailField`` like any other form field. When the -``is_valid()`` method is called on the form, the ``MultiEmailField.clean()`` -method will be run as part of the cleaning process and it will, in turn, call -the custom ``to_python()`` and ``validate()`` methods. - -Cleaning a specific field attribute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Continuing on from the previous example, suppose that in our ``ContactForm``, -we want to make sure that the ``recipients`` field always contains the address -``"fred@example.com"``. This is validation that is specific to our form, so we -don't want to put it into the general ``MultiEmailField`` class. Instead, we -write a cleaning method that operates on the ``recipients`` field, like so:: - - class ContactForm(forms.Form): - # Everything as before. - ... - - def clean_recipients(self): - data = self.cleaned_data['recipients'] - if "fred@example.com" not in data: - raise forms.ValidationError("You have forgotten about Fred!") - - # Always return the cleaned data, whether you have changed it or - # not. - return data - -Cleaning and validating fields that depend on each other -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Suppose we add another requirement to our contact form: if the ``cc_myself`` -field is ``True``, the ``subject`` must contain the word ``"help"``. We are -performing validation on more than one field at a time, so the form's -``clean()`` method is a good spot to do this. Notice that we are talking about -the ``clean()`` method on the form here, whereas earlier we were writing a -``clean()`` method on a field. It's important to keep the field and form -difference clear when working out where to validate things. Fields are single -data points, forms are a collection of fields. - -By the time the form's ``clean()`` method is called, all the individual field -clean methods will have been run (the previous two sections), so -``self.cleaned_data`` will be populated with any data that has survived so -far. So you also need to remember to allow for the fact that the fields you -are wanting to validate might not have survived the initial individual field -checks. - -There are two way to report any errors from this step. Probably the most -common method is to display the error at the top of the form. To create such -an error, you can raise a ``ValidationError`` from the ``clean()`` method. For -example:: - - class ContactForm(forms.Form): - # Everything as before. - ... - - def clean(self): - cleaned_data = self.cleaned_data - cc_myself = cleaned_data.get("cc_myself") - subject = cleaned_data.get("subject") - - if cc_myself and subject: - # Only do something if both fields are valid so far. - if "help" not in subject: - raise forms.ValidationError("Did not send for 'help' in " - "the subject despite CC'ing yourself.") - - # Always return the full collection of cleaned data. - return cleaned_data - -In this code, if the validation error is raised, the form will display an -error message at the top of the form (normally) describing the problem. - -The second approach might involve assigning the error message to one of the -fields. In this case, let's assign an error message to both the "subject" and -"cc_myself" rows in the form display. Be careful when doing this in practice, -since it can lead to confusing form output. We're showing what is possible -here and leaving it up to you and your designers to work out what works -effectively in your particular situation. Our new code (replacing the previous -sample) looks like this:: - - class ContactForm(forms.Form): - # Everything as before. - ... - - def clean(self): - cleaned_data = self.cleaned_data - cc_myself = cleaned_data.get("cc_myself") - subject = cleaned_data.get("subject") - - if cc_myself and subject and "help" not in subject: - # We know these are not in self._errors now (see discussion - # below). - msg = u"Must put 'help' in subject when cc'ing yourself." - self._errors["cc_myself"] = self.error_class([msg]) - self._errors["subject"] = self.error_class([msg]) - - # These fields are no longer valid. Remove them from the - # cleaned data. - del cleaned_data["cc_myself"] - del cleaned_data["subject"] - - # Always return the full collection of cleaned data. - return cleaned_data - -As you can see, this approach requires a bit more effort, not withstanding the -extra design effort to create a sensible form display. The details are worth -noting, however. Firstly, earlier we mentioned that you might need to check if -the field name keys already exist in the ``_errors`` dictionary. In this case, -since we know the fields exist in ``self.cleaned_data``, they must have been -valid when cleaned as individual fields, so there will be no corresponding -entries in ``_errors``. - -Secondly, once we have decided that the combined data in the two fields we are -considering aren't valid, we must remember to remove them from the -``cleaned_data``. - -In fact, Django will currently completely wipe out the ``cleaned_data`` -dictionary if there are any errors in the form. However, this behaviour may -change in the future, so it's not a bad idea to clean up after yourself in the -first place. diff --git a/parts/django/docs/ref/forms/widgets.txt b/parts/django/docs/ref/forms/widgets.txt deleted file mode 100644 index 9d78b84..0000000 --- a/parts/django/docs/ref/forms/widgets.txt +++ /dev/null @@ -1,247 +0,0 @@ -======= -Widgets -======= - -.. module:: django.forms.widgets - :synopsis: Django's built-in form widgets. - -.. currentmodule:: django.forms - -A widget is Django's representation of a HTML input element. The widget -handles the rendering of the HTML, and the extraction of data from a GET/POST -dictionary that corresponds to the widget. - -Django provides a representation of all the basic HTML widgets, plus some -commonly used groups of widgets: - -.. class:: TextInput - - Text input: ``<input type='text' ...>`` - -.. class:: PasswordInput - - Password input: ``<input type='password' ...>`` - - Takes one optional argument: - - .. attribute:: PasswordInput.render_value - - Determines whether the widget will have a value filled in when the - form is re-displayed after a validation error (default is ``True``). - -.. class:: HiddenInput - - Hidden input: ``<input type='hidden' ...>`` - -.. class:: MultipleHiddenInput - - Multiple ``<input type='hidden' ...>`` widgets. - -.. class:: FileInput - - File upload input: ``<input type='file' ...>`` - -.. class:: DateInput - - .. versionadded:: 1.1 - - Date input as a simple text box: ``<input type='text' ...>`` - - Takes one optional argument: - - .. attribute:: DateInput.format - - The format in which this field's initial value will be displayed. - - If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``. - -.. class:: DateTimeInput - - .. versionadded:: 1.0 - - Date/time input as a simple text box: ``<input type='text' ...>`` - - Takes one optional argument: - - .. attribute:: DateTimeInput.format - - The format in which this field's initial value will be displayed. - - If no ``format`` argument is provided, the default format is ``'%Y-%m-%d - %H:%M:%S'``. - -.. class:: TimeInput - - Time input as a simple text box: ``<input type='text' ...>`` - - Takes one optional argument: - - .. attribute:: TimeInput.format - - The format in which this field's initial value will be displayed. - - If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``. - - .. versionchanged:: 1.1 - The ``format`` argument was not supported in Django 1.0. - -.. class:: Textarea - - Text area: ``<textarea>...</textarea>`` - -.. class:: CheckboxInput - - Checkbox: ``<input type='checkbox' ...>`` - - Takes one optional argument: - - .. attribute:: CheckboxInput.check_test - - A callable that takes the value of the CheckBoxInput - and returns ``True`` if the checkbox should be checked for - that value. - -.. class:: Select - - Select widget: ``<select><option ...>...</select>`` - - Requires that your field provides :attr:`~Field.choices`. - -.. class:: NullBooleanSelect - - Select widget with options 'Unknown', 'Yes' and 'No' - -.. class:: SelectMultiple - - Select widget allowing multiple selection: ``<select - multiple='multiple'>...</select>`` - - Requires that your field provides :attr:`~Field.choices`. - -.. class:: RadioSelect - - A list of radio buttons: - - .. code-block:: html - - <ul> - <li><input type='radio' ...></li> - ... - </ul> - - Requires that your field provides :attr:`~Field.choices`. - -.. class:: CheckboxSelectMultiple - - A list of checkboxes: - - .. code-block:: html - - <ul> - <li><input type='checkbox' ...></li> - ... - </ul> - -.. class:: MultiWidget - - Wrapper around multiple other widgets - -.. class:: SplitDateTimeWidget - - Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput`` - for the time. - - Takes two optional arguments, ``date_format`` and ``time_format``, which - work just like the ``format`` argument for ``DateInput`` and ``TimeInput``. - - .. versionchanged:: 1.1 - The ``date_format`` and ``time_format`` arguments were not supported in Django 1.0. - -.. class:: SelectDateWidget - - Wrapper around three select widgets: one each for month, day, and year. - Note that this widget lives in a separate file from the standard widgets. - - .. code-block:: python - - from django.forms.extras.widgets import SelectDateWidget - - date = forms.DateField(widget=SelectDateWidget()) - -Specifying widgets ------------------- - -.. attribute:: Form.widget - -Whenever you specify a field on a form, Django will use a default widget -that is appropriate to the type of data that is to be displayed. To find -which widget is used on which field, see the documentation for the -built-in Field classes. - -However, if you want to use a different widget for a field, you can - -just use the 'widget' argument on the field definition. For example:: - - from django import forms - - class CommentForm(forms.Form): - name = forms.CharField() - url = forms.URLField() - comment = forms.CharField(widget=forms.Textarea) - -This would specify a form with a comment that uses a larger Textarea widget, -rather than the default TextInput widget. - -Customizing widget instances ----------------------------- - -When Django renders a widget as HTML, it only renders the bare minimum -HTML - Django doesn't add a class definition, or any other widget-specific -attributes. This means that all 'TextInput' widgets will appear the same -on your Web page. - -If you want to make one widget look different to another, you need to -specify additional attributes for each widget. When you specify a -widget, you can provide a list of attributes that will be added to the -rendered HTML for the widget. - -For example, take the following simple form:: - - class CommentForm(forms.Form): - name = forms.CharField() - url = forms.URLField() - comment = forms.CharField() - -This form will include three default TextInput widgets, with default rendering - -no CSS class, no extra attributes. This means that the input boxes provided for -each widget will be rendered exactly the same:: - - >>> f = CommentForm(auto_id=False) - >>> f.as_table() - <tr><th>Name:</th><td><input type="text" name="name" /></td></tr> - <tr><th>Url:</th><td><input type="text" name="url"/></td></tr> - <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> - - -On a real Web page, you probably don't want every widget to look the same. You -might want a larger input element for the comment, and you might want the 'name' -widget to have some special CSS class. To do this, you use the ``attrs`` -argument when creating the widget: - -.. attribute:: Widget.attrs - -For example:: - - class CommentForm(forms.Form): - name = forms.CharField( - widget=forms.TextInput(attrs={'class':'special'})) - url = forms.URLField() - comment = forms.CharField( - widget=forms.TextInput(attrs={'size':'40'})) - -Django will then include the extra attributes in the rendered output:: - - >>> f = CommentForm(auto_id=False) - >>> f.as_table() - <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr> - <tr><th>Url:</th><td><input type="text" name="url"/></td></tr> - <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr> diff --git a/parts/django/docs/ref/generic-views.txt b/parts/django/docs/ref/generic-views.txt deleted file mode 100644 index ea7fe2a..0000000 --- a/parts/django/docs/ref/generic-views.txt +++ /dev/null @@ -1,1095 +0,0 @@ -============= -Generic views -============= - -Writing Web applications can be monotonous, because we repeat certain patterns -again and again. In Django, the most common of these patterns have been -abstracted into "generic views" that let you quickly provide common views of -an object without actually needing to write any Python code. - -A general introduction to generic views can be found in the :doc:`topic guide -</topics/http/generic-views>`. - -This reference contains details of Django's built-in generic views, along with -a list of all keyword arguments that a generic view expects. Remember that -arguments may either come from the URL pattern or from the ``extra_context`` -additional-information dictionary. - -Most generic views require the ``queryset`` key, which is a ``QuerySet`` -instance; see :doc:`/topics/db/queries` for more information about ``QuerySet`` -objects. - -"Simple" generic views -====================== - -The ``django.views.generic.simple`` module contains simple views to handle a -couple of common cases: rendering a template when no view logic is needed, -and issuing a redirect. - -``django.views.generic.simple.direct_to_template`` --------------------------------------------------- - -**Description:** - -Renders a given template, passing it a ``{{ params }}`` template variable, -which is a dictionary of the parameters captured in the URL. - -**Required arguments:** - - * ``template``: The full name of a template to use. - -**Optional arguments:** - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_CONTENT_TYPE`` setting. - -**Example:** - -Given the following URL patterns:: - - urlpatterns = patterns('django.views.generic.simple', - (r'^foo/$', 'direct_to_template', {'template': 'foo_index.html'}), - (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}), - ) - -... a request to ``/foo/`` would render the template ``foo_index.html``, and a -request to ``/foo/15/`` would render the ``foo_detail.html`` with a context -variable ``{{ params.id }}`` that is set to ``15``. - -``django.views.generic.simple.redirect_to`` -------------------------------------------- - -**Description:** - -Redirects to a given URL. - -The given URL may contain dictionary-style string formatting, which will be -interpolated against the parameters captured in the URL. Because keyword -interpolation is *always* done (even if no arguments are passed in), any ``"%"`` -characters in the URL must be written as ``"%%"`` so that Python will convert -them to a single percent sign on output. - -If the given URL is ``None``, Django will return an ``HttpResponseGone`` (410). - -**Required arguments:** - - * ``url``: The URL to redirect to, as a string. Or ``None`` to raise a 410 - (Gone) HTTP error. - -**Optional arguments:** - - * ``permanent``: Whether the redirect should be permanent. The only - difference here is the HTTP status code returned. If ``True``, then the - redirect will use status code 301. If ``False``, then the redirect will - use status code 302. By default, ``permanent`` is ``True``. - -.. versionadded:: 1.1 - The ``permanent`` keyword argument is new in Django 1.1. - -**Example:** - -This example issues a permanent redirect (HTTP status code 301) from -``/foo/<id>/`` to ``/bar/<id>/``:: - - urlpatterns = patterns('django.views.generic.simple', - ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}), - ) - -This example issues a non-permanent redirect (HTTP status code 302) from -``/foo/<id>/`` to ``/bar/<id>/``:: - - urlpatterns = patterns('django.views.generic.simple', - ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/', 'permanent': False}), - ) - -This example returns a 410 HTTP error for requests to ``/bar/``:: - - urlpatterns = patterns('django.views.generic.simple', - ('^bar/$', 'redirect_to', {'url': None}), - ) - -This example shows how ``"%"`` characters must be written in the URL in order -to avoid confusion with Python's string formatting markers. If the redirect -string is written as ``"%7Ejacob/"`` (with only a single ``%``), an exception would be raised:: - - urlpatterns = patterns('django.views.generic.simple', - ('^bar/$', 'redirect_to', {'url': '%%7Ejacob.'}), - ) - -Date-based generic views -======================== - -Date-based generic views (in the module ``django.views.generic.date_based``) -are views for displaying drilldown pages for date-based data. - -``django.views.generic.date_based.archive_index`` -------------------------------------------------- - -**Description:** - -A top-level index page showing the "latest" objects, by date. Objects with -a date in the *future* are not included unless you set ``allow_future`` to -``True``. - -**Required arguments:** - - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. - - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. - -**Optional arguments:** - - * ``num_latest``: The number of latest objects to send to the template - context. By default, it's 15. - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``True``. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - 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``. - - .. versionadded:: 1.0 - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'latest'``. - -**Template name:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_archive.html`` by default, where: - - * ``<model_name>`` is your model's name in all lowercase. For a model - ``StaffMember``, that'd be ``staffmember``. - - * ``<app_label>`` is the right-most part of the full Python path to - your model's app. For example, if your model lives in - ``apps/blog/models.py``, that'd be ``blog``. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``date_list``: A ``DateQuerySet`` object containing all years that have - have objects available according to ``queryset``, represented as - ``datetime.datetime`` objects. These are ordered in reverse. This is - equivalent to ``queryset.dates(date_field, 'year')[::-1]``. - - .. versionchanged:: 1.0 - The behaviour depending on ``template_object_name`` is new in this version. - - * ``latest``: The ``num_latest`` objects in the system, ordered descending - by ``date_field``. For example, if ``num_latest`` is ``10``, then - ``latest`` will be a list of the latest 10 objects in ``queryset``. - - This variable's name depends on the ``template_object_name`` parameter, - which is ``'latest'`` by default. If ``template_object_name`` is - ``'foo'``, this variable's name will be ``foo``. - -``django.views.generic.date_based.archive_year`` ------------------------------------------------- - -**Description:** - -A yearly archive page showing all available months in a given year. Objects -with a date in the *future* are not displayed unless you set ``allow_future`` -to ``True``. - -**Required arguments:** - - * ``year``: The four-digit year for which the archive serves. - - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. - - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. - -**Optional arguments:** - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``False``. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. - - * ``make_object_list``: A boolean specifying whether to retrieve the full - list of objects for this year and pass those to the template. If ``True``, - this list of objects will be made available to the template as - ``object_list``. (The name ``object_list`` may be different; see the docs - for ``object_list`` in the "Template context" section below.) By default, - this is ``False``. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - 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:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_archive_year.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``date_list``: A ``DateQuerySet`` object containing all months that have - have objects available according to ``queryset``, represented as - ``datetime.datetime`` objects, in ascending order. - - * ``year``: The given year, as a four-character string. - - * ``object_list``: If the ``make_object_list`` parameter is ``True``, this - will be set to a list of objects available for the given year, ordered by - the date field. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo_list``. - - If ``make_object_list`` is ``False``, ``object_list`` will be passed to - the template as an empty list. - -``django.views.generic.date_based.archive_month`` -------------------------------------------------- - -**Description:** - -A monthly archive page showing all objects in a given month. Objects with a -date in the *future* are not displayed unless you set ``allow_future`` to -``True``. - -**Required arguments:** - - * ``year``: The four-digit year for which the archive serves (a string). - - * ``month``: The month for which the archive serves, formatted according to - the ``month_format`` argument. - - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. - - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. - -**Optional arguments:** - - * ``month_format``: A format string that regulates what format the - ``month`` parameter uses. This should be in the syntax accepted by - Python's ``time.strftime``. (See the `strftime docs`_.) It's set to - ``"%b"`` by default, which is a three-letter month abbreviation. To - change it to use numbers, use ``"%m"``. - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``False``. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - 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:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_archive_month.html`` by default. - -**Template context:** - -.. versionadded:: 1.2 - The inclusion of ``date_list`` in the template's context is new. - -In addition to ``extra_context``, the template's context will be: - - * ``date_list``: A ``DateQuerySet`` object containing all days that have - have objects available in the given month, according to ``queryset``, - represented as ``datetime.datetime`` objects, in ascending order. - - * ``month``: A ``datetime.date`` object representing the given month. - - * ``next_month``: A ``datetime.date`` object representing the first day of - the next month. If the next month is in the future, this will be - ``None``. - - * ``previous_month``: A ``datetime.date`` object representing the first day - of the previous month. Unlike ``next_month``, this will never be - ``None``. - - * ``object_list``: A list of objects available for the given month. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo_list``. - -.. _strftime docs: http://docs.python.org/library/time.html#time.strftime - -``django.views.generic.date_based.archive_week`` ------------------------------------------------- - -**Description:** - -A weekly archive page showing all objects in a given week. Objects with a date -in the *future* are not displayed unless you set ``allow_future`` to ``True``. - -**Required arguments:** - - * ``year``: The four-digit year for which the archive serves (a string). - - * ``week``: The week of the year for which the archive serves (a string). - Weeks start with Sunday. - - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. - - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. - -**Optional arguments:** - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``True``. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - 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:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_archive_week.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``week``: A ``datetime.date`` object representing the first day of the - given week. - - * ``object_list``: A list of objects available for the given week. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo_list``. - -``django.views.generic.date_based.archive_day`` ------------------------------------------------ - -**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, unless -you set ``allow_future`` to ``True``. - -**Required arguments:** - - * ``year``: The four-digit year for which the archive serves (a string). - - * ``month``: The month for which the archive serves, formatted according to - the ``month_format`` argument. - - * ``day``: The day for which the archive serves, formatted according to the - ``day_format`` argument. - - * ``queryset``: A ``QuerySet`` of objects for which the archive serves. - - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the date-based archive should use to - determine the objects on the page. - -**Optional arguments:** - - * ``month_format``: A format string that regulates what format the - ``month`` parameter uses. This should be in the syntax accepted by - Python's ``time.strftime``. (See the `strftime docs`_.) It's set to - ``"%b"`` by default, which is a three-letter month abbreviation. To - change it to use numbers, use ``"%m"``. - - * ``day_format``: Like ``month_format``, but for the ``day`` parameter. - It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``False``. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - 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:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_archive_day.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``day``: A ``datetime.date`` object representing the given day. - - * ``next_day``: A ``datetime.date`` object representing the next day. If - the next day is in the future, this will be ``None``. - - * ``previous_day``: A ``datetime.date`` object representing the previous day. - Unlike ``next_day``, this will never be ``None``. - - * ``object_list``: A list of objects available for the given day. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo_list``. - -``django.views.generic.date_based.archive_today`` -------------------------------------------------- - -**Description:** - -A day archive page showing all objects for *today*. This is exactly the same as -``archive_day``, except the ``year``/``month``/``day`` arguments are not used, -and today's date is used instead. - -``django.views.generic.date_based.object_detail`` -------------------------------------------------- - -**Description:** - -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:** - - * ``year``: The object's four-digit year (a string). - - * ``month``: The object's month , formatted according to the - ``month_format`` argument. - - * ``day``: The object's day , formatted according to the ``day_format`` - argument. - - * ``queryset``: A ``QuerySet`` that contains the object. - - * ``date_field``: The name of the ``DateField`` or ``DateTimeField`` in - the ``QuerySet``'s model that the generic view should use to look up the - object according to ``year``, ``month`` and ``day``. - - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. - - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. - -**Optional arguments:** - - * ``month_format``: A format string that regulates what format the - ``month`` parameter uses. This should be in the syntax accepted by - Python's ``time.strftime``. (See the `strftime docs`_.) It's set to - ``"%b"`` by default, which is a three-letter month abbreviation. To - change it to use numbers, use ``"%m"``. - - * ``day_format``: Like ``month_format``, but for the ``day`` parameter. - It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_name_field``: The name of a field on the object whose value is - the template name to use. This lets you store template names in the data. - In other words, if your object has a field ``'the_template'`` that - contains a string ``'foo.html'``, and you set ``template_name_field`` to - ``'the_template'``, then the generic view for this object will use the - template ``'foo.html'``. - - It's a bit of a brain-bender, but it's useful in some cases. - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - 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_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:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_detail.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``object``: The object. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo``. - -List/detail generic views -========================= - -The list-detail generic-view framework (in the -``django.views.generic.list_detail`` module) is similar to the date-based one, -except the former simply has two views: a list of objects and an individual -object page. - -``django.views.generic.list_detail.object_list`` ------------------------------------------------- - -**Description:** - -A page representing a list of objects. - -**Required arguments:** - - * ``queryset``: A ``QuerySet`` that represents the objects. - -**Optional arguments:** - - * ``paginate_by``: An integer specifying how many objects should be - displayed per page. If this is given, the view will paginate objects with - ``paginate_by`` objects per page. The view will expect either a ``page`` - query string parameter (via ``GET``) or a ``page`` variable specified in - the URLconf. See `Notes on pagination`_ below. - - * ``page``: The current page number, as an integer, or the string - ``'last'``. This is 1-based. See `Notes on pagination`_ below. - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``allow_empty``: A boolean specifying whether to display the page if no - objects are available. If this is ``False`` and no objects are available, - the view will raise a 404 instead of displaying an empty page. By - default, this is ``True``. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. - - * ``mimetype``: The MIME type to use for the resulting document. Defaults - to the value of the ``DEFAULT_CONTENT_TYPE`` setting. - -**Template name:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_list.html`` by default. - -**Template context:** - -.. versionadded:: 1.0 - The ``paginator`` and ``page_obj`` context variables are new. - -In addition to ``extra_context``, the template's context will be: - - * ``object_list``: The list of objects. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo_list``. - - * ``is_paginated``: A boolean representing whether the results are - paginated. Specifically, this is set to ``False`` if the number of - available objects is less than or equal to ``paginate_by``. - -If the results are paginated, the context will contain these extra variables: - - * ``paginator``: An instance of ``django.core.paginator.Paginator``. - - * ``page_obj``: An instance of ``django.core.paginator.Page``. - -Notes on pagination -~~~~~~~~~~~~~~~~~~~ - -If ``paginate_by`` is specified, Django will paginate the results. You can -specify the page number in the URL in one of two ways: - - * Use the ``page`` parameter in the URLconf. For example, this is what - your URLconf might look like:: - - (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict)) - - * Pass the page number via the ``page`` query-string parameter. For - example, a URL would look like this:: - - /objects/?page=3 - - * To loop over all the available page numbers, use the ``page_range`` - variable. You can iterate over the list provided by ``page_range`` - to create a link to every page of results. - -These values and lists are 1-based, not 0-based, so the first page would be -represented as page ``1``. - -For more on pagination, read the :doc:`pagination documentation -</topics/pagination>`. - -.. versionadded:: 1.0 - -As a special case, you are also permitted to use ``last`` as a value for -``page``:: - - /objects/?page=last - -This allows you to access the final page of results without first having to -determine how many pages there are. - -Note that ``page`` *must* be either a valid page number or the value ``last``; -any other value for ``page`` will result in a 404 error. - -``django.views.generic.list_detail.object_detail`` --------------------------------------------------- - -A page representing an individual object. - -**Description:** - -A page representing an individual object. - -**Required arguments:** - - * ``queryset``: A ``QuerySet`` that contains the object. - - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. - - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. - -**Optional arguments:** - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_name_field``: The name of a field on the object whose value is - the template name to use. This lets you store template names in the data. - In other words, if your object has a field ``'the_template'`` that - contains a string ``'foo.html'``, and you set ``template_name_field`` to - ``'the_template'``, then the generic view for this object will use the - template ``'foo.html'``. - - It's a bit of a brain-bender, but it's useful in some cases. - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - 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_CONTENT_TYPE`` setting. - -**Template name:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_detail.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``object``: The object. This variable's name depends on the - ``template_object_name`` parameter, which is ``'object'`` by default. If - ``template_object_name`` is ``'foo'``, this variable's name will be - ``foo``. - -Create/update/delete generic views -================================== - -The ``django.views.generic.create_update`` module contains a set of functions -for creating, editing and deleting objects. - -.. versionchanged:: 1.0 - -``django.views.generic.create_update.create_object`` and -``django.views.generic.create_update.update_object`` now use the new :doc:`forms -library </topics/forms/index>` to build and display the form. - -``django.views.generic.create_update.create_object`` ----------------------------------------------------- - -**Description:** - -A page that displays a form for creating an object, redisplaying the form with -validation errors (if there are any) and saving the object. - -**Required arguments:** - - * Either ``form_class`` or ``model`` is required. - - If you provide ``form_class``, it should be a ``django.forms.ModelForm`` - subclass. Use this argument when you need to customize the model's form. - See the :doc:`ModelForm docs </topics/forms/modelforms>` for more - information. - - Otherwise, ``model`` should be a Django model class and the form used - will be a standard ``ModelForm`` for ``model``. - -**Optional arguments:** - - * ``post_save_redirect``: A URL to which the view will redirect after - saving the object. By default, it's ``object.get_absolute_url()``. - - ``post_save_redirect`` may contain dictionary string formatting, which - will be interpolated against the object's field attributes. For example, - you could use ``post_save_redirect="/polls/%(slug)s/"``. - - * ``login_required``: A boolean that designates whether a user must be - logged in, in order to see the page and save changes. This hooks into the - Django :doc:`authentication system </topics/auth>`. By default, this is - ``False``. - - If this is ``True``, and a non-logged-in user attempts to visit this page - or save the form, Django will redirect the request to ``/accounts/login/``. - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - -**Template name:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_form.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``form``: A ``django.forms.ModelForm`` instance representing the form - for creating the object. This lets you refer to form fields easily in the - template system. - - For example, if the model has two fields, ``name`` and ``address``:: - - <form action="" method="post"> - <p>{{ form.name.label_tag }} {{ form.name }}</p> - <p>{{ form.address.label_tag }} {{ form.address }}</p> - </form> - - See the :doc:`forms documentation </topics/forms/index>` for more - information about using ``Form`` objects in templates. - -``django.views.generic.create_update.update_object`` ----------------------------------------------------- - -**Description:** - -A page that displays a form for editing an existing object, redisplaying the -form with validation errors (if there are any) and saving changes to the -object. This uses a form automatically generated from the object's -model class. - -**Required arguments:** - - * Either ``form_class`` or ``model`` is required. - - If you provide ``form_class``, it should be a ``django.forms.ModelForm`` - subclass. Use this argument when you need to customize the model's form. - See the :doc:`ModelForm docs </topics/forms/modelforms>` for more - information. - - Otherwise, ``model`` should be a Django model class and the form used - will be a standard ``ModelForm`` for ``model``. - - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. - - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. - -**Optional arguments:** - - * ``post_save_redirect``: A URL to which the view will redirect after - saving the object. By default, it's ``object.get_absolute_url()``. - - ``post_save_redirect`` may contain dictionary string formatting, which - will be interpolated against the object's field attributes. For example, - you could use ``post_save_redirect="/polls/%(slug)s/"``. - - * ``login_required``: A boolean that designates whether a user must be - logged in, in order to see the page and save changes. This hooks into the - Django :doc:`authentication system </topics/auth>`. By default, this is - ``False``. - - If this is ``True``, and a non-logged-in user attempts to visit this page - or save the form, Django will redirect the request to ``/accounts/login/``. - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. - -**Template name:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_form.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``form``: A ``django.forms.ModelForm`` instance representing the form - for editing the object. This lets you refer to form fields easily in the - template system. - - For example, if the model has two fields, ``name`` and ``address``:: - - <form action="" method="post"> - <p>{{ form.name.label_tag }} {{ form.name }}</p> - <p>{{ form.address.label_tag }} {{ form.address }}</p> - </form> - - See the :doc:`forms documentation </topics/forms/index>` for more - information about using ``Form`` objects in templates. - - * ``object``: The original object being edited. This variable's name - depends on the ``template_object_name`` parameter, which is ``'object'`` - by default. If ``template_object_name`` is ``'foo'``, this variable's - name will be ``foo``. - -``django.views.generic.create_update.delete_object`` ----------------------------------------------------- - -**Description:** - -A view that displays a confirmation page and deletes an existing object. The -given object will only be deleted if the request method is ``POST``. If this -view is fetched via ``GET``, it will display a confirmation page that should -contain a form that POSTs to the same URL. - -**Required arguments:** - - * ``model``: The Django model class of the object that the form will - create. - - * Either ``object_id`` or (``slug`` *and* ``slug_field``) is required. - - If you provide ``object_id``, it should be the value of the primary-key - field for the object being displayed on this page. - - Otherwise, ``slug`` should be the slug of the given object, and - ``slug_field`` should be the name of the slug field in the ``QuerySet``'s - model. By default, ``slug_field`` is ``'slug'``. - - * ``post_delete_redirect``: A URL to which the view will redirect after - deleting the object. - -**Optional arguments:** - - * ``login_required``: A boolean that designates whether a user must be - logged in, in order to see the page and save changes. This hooks into the - Django :doc:`authentication system </topics/auth>`. By default, this is - ``False``. - - If this is ``True``, and a non-logged-in user attempts to visit this page - or save the form, Django will redirect the request to ``/accounts/login/``. - - * ``template_name``: The full name of a template to use in rendering the - page. This lets you override the default template name (see below). - - * ``template_loader``: The template loader to use when loading the - template. By default, it's ``django.template.loader``. - - * ``extra_context``: A dictionary of values to add to the template - context. By default, this is an empty dictionary. If a value in the - dictionary is callable, the generic view will call it - just before rendering the template. - - * ``context_processors``: A list of template-context processors to apply to - the view's template. - - * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. - -**Template name:** - -If ``template_name`` isn't specified, this view will use the template -``<app_label>/<model_name>_confirm_delete.html`` by default. - -**Template context:** - -In addition to ``extra_context``, the template's context will be: - - * ``object``: The original object that's about to be deleted. This - variable's name depends on the ``template_object_name`` parameter, which - is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, - this variable's name will be ``foo``. diff --git a/parts/django/docs/ref/index.txt b/parts/django/docs/ref/index.txt deleted file mode 100644 index 0919417..0000000 --- a/parts/django/docs/ref/index.txt +++ /dev/null @@ -1,24 +0,0 @@ -============= -API Reference -============= - -.. toctree:: - :maxdepth: 1 - - authbackends - contrib/index - databases - django-admin - exceptions - files/index - forms/index - generic-views - middleware - models/index - request-response - settings - signals - templates/index - unicode - utils - validators diff --git a/parts/django/docs/ref/middleware.txt b/parts/django/docs/ref/middleware.txt deleted file mode 100644 index b3ddb23..0000000 --- a/parts/django/docs/ref/middleware.txt +++ /dev/null @@ -1,212 +0,0 @@ -========== -Middleware -========== - -.. module:: django.middleware - :synopsis: Django's built-in middleware classes. - -This document explains all middleware components that come with Django. For -information on how how to use them and how to write your own middleware, see -the :doc:`middleware usage guide </topics/http/middleware>`. - -Available middleware -==================== - -Cache middleware ----------------- - -.. module:: django.middleware.cache - :synopsis: Middleware for the site-wide cache. - -.. class:: UpdateCacheMiddleware - -.. class:: FetchFromCacheMiddleware - -Enable the site-wide cache. If these are enabled, each Django-powered page will -be cached for as long as the :setting:`CACHE_MIDDLEWARE_SECONDS` setting -defines. See the :doc:`cache documentation </topics/cache>`. - -"Common" middleware -------------------- - -.. module:: django.middleware.common - :synopsis: Middleware adding "common" conveniences for perfectionists. - -.. class:: CommonMiddleware - -Adds a few conveniences for perfectionists: - - * Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS` - setting, which should be a list of strings. - - * Performs URL rewriting based on the :setting:`APPEND_SLASH` and - :setting:`PREPEND_WWW` settings. - - If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end - with a slash, and it is not found in the URLconf, then a new URL is - formed by appending a slash at the end. If this new URL is found in the - URLconf, then Django redirects the request to this new URL. Otherwise, - the initial URL is processed as usual. - - For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if - you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a - valid pattern for ``foo.com/bar/``. - - .. versionchanged:: 1.0 - The behavior of :setting:`APPEND_SLASH` has changed slightly in this - version. It didn't used to check whether the pattern was matched in - the URLconf. - - If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www." - will be redirected to the same URL with a leading "www." - - Both of these options are meant to normalize URLs. The philosophy is that - each URL should exist in one, and only one, place. Technically a URL - ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine - indexer would treat them as separate URLs -- so it's best practice to - normalize URLs. - - * Sends broken link notification emails to :setting:`MANAGERS` if - :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True``. - - * Handles ETags based on the :setting:`USE_ETAGS` setting. If - :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag - for each request by MD5-hashing the page content, and it'll take care of - sending ``Not Modified`` responses, if appropriate. - -View metadata middleware ------------------------- - -.. module:: django.middleware.doc - :synopsis: Middleware to help your app self-document. - -.. class:: XViewMiddleware - -Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP -addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by -Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`. - -GZIP middleware ---------------- - -.. module:: django.middleware.gzip - :synopsis: Middleware to serve gziped content for performance. - -.. class:: GZipMiddleware - -Compresses content for browsers that understand gzip compression (all modern -browsers). - -It is suggested to place this first in the middleware list, so that the -compression of the response content is the last thing that happens. Will not -compress content bodies less than 200 bytes long, when the response code is -something other than 200, JavaScript files (for IE compatibility), or -responses that have the ``Content-Encoding`` header already specified. - -Conditional GET middleware --------------------------- - -.. module:: django.middleware.http - :synopsis: Middleware handling advanced HTTP features. - -.. class:: ConditionalGetMiddleware - -Handles conditional GET operations. If the response has a ``ETag`` or -``Last-Modified`` header, and the request has ``If-None-Match`` or -``If-Modified-Since``, the response is replaced by an -:class:`~django.http.HttpNotModified`. - -Also sets the ``Date`` and ``Content-Length`` response-headers. - -Reverse proxy middleware ------------------------- - -.. class:: SetRemoteAddrFromForwardedFor - -.. versionchanged:: 1.1 - -This middleware was removed in Django 1.1. See :ref:`the release notes -<removed-setremoteaddrfromforwardedfor-middleware>` for details. - -Locale middleware ------------------ - -.. module:: django.middleware.locale - :synopsis: Middleware to enable language selection based on the request. - -.. class:: LocaleMiddleware - -Enables language selection based on data from the request. It customizes -content for each user. See the :doc:`internationalization documentation -</topics/i18n/index>`. - -Message middleware ------------------- - -.. module:: django.contrib.messages.middleware - :synopsis: Message middleware. - -.. class:: MessageMiddleware - -.. versionadded:: 1.2 - ``MessageMiddleware`` was added. - -Enables cookie- and session-based message support. See the -:doc:`messages documentation </ref/contrib/messages>`. - -Session middleware ------------------- - -.. module:: django.contrib.sessions.middleware - :synopsis: Session middleware. - -.. class:: SessionMiddleware - -Enables session support. See the :doc:`session documentation -</topics/http/sessions>`. - -Authentication middleware -------------------------- - -.. module:: django.contrib.auth.middleware - :synopsis: Authentication middleware. - -.. class:: AuthenticationMiddleware - -Adds the ``user`` attribute, representing the currently-logged-in user, to -every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests -</topics/auth>`. - -CSRF protection middleware --------------------------- - -.. module:: django.middleware.csrf - :synopsis: Middleware adding protection against Cross Site Request - Forgeries. - -.. class:: CsrfMiddleware - -.. versionadded:: 1.0 - -Adds protection against Cross Site Request Forgeries by adding hidden form -fields to POST forms and checking requests for the correct value. See the -:doc:`Cross Site Request Forgery protection documentation </ref/contrib/csrf>`. - -Transaction middleware ----------------------- - -.. module:: django.middleware.transaction - :synopsis: Middleware binding a database transaction to each Web request. - -.. class:: TransactionMiddleware - -Binds commit and rollback to the request/response phase. If a view function -runs successfully, a commit is done. If it fails with an exception, a rollback -is done. - -The order of this middleware in the stack is important: middleware modules -running outside of it run with commit-on-save - the default Django behavior. -Middleware modules running inside it (coming later in the stack) will be under -the same transaction control as the view functions. - -See the :doc:`transaction management documentation </topics/db/transactions>`. diff --git a/parts/django/docs/ref/models/fields.txt b/parts/django/docs/ref/models/fields.txt deleted file mode 100644 index 146ca43..0000000 --- a/parts/django/docs/ref/models/fields.txt +++ /dev/null @@ -1,1063 +0,0 @@ -===================== -Model field reference -===================== - -.. module:: django.db.models.fields - :synopsis: Built-in field types. - -.. currentmodule:: django.db.models - -This document contains all the gory details about all the `field options`_ and -`field types`_ Django's got to offer. - -.. seealso:: - - If the built-in fields don't do the trick, you can easily :doc:`write your - own custom model fields </howto/custom-model-fields>`. - -.. note:: - - Technically, these models are defined in :mod:`django.db.models.fields`, but - for convenience they're imported into :mod:`django.db.models`; the standard - convention is to use ``from django.db import models`` and refer to fields as - ``models.<Foo>Field``. - -.. _common-model-field-options: - -Field options -============= - -The following arguments are available to all field types. All are optional. - -``null`` --------- - -.. attribute:: Field.null - -If ``True``, Django will store empty values as ``NULL`` in the database. Default -is ``False``. - -Note that empty string values will always get stored as empty strings, not as -``NULL``. Only use ``null=True`` for non-string fields such as integers, -booleans and dates. For both types of fields, you will also need to set -``blank=True`` if you wish to permit empty values in forms, as the -:attr:`~Field.null` parameter only affects database storage (see -:attr:`~Field.blank`). - -Avoid using :attr:`~Field.null` on string-based fields such as -:class:`CharField` and :class:`TextField` unless you have an excellent reason. -If a string-based field has ``null=True``, that means it has two possible values -for "no data": ``NULL``, and the empty string. In most cases, it's redundant to -have two possible values for "no data;" Django convention is to use the empty -string, not ``NULL``. - -.. note:: - - When using the Oracle database backend, the ``null=True`` option will be - coerced for string-based fields that have the empty string as a possible - value, and the value ``NULL`` will be stored to denote the empty string. - -``blank`` ---------- - -.. attribute:: Field.blank - -If ``True``, the field is allowed to be blank. Default is ``False``. - -Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is -purely database-related, whereas :attr:`~Field.blank` is validation-related. If -a field has ``blank=True``, validation on Django's admin site will allow entry -of an empty value. If a field has ``blank=False``, the field will be required. - -.. _field-choices: - -``choices`` ------------ - -.. attribute:: Field.choices - -An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this -field. - -If this is given, Django's admin will use a select box instead of the standard -text field and will limit choices to the choices given. - -A choices list looks like this:: - - YEAR_IN_SCHOOL_CHOICES = ( - ('FR', 'Freshman'), - ('SO', 'Sophomore'), - ('JR', 'Junior'), - ('SR', 'Senior'), - ('GR', 'Graduate'), - ) - -The first element in each tuple is the actual value to be stored. The second -element is the human-readable name for the option. - -The choices list can be defined either as part of your model class:: - - class Foo(models.Model): - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) - gender = models.CharField(max_length=1, choices=GENDER_CHOICES) - -or outside your model class altogether:: - - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) - class Foo(models.Model): - gender = models.CharField(max_length=1, choices=GENDER_CHOICES) - -You can also collect your available choices into named groups that can -be used for organizational purposes:: - - MEDIA_CHOICES = ( - ('Audio', ( - ('vinyl', 'Vinyl'), - ('cd', 'CD'), - ) - ), - ('Video', ( - ('vhs', 'VHS Tape'), - ('dvd', 'DVD'), - ) - ), - ('unknown', 'Unknown'), - ) - -The first element in each tuple is the name to apply to the group. The -second element is an iterable of 2-tuples, with each 2-tuple containing -a value and a human-readable name for an option. Grouped options may be -combined with ungrouped options within a single list (such as the -`unknown` option in this example). - -For each model field that has :attr:`~Field.choices` set, Django will add a -method to retrieve the human-readable name for the field's current value. See -:meth:`~django.db.models.Model.get_FOO_display` in the database API -documentation. - -Finally, note that choices can be any iterable object -- not necessarily a list -or tuple. This lets you construct choices dynamically. But if you find yourself -hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a -proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is -meant for static data that doesn't change much, if ever. - -``db_column`` -------------- - -.. attribute:: Field.db_column - -The name of the database column to use for this field. If this isn't given, -Django will use the field's name. - -If your database column name is an SQL reserved word, or contains -characters that aren't allowed in Python variable names -- notably, the -hyphen -- that's OK. Django quotes column and table names behind the -scenes. - -``db_index`` ------------- - -.. attribute:: Field.db_index - -If ``True``, djadmin:`django-admin.py sqlindexes <sqlindexes>` will output a -``CREATE INDEX`` statement for this field. - -``db_tablespace`` ------------------ - -.. attribute:: Field.db_tablespace - -.. versionadded:: 1.0 - -The name of the database tablespace to use for this field's index, if this field -is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE` -setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If -the backend doesn't support tablespaces, this option is ignored. - -``default`` ------------ - -.. attribute:: Field.default - -The default value for the field. This can be a value or a callable object. If -callable it will be called every time a new object is created. - -``editable`` ------------- - -.. attribute:: Field.editable - -If ``False``, the field will not be editable in the admin or via forms -automatically generated from the model class. Default is ``True``. - -``error_messages`` ------------------- - -.. versionadded:: 1.2 - -.. attribute:: Field.error_messages - -The ``error_messages`` argument lets you override the default messages that the -field will raise. Pass in a dictionary with keys matching the error messages you -want to override. - -``help_text`` -------------- - -.. attribute:: Field.help_text - -Extra "help" text to be displayed under the field on the object's admin form. -It's useful for documentation even if your object doesn't have an admin form. - -Note that this value is *not* HTML-escaped when it's displayed in the admin -interface. This lets you include HTML in :attr:`~Field.help_text` if you so -desire. For example:: - - help_text="Please use the following format: <em>YYYY-MM-DD</em>." - -Alternatively you can use plain text and -``django.utils.html.escape()`` to escape any HTML special characters. - -``primary_key`` ---------------- - -.. attribute:: Field.primary_key - -If ``True``, this field is the primary key for the model. - -If you don't specify ``primary_key=True`` for any fields in your model, Django -will automatically add an :class:`IntegerField` to hold the primary key, so you -don't need to set ``primary_key=True`` on any of your fields unless you want to -override the default primary-key behavior. For more, see -:ref:`automatic-primary-key-fields`. - -``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`. -Only one primary key is allowed on an object. - -``unique`` ----------- - -.. attribute:: Field.unique - -If ``True``, this field must be unique throughout the table. - -This is enforced at the database level and at the Django admin-form level. If -you try to save a model with a duplicate value in a :attr:`~Field.unique` -field, a :exc:`django.db.IntegrityError` will be raised by the model's -:meth:`~django.db.models.Model.save` method. - -This option is valid on all field types except :class:`ManyToManyField` and -:class:`FileField`. - -``unique_for_date`` -------------------- - -.. attribute:: Field.unique_for_date - -Set this to the name of a :class:`DateField` or :class:`DateTimeField` to -require that this field be unique for the value of the date field. - -For example, if you have a field ``title`` that has -``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two -records with the same ``title`` and ``pub_date``. - -This is enforced at the Django admin-form level but not at the database level. - -``unique_for_month`` --------------------- - -.. attribute:: Field.unique_for_month - -Like :attr:`~Field.unique_for_date`, but requires the field to be unique with -respect to the month. - -``unique_for_year`` -------------------- - -.. attribute:: Field.unique_for_year - -Like :attr:`~Field.unique_for_date` and :attr:`~Field.unique_for_month`. - -``verbose_name`` -------------------- - -.. attribute:: Field.verbose_name - -A human-readable name for the field. If the verbose name isn't given, Django -will automatically create it using the field's attribute name, converting -underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`. - -``validators`` -------------------- - -.. versionadded:: 1.2 - -.. attribute:: Field.validators - -A list of validators to run for this field.See the :doc:`validators -documentation </ref/validators>` for more information. - -.. _model-field-types: - -Field types -=========== - -.. currentmodule:: django.db.models - -``AutoField`` -------------- - -.. class:: AutoField(**options) - -An :class:`IntegerField` that automatically increments -according to available IDs. You usually won't need to use this directly; a -primary key field will automatically be added to your model if you don't specify -otherwise. See :ref:`automatic-primary-key-fields`. - -``BigIntegerField`` -------------------- - -.. versionadded:: 1.2 - -.. class:: BigIntegerField([**options]) - -A 64 bit integer, much like an :class:`IntegerField` except that it is -guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The -admin represents this as an ``<input type="text">`` (a single-line input). - - -``BooleanField`` ----------------- - -.. class:: BooleanField(**options) - -A true/false field. - -The admin represents this as a checkbox. - -.. versionchanged:: 1.2 - - In previous versions of Django when running under MySQL ``BooleanFields`` - would return their data as ``ints``, instead of true ``bools``. See the - release notes for a complete description of the change. - -``CharField`` -------------- - -.. class:: CharField(max_length=None, [**options]) - -A string field, for small- to large-sized strings. - -For large amounts of text, use :class:`~django.db.models.TextField`. - -The admin represents this as an ``<input type="text">`` (a single-line input). - -:class:`CharField` has one extra required argument: - -.. attribute:: CharField.max_length - - The maximum length (in characters) of the field. The max_length is enforced - at the database level and in Django's validation. - -.. note:: - - If you are writing an application that must be portable to multiple - database backends, you should be aware that there are restrictions on - ``max_length`` for some backends. Refer to the :doc:`database backend - notes </ref/databases>` for details. - -.. admonition:: MySQL users - - If you are using this field with MySQLdb 1.2.2 and the ``utf8_bin`` - collation (which is *not* the default), there are some issues to be aware - of. Refer to the :ref:`MySQL database notes <mysql-collation>` for - details. - - -``CommaSeparatedIntegerField`` ------------------------------- - -.. class:: CommaSeparatedIntegerField(max_length=None, [**options]) - -A field of integers separated by commas. As in :class:`CharField`, the -:attr:`~CharField.max_length` argument is required and the note about database -portability mentioned there should be heeded. - -``DateField`` -------------- - -.. class:: DateField([auto_now=False, auto_now_add=False, **options]) - -A date, represented in Python by a ``datetime.date`` instance. Has a few extra, -optional arguments: - -.. attribute:: DateField.auto_now - - Automatically set the field to now every time the object is saved. Useful - for "last-modified" timestamps. Note that the current date is *always* - used; it's not just a default value that you can override. - -.. attribute:: DateField.auto_now_add - - Automatically set the field to now when the object is first created. Useful - for creation of timestamps. Note that the current date is *always* used; - it's not just a default value that you can override. - -The admin represents this as an ``<input type="text">`` with a JavaScript -calendar, and a shortcut for "Today". The JavaScript calendar will always -start the week on a Sunday. - -.. note:: - As currently implemented, setting ``auto_now`` or ``auto_add_now`` to - ``True`` will cause the field to have ``editable=False`` and ``blank=True`` - set. - -``DateTimeField`` ------------------ - -.. class:: DateTimeField([auto_now=False, auto_now_add=False, **options]) - -A date and time, represented in Python by a ``datetime.datetime`` instance. -Takes the same extra arguments as :class:`DateField`. - -The admin represents this as two ``<input type="text">`` fields, with -JavaScript shortcuts. - -``DecimalField`` ----------------- - -.. versionadded:: 1.0 - -.. class:: DecimalField(max_digits=None, decimal_places=None, [**options]) - -A fixed-precision decimal number, represented in Python by a -:class:`~decimal.Decimal` instance. Has two **required** arguments: - -.. attribute:: DecimalField.max_digits - - The maximum number of digits allowed in the number - -.. attribute:: DecimalField.decimal_places - - The number of decimal places to store with the number - -For example, to store numbers up to 999 with a resolution of 2 decimal places, -you'd use:: - - models.DecimalField(..., max_digits=5, decimal_places=2) - -And to store numbers up to approximately one billion with a resolution of 10 -decimal places:: - - models.DecimalField(..., max_digits=19, decimal_places=10) - -The admin represents this as an ``<input type="text">`` (a single-line input). - -``EmailField`` --------------- - -.. class:: EmailField([max_length=75, **options]) - -A :class:`CharField` that checks that the value is a valid e-mail address. - -``FileField`` -------------- - -.. class:: FileField(upload_to=None, [max_length=100, **options]) - -A file-upload field. - -.. note:: - The ``primary_key`` and ``unique`` arguments are not supported, and will - raise a ``TypeError`` if used. - -Has one **required** argument: - -.. attribute:: FileField.upload_to - - A local filesystem path that will be appended to your :setting:`MEDIA_ROOT` - setting to determine the value of the :attr:`~django.core.files.File.url` - attribute. - - This path may contain `strftime formatting`_, which will be replaced by the - date/time of the file upload (so that uploaded files don't fill up the given - directory). - - .. versionchanged:: 1.0 - - This may also be a callable, such as a function, which will be called to - obtain the upload path, including the filename. This callable must be able - to accept two arguments, and return a Unix-style path (with forward slashes) - to be passed along to the storage system. The two arguments that will be - passed are: - - ====================== =============================================== - Argument Description - ====================== =============================================== - ``instance`` An instance of the model where the - ``FileField`` is defined. More specifically, - this is the particular instance where the - current file is being attached. - - In most cases, this object will not have been - saved to the database yet, so if it uses the - default ``AutoField``, *it might not yet have a - value for its primary key field*. - - ``filename`` The filename that was originally given to the - file. This may or may not be taken into account - when determining the final destination path. - ====================== =============================================== - -Also has one optional argument: - -.. attribute:: FileField.storage - - .. versionadded:: 1.0 - - Optional. A storage object, which handles the storage and retrieval of your - files. See :doc:`/topics/files` for details on how to provide this object. - -The admin represents this field as an ``<input type="file">`` (a file-upload -widget). - -Using a :class:`FileField` or an :class:`ImageField` (see below) in a model -takes a few steps: - - 1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the - full path to a directory where you'd like Django to store uploaded files. - (For performance, these files are not stored in the database.) Define - :setting:`MEDIA_URL` as the base public URL of that directory. Make sure - that this directory is writable by the Web server's user account. - - 2. Add the :class:`FileField` or :class:`ImageField` to your model, making - sure to define the :attr:`~FileField.upload_to` option to tell Django - to which subdirectory of :setting:`MEDIA_ROOT` it should upload files. - - 3. All that will be stored in your database is a path to the file - (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the - convenience :attr:`~django.core.files.File.url` function provided by - Django. For example, if your :class:`ImageField` is called ``mug_shot``, - you can get the absolute path to your image in a template with - ``{{ object.mug_shot.url }}``. - -For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and -:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` -part of :attr:`~FileField.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``. - -If you want to retrieve the upload file's on-disk filename, or a URL that refers -to that file, or the file's size, you can use the -:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url` -and :attr:`~django.core.files.File.size` attributes; see :doc:`/topics/files`. - -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. - -.. versionadded:: 1.0 - The ``max_length`` argument was added in this version. - -By default, :class:`FileField` instances are -created as ``varchar(100)`` columns in your database. As with other fields, you -can change the maximum length using the :attr:`~CharField.max_length` argument. - -.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime - -FileField and FieldFile -~~~~~~~~~~~~~~~~~~~~~~~ - -When you access a :class:`FileField` on a model, you are given an instance -of :class:`FieldFile` as a proxy for accessing the underlying file. This -class has several methods that can be used to interact with file data: - -.. method:: FieldFile.open(mode='rb') - -Behaves like the standard Python ``open()`` method and opens the file -associated with this instance in the mode specified by ``mode``. - -.. method:: FieldFile.close() - -Behaves like the standard Python ``file.close()`` method and closes the file -associated with this instance. - -.. method:: FieldFile.save(name, content, save=True) - -This method takes a filename and file contents and passes them to the storage -class for the field, then associates the stored file with the model field. -If you want to manually associate file data with :class:`FileField` -instances on your model, the ``save()`` method is used to persist that file -data. - -Takes two required arguments: ``name`` which is the name of the file, and -``content`` which is a file-like object containing the file's contents. The -optional ``save`` argument controls whether or not the instance is saved after -the file has been altered. Defaults to ``True``. - -.. method:: FieldFile.delete(save=True) - -Deletes the file associated with this instance and clears all attributes on -the field. Note: This method will close the file if it happens to be open when -``delete()`` is called. - -The optional ``save`` argument controls whether or not the instance is saved -after the file has been deleted. Defaults to ``True``. - -``FilePathField`` ------------------ - -.. class:: FilePathField(path=None, [match=None, recursive=False, max_length=100, **options]) - -A :class:`CharField` whose choices are limited to the filenames in a certain -directory on the filesystem. Has three special arguments, of which the first is -**required**: - -.. attribute:: FilePathField.path - - Required. The absolute filesystem path to a directory from which this - :class:`FilePathField` should get its choices. Example: ``"/home/images"``. - -.. attribute:: FilePathField.match - - Optional. A regular expression, as a string, that :class:`FilePathField` - will use to filter filenames. Note that the regex will be applied to the - base filename, not the full path. Example: ``"foo.*\.txt$"``, which will - match a file called ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``. - -.. attribute:: FilePathField.recursive - - Optional. Either ``True`` or ``False``. Default is ``False``. Specifies - whether all subdirectories of :attr:`~FilePathField.path` should be included - -Of course, these arguments can be used together. - -The one potential gotcha is that :attr:`~FilePathField.match` applies to the -base filename, not the full path. So, this example:: - - FilePathField(path="/home/images", match="foo.*", recursive=True) - -...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif`` -because the :attr:`~FilePathField.match` applies to the base filename -(``foo.gif`` and ``bar.gif``). - -.. versionadded:: 1.0 - The ``max_length`` argument was added in this version. - -By default, :class:`FilePathField` instances are -created as ``varchar(100)`` columns in your database. As with other fields, you -can change the maximum length using the :attr:`~CharField.max_length` argument. - -``FloatField`` --------------- - -.. class:: FloatField([**options]) - -.. versionchanged:: 1.0 - -A floating-point number represented in Python by a ``float`` instance. - -The admin represents this as an ``<input type="text">`` (a single-line input). - -``ImageField`` --------------- - -.. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options]) - -Inherits all attributes and methods from :class:`FileField`, but also -validates that the uploaded object is a valid image. - -In addition to the special attributes that are available for :class:`FileField`, -an :class:`ImageField` also has :attr:`~django.core.files.File.height` and -:attr:`~django.core.files.File.width` attributes. - -To facilitate querying on those attributes, :class:`ImageField` has two extra -optional arguments: - -.. attribute:: ImageField.height_field - - Name of a model field which will be auto-populated with the height of the - image each time the model instance is saved. - -.. attribute:: ImageField.width_field - - Name of a model field which will be auto-populated with the width of the - image each time the model instance is saved. - -Requires the `Python Imaging Library`_. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - -.. versionadded:: 1.0 - The ``max_length`` argument was added in this version. - -By default, :class:`ImageField` instances are created as ``varchar(100)`` -columns in your database. As with other fields, you can change the maximum -length using the :attr:`~CharField.max_length` argument. - -``IntegerField`` ----------------- - -.. class:: IntegerField([**options]) - -An integer. The admin represents this as an ``<input type="text">`` (a -single-line input). - -``IPAddressField`` ------------------- - -.. class:: IPAddressField([**options]) - -An IP address, in string format (e.g. "192.0.2.30"). The admin represents this -as an ``<input type="text">`` (a single-line input). - -``NullBooleanField`` --------------------- - -.. class:: NullBooleanField([**options]) - -Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use -this instead of a :class:`BooleanField` with ``null=True``. The admin represents -this as a ``<select>`` box with "Unknown", "Yes" and "No" choices. - -``PositiveIntegerField`` ------------------------- - -.. class:: PositiveIntegerField([**options]) - -Like an :class:`IntegerField`, but must be positive. - -``PositiveSmallIntegerField`` ------------------------------ - -.. class:: PositiveSmallIntegerField([**options]) - -Like a :class:`PositiveIntegerField`, but only allows values under a certain -(database-dependent) point. - -``SlugField`` -------------- - -.. class:: SlugField([max_length=50, **options]) - -:term:`Slug` is a newspaper term. A slug is a short label for something, -containing only letters, numbers, underscores or hyphens. They're generally used -in URLs. - -Like a CharField, you can specify :attr:`~CharField.max_length` (read the note -about database portability and :attr:`~CharField.max_length` in that section, -too). If :attr:`~CharField.max_length` is not specified, Django will use a -default length of 50. - -Implies setting :attr:`Field.db_index` to ``True``. - -It is often useful to automatically prepopulate a SlugField based on the value -of some other value. You can do this automatically in the admin using -:attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`. - -``SmallIntegerField`` ---------------------- - -.. class:: SmallIntegerField([**options]) - -Like an :class:`IntegerField`, but only allows values under a certain -(database-dependent) point. - -``TextField`` -------------- - -.. class:: TextField([**options]) - -A large text field. The admin represents this as a ``<textarea>`` (a multi-line -input). - -.. admonition:: MySQL users - - If you are using this field with MySQLdb 1.2.1p2 and the ``utf8_bin`` - collation (which is *not* the default), there are some issues to be aware - of. Refer to the :ref:`MySQL database notes <mysql-collation>` for - details. - -``TimeField`` -------------- - -.. class:: TimeField([auto_now=False, auto_now_add=False, **options]) - -A time, represented in Python by a ``datetime.time`` instance. Accepts the same -auto-population options as :class:`DateField`. - -The admin represents this as an ``<input type="text">`` with some JavaScript -shortcuts. - -``URLField`` ------------- - -.. class:: URLField([verify_exists=True, max_length=200, **options]) - -A :class:`CharField` for a URL. Has one extra optional argument: - -.. attribute:: URLField.verify_exists - - If ``True`` (the default), the URL given will be checked for existence - (i.e., the URL actually loads and doesn't give a 404 response). - - Note that when you're using the single-threaded development server, - validating a URL being served by the same server will hang. This should not - be a problem for multithreaded servers. - -The admin represents this as an ``<input type="text">`` (a single-line input). - -Like all :class:`CharField` subclasses, :class:`URLField` takes the optional -:attr:`~CharField.max_length`argument. If you don't specify -:attr:`~CharField.max_length`, a default of 200 is used. - -``XMLField`` ------------- - -.. class:: XMLField(schema_path=None, [**options]) - -A :class:`TextField` that checks that the value is valid XML that matches a -given schema. Takes one required argument: - -.. attribute:: schema_path - - The filesystem path to a RelaxNG_ schema against which to validate the - field. - -.. _RelaxNG: http://www.relaxng.org/ - -Relationship fields -=================== - -.. module:: django.db.models.fields.related - :synopsis: Related field types - -.. currentmodule:: django.db.models - -Django also defines a set of fields that represent relations. - -.. _ref-foreignkey: - -``ForeignKey`` --------------- - -.. class:: ForeignKey(othermodel, [**options]) - -A many-to-one relationship. Requires a positional argument: the class to which -the model is related. - -.. _recursive-relationships: - -To create a recursive relationship -- an object that has a many-to-one -relationship with itself -- use ``models.ForeignKey('self')``. - -.. _lazy-relationships: - -If you need to create a relationship on a model that has not yet been defined, -you can use the name of the model, rather than the model object itself:: - - class Car(models.Model): - manufacturer = models.ForeignKey('Manufacturer') - # ... - - class Manufacturer(models.Model): - # ... - -.. versionadded:: 1.0 - -To refer to models defined in another application, you can explicitly specify -a model with the full application label. For example, if the ``Manufacturer`` -model above is defined in another application called ``production``, you'd -need to use:: - - class Car(models.Model): - manufacturer = models.ForeignKey('production.Manufacturer') - -This sort of reference can be useful when resolving circular import -dependencies between two applications. - -Database Representation -~~~~~~~~~~~~~~~~~~~~~~~ - -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`` -model will have a ``manufacturer_id`` column. (You can change this explicitly by -specifying :attr:`~Field.db_column`) However, your code should never have to -deal with the database column name, unless you write custom SQL. You'll always -deal with the field names of your model object. - -.. _foreign-key-arguments: - -Arguments -~~~~~~~~~ - -:class:`ForeignKey` accepts an extra set of arguments -- all optional -- that -define the details of how the relation works. - -.. attribute:: ForeignKey.limit_choices_to - - A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`) - that limit the available admin choices for this object. Use this with - functions from the Python ``datetime`` module to limit choices of objects by - date. For example:: - - limit_choices_to = {'pub_date__lte': datetime.now} - - only allows the choice of related objects with a ``pub_date`` before the - current date/time to be chosen. - - Instead of a dictionary this can also be a :class:`~django.db.models.Q` - object for more :ref:`complex queries <complex-lookups-with-q>`. However, - if ``limit_choices_to`` is a :class:`~django.db.models.Q` object then it - will only have an effect on the choices available in the admin when the - field is not listed in ``raw_id_fields`` in the ``ModelAdmin`` for the model. - -.. attribute:: ForeignKey.related_name - - The name to use for the relation from the related object back to this one. - See the :ref:`related objects documentation <backwards-related-objects>` for - a full explanation and example. Note that you must set this value - when defining relations on :ref:`abstract models - <abstract-base-classes>`; and when you do so - :ref:`some special syntax <abstract-related-name>` is available. - - If you wish to suppress the provision of a backwards relation, you may - simply provide a ``related_name`` which ends with a ``'+'`` character. - For example:: - - user = models.ForeignKey(User, related_name='+') - - will ensure that no backwards relation to this model is provided on the - ``User`` model. - -.. attribute:: ForeignKey.to_field - - The field on the related object that the relation is to. By default, Django - uses the primary key of the related object. - -.. _ref-manytomany: - -``ManyToManyField`` -------------------- - -.. class:: ManyToManyField(othermodel, [**options]) - -A many-to-many relationship. Requires a positional argument: the class to which -the model is related. This works exactly the same as it does for -:class:`ForeignKey`, including all the options regarding :ref:`recursive -<recursive-relationships>` and :ref:`lazy <lazy-relationships>` relationships. - -Database Representation -~~~~~~~~~~~~~~~~~~~~~~~ - -Behind the scenes, Django creates an intermediary join table to -represent the many-to-many relationship. By default, this table name -is generated using the name of the many-to-many field and the model -that contains it. Since some databases don't support table names above -a certain length, these table names will be automatically truncated to -64 characters and a uniqueness hash will be used. This means you might -see table names like ``author_books_9cdf4``; this is perfectly normal. -You can manually provide the name of the join table using the -:attr:`~ManyToManyField.db_table` option. - -.. _manytomany-arguments: - -Arguments -~~~~~~~~~ - -:class:`ManyToManyField` accepts an extra set of arguments -- all optional -- -that control how the relationship functions. - -.. attribute:: ManyToManyField.related_name - - Same as :attr:`ForeignKey.related_name`. - -.. attribute:: ManyToManyField.limit_choices_to - - Same as :attr:`ForeignKey.limit_choices_to`. - - ``limit_choices_to`` has no effect when used on a ``ManyToManyField`` with a - custom intermediate table specified using the - :attr:`~ManyToManyField.through` parameter. - -.. attribute:: ManyToManyField.symmetrical - - Only used in the definition of ManyToManyFields on self. Consider the - following model:: - - class Person(models.Model): - friends = models.ManyToManyField("self") - - When Django processes this model, it identifies that it has a - :class:`ManyToManyField` on itself, and as a result, it doesn't add a - ``person_set`` attribute to the ``Person`` class. Instead, the - :class:`ManyToManyField` is assumed to be symmetrical -- that is, if I am - your friend, then you are my friend. - - If you do not want symmetry in many-to-many relationships with ``self``, set - :attr:`~ManyToManyField.symmetrical` to ``False``. This will force Django to - add the descriptor for the reverse relationship, allowing - :class:`ManyToManyField` relationships to be non-symmetrical. - -.. attribute:: ManyToManyField.through - - Django will automatically generate a table to manage many-to-many - relationships. However, if you want to manually specify the intermediary - table, you can use the :attr:`~ManyToManyField.through` option to specify - the Django model that represents the intermediate table that you want to - use. - - The most common use for this option is when you want to associate - :ref:`extra data with a many-to-many relationship - <intermediary-manytomany>`. - -.. attribute:: ManyToManyField.db_table - - The name of the table to create for storing the many-to-many data. If this - is not provided, Django will assume a default name based upon the names of - the two tables being joined. - -.. _ref-onetoone: - -``OneToOneField`` ------------------ - -.. class:: OneToOneField(othermodel, [parent_link=False, **options]) - -A one-to-one relationship. Conceptually, this is similar to a -:class:`ForeignKey` with :attr:`unique=True <Field.unique>`, but the -"reverse" side of the relation will directly return a single object. - -This is most useful as the primary key of a model which "extends" -another model in some way; :ref:`multi-table-inheritance` is -implemented by adding an implicit one-to-one relation from the child -model to the parent model, for example. - -One positional argument is required: the class to which the model will be -related. This works exactly the same as it does for :class:`ForeignKey`, -including all the options regarding :ref:`recursive <recursive-relationships>` -and :ref:`lazy <lazy-relationships>` relationships. - -.. _onetoone-arguments: - -Additionally, ``OneToOneField`` accepts all of the extra arguments -accepted by :class:`ForeignKey`, plus one extra argument: - -.. attribute:: OneToOneField.parent_link - - When ``True`` and used in a model which inherits from another - (concrete) model, indicates that this field should be used as the - link back to the parent class, rather than the extra - ``OneToOneField`` which would normally be implicitly created by - subclassing. diff --git a/parts/django/docs/ref/models/index.txt b/parts/django/docs/ref/models/index.txt deleted file mode 100644 index b5896c3..0000000 --- a/parts/django/docs/ref/models/index.txt +++ /dev/null @@ -1,14 +0,0 @@ -====== -Models -====== - -Model API reference. For introductory material, see :doc:`/topics/db/models`. - -.. toctree:: - :maxdepth: 1 - - fields - relations - options - instances - querysets diff --git a/parts/django/docs/ref/models/instances.txt b/parts/django/docs/ref/models/instances.txt deleted file mode 100644 index 1730ec6..0000000 --- a/parts/django/docs/ref/models/instances.txt +++ /dev/null @@ -1,570 +0,0 @@ -======================== -Model instance reference -======================== - -.. currentmodule:: django.db.models - -This document describes the details of the ``Model`` API. It builds on the -material presented in the :doc:`model </topics/db/models>` and :doc:`database -query </topics/db/queries>` guides, so you'll probably want to read and -understand those documents before reading this one. - -Throughout this reference we'll use the :ref:`example Weblog models -<queryset-model-example>` presented in the :doc:`database query guide -</topics/db/queries>`. - -Creating objects -================ - -To create a new instance of a model, just instantiate it like any other Python -class: - -.. class:: Model(**kwargs) - -The keyword arguments are simply the names of the fields you've defined on your -model. Note that instantiating a model in no way touches your database; for -that, you need to ``save()``. - -.. _validating-objects: - -Validating objects -================== - -.. versionadded:: 1.2 - -There are three steps involved in validating a model: - - 1. Validate the model fields - 2. Validate the model as a whole - 3. Validate the field uniqueness - -All three steps are performed when you call by a model's -``full_clean()`` method. - -When you use a ``ModelForm``, the call to ``is_valid()`` will perform -these validation steps for all the fields that are included on the -form. (See the :doc:`ModelForm documentation -</topics/forms/modelforms>` for more information.) You should only need -to call a model's ``full_clean()`` method if you plan to handle -validation errors yourself, or if you have excluded fields from the -ModelForm that require validation. - -.. method:: Model.full_clean(exclude=None) - -This method calls ``Model.clean_fields()``, ``Model.clean()``, and -``Model.validate_unique()``, in that order and raises a ``ValidationError`` -that has a ``message_dict`` attribute containing errors from all three stages. - -The optional ``exclude`` argument can be used to provide a list of field names -that can be excluded from validation and cleaning. ``ModelForm`` uses this -argument to exclude fields that aren't present on your form from being -validated since any errors raised could not be corrected by the user. - -Note that ``full_clean()`` will *not* be called automatically when you -call your model's ``save()`` method, nor as a result of ``ModelForm`` -validation. You'll need to call it manually when you want to run model -validation outside of a ``ModelForm``. - -Example:: - - try: - article.full_clean() - except ValidationError, e: - # Do something based on the errors contained in e.message_dict. - # Display them to a user, or handle them programatically. - -The first step ``full_clean()`` performs is to clean each individual field. - -.. method:: Model.clean_fields(exclude=None) - -This method will validate all fields on your model. The optional ``exclude`` -argument lets you provide a list of field names to exclude from validation. It -will raise a ``ValidationError`` if any fields fail validation. - -The second step ``full_clean()`` performs is to call ``Model.clean()``. -This method should be overridden to perform custom validation on your model. - -.. method:: Model.clean() - -This method should be used to provide custom model validation, and to modify -attributes on your model if desired. For instance, you could use it to -automatically provide a value for a field, or to do validation that requires -access to more than a single field:: - - def clean(self): - from django.core.exceptions import ValidationError - # Don't allow draft entries to have a pub_date. - if self.status == 'draft' and self.pub_date is not None: - raise ValidationError('Draft entries may not have a publication date.') - # Set the pub_date for published items if it hasn't been set already. - if self.status == 'published' and self.pub_date is None: - self.pub_date = datetime.datetime.now() - -Any ``ValidationError`` raised by ``Model.clean()`` will be stored under a -special key that is used for errors that are tied to the entire model instead -of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``:: - - - from django.core.exceptions import ValidationError, NON_FIELD_ERRORS - try: - article.full_clean() - except ValidationError, e: - non_field_errors = e.message_dict[NON_FIELD_ERRORS] - -Finally, ``full_clean()`` will check any unique constraints on your model. - -.. method:: Model.validate_unique(exclude=None) - -This method is similar to ``clean_fields``, but validates all uniqueness -constraints on your model instead of individual field values. The optional -``exclude`` argument allows you to provide a list of field names to exclude -from validation. It will raise a ``ValidationError`` if any fields fail -validation. - -Note that if you provide an ``exclude`` argument to ``validate_unique``, any -``unique_together`` constraint that contains one of the fields you provided -will not be checked. - - -Saving objects -============== - -To save an object back to the database, call ``save()``: - -.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS]) - -.. versionadded:: 1.0 - The ``force_insert`` and ``force_update`` arguments were added. - -.. versionadded:: 1.2 - The ``using`` argument was added. - -If you want customized saving behavior, you can override this -``save()`` method. See :ref:`overriding-model-methods` for more -details. - -The model save process also has some subtleties; see the sections -below. - -Auto-incrementing primary keys ------------------------------- - -If a model has an ``AutoField`` -- an auto-incrementing primary key -- then -that auto-incremented value will be calculated and saved as an attribute on -your object the first time you call ``save()``:: - - >>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') - >>> b2.id # Returns None, because b doesn't have an ID yet. - >>> b2.save() - >>> b2.id # Returns the ID of your new object. - -There's no way to tell what the value of an ID will be before you call -``save()``, because that value is calculated by your database, not by Django. - -(For convenience, each model has an ``AutoField`` named ``id`` by default -unless you explicitly specify ``primary_key=True`` on a field. See the -documentation for ``AutoField`` for more details. - -The ``pk`` property -~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -.. attribute:: Model.pk - -Regardless of whether you define a primary key field yourself, or let Django -supply one for you, each model will have a property called ``pk``. It behaves -like a normal attribute on the model, but is actually an alias for whichever -attribute is the primary key field for the model. You can read and set this -value, just as you would for any other attribute, and it will update the -correct field in the model. - -Explicitly specifying auto-primary-key values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If a model has an ``AutoField`` but you want to define a new object's ID -explicitly when saving, just define it explicitly before saving, rather than -relying on the auto-assignment of the ID:: - - >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') - >>> b3.id # Returns 3. - >>> b3.save() - >>> b3.id # Returns 3. - -If you assign auto-primary-key values manually, make sure not to use an -already-existing primary-key value! If you create a new object with an explicit -primary-key value that already exists in the database, Django will assume you're -changing the existing record rather than creating a new one. - -Given the above ``'Cheddar Talk'`` blog example, this example would override the -previous record in the database:: - - b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.') - b4.save() # Overrides the previous blog with ID=3! - -See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this -happens. - -Explicitly specifying auto-primary-key values is mostly useful for bulk-saving -objects, when you're confident you won't have primary-key collision. - -What happens when you save? ---------------------------- - -When you save an object, Django performs the following steps: - - 1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` - :attr:`django.db.models.signals.pre_save` is sent, allowing any - functions listening for that signal to take some customized - action. - - 2. **Pre-process the data.** Each field on the object is asked to - perform any automated data modification that the field may need - to perform. - - Most fields do *no* pre-processing -- the field data is kept as-is. - Pre-processing is only used on fields that have special behavior. - For example, if your model has a ``DateField`` with ``auto_now=True``, - the pre-save phase will alter the data in the object to ensure that - the date field contains the current date stamp. (Our documentation - doesn't yet include a list of all the fields with this "special - behavior.") - - 3. **Prepare the data for the database.** Each field is asked to provide - its current value in a data type that can be written to the database. - - Most fields require *no* data preparation. Simple data types, such as - integers and strings, are 'ready to write' as a Python object. However, - more complex data types often require some modification. - - For example, ``DateFields`` use a Python ``datetime`` object to store - data. Databases don't store ``datetime`` objects, so the field value - must be converted into an ISO-compliant date string for insertion - into the database. - - 4. **Insert the data into the database.** The pre-processed, prepared - data is then composed into an SQL statement for insertion into the - database. - - 5. **Emit a post-save signal.** The signal - :attr:`django.db.models.signals.post_save` is sent, allowing - any functions listening for that signal to take some customized - action. - -How Django knows to UPDATE vs. INSERT -------------------------------------- - -You may have noticed Django database objects use the same ``save()`` method -for creating and changing objects. Django abstracts the need to use ``INSERT`` -or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django -follows this algorithm: - - * If the object's primary key attribute is set to a value that evaluates to - ``True`` (i.e., a value other than ``None`` or the empty string), Django - executes a ``SELECT`` query to determine whether a record with the given - primary key already exists. - * If the record with the given primary key does already exist, Django - executes an ``UPDATE`` query. - * If the object's primary key attribute is *not* set, or if it's set but a - record doesn't exist, Django executes an ``INSERT``. - -The one gotcha here is that you should be careful not to specify a primary-key -value explicitly when saving new objects, if you cannot guarantee the -primary-key value is unused. For more on this nuance, see `Explicitly specifying -auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below. - -.. _ref-models-force-insert: - -Forcing an INSERT or UPDATE -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -In some rare circumstances, it's necessary to be able to force the ``save()`` -method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``. -Or vice-versa: update, if possible, but not insert a new row. In these cases -you can pass the ``force_insert=True`` or ``force_update=True`` parameters to -the ``save()`` method. Passing both parameters is an error, since you cannot -both insert *and* update at the same time. - -It should be very rare that you'll need to use these parameters. Django will -almost always do the right thing and trying to override that will lead to -errors that are difficult to track down. This feature is for advanced use -only. - -Updating attributes based on existing fields --------------------------------------------- - -Sometimes you'll need to perform a simple arithmetic task on a field, such -as incrementing or decrementing the current value. The obvious way to -achieve this is to do something like:: - - >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') - >>> product.number_sold += 1 - >>> product.save() - -If the old ``number_sold`` value retrieved from the database was 10, then -the value of 11 will be written back to the database. - -This can be optimized slightly by expressing the update relative to the -original field value, rather than as an explicit assignment of a new value. -Django provides :ref:`F() expressions <query-expressions>` as a way of -performing this kind of relative update. Using ``F()`` expressions, the -previous example would be expressed as:: - - >>> from django.db.models import F - >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') - >>> product.number_sold = F('number_sold') + 1 - >>> product.save() - -This approach doesn't use the initial value from the database. Instead, it -makes the database do the update based on whatever value is current at the -time that the save() is executed. - -Once the object has been saved, you must reload the object in order to access -the actual value that was applied to the updated field:: - - >>> product = Products.objects.get(pk=product.pk) - >>> print product.number_sold - 42 - -For more details, see the documentation on :ref:`F() expressions -<query-expressions>` and their :ref:`use in update queries -<topics-db-queries-update>`. - -Deleting objects -================ - -.. method:: Model.delete([using=DEFAULT_DB_ALIAS]) - -.. versionadded:: 1.2 - The ``using`` argument was added. - -Issues a SQL ``DELETE`` for the object. This only deletes the object -in the database; the Python instance will still be around, and will -still have data in its fields. - -For more details, including how to delete objects in bulk, see -:ref:`topics-db-queries-delete`. - -If you want customized deletion behavior, you can override this -``delete()`` method. See :ref:`overriding-model-methods` for more -details. - -.. _model-instance-methods: - -Other model instance methods -============================ - -A few object methods have special purposes. - -``__str__`` ------------ - -.. method:: Model.__str__() - -``__str__()`` is a Python "magic method" that defines what should be returned -if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related -function, ``unicode(obj)`` -- see below) in a number of places, most notably -as the value displayed to render an object in the Django admin site and as the -value inserted into a template when it displays an object. Thus, you should -always return a nice, human-readable string for the object's ``__str__``. -Although this isn't required, it's strongly encouraged (see the description of -``__unicode__``, below, before putting ``__str__`` methods everywhere). - -For example:: - - class Person(models.Model): - first_name = models.CharField(max_length=50) - last_name = models.CharField(max_length=50) - - def __str__(self): - # Note use of django.utils.encoding.smart_str() here because - # first_name and last_name will be unicode strings. - return smart_str('%s %s' % (self.first_name, self.last_name)) - -``__unicode__`` ---------------- - -.. method:: Model.__unicode__() - -The ``__unicode__()`` method is called whenever you call ``unicode()`` on an -object. Since Django's database backends will return Unicode strings in your -model's attributes, you would normally want to write a ``__unicode__()`` -method for your model. The example in the previous section could be written -more simply as:: - - class Person(models.Model): - first_name = models.CharField(max_length=50) - last_name = models.CharField(max_length=50) - - def __unicode__(self): - return u'%s %s' % (self.first_name, self.last_name) - -If you define a ``__unicode__()`` method on your model and not a ``__str__()`` -method, Django will automatically provide you with a ``__str__()`` that calls -``__unicode__()`` and then converts the result correctly to a UTF-8 encoded -string object. This is recommended development practice: define only -``__unicode__()`` and let Django take care of the conversion to string objects -when required. - -``get_absolute_url`` --------------------- - -.. method:: Model.get_absolute_url() - -Define a ``get_absolute_url()`` method to tell Django how to calculate the -URL for an object. For example:: - - def get_absolute_url(self): - return "/people/%i/" % self.id - -Django uses this in its admin interface. If an object defines -``get_absolute_url()``, the object-editing page will have a "View on site" -link that will jump you directly to the object's public view, according to -``get_absolute_url()``. - -Also, a couple of other bits of Django, such as the :doc:`syndication feed -framework </ref/contrib/syndication>`, use ``get_absolute_url()`` as a -convenience to reward people who've defined the method. - -It's good practice to use ``get_absolute_url()`` in templates, instead of -hard-coding your objects' URLs. For example, this template code is bad:: - - <a href="/people/{{ object.id }}/">{{ object.name }}</a> - -But this template code is good:: - - <a href="{{ object.get_absolute_url }}">{{ object.name }}</a> - -.. note:: - The string you return from ``get_absolute_url()`` must contain only ASCII - characters (required by the URI spec, `RFC 2396`_) that have been - URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` - should be able to use the result directly without needing to do any - further processing. You may wish to use the - ``django.utils.encoding.iri_to_uri()`` function to help with this if you - are using unicode strings a lot. - -.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt - -The ``permalink`` decorator -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The problem with the way we wrote ``get_absolute_url()`` above is that it -slightly violates the DRY principle: the URL for this object is defined both -in the URLconf file and in the model. - -You can further decouple your models from the URLconf using the ``permalink`` -decorator: - -.. function:: permalink() - -This decorator is passed the view function, a list of positional parameters and -(optionally) a dictionary of named parameters. Django then works out the correct -full URL path using the URLconf, substituting the parameters you have given into -the URL. For example, if your URLconf contained a line such as:: - - (r'^people/(\d+)/$', 'people.views.details'), - -...your model could have a ``get_absolute_url`` method that looked like this:: - - from django.db import models - - @models.permalink - def get_absolute_url(self): - return ('people.views.details', [str(self.id)]) - -Similarly, if you had a URLconf entry that looked like:: - - (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view) - -...you could reference this using ``permalink()`` as follows:: - - @models.permalink - def get_absolute_url(self): - return ('archive_view', (), { - 'year': self.created.year, - 'month': self.created.month, - 'day': self.created.day}) - -Notice that we specify an empty sequence for the second parameter in this case, -because we only want to pass keyword parameters, not positional ones. - -In this way, you're tying the model's absolute path to the view that is used -to display it, without repeating the URL information anywhere. You can still -use the ``get_absolute_url`` method in templates, as before. - -In some cases, such as the use of generic views or the re-use of -custom views for multiple models, specifying the view function may -confuse the reverse URL matcher (because multiple patterns point to -the same view). - -For that problem, Django has **named URL patterns**. Using a named -URL pattern, it's possible to give a name to a pattern, and then -reference the name rather than the view function. A named URL -pattern is defined by replacing the pattern tuple by a call to -the ``url`` function):: - - from django.conf.urls.defaults import * - - url(r'^people/(\d+)/$', - 'django.views.generic.list_detail.object_detail', - name='people_view'), - -...and then using that name to perform the reverse URL resolution instead -of the view name:: - - from django.db import models - - @models.permalink - def get_absolute_url(self): - return ('people_view', [str(self.id)]) - -More details on named URL patterns are in the :doc:`URL dispatch documentation -</topics/http/urls>`. - -Extra instance methods -====================== - -In addition to ``save()``, ``delete()``, a model object might get any or all -of the following methods: - -.. method:: Model.get_FOO_display() - -For every field that has ``choices`` set, the object will have a -``get_FOO_display()`` method, where ``FOO`` is the name of the field. This -method returns the "human-readable" value of the field. For example, in the -following model:: - - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) - class Person(models.Model): - name = models.CharField(max_length=20) - gender = models.CharField(max_length=1, choices=GENDER_CHOICES) - -...each ``Person`` instance will have a ``get_gender_display()`` method. Example:: - - >>> p = Person(name='John', gender='M') - >>> p.save() - >>> p.gender - 'M' - >>> p.get_gender_display() - 'Male' - -.. method:: Model.get_next_by_FOO(\**kwargs) -.. method:: Model.get_previous_by_FOO(\**kwargs) - -For every ``DateField`` and ``DateTimeField`` that does not have ``null=True``, -the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()`` -methods, where ``FOO`` is the name of the field. This returns the next and -previous object with respect to the date field, raising the appropriate -``DoesNotExist`` exception when appropriate. - -Both methods accept optional keyword arguments, which should be in the format -described in :ref:`Field lookups <field-lookups>`. - -Note that in the case of identical date values, these methods will use the ID -as a fallback check. This guarantees that no records are skipped or duplicated. diff --git a/parts/django/docs/ref/models/options.txt b/parts/django/docs/ref/models/options.txt deleted file mode 100644 index 1b04c46..0000000 --- a/parts/django/docs/ref/models/options.txt +++ /dev/null @@ -1,269 +0,0 @@ -====================== -Model ``Meta`` options -====================== - -This document explains all the possible :ref:`metadata options -<meta-options>` that you can give your model in its internal ``class -Meta``. - -Available ``Meta`` options -========================== - -.. currentmodule:: django.db.models - -``abstract`` ------------- - -.. attribute:: Options.abstract - -If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`. - -``app_label`` -------------- - -.. attribute:: Options.app_label - -If a model exists outside of the standard :file:`models.py` (for instance, if -the app's models are in submodules of ``myapp.models``), the model must define -which app it is part of:: - - app_label = 'myapp' - -``db_table`` ------------- - -.. attribute:: Options.db_table - -The name of the database table to use for the model:: - - db_table = 'music_album' - -.. _table-names: - -Table names -~~~~~~~~~~~ - -To save you time, Django automatically derives the name of the database table -from the name of your model class and the app that contains it. A model's -database table name is constructed by joining the model's "app label" -- the -name you used in ``manage.py startapp`` -- to the model's class name, with an -underscore between them. - -For example, if you have an app ``bookstore`` (as created by -``manage.py startapp bookstore``), a model defined as ``class Book`` will have -a database table named ``bookstore_book``. - -To override the database table name, use the ``db_table`` parameter in -``class Meta``. - -If your database table name is an SQL reserved word, or contains characters that -aren't allowed in Python variable names -- notably, the hyphen -- that's OK. -Django quotes column and table names behind the scenes. - -``db_tablespace`` ------------------ - -.. attribute:: Options.db_tablespace - -.. versionadded:: 1.0 - -The name of the database tablespace to use for the model. If the backend doesn't -support tablespaces, this option is ignored. - -``get_latest_by`` ------------------ - -.. attribute:: Options.get_latest_by - -The name of a :class:`DateField` or :class:`DateTimeField` in the model. This -specifies the default field to use in your model :class:`Manager`'s -:class:`~QuerySet.latest` method. - -Example:: - - get_latest_by = "order_date" - -See the docs for :meth:`~django.db.models.QuerySet.latest` for more. - -``managed`` ------------------------ - -.. attribute:: Options.managed - -.. versionadded:: 1.1 - -Defaults to ``True``, meaning Django will create the appropriate database -tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset` -management command. That is, Django *manages* the database tables' lifecycles. - -If ``False``, no database table creation or deletion operations will be -performed for this model. This is useful if the model represents an existing -table or a database view that has been created by some other means. This is -the *only* difference when ``managed`` is ``False``. All other aspects of -model handling are exactly the same as normal. This includes - - 1. Adding an automatic primary key field to the model if you don't declare - it. To avoid confusion for later code readers, it's recommended to - specify all the columns from the database table you are modeling when - using unmanaged models. - - 2. If a model with ``managed=False`` contains a - :class:`~django.db.models.ManyToManyField` that points to another - unmanaged model, then the intermediate table for the many-to-many join - will also not be created. However, a the intermediary table between one - managed and one unmanaged model *will* be created. - - If you need to change this default behavior, create the intermediary - table as an explicit model (with ``managed`` set as needed) and use the - :attr:`ManyToManyField.through` attribute to make the relation use your - custom model. - -For tests involving models with ``managed=False``, it's up to you to ensure -the correct tables are created as part of the test setup. - -If you're interested in changing the Python-level behavior of a model class, -you *could* use ``managed=False`` and create a copy of an existing model. -However, there's a better approach for that situation: :ref:`proxy-models`. - -``order_with_respect_to`` -------------------------- - -.. attribute:: Options.order_with_respect_to - -Marks this object as "orderable" with respect to the given field. This is almost -always used with related objects to allow them to be ordered with respect to a -parent object. For example, if an ``Answer`` relates to a ``Question`` object, -and a question has more than one answer, and the order of answers matters, you'd -do this:: - - class Answer(models.Model): - question = models.ForeignKey(Question) - # ... - - class Meta: - order_with_respect_to = 'question' - -When ``order_with_respect_to`` is set, two additional methods are provided to -retrieve and to set the order of the related objects: ``get_RELATED_order()`` -and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For -example, assuming that a ``Question`` object has multiple related ``Answer`` -objects, the list returned contains the primary keys of the related ``Answer`` -objects:: - - >>> question = Question.objects.get(id=1) - >>> question.get_answer_order() - [1, 2, 3] - -The order of a ``Question`` object's related ``Answer`` objects can be set by -passing in a list of ``Answer`` primary keys:: - - >>> question.set_answer_order([3, 1, 2]) - -The related objects also get two methods, ``get_next_in_order()`` and -``get_previous_in_order()``, which can be used to access those objects in their -proper order. Assuming the ``Answer`` objects are ordered by ``id``:: - - >>> answer = Answer.objects.get(id=2) - >>> answer.get_next_in_order() - <Answer: 3> - >>> answer.get_previous_in_order() - <Answer: 1> - -``ordering`` ------------- - -.. attribute:: Options.ordering - -The default ordering for the object, for use when obtaining lists of objects:: - - ordering = ['-order_date'] - -This is a tuple or list of strings. Each string is a field name with an optional -"-" prefix, which indicates descending order. Fields without a leading "-" will -be ordered ascending. Use the string "?" to order randomly. - -.. note:: - - Regardless of how many fields are in :attr:`~Options.ordering`, the admin - site uses only the first field. - -For example, to order by a ``pub_date`` field ascending, use this:: - - ordering = ['pub_date'] - -To order by ``pub_date`` descending, use this:: - - ordering = ['-pub_date'] - -To order by ``pub_date`` descending, then by ``author`` ascending, use this:: - - ordering = ['-pub_date', 'author'] - -``permissions`` ---------------- - -.. attribute:: Options.permissions - -Extra permissions to enter into the permissions table when creating this object. -Add, delete and change permissions are automatically created for each object -that has ``admin`` set. This example specifies an extra permission, -``can_deliver_pizzas``:: - - permissions = (("can_deliver_pizzas", "Can deliver pizzas"),) - -This is a list or tuple of 2-tuples in the format ``(permission_code, -human_readable_permission_name)``. - -``proxy`` ---------- - -.. attribute:: Options.proxy - -.. versionadded:: 1.1 - -If set to ``True``, a model which subclasses another model will be treated as -a :ref:`proxy model <proxy-models>`. - -``unique_together`` -------------------- - -.. attribute:: Options.unique_together - -Sets of field names that, taken together, must be unique:: - - unique_together = (("driver", "restaurant"),) - -This is a list of lists of fields that must be unique when considered together. -It's used in the Django admin and is enforced at the database level (i.e., the -appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE`` -statement). - -.. versionadded:: 1.0 - -For convenience, unique_together can be a single list when dealing with a single -set of fields:: - - unique_together = ("driver", "restaurant") - -``verbose_name`` ----------------- - -.. attribute:: Options.verbose_name - -A human-readable name for the object, singular:: - - verbose_name = "pizza" - -If this isn't given, Django will use a munged version of the class name: -``CamelCase`` becomes ``camel case``. - -``verbose_name_plural`` ------------------------ - -.. attribute:: Options.verbose_name_plural - -The plural name for the object:: - - verbose_name_plural = "stories" - -If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``. diff --git a/parts/django/docs/ref/models/querysets.txt b/parts/django/docs/ref/models/querysets.txt deleted file mode 100644 index 9f0de1f..0000000 --- a/parts/django/docs/ref/models/querysets.txt +++ /dev/null @@ -1,1888 +0,0 @@ -====================== -QuerySet API reference -====================== - -.. currentmodule:: django.db.models.QuerySet - -This document describes the details of the ``QuerySet`` API. It builds on the -material presented in the :doc:`model </topics/db/models>` and :doc:`database -query </topics/db/queries>` guides, so you'll probably want to read and -understand those documents before reading this one. - -Throughout this reference we'll use the :ref:`example Weblog models -<queryset-model-example>` presented in the :doc:`database query guide -</topics/db/queries>`. - -.. _when-querysets-are-evaluated: - -When QuerySets are evaluated -============================ - -Internally, a ``QuerySet`` can be constructed, filtered, sliced, and generally -passed around without actually hitting the database. No database activity -actually occurs until you do something to evaluate the queryset. - -You can evaluate a ``QuerySet`` in the following ways: - - * **Iteration.** A ``QuerySet`` is iterable, and it executes its database - query the first time you iterate over it. For example, this will print - the headline of all entries in the database:: - - for e in Entry.objects.all(): - print e.headline - - * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can - be sliced, using Python's array-slicing syntax. Usually slicing a - ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will - execute the database query if you use the "step" parameter of slice - syntax. - - * **Pickling/Caching.** See the following section for details of what - is involved when `pickling QuerySets`_. The important thing for the - purposes of this section is that the results are read from the database. - - * **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it. - This is for convenience in the Python interactive interpreter, so you can - immediately see your results when using the API interactively. - - * **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it. - This, as you might expect, returns the length of the result list. - - Note: *Don't* use ``len()`` on ``QuerySet``\s if all you want to do is - determine the number of records in the set. It's much more efficient to - handle a count at the database level, using SQL's ``SELECT COUNT(*)``, - and Django provides a ``count()`` method for precisely this reason. See - ``count()`` below. - - * **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on - it. For example:: - - entry_list = list(Entry.objects.all()) - - Be warned, though, that this could have a large memory overhead, because - Django will load each element of the list into memory. In contrast, - iterating over a ``QuerySet`` will take advantage of your database to - load data and instantiate objects only as you need them. - - * **bool().** Testing a ``QuerySet`` in a boolean context, such as using - ``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query - to be executed. If there is at least one result, the ``QuerySet`` is - ``True``, otherwise ``False``. For example:: - - if Entry.objects.filter(headline="Test"): - print "There is at least one Entry with the headline Test" - - Note: *Don't* use this if all you want to do is determine if at least one - result exists, and don't need the actual objects. It's more efficient to - use ``exists()`` (see below). - -.. _pickling QuerySets: - -Pickling QuerySets ------------------- - -If you pickle_ a ``QuerySet``, this will force all the results to be loaded -into memory prior to pickling. Pickling is usually used as a precursor to -caching and when the cached queryset is reloaded, you want the results to -already be present and ready for use (reading from the database can take some -time, defeating the purpose of caching). This means that when you unpickle a -``QuerySet``, it contains the results at the moment it was pickled, rather -than the results that are currently in the database. - -If you only want to pickle the necessary information to recreate the -``QuerySet`` from the database at a later time, pickle the ``query`` attribute -of the ``QuerySet``. You can then recreate the original ``QuerySet`` (without -any results loaded) using some code like this:: - - >>> import pickle - >>> query = pickle.loads(s) # Assuming 's' is the pickled string. - >>> qs = MyModel.objects.all() - >>> qs.query = query # Restore the original 'query'. - -The ``query`` attribute is an opaque object. It represents the internals of -the query construction and is not part of the public API. However, it is safe -(and fully supported) to pickle and unpickle the attribute's contents as -described here. - -.. admonition:: You can't share pickles between versions - - Pickles of QuerySets are only valid for the version of Django that - was used to generate them. If you generate a pickle using Django - version N, there is no guarantee that pickle will be readable with - Django version N+1. Pickles should not be used as part of a long-term - archival strategy. - -.. _pickle: http://docs.python.org/library/pickle.html - -.. _queryset-api: - -QuerySet API -============ - -Though you usually won't create one manually -- you'll go through a -:class:`Manager` -- here's the formal declaration of a ``QuerySet``: - -.. class:: QuerySet([model=None]) - -Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining -filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets. - -Methods that return new QuerySets ---------------------------------- - -Django provides a range of ``QuerySet`` refinement methods that modify either -the types of results returned by the ``QuerySet`` or the way its SQL query is -executed. - -filter -~~~~~~ - -.. method:: filter(**kwargs) - -Returns a new ``QuerySet`` containing objects that match the given lookup -parameters. - -The lookup parameters (``**kwargs``) should be in the format described in -`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the -underlying SQL statement. - -exclude -~~~~~~~ - -.. method:: exclude(**kwargs) - -Returns a new ``QuerySet`` containing objects that do *not* match the given -lookup parameters. - -The lookup parameters (``**kwargs``) should be in the format described in -`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the -underlying SQL statement, and the whole thing is enclosed in a ``NOT()``. - -This example excludes all entries whose ``pub_date`` is later than 2005-1-3 -AND whose ``headline`` is "Hello":: - - Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello') - -In SQL terms, that evaluates to:: - - SELECT ... - WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello') - -This example excludes all entries whose ``pub_date`` is later than 2005-1-3 -OR whose headline is "Hello":: - - Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello') - -In SQL terms, that evaluates to:: - - SELECT ... - WHERE NOT pub_date > '2005-1-3' - AND NOT headline = 'Hello' - -Note the second example is more restrictive. - -annotate -~~~~~~~~ - -.. method:: annotate(*args, **kwargs) - -.. versionadded:: 1.1 - -Annotates each object in the ``QuerySet`` with the provided list of -aggregate values (averages, sums, etc) that have been computed over -the objects that are related to the objects in the ``QuerySet``. -Each argument to ``annotate()`` is an annotation that will be added -to each object in the ``QuerySet`` that is returned. - -The aggregation functions that are provided by Django are described -in `Aggregation Functions`_ below. - -Annotations specified using keyword arguments will use the keyword as -the alias for the annotation. Anonymous arguments will have an alias -generated for them based upon the name of the aggregate function and -the model field that is being aggregated. - -For example, if you were manipulating a list of blogs, you may want -to determine how many entries have been made in each blog:: - - >>> q = Blog.objects.annotate(Count('entry')) - # The name of the first blog - >>> q[0].name - 'Blogasaurus' - # The number of entries on the first blog - >>> q[0].entry__count - 42 - -The ``Blog`` model doesn't define an ``entry__count`` attribute by itself, -but by using a keyword argument to specify the aggregate function, you can -control the name of the annotation:: - - >>> q = Blog.objects.annotate(number_of_entries=Count('entry')) - # The number of entries on the first blog, using the name provided - >>> q[0].number_of_entries - 42 - -For an in-depth discussion of aggregation, see :doc:`the topic guide on -Aggregation </topics/db/aggregation>`. - -order_by -~~~~~~~~ - -.. method:: order_by(*fields) - -By default, results returned by a ``QuerySet`` are ordered by the ordering -tuple given by the ``ordering`` option in the model's ``Meta``. You can -override this on a per-``QuerySet`` basis by using the ``order_by`` method. - -Example:: - - Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline') - -The result above will be ordered by ``pub_date`` descending, then by -``headline`` ascending. The negative sign in front of ``"-pub_date"`` indicates -*descending* order. Ascending order is implied. To order randomly, use ``"?"``, -like so:: - - Entry.objects.order_by('?') - -Note: ``order_by('?')`` queries may be expensive and slow, depending on the -database backend you're using. - -To order by a field in a different model, use the same syntax as when you are -querying across model relations. That is, the name of the field, followed by a -double underscore (``__``), followed by the name of the field in the new model, -and so on for as many models as you want to join. For example:: - - Entry.objects.order_by('blog__name', 'headline') - -If you try to order by a field that is a relation to another model, Django will -use the default ordering on the related model (or order by the related model's -primary key if there is no ``Meta.ordering`` specified. For example:: - - Entry.objects.order_by('blog') - -...is identical to:: - - Entry.objects.order_by('blog__id') - -...since the ``Blog`` model has no default ordering specified. - -Be cautious when ordering by fields in related models if you are also using -``distinct()``. See the note in :meth:`distinct` for an explanation of how -related model ordering can change the expected results. - -It is permissible to specify a multi-valued field to order the results by (for -example, a ``ManyToMany`` field). Normally this won't be a sensible thing to -do and it's really an advanced usage feature. However, if you know that your -queryset's filtering or available data implies that there will only be one -ordering piece of data for each of the main items you are selecting, the -ordering may well be exactly what you want to do. Use ordering on multi-valued -fields with care and make sure the results are what you expect. - -.. versionadded:: 1.0 - -The syntax for ordering across related models has changed. See the `Django 0.96 -documentation`_ for the old behaviour. - -.. _Django 0.96 documentation: http://www.djangoproject.com/documentation/0.96/model-api/#floatfield - -There's no way to specify whether ordering should be case sensitive. With -respect to case-sensitivity, Django will order results however your database -backend normally orders them. - -If you don't want any ordering to be applied to a query, not even the default -ordering, call ``order_by()`` with no parameters. - -.. versionadded:: 1.1 - -You can tell if a query is ordered or not by checking the -:attr:`QuerySet.ordered` attribute, which will be ``True`` if the -``QuerySet`` has been ordered in any way. - -reverse -~~~~~~~ - -.. method:: reverse() - -.. versionadded:: 1.0 - -Use the ``reverse()`` method to reverse the order in which a queryset's -elements are returned. Calling ``reverse()`` a second time restores the -ordering back to the normal direction. - -To retrieve the ''last'' five items in a queryset, you could do this:: - - my_queryset.reverse()[:5] - -Note that this is not quite the same as slicing from the end of a sequence in -Python. The above example will return the last item first, then the -penultimate item and so on. If we had a Python sequence and looked at -``seq[-5:]``, we would see the fifth-last item first. Django doesn't support -that mode of access (slicing from the end), because it's not possible to do it -efficiently in SQL. - -Also, note that ``reverse()`` should generally only be called on a -``QuerySet`` which has a defined ordering (e.g., when querying against -a model which defines a default ordering, or when using -``order_by()``). If no such ordering is defined for a given -``QuerySet``, calling ``reverse()`` on it has no real effect (the -ordering was undefined prior to calling ``reverse()``, and will remain -undefined afterward). - -distinct -~~~~~~~~ - -.. method:: distinct() - -Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This -eliminates duplicate rows from the query results. - -By default, a ``QuerySet`` will not eliminate duplicate rows. In practice, this -is rarely a problem, because simple queries such as ``Blog.objects.all()`` -don't introduce the possibility of duplicate result rows. However, if your -query spans multiple tables, it's possible to get duplicate results when a -``QuerySet`` is evaluated. That's when you'd use ``distinct()``. - -.. note:: - Any fields used in an :meth:`order_by` call are included in the SQL - ``SELECT`` columns. This can sometimes lead to unexpected results when - used in conjunction with ``distinct()``. If you order by fields from a - related model, those fields will be added to the selected columns and they - may make otherwise duplicate rows appear to be distinct. Since the extra - columns don't appear in the returned results (they are only there to - support ordering), it sometimes looks like non-distinct results are being - returned. - - Similarly, if you use a ``values()`` query to restrict the columns - selected, the columns used in any ``order_by()`` (or default model - ordering) will still be involved and may affect uniqueness of the results. - - The moral here is that if you are using ``distinct()`` be careful about - ordering by related models. Similarly, when using ``distinct()`` and - ``values()`` together, be careful when ordering by fields not in the - ``values()`` call. - -values -~~~~~~ - -.. method:: values(*fields) - -Returns a ``ValuesQuerySet`` -- a ``QuerySet`` that returns dictionaries when -used as an iterable, rather than model-instance objects. - -Each of those dictionaries represents an object, with the keys corresponding to -the attribute names of model objects. - -This example compares the dictionaries of ``values()`` with the normal model -objects:: - - # This list contains a Blog object. - >>> Blog.objects.filter(name__startswith='Beatles') - [<Blog: Beatles Blog>] - - # This list contains a dictionary. - >>> Blog.objects.filter(name__startswith='Beatles').values() - [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}] - -``values()`` takes optional positional arguments, ``*fields``, which specify -field names to which the ``SELECT`` should be limited. If you specify the -fields, each dictionary will contain only the field keys/values for the fields -you specify. If you don't specify the fields, each dictionary will contain a -key and value for every field in the database table. - -Example:: - - >>> Blog.objects.values() - [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}], - >>> Blog.objects.values('id', 'name') - [{'id': 1, 'name': 'Beatles Blog'}] - -A couple of subtleties that are worth mentioning: - - * The ``values()`` method does not return anything for - :class:`~django.db.models.ManyToManyField` attributes and will raise an - error if you try to pass in this type of field to it. - * If you have a field called ``foo`` that is a - :class:`~django.db.models.ForeignKey`, the default ``values()`` call - will return a dictionary key called ``foo_id``, since this is the name - of the hidden model attribute that stores the actual value (the ``foo`` - attribute refers to the related model). When you are calling - ``values()`` and passing in field names, you can pass in either ``foo`` - or ``foo_id`` and you will get back the same thing (the dictionary key - will match the field name you passed in). - - For example:: - - >>> Entry.objects.values() - [{'blog_id': 1, 'headline': u'First Entry', ...}, ...] - - >>> Entry.objects.values('blog') - [{'blog': 1}, ...] - - >>> Entry.objects.values('blog_id') - [{'blog_id': 1}, ...] - - * When using ``values()`` together with ``distinct()``, be aware that - ordering can affect the results. See the note in :meth:`distinct` for - details. - - * If you use a ``values()`` clause after an ``extra()`` clause, - any fields defined by a ``select`` argument in the ``extra()`` - must be explicitly included in the ``values()`` clause. However, - if the ``extra()`` clause is used after the ``values()``, the - fields added by the select will be included automatically. - -.. versionadded:: 1.0 - -Previously, it was not possible to pass ``blog_id`` to ``values()`` in the above -example, only ``blog``. - -A ``ValuesQuerySet`` is useful when you know you're only going to need values -from a small number of the available fields and you won't need the -functionality of a model instance object. It's more efficient to select only -the fields you need to use. - -Finally, note a ``ValuesQuerySet`` is a subclass of ``QuerySet``, so it has all -methods of ``QuerySet``. You can call ``filter()`` on it, or ``order_by()``, or -whatever. Yes, that means these two calls are identical:: - - Blog.objects.values().order_by('id') - Blog.objects.order_by('id').values() - -The people who made Django prefer to put all the SQL-affecting methods first, -followed (optionally) by any output-affecting methods (such as ``values()``), -but it doesn't really matter. This is your chance to really flaunt your -individualism. - -values_list -~~~~~~~~~~~ - -.. method:: values_list(*fields) - -.. versionadded:: 1.0 - -This is similar to ``values()`` except that instead of returning dictionaries, -it returns tuples when iterated over. Each tuple contains the value from the -respective field passed into the ``values_list()`` call -- so the first item is -the first field, etc. For example:: - - >>> Entry.objects.values_list('id', 'headline') - [(1, u'First entry'), ...] - -If you only pass in a single field, you can also pass in the ``flat`` -parameter. If ``True``, this will mean the returned results are single values, -rather than one-tuples. An example should make the difference clearer:: - - >>> Entry.objects.values_list('id').order_by('id') - [(1,), (2,), (3,), ...] - - >>> Entry.objects.values_list('id', flat=True).order_by('id') - [1, 2, 3, ...] - -It is an error to pass in ``flat`` when there is more than one field. - -If you don't pass any values to ``values_list()``, it will return all the -fields in the model, in the order they were declared. - -dates -~~~~~ - -.. method:: dates(field, kind, order='ASC') - -Returns a ``DateQuerySet`` -- a ``QuerySet`` that evaluates to a list of -``datetime.datetime`` objects representing all available dates of a particular -kind within the contents of the ``QuerySet``. - -``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your -model. - -``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each -``datetime.datetime`` object in the result list is "truncated" to the given -``type``. - - * ``"year"`` returns a list of all distinct year values for the field. - * ``"month"`` returns a list of all distinct year/month values for the field. - * ``"day"`` returns a list of all distinct year/month/day values for the field. - -``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or -``'DESC'``. This specifies how to order the results. - -Examples:: - - >>> Entry.objects.dates('pub_date', 'year') - [datetime.datetime(2005, 1, 1)] - >>> Entry.objects.dates('pub_date', 'month') - [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)] - >>> Entry.objects.dates('pub_date', 'day') - [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)] - >>> Entry.objects.dates('pub_date', 'day', order='DESC') - [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] - >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') - [datetime.datetime(2005, 3, 20)] - -none -~~~~ - -.. method:: none() - -.. versionadded:: 1.0 - -Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to -an empty list. This can be used in cases where you know that you should -return an empty result set and your caller is expecting a ``QuerySet`` -object (instead of returning an empty list, for example.) - -Examples:: - - >>> Entry.objects.none() - [] - -all -~~~ - -.. method:: all() - -.. versionadded:: 1.0 - -Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you -pass in). This can be useful in some situations where you might want to pass -in either a model manager or a ``QuerySet`` and do further filtering on the -result. You can safely call ``all()`` on either object and then you'll -definitely have a ``QuerySet`` to work with. - -.. _select-related: - -select_related -~~~~~~~~~~~~~~ - -.. method:: select_related() - -Returns a ``QuerySet`` that will automatically "follow" foreign-key -relationships, selecting that additional related-object data when it executes -its query. This is a performance booster which results in (sometimes much) -larger queries but means later use of foreign-key relationships won't require -database queries. - -The following examples illustrate the difference between plain lookups and -``select_related()`` lookups. Here's standard lookup:: - - # Hits the database. - e = Entry.objects.get(id=5) - - # Hits the database again to get the related Blog object. - b = e.blog - -And here's ``select_related`` lookup:: - - # Hits the database. - e = Entry.objects.select_related().get(id=5) - - # Doesn't hit the database, because e.blog has been prepopulated - # in the previous query. - b = e.blog - -``select_related()`` follows foreign keys as far as possible. If you have the -following models:: - - class City(models.Model): - # ... - - class Person(models.Model): - # ... - hometown = models.ForeignKey(City) - - class Book(models.Model): - # ... - author = models.ForeignKey(Person) - -...then a call to ``Book.objects.select_related().get(id=4)`` will cache the -related ``Person`` *and* the related ``City``:: - - b = Book.objects.select_related().get(id=4) - p = b.author # Doesn't hit the database. - c = p.hometown # Doesn't hit the database. - - b = Book.objects.get(id=4) # No select_related() in this example. - p = b.author # Hits the database. - c = p.hometown # Hits the database. - -Note that, by default, ``select_related()`` does not follow foreign keys that -have ``null=True``. - -Usually, using ``select_related()`` can vastly improve performance because your -app can avoid many database calls. However, in situations with deeply nested -sets of relationships ``select_related()`` can sometimes end up following "too -many" relations, and can generate queries so large that they end up being slow. - -In these situations, you can use the ``depth`` argument to ``select_related()`` -to control how many "levels" of relations ``select_related()`` will actually -follow:: - - b = Book.objects.select_related(depth=1).get(id=4) - p = b.author # Doesn't hit the database. - c = p.hometown # Requires a database call. - -Sometimes you only want to access specific models that are related to your root -model, not all of the related models. In these cases, you can pass the related -field names to ``select_related()`` and it will only follow those relations. -You can even do this for models that are more than one relation away by -separating the field names with double underscores, just as for filters. For -example, if you have this model:: - - class Room(models.Model): - # ... - building = models.ForeignKey(...) - - class Group(models.Model): - # ... - teacher = models.ForeignKey(...) - room = models.ForeignKey(Room) - subject = models.ForeignKey(...) - -...and you only needed to work with the ``room`` and ``subject`` attributes, -you could write this:: - - g = Group.objects.select_related('room', 'subject') - -This is also valid:: - - g = Group.objects.select_related('room__building', 'subject') - -...and would also pull in the ``building`` relation. - -You can refer to any ``ForeignKey`` or ``OneToOneField`` relation in -the list of fields passed to ``select_related``. Ths includes foreign -keys that have ``null=True`` (unlike the default ``select_related()`` -call). It's an error to use both a list of fields and the ``depth`` -parameter in the same ``select_related()`` call, since they are -conflicting options. - -.. versionadded:: 1.0 - -Both the ``depth`` argument and the ability to specify field names in the call -to ``select_related()`` are new in Django version 1.0. - -.. versionchanged:: 1.2 - -You can also refer to the reverse direction of a ``OneToOneFields`` in -the list of fields passed to ``select_related`` -- that is, you can traverse -a ``OneToOneField`` back to the object on which the field is defined. Instead -of specifying the field name, use the ``related_name`` for the field on the -related object. - -``OneToOneFields`` will not be traversed in the reverse direction if you -are performing a depth-based ``select_related``. - -extra -~~~~~ - -.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None) - -Sometimes, the Django query syntax by itself can't easily express a complex -``WHERE`` clause. For these edge cases, Django provides the ``extra()`` -``QuerySet`` modifier -- a hook for injecting specific clauses into the SQL -generated by a ``QuerySet``. - -By definition, these extra lookups may not be portable to different database -engines (because you're explicitly writing SQL code) and violate the DRY -principle, so you should avoid them if possible. - -Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None -of the arguments is required, but you should use at least one of them. - - * ``select`` - The ``select`` argument lets you put extra fields in the ``SELECT`` clause. - It should be a dictionary mapping attribute names to SQL clauses to use to - calculate that attribute. - - Example:: - - Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"}) - - As a result, each ``Entry`` object will have an extra attribute, - ``is_recent``, a boolean representing whether the entry's ``pub_date`` is - greater than Jan. 1, 2006. - - Django inserts the given SQL snippet directly into the ``SELECT`` - statement, so the resulting SQL of the above example would be something - like:: - - SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent - FROM blog_entry; - - - The next example is more advanced; it does a subquery to give each - resulting ``Blog`` object an ``entry_count`` attribute, an integer count - of associated ``Entry`` objects:: - - Blog.objects.extra( - select={ - 'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id' - }, - ) - - (In this particular case, we're exploiting the fact that the query will - already contain the ``blog_blog`` table in its ``FROM`` clause.) - - The resulting SQL of the above example would be:: - - SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count - FROM blog_blog; - - Note that the parenthesis required by most database engines around - subqueries are not required in Django's ``select`` clauses. Also note that - some database backends, such as some MySQL versions, don't support - subqueries. - - .. versionadded:: 1.0 - - In some rare cases, you might wish to pass parameters to the SQL fragments - in ``extra(select=...)``. For this purpose, use the ``select_params`` - parameter. Since ``select_params`` is a sequence and the ``select`` - attribute is a dictionary, some care is required so that the parameters - are matched up correctly with the extra select pieces. In this situation, - you should use a ``django.utils.datastructures.SortedDict`` for the - ``select`` value, not just a normal Python dictionary. - - This will work, for example:: - - Blog.objects.extra( - select=SortedDict([('a', '%s'), ('b', '%s')]), - select_params=('one', 'two')) - - The only thing to be careful about when using select parameters in - ``extra()`` is to avoid using the substring ``"%%s"`` (that's *two* - percent characters before the ``s``) in the select strings. Django's - tracking of parameters looks for ``%s`` and an escaped ``%`` character - like this isn't detected. That will lead to incorrect results. - - * ``where`` / ``tables`` - You can define explicit SQL ``WHERE`` clauses -- perhaps to perform - non-explicit joins -- by using ``where``. You can manually add tables to - the SQL ``FROM`` clause by using ``tables``. - - ``where`` and ``tables`` both take a list of strings. All ``where`` - parameters are "AND"ed to any other search criteria. - - Example:: - - Entry.objects.extra(where=['id IN (3, 4, 5, 20)']) - - ...translates (roughly) into the following SQL:: - - SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20); - - Be careful when using the ``tables`` parameter if you're specifying - tables that are already used in the query. When you add extra tables - via the ``tables`` parameter, Django assumes you want that table included - an extra time, if it is already included. That creates a problem, - since the table name will then be given an alias. If a table appears - multiple times in an SQL statement, the second and subsequent occurrences - must use aliases so the database can tell them apart. If you're - referring to the extra table you added in the extra ``where`` parameter - this is going to cause errors. - - Normally you'll only be adding extra tables that don't already appear in - the query. However, if the case outlined above does occur, there are a few - solutions. First, see if you can get by without including the extra table - and use the one already in the query. If that isn't possible, put your - ``extra()`` call at the front of the queryset construction so that your - table is the first use of that table. Finally, if all else fails, look at - the query produced and rewrite your ``where`` addition to use the alias - given to your extra table. The alias will be the same each time you - construct the queryset in the same way, so you can rely upon the alias - name to not change. - - * ``order_by`` - If you need to order the resulting queryset using some of the new fields - or tables you have included via ``extra()`` use the ``order_by`` parameter - to ``extra()`` and pass in a sequence of strings. These strings should - either be model fields (as in the normal ``order_by()`` method on - querysets), of the form ``table_name.column_name`` or an alias for a column - that you specified in the ``select`` parameter to ``extra()``. - - For example:: - - q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"}) - q = q.extra(order_by = ['-is_recent']) - - This would sort all the items for which ``is_recent`` is true to the front - of the result set (``True`` sorts before ``False`` in a descending - ordering). - - This shows, by the way, that you can make multiple calls to - ``extra()`` and it will behave as you expect (adding new constraints each - time). - - * ``params`` - The ``where`` parameter described above may use standard Python database - string placeholders -- ``'%s'`` to indicate parameters the database engine - should automatically quote. The ``params`` argument is a list of any extra - parameters to be substituted. - - Example:: - - Entry.objects.extra(where=['headline=%s'], params=['Lennon']) - - Always use ``params`` instead of embedding values directly into ``where`` - because ``params`` will ensure values are quoted correctly according to - your particular backend. (For example, quotes will be escaped correctly.) - - Bad:: - - Entry.objects.extra(where=["headline='Lennon'"]) - - Good:: - - Entry.objects.extra(where=['headline=%s'], params=['Lennon']) - -defer -~~~~~ - -.. method:: defer(*fields) - -.. versionadded:: 1.1 - -In some complex data-modeling situations, your models might contain a lot of -fields, some of which could contain a lot of data (for example, text fields), -or require expensive processing to convert them to Python objects. If you are -using the results of a queryset in some situation where you know you don't -need those particular fields, you can tell Django not to retrieve them from -the database. - -This is done by passing the names of the fields to not load to ``defer()``:: - - Entry.objects.defer("headline", "body") - -A queryset that has deferred fields will still return model instances. Each -deferred field will be retrieved from the database if you access that field -(one at a time, not all the deferred fields at once). - -You can make multiple calls to ``defer()``. Each call adds new fields to the -deferred set:: - - # Defers both the body and headline fields. - Entry.objects.defer("body").filter(rating=5).defer("headline") - -The order in which fields are added to the deferred set does not matter. -Calling ``defer()`` with a field name that has already been deferred is -harmless (the field will still be deferred). - -You can defer loading of fields in related models (if the related models are -loading via ``select_related()``) by using the standard double-underscore -notation to separate related fields:: - - Blog.objects.select_related().defer("entry__headline", "entry__body") - -If you want to clear the set of deferred fields, pass ``None`` as a parameter -to ``defer()``:: - - # Load all fields immediately. - my_queryset.defer(None) - -Some fields in a model won't be deferred, even if you ask for them. You can -never defer the loading of the primary key. If you are using -``select_related()`` to retrieve other models at the same time you shouldn't -defer the loading of the field that connects from the primary model to the -related one (at the moment, that doesn't raise an error, but it will -eventually). - -.. note:: - - The ``defer()`` method (and its cousin, ``only()``, below) are only for - advanced use-cases. They provide an optimization for when you have - analyzed your queries closely and understand *exactly* what information - you need and have measured that the difference between returning the - fields you need and the full set of fields for the model will be - significant. When you are initially developing your applications, don't - bother using ``defer()``; leave it until your query construction has - settled down and you understand where the hot-points are. - -only -~~~~ - -.. method:: only(*fields) - -.. versionadded:: 1.1 - -The ``only()`` method is more or less the opposite of ``defer()``. You -call it with the fields that should *not* be deferred when retrieving a model. -If you have a model where almost all the fields need to be deferred, using -``only()`` to specify the complementary set of fields could result in simpler -code. - -If you have a model with fields ``name``, ``age`` and ``biography``, the -following two querysets are the same, in terms of deferred fields:: - - Person.objects.defer("age", "biography") - Person.objects.only("name") - -Whenever you call ``only()`` it *replaces* the set of fields to load -immediately. The method's name is mnemonic: **only** those fields are loaded -immediately; the remainder are deferred. Thus, successive calls to ``only()`` -result in only the final fields being considered:: - - # This will defer all fields except the headline. - Entry.objects.only("body", "rating").only("headline") - -Since ``defer()`` acts incrementally (adding fields to the deferred list), you -can combine calls to ``only()`` and ``defer()`` and things will behave -logically:: - - # Final result is that everything except "headline" is deferred. - Entry.objects.only("headline", "body").defer("body") - - # Final result loads headline and body immediately (only() replaces any - # existing set of fields). - Entry.objects.defer("body").only("headline", "body") - -using -~~~~~ - -.. method:: using(alias) - -.. versionadded:: 1.2 - -This method is for controlling which database the ``QuerySet`` will be -evaluated against if you are using more than one database. The only argument -this method takes is the alias of a database, as defined in -:setting:`DATABASES`. - -For example:: - - # queries the database with the 'default' alias. - >>> Entry.objects.all() - - # queries the database with the 'backup' alias - >>> Entry.objects.using('backup') - - -Methods that do not return QuerySets ------------------------------------- - -The following ``QuerySet`` methods evaluate the ``QuerySet`` and return -something *other than* a ``QuerySet``. - -These methods do not use a cache (see :ref:`caching-and-querysets`). Rather, -they query the database each time they're called. - -get -~~~ - -.. method:: get(**kwargs) - -Returns the object matching the given lookup parameters, which should be in -the format described in `Field lookups`_. - -``get()`` raises ``MultipleObjectsReturned`` if more than one object was -found. The ``MultipleObjectsReturned`` exception is an attribute of the model -class. - -``get()`` raises a ``DoesNotExist`` exception if an object wasn't found for -the given parameters. This exception is also an attribute of the model class. -Example:: - - Entry.objects.get(id='foo') # raises Entry.DoesNotExist - -The ``DoesNotExist`` exception inherits from -``django.core.exceptions.ObjectDoesNotExist``, so you can target multiple -``DoesNotExist`` exceptions. Example:: - - from django.core.exceptions import ObjectDoesNotExist - try: - e = Entry.objects.get(id=3) - b = Blog.objects.get(id=1) - except ObjectDoesNotExist: - print "Either the entry or blog doesn't exist." - -create -~~~~~~ - -.. method:: create(**kwargs) - -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(force_insert=True) - -are equivalent. - -The :ref:`force_insert <ref-models-force-insert>` parameter is documented -elsewhere, but all it means is that a new object will always be created. -Normally you won't need to worry about this. However, if your model contains a -manual primary key value that you set and if that value already exists in the -database, a call to ``create()`` will fail with an :exc:`IntegrityError` since -primary keys must be unique. So remember to be prepared to handle the exception -if you are using manual primary keys. - -get_or_create -~~~~~~~~~~~~~ - -.. method:: get_or_create(**kwargs) - -A convenience method for looking up an object with the given kwargs, creating -one if necessary. - -Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or -created object and ``created`` is a boolean specifying whether a new object was -created. - -This is meant as a shortcut to boilerplatish code and is mostly useful for -data-import scripts. For example:: - - try: - obj = Person.objects.get(first_name='John', last_name='Lennon') - except Person.DoesNotExist: - obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9)) - obj.save() - -This pattern gets quite unwieldy as the number of fields in a model goes up. -The above example can be rewritten using ``get_or_create()`` like so:: - - obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon', - defaults={'birthday': date(1940, 10, 9)}) - -Any keyword arguments passed to ``get_or_create()`` -- *except* an optional one -called ``defaults`` -- will be used in a ``get()`` call. If an object is found, -``get_or_create()`` returns a tuple of that object and ``False``. If an object -is *not* found, ``get_or_create()`` will instantiate and save a new object, -returning a tuple of the new object and ``True``. The new object will be -created roughly according to this algorithm:: - - defaults = kwargs.pop('defaults', {}) - params = dict([(k, v) for k, v in kwargs.items() if '__' not in k]) - params.update(defaults) - obj = self.model(**params) - obj.save() - -In English, that means start with any non-``'defaults'`` keyword argument that -doesn't contain a double underscore (which would indicate a non-exact lookup). -Then add the contents of ``defaults``, overriding any keys if necessary, and -use the result as the keyword arguments to the model class. As hinted at -above, this is a simplification of the algorithm that is used, but it contains -all the pertinent details. The internal implementation has some more -error-checking than this and handles some extra edge-conditions; if you're -interested, read the code. - -If you have a field named ``defaults`` and want to use it as an exact lookup in -``get_or_create()``, just use ``'defaults__exact'``, like so:: - - Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'}) - - -The ``get_or_create()`` method has similar error behaviour to ``create()`` -when you are using manually specified primary keys. If an object needs to be -created and the key already exists in the database, an ``IntegrityError`` will -be raised. - -Finally, a word on using ``get_or_create()`` in Django views. As mentioned -earlier, ``get_or_create()`` is mostly useful in scripts that need to parse -data and create new records if existing ones aren't available. But if you need -to use ``get_or_create()`` in a view, please make sure to use it only in -``POST`` requests unless you have a good reason not to. ``GET`` requests -shouldn't have any effect on data; use ``POST`` whenever a request to a page -has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec. - -.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 - -count -~~~~~ - -.. method:: count() - -Returns an integer representing the number of objects in the database matching -the ``QuerySet``. ``count()`` never raises exceptions. - -Example:: - - # Returns the total number of entries in the database. - Entry.objects.count() - - # Returns the number of entries whose headline contains 'Lennon' - Entry.objects.filter(headline__contains='Lennon').count() - -``count()`` performs a ``SELECT COUNT(*)`` behind the scenes, so you should -always use ``count()`` rather than loading all of the record into Python -objects and calling ``len()`` on the result (unless you need to load the -objects into memory anyway, in which case ``len()`` will be faster). - -Depending on which database you're using (e.g. PostgreSQL vs. MySQL), -``count()`` may return a long integer instead of a normal Python integer. This -is an underlying implementation quirk that shouldn't pose any real-world -problems. - -in_bulk -~~~~~~~ - -.. method:: in_bulk(id_list) - -Takes a list of primary-key values and returns a dictionary mapping each -primary-key value to an instance of the object with the given ID. - -Example:: - - >>> Blog.objects.in_bulk([1]) - {1: <Blog: Beatles Blog>} - >>> Blog.objects.in_bulk([1, 2]) - {1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>} - >>> Blog.objects.in_bulk([]) - {} - -If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. - -iterator -~~~~~~~~ - -.. method:: iterator() - -Evaluates the ``QuerySet`` (by performing the query) and returns an -`iterator`_ over the results. A ``QuerySet`` typically caches its -results internally so that repeated evaluations do not result in -additional queries; ``iterator()`` will instead read results directly, -without doing any caching at the ``QuerySet`` level. For a -``QuerySet`` which returns a large number of objects, this often -results in better performance and a significant reduction in memory - -Note that using ``iterator()`` on a ``QuerySet`` which has already -been evaluated will force it to evaluate again, repeating the query. - -.. _iterator: http://www.python.org/dev/peps/pep-0234/ - -latest -~~~~~~ - -.. method:: latest(field_name=None) - -Returns the latest object in the table, by date, using the ``field_name`` -provided as the date field. - -This example returns the latest ``Entry`` in the table, according to the -``pub_date`` field:: - - Entry.objects.latest('pub_date') - -If your model's ``Meta`` specifies ``get_latest_by``, you can leave off the -``field_name`` argument to ``latest()``. Django will use the field specified in -``get_latest_by`` by default. - -Like ``get()``, ``latest()`` raises ``DoesNotExist`` if an object doesn't -exist with the given parameters. - -Note ``latest()`` exists purely for convenience and readability. - -aggregate -~~~~~~~~~ - -.. method:: aggregate(*args, **kwargs) - -.. versionadded:: 1.1 - -Returns a dictionary of aggregate values (averages, sums, etc) calculated -over the ``QuerySet``. Each argument to ``aggregate()`` specifies -a value that will be included in the dictionary that is returned. - -The aggregation functions that are provided by Django are described -in `Aggregation Functions`_ below. - -Aggregates specified using keyword arguments will use the keyword as -the name for the annotation. Anonymous arguments will have an name -generated for them based upon the name of the aggregate function and -the model field that is being aggregated. - -For example, if you were manipulating blog entries, you may want to know -the number of authors that have contributed blog entries:: - - >>> q = Blog.objects.aggregate(Count('entry')) - {'entry__count': 16} - -By using a keyword argument to specify the aggregate function, you can -control the name of the aggregation value that is returned:: - - >>> q = Blog.objects.aggregate(number_of_entries=Count('entry')) - {'number_of_entries': 16} - -For an in-depth discussion of aggregation, see :doc:`the topic guide on -Aggregation </topics/db/aggregation>`. - -exists -~~~~~~ - -.. method:: exists() - -.. versionadded:: 1.2 - -Returns ``True`` if the :class:`QuerySet` contains any results, and ``False`` -if not. This tries to perform the query in the simplest and fastest way -possible, but it *does* execute nearly the same query. This means that calling -:meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by -a large degree. If ``some_query_set`` has not yet been evaluated, but you know -that it will be at some point, then using ``some_query_set.exists()`` will do -more overall work (an additional query) than simply using -``bool(some_query_set)``. - -update -~~~~~~ - -.. method:: update(**kwargs) - -Performs an SQL update query for the specified fields, and returns -the number of rows affected. The ``update()`` method is applied instantly and -the only restriction on the :class:`QuerySet` that is updated is that it can -only update columns in the model's main table. Filtering based on related -fields is still possible. You cannot call ``update()`` on a -:class:`QuerySet` that has had a slice taken or can otherwise no longer be -filtered. - -For example, if you wanted to update all the entries in a particular blog -to use the same headline:: - - >>> b = Blog.objects.get(pk=1) - - # Update all the headlines belonging to this Blog. - >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same') - -The ``update()`` method does a bulk update and does not call any ``save()`` -methods on your models, nor does it emit the ``pre_save`` or ``post_save`` -signals (which are a consequence of calling ``save()``). - -delete -~~~~~~ - -.. method:: delete() - -Performs an SQL delete query on all rows in the :class:`QuerySet`. The -``delete()`` is applied instantly. You cannot call ``delete()`` on a -:class:`QuerySet` that has had a slice taken or can otherwise no longer be -filtered. - -For example, to delete all the entries in a particular blog:: - - >>> b = Blog.objects.get(pk=1) - - # Delete all the entries belonging to this Blog. - >>> Entry.objects.filter(blog=b).delete() - -Django emulates the SQL constraint ``ON DELETE CASCADE`` -- in other words, any -objects with foreign keys pointing at the objects to be deleted will be deleted -along with them. For example:: - - blogs = Blog.objects.all() - # This will delete all Blogs and all of their Entry objects. - blogs.delete() - -The ``delete()`` method does a bulk delete and does not call any ``delete()`` -methods on your models. It does, however, emit the -:data:`~django.db.models.signals.pre_delete` and -:data:`~django.db.models.signals.post_delete` signals for all deleted objects -(including cascaded deletions). - -.. _field-lookups: - -Field lookups -------------- - -Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're -specified as keyword arguments to the ``QuerySet`` methods ``filter()``, -``exclude()`` and ``get()``. - -For an introduction, see :ref:`field-lookups-intro`. - -.. fieldlookup:: exact - -exact -~~~~~ - -Exact match. If the value provided for comparison is ``None``, it will -be interpreted as an SQL ``NULL`` (See isnull_ for more details). - -Examples:: - - Entry.objects.get(id__exact=14) - Entry.objects.get(id__exact=None) - -SQL equivalents:: - - SELECT ... WHERE id = 14; - SELECT ... WHERE id IS NULL; - -.. versionchanged:: 1.0 - The semantics of ``id__exact=None`` have changed in Django 1.0. Previously, - it was (intentionally) converted to ``WHERE id = NULL`` at the SQL level, - which would never match anything. It has now been changed to behave the - same as ``id__isnull=True``. - -.. admonition:: MySQL comparisons - - In MySQL, a database table's "collation" setting determines whether - ``exact`` comparisons are case-sensitive. This is a database setting, *not* - a Django setting. It's possible to configure your MySQL tables to use - case-sensitive comparisons, but some trade-offs are involved. For more - information about this, see the :ref:`collation section <mysql-collation>` - in the :doc:`databases </ref/databases>` documentation. - -.. fieldlookup:: iexact - -iexact -~~~~~~ - -Case-insensitive exact match. - -Example:: - - Blog.objects.get(name__iexact='beatles blog') - -SQL equivalent:: - - SELECT ... WHERE name ILIKE 'beatles blog'; - -Note this will match ``'Beatles Blog'``, ``'beatles blog'``, ``'BeAtLes -BLoG'``, etc. - -.. admonition:: SQLite users - - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. SQLite does not do case-insensitive matching for Unicode - strings. - -.. fieldlookup:: contains - -contains -~~~~~~~~ - -Case-sensitive containment test. - -Example:: - - Entry.objects.get(headline__contains='Lennon') - -SQL equivalent:: - - SELECT ... WHERE headline LIKE '%Lennon%'; - -Note this will match the headline ``'Today Lennon honored'`` but not -``'today lennon honored'``. - -SQLite doesn't support case-sensitive ``LIKE`` statements; ``contains`` acts -like ``icontains`` for SQLite. - -.. fieldlookup:: icontains - -icontains -~~~~~~~~~ - -Case-insensitive containment test. - -Example:: - - Entry.objects.get(headline__icontains='Lennon') - -SQL equivalent:: - - SELECT ... WHERE headline ILIKE '%Lennon%'; - -.. admonition:: SQLite users - - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. - -.. fieldlookup:: in - -in -~~ - -In a given list. - -Example:: - - Entry.objects.filter(id__in=[1, 3, 4]) - -SQL equivalent:: - - SELECT ... WHERE id IN (1, 3, 4); - -You can also use a queryset to dynamically evaluate the list of values -instead of providing a list of literal values:: - - inner_qs = Blog.objects.filter(name__contains='Cheddar') - entries = Entry.objects.filter(blog__in=inner_qs) - -This queryset will be evaluated as subselect statement:: - - SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%') - -The above code fragment could also be written as follows:: - - inner_q = Blog.objects.filter(name__contains='Cheddar').values('pk').query - entries = Entry.objects.filter(blog__in=inner_q) - - -.. versionchanged:: 1.1 - In Django 1.0, only the latter piece of code is valid. - -This second form is a bit less readable and unnatural to write, since it -accesses the internal ``query`` attribute and requires a ``ValuesQuerySet``. -If your code doesn't require compatibility with Django 1.0, use the first -form, passing in a queryset directly. - -If you pass in a ``ValuesQuerySet`` or ``ValuesListQuerySet`` (the result of -calling ``values()`` or ``values_list()`` on a queryset) as the value to an -``__in`` lookup, you need to ensure you are only extracting one field in the -result. For example, this will work (filtering on the blog names):: - - inner_qs = Blog.objects.filter(name__contains='Ch').values('name') - entries = Entry.objects.filter(blog__name__in=inner_qs) - -This example will raise an exception, since the inner query is trying to -extract two field values, where only one is expected:: - - # Bad code! Will raise a TypeError. - inner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id') - entries = Entry.objects.filter(blog__name__in=inner_qs) - -.. warning:: - - This ``query`` attribute should be considered an opaque internal attribute. - It's fine to use it like above, but its API may change between Django - versions. - -.. admonition:: Performance considerations - - Be cautious about using nested queries and understand your database - server's performance characteristics (if in doubt, benchmark!). Some - database backends, most notably MySQL, don't optimize nested queries very - well. It is more efficient, in those cases, to extract a list of values - and then pass that into the second query. That is, execute two queries - instead of one:: - - values = Blog.objects.filter( - name__contains='Cheddar').values_list('pk', flat=True) - entries = Entry.objects.filter(blog__in=list(values)) - - Note the ``list()`` call around the Blog ``QuerySet`` to force execution of - the first query. Without it, a nested query would be executed, because - :ref:`querysets-are-lazy`. - -.. fieldlookup:: gt - -gt -~~ - -Greater than. - -Example:: - - Entry.objects.filter(id__gt=4) - -SQL equivalent:: - - SELECT ... WHERE id > 4; - -.. fieldlookup:: gte - -gte -~~~ - -Greater than or equal to. - -.. fieldlookup:: lt - -lt -~~ - -Less than. - -.. fieldlookup:: lte - -lte -~~~ - -Less than or equal to. - -.. fieldlookup:: startswith - -startswith -~~~~~~~~~~ - -Case-sensitive starts-with. - -Example:: - - Entry.objects.filter(headline__startswith='Will') - -SQL equivalent:: - - SELECT ... WHERE headline LIKE 'Will%'; - -SQLite doesn't support case-sensitive ``LIKE`` statements; ``startswith`` acts -like ``istartswith`` for SQLite. - -.. fieldlookup:: istartswith - -istartswith -~~~~~~~~~~~ - -Case-insensitive starts-with. - -Example:: - - Entry.objects.filter(headline__istartswith='will') - -SQL equivalent:: - - SELECT ... WHERE headline ILIKE 'Will%'; - -.. admonition:: SQLite users - - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. - -.. fieldlookup:: endswith - -endswith -~~~~~~~~ - -Case-sensitive ends-with. - -Example:: - - Entry.objects.filter(headline__endswith='cats') - -SQL equivalent:: - - SELECT ... WHERE headline LIKE '%cats'; - -SQLite doesn't support case-sensitive ``LIKE`` statements; ``endswith`` acts -like ``iendswith`` for SQLite. - -.. fieldlookup:: iendswith - -iendswith -~~~~~~~~~ - -Case-insensitive ends-with. - -Example:: - - Entry.objects.filter(headline__iendswith='will') - -SQL equivalent:: - - SELECT ... WHERE headline ILIKE '%will' - -.. admonition:: SQLite users - - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. - -.. fieldlookup:: range - -range -~~~~~ - -Range test (inclusive). - -Example:: - - start_date = datetime.date(2005, 1, 1) - end_date = datetime.date(2005, 3, 31) - Entry.objects.filter(pub_date__range=(start_date, end_date)) - -SQL equivalent:: - - SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31'; - -You can use ``range`` anywhere you can use ``BETWEEN`` in SQL -- for dates, -numbers and even characters. - -.. fieldlookup:: year - -year -~~~~ - -For date/datetime fields, exact year match. Takes a four-digit year. - -Example:: - - Entry.objects.filter(pub_date__year=2005) - -SQL equivalent:: - - SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005'; - -(The exact SQL syntax varies for each database engine.) - -.. fieldlookup:: month - -month -~~~~~ - -For date/datetime fields, exact month match. Takes an integer 1 (January) -through 12 (December). - -Example:: - - Entry.objects.filter(pub_date__month=12) - -SQL equivalent:: - - SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12'; - -(The exact SQL syntax varies for each database engine.) - -.. fieldlookup:: day - -day -~~~ - -For date/datetime fields, exact day match. - -Example:: - - Entry.objects.filter(pub_date__day=3) - -SQL equivalent:: - - SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3'; - -(The exact SQL syntax varies for each database engine.) - -Note this will match any record with a pub_date on the third day of the month, -such as January 3, July 3, etc. - -.. fieldlookup:: week_day - -week_day -~~~~~~~~ - -.. versionadded:: 1.1 - -For date/datetime fields, a 'day of the week' match. - -Takes an integer value representing the day of week from 1 (Sunday) to 7 -(Saturday). - -Example:: - - Entry.objects.filter(pub_date__week_day=2) - -(No equivalent SQL code fragment is included for this lookup because -implementation of the relevant query varies among different database engines.) - -Note this will match any record with a pub_date that falls on a Monday (day 2 -of the week), regardless of the month or year in which it occurs. Week days -are indexed with day 1 being Sunday and day 7 being Saturday. - -.. fieldlookup:: isnull - -isnull -~~~~~~ - -Takes either ``True`` or ``False``, which correspond to SQL queries of -``IS NULL`` and ``IS NOT NULL``, respectively. - -Example:: - - Entry.objects.filter(pub_date__isnull=True) - -SQL equivalent:: - - SELECT ... WHERE pub_date IS NULL; - -.. fieldlookup:: search - -search -~~~~~~ - -A boolean full-text search, taking advantage of full-text indexing. This is -like ``contains`` but is significantly faster due to full-text indexing. - -Example:: - - Entry.objects.filter(headline__search="+Django -jazz Python") - -SQL equivalent:: - - SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE); - -Note this is only available in MySQL and requires direct manipulation of the -database to add the full-text index. By default Django uses BOOLEAN MODE for -full text searches. `See the MySQL documentation for additional details. -<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_ - - -.. fieldlookup:: regex - -regex -~~~~~ - -.. versionadded:: 1.0 - -Case-sensitive regular expression match. - -The regular expression syntax is that of the database backend in use. -In the case of SQLite, which has no built in regular expression support, -this feature is provided by a (Python) user-defined REGEXP function, and -the regular expression syntax is therefore that of Python's ``re`` module. - -Example:: - - Entry.objects.get(title__regex=r'^(An?|The) +') - -SQL equivalents:: - - SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL - - SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'c'); -- Oracle - - SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL - - SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite - -Using raw strings (e.g., ``r'foo'`` instead of ``'foo'``) for passing in the -regular expression syntax is recommended. - -.. fieldlookup:: iregex - -iregex -~~~~~~ - -.. versionadded:: 1.0 - -Case-insensitive regular expression match. - -Example:: - - Entry.objects.get(title__iregex=r'^(an?|the) +') - -SQL equivalents:: - - SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL - - SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle - - SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL - - SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite - -.. _aggregation-functions: - -Aggregation Functions ---------------------- - -.. versionadded:: 1.1 - -Django provides the following aggregation functions in the -``django.db.models`` module. For details on how to use these -aggregate functions, see -:doc:`the topic guide on aggregation </topics/db/aggregation>`. - -Avg -~~~ - -.. class:: Avg(field) - -Returns the mean value of the given field. - - * Default alias: ``<field>__avg`` - * Return type: float - -Count -~~~~~ - -.. class:: Count(field, distinct=False) - -Returns the number of objects that are related through the provided field. - - * Default alias: ``<field>__count`` - * Return type: integer - -Has one optional argument: - -.. attribute:: distinct - - If distinct=True, the count will only include unique instances. This has - the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``. - -Max -~~~ - -.. class:: Max(field) - -Returns the maximum value of the given field. - - * Default alias: ``<field>__max`` - * Return type: same as input field - -Min -~~~ - -.. class:: Min(field) - -Returns the minimum value of the given field. - - * Default alias: ``<field>__min`` - * Return type: same as input field - -StdDev -~~~~~~ - -.. class:: StdDev(field, sample=False) - -Returns the standard deviation of the data in the provided field. - - * Default alias: ``<field>__stddev`` - * Return type: float - -Has one optional argument: - -.. attribute:: sample - - By default, ``StdDev`` returns the population standard deviation. However, - if ``sample=True``, the return value will be the sample standard deviation. - -.. admonition:: SQLite - - SQLite doesn't provide ``StdDev`` out of the box. An implementation is - available as an extension module for SQLite. Consult the SQlite - documentation for instructions on obtaining and installing this extension. - -Sum -~~~ - -.. class:: Sum(field) - -Computes the sum of all values of the given field. - - * Default alias: ``<field>__sum`` - * Return type: same as input field - -Variance -~~~~~~~~ - -.. class:: Variance(field, sample=False) - -Returns the variance of the data in the provided field. - - * Default alias: ``<field>__variance`` - * Return type: float - -Has one optional argument: - -.. attribute:: sample - - By default, ``Variance`` returns the population variance. However, - if ``sample=True``, the return value will be the sample variance. - -.. admonition:: SQLite - - SQLite doesn't provide ``Variance`` out of the box. An implementation is - available as an extension module for SQLite. Consult the SQlite - documentation for instructions on obtaining and installing this extension. diff --git a/parts/django/docs/ref/models/relations.txt b/parts/django/docs/ref/models/relations.txt deleted file mode 100644 index ee6bcdd..0000000 --- a/parts/django/docs/ref/models/relations.txt +++ /dev/null @@ -1,105 +0,0 @@ -========================= -Related objects reference -========================= - -.. currentmodule:: django.db.models.fields.related - -.. class:: RelatedManager - - A "related manager" is a manager used in a one-to-many or many-to-many - related context. This happens in two cases: - - * The "other side" of a :class:`~django.db.models.ForeignKey` relation. - That is:: - - class Reporter(models.Model): - ... - - class Article(models.Model): - reporter = models.ForeignKey(Reporter) - - In the above example, the methods below will be available on - the manager ``reporter.article_set``. - - * Both sides of a :class:`~django.db.models.ManyToManyField` relation:: - - class Topping(models.Model): - ... - - class Pizza(models.Model): - toppings = models.ManyToManyField(Topping) - - In this example, the methods below will be available both on - ``topping.pizza_set`` and on ``pizza.toppings``. - - These related managers have some extra methods: - - .. method:: add(obj1, [obj2, ...]) - - Adds the specified model objects to the related object set. - - Example:: - - >>> b = Blog.objects.get(id=1) - >>> e = Entry.objects.get(id=234) - >>> b.entry_set.add(e) # Associates Entry e with Blog b. - - .. method:: create(**kwargs) - - Creates a new object, saves it and puts it in the related object set. - Returns the newly created object:: - - >>> b = Blog.objects.get(id=1) - >>> e = b.entry_set.create( - ... headline='Hello', - ... body_text='Hi', - ... pub_date=datetime.date(2005, 1, 1) - ... ) - - # No need to call e.save() at this point -- it's already been saved. - - This is equivalent to (but much simpler than):: - - >>> b = Blog.objects.get(id=1) - >>> e = Entry( - ... blog=b, - ... headline='Hello', - ... body_text='Hi', - ... pub_date=datetime.date(2005, 1, 1) - ... ) - >>> e.save(force_insert=True) - - Note that there's no need to specify the keyword argument of the model - that defines the relationship. In the above example, we don't pass the - parameter ``blog`` to ``create()``. Django figures out that the new - ``Entry`` object's ``blog`` field should be set to ``b``. - - .. method:: remove(obj1, [obj2, ...]) - - Removes the specified model objects from the related object set:: - - >>> b = Blog.objects.get(id=1) - >>> e = Entry.objects.get(id=234) - >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. - - In order to prevent database inconsistency, this method only exists on - :class:`~django.db.models.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`` - :class:`~django.db.models.ForeignKey` doesn't have ``null=True``, this - is invalid. - - .. method:: clear() - - Removes all objects from the related object set:: - - >>> b = Blog.objects.get(id=1) - >>> b.entry_set.clear() - - Note this doesn't delete the related objects -- it just disassociates - them. - - Just like ``remove()``, ``clear()`` is only available on - :class:`~django.db.models.ForeignKey`\s where ``null=True``. diff --git a/parts/django/docs/ref/request-response.txt b/parts/django/docs/ref/request-response.txt deleted file mode 100644 index c663c1e..0000000 --- a/parts/django/docs/ref/request-response.txt +++ /dev/null @@ -1,646 +0,0 @@ -============================ -Request and response objects -============================ - -.. module:: django.http - :synopsis: Classes dealing with HTTP requests and responses. - -Quick overview -============== - -Django uses request and response objects to pass state through the system. - -When a page is requested, Django creates an :class:`HttpRequest` object that -contains metadata about the request. Then Django loads the appropriate view, -passing the :class:`HttpRequest` as the first argument to the view function. -Each view is responsible for returning an :class:`HttpResponse` object. - -This document explains the APIs for :class:`HttpRequest` and -:class:`HttpResponse` objects. - -HttpRequest objects -=================== - -.. class:: HttpRequest - -Attributes ----------- - -All attributes except ``session`` should be considered read-only. - -.. attribute:: HttpRequest.path - - A string representing the full path to the requested page, not including - the domain. - - Example: ``"/music/bands/the_beatles/"`` - -.. attribute:: HttpRequest.path_info - - Under some web server configurations, the portion of the URL after the host - name is split up into a script prefix portion and a path info portion - (this happens, for example, when using the ``django.root`` option - with the :ref:`modpython handler from Apache <howto-deployment-modpython>`). - The ``path_info`` attribute always contains the path info portion of the - path, no matter what web server is being used. Using this instead of - attr:`~HttpRequest.path` can make your code much easier to move between test - and deployment servers. - - For example, if the ``django.root`` for your application is set to - ``"/minfo"``, then ``path`` might be ``"/minfo/music/bands/the_beatles/"`` - and ``path_info`` would be ``"/music/bands/the_beatles/"``. - -.. attribute:: HttpRequest.method - - A string representing the HTTP method used in the request. This is - guaranteed to be uppercase. Example:: - - if request.method == 'GET': - do_something() - elif request.method == 'POST': - do_something_else() - -.. attribute:: HttpRequest.encoding - - A string representing the current encoding used to decode form submission - data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is - used). You can write to this attribute to change the encoding used when - accessing the form data. Any subsequent attribute accesses (such as reading - from ``GET`` or ``POST``) will use the new ``encoding`` value. Useful if - you know the form data is not in the :setting:`DEFAULT_CHARSET` encoding. - -.. attribute:: HttpRequest.GET - - A dictionary-like object containing all given HTTP GET parameters. See the - :class:`QueryDict` documentation below. - -.. attribute:: HttpRequest.POST - - A dictionary-like object containing all given HTTP POST parameters. See the - :class:`QueryDict` documentation below. - - It's possible that a request can come in via POST with an empty ``POST`` - dictionary -- if, say, a form is requested via the POST HTTP method but - does not include form data. Therefore, you shouldn't use ``if request.POST`` - to check for use of the POST method; instead, use ``if request.method == - "POST"`` (see above). - - Note: ``POST`` does *not* include file-upload information. See ``FILES``. - -.. attribute:: HttpRequest.REQUEST - - For convenience, a dictionary-like object that searches ``POST`` first, - then ``GET``. Inspired by PHP's ``$_REQUEST``. - - For example, if ``GET = {"name": "john"}`` and ``POST = {"age": '34'}``, - ``REQUEST["name"]`` would be ``"john"``, and ``REQUEST["age"]`` would be - ``"34"``. - - It's strongly suggested that you use ``GET`` and ``POST`` instead of - ``REQUEST``, because the former are more explicit. - -.. attribute:: HttpRequest.COOKIES - - A standard Python dictionary containing all cookies. Keys and values are - strings. - -.. attribute:: HttpRequest.FILES - - A dictionary-like object containing all uploaded files. Each key in - ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each - value in ``FILES`` is an :class:`UploadedFile` as described below. - - See :doc:`/topics/files` for more information. - - Note that ``FILES`` will only contain data if the request method was POST - and the ``<form>`` that posted to the request had - ``enctype="multipart/form-data"``. Otherwise, ``FILES`` will be a blank - dictionary-like object. - - .. versionchanged:: 1.0 - - In previous versions of Django, ``request.FILES`` contained simple ``dict`` - objects representing uploaded files. This is no longer true -- files are - represented by :class:`UploadedFile` objects. - - These :class:`UploadedFile` objects will emulate the old-style ``dict`` - interface, but this is deprecated and will be removed in the next release - of Django. - -.. attribute:: HttpRequest.META - - A standard Python dictionary containing all available HTTP headers. - Available headers depend on the client and server, but here are some - examples: - - * ``CONTENT_LENGTH`` - * ``CONTENT_TYPE`` - * ``HTTP_ACCEPT_ENCODING`` - * ``HTTP_ACCEPT_LANGUAGE`` - * ``HTTP_HOST`` -- The HTTP Host header sent by the client. - * ``HTTP_REFERER`` -- The referring page, if any. - * ``HTTP_USER_AGENT`` -- The client's user-agent string. - * ``QUERY_STRING`` -- The query string, as a single (unparsed) string. - * ``REMOTE_ADDR`` -- The IP address of the client. - * ``REMOTE_HOST`` -- The hostname of the client. - * ``REMOTE_USER`` -- The user authenticated by the Web server, if any. - * ``REQUEST_METHOD`` -- A string such as ``"GET"`` or ``"POST"``. - * ``SERVER_NAME`` -- The hostname of the server. - * ``SERVER_PORT`` -- The port of the server. - - With the exception of ``CONTENT_LENGTH`` and ``CONTENT_TYPE``, as given - above, any HTTP headers in the request are converted to ``META`` keys by - converting all characters to uppercase, replacing any hyphens with - underscores and adding an ``HTTP_`` prefix to the name. So, for example, a - header called ``X-Bender`` would be mapped to the ``META`` key - ``HTTP_X_BENDER``. - -.. attribute:: HttpRequest.user - - 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_authenticated()``, like so:: - - 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 - :doc:`/topics/auth`. - -.. attribute:: HttpRequest.session - - A readable-and-writable, dictionary-like object that represents the current - session. This is only available if your Django installation has session - support activated. See the :doc:`session documentation - </topics/http/sessions>` for full details. - -.. attribute:: HttpRequest.raw_post_data - - The raw HTTP POST data. This is only useful for advanced processing. Use - ``POST`` instead. - -.. attribute:: HttpRequest.urlconf - - Not defined by Django itself, but will be read if other code (e.g., a custom - middleware class) sets it. When present, this will be used as the root - URLconf for the current request, overriding the :setting:`ROOT_URLCONF` - setting. See :ref:`how-django-processes-a-request` for details. - -Methods -------- - -.. method:: HttpRequest.get_host() - - Returns the originating host of the request using information from the - ``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If - they don't provide a value, the method uses a combination of - ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in `PEP 333`_. - - .. _PEP 333: http://www.python.org/dev/peps/pep-0333/ - - Example: ``"127.0.0.1:8000"`` - - .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is - behind multiple proxies. One solution is to use middleware to rewrite - the proxy headers, as in the following example:: - - class MultipleProxyMiddleware(object): - FORWARDED_FOR_FIELDS = [ - 'HTTP_X_FORWARDED_FOR', - 'HTTP_X_FORWARDED_HOST', - 'HTTP_X_FORWARDED_SERVER', - ] - - def process_request(self, request): - """ - Rewrites the proxy headers so that only the most - recent proxy is used. - """ - for field in self.FORWARDED_FOR_FIELDS: - if field in request.META: - if ',' in request.META[field]: - parts = request.META[field].split(',') - request.META[field] = parts[-1].strip() - - -.. method:: HttpRequest.get_full_path() - - Returns the ``path``, plus an appended query string, if applicable. - - Example: ``"/music/bands/the_beatles/?print=true"`` - -.. method:: HttpRequest.build_absolute_uri(location) - - Returns the absolute URI form of ``location``. If no location is provided, - the location will be set to ``request.get_full_path()``. - - If the location is already an absolute URI, it will not be altered. - Otherwise the absolute URI is built using the server variables available in - this request. - - Example: ``"http://example.com/music/bands/the_beatles/?print=true"`` - -.. method:: HttpRequest.is_secure() - - Returns ``True`` if the request is secure; that is, if it was made with - HTTPS. - -.. method:: HttpRequest.is_ajax() - - Returns ``True`` if the request was made via an ``XMLHttpRequest``, by - checking the ``HTTP_X_REQUESTED_WITH`` header for the string - ``'XMLHttpRequest'``. Most modern JavaScript libraries send this header. - If you write your own XMLHttpRequest call (on the browser side), you'll - have to set this header manually if you want ``is_ajax()`` to work. - - -UploadedFile objects -==================== - -.. class:: UploadedFile - - -Attributes ----------- - -.. attribute:: UploadedFile.name - - The name of the uploaded file. - -.. attribute:: UploadedFile.size - - The size, in bytes, of the uploaded file. - -Methods ----------- - -.. method:: UploadedFile.chunks(chunk_size=None) - - Returns a generator that yields sequential chunks of data. - -.. method:: UploadedFile.read(num_bytes=None) - - Read a number of bytes from the file. - - - -QueryDict objects -================= - -.. class:: QueryDict - -In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are instances -of ``django.http.QueryDict``. :class:`QueryDict` is a dictionary-like -class customized to deal with multiple values for the same key. This is -necessary because some HTML form elements, notably -``<select multiple="multiple">``, pass multiple values for the same key. - -``QueryDict`` instances are immutable, unless you create a ``copy()`` of them. -That means you can't change attributes of ``request.POST`` and ``request.GET`` -directly. - -Methods -------- - -:class:`QueryDict` implements all the standard dictionary methods, because it's -a subclass of dictionary. Exceptions are outlined here: - -.. method:: QueryDict.__getitem__(key) - - Returns the value for the given key. If the key has more than one value, - ``__getitem__()`` returns the last value. Raises - ``django.utils.datastructures.MultiValueDictKeyError`` if the key does not - exist. (This is a subclass of Python's standard ``KeyError``, so you can - stick to catching ``KeyError``.) - -.. method:: QueryDict.__setitem__(key, value) - - Sets the given key to ``[value]`` (a Python list whose single element is - ``value``). Note that this, as other dictionary functions that have side - effects, can only be called on a mutable ``QueryDict`` (one that was created - via ``copy()``). - -.. method:: QueryDict.__contains__(key) - - Returns ``True`` if the given key is set. This lets you do, e.g., ``if "foo" - in request.GET``. - -.. method:: QueryDict.get(key, default) - - Uses the same logic as ``__getitem__()`` above, with a hook for returning a - default value if the key doesn't exist. - -.. method:: QueryDict.setdefault(key, default) - - Just like the standard dictionary ``setdefault()`` method, except it uses - ``__setitem__()`` internally. - -.. method:: QueryDict.update(other_dict) - - Takes either a ``QueryDict`` or standard dictionary. Just like the standard - dictionary ``update()`` method, except it *appends* to the current - dictionary items rather than replacing them. For example:: - - >>> q = QueryDict('a=1') - >>> q = q.copy() # to make it mutable - >>> q.update({'a': '2'}) - >>> q.getlist('a') - [u'1', u'2'] - >>> q['a'] # returns the last - [u'2'] - -.. method:: QueryDict.items() - - Just like the standard dictionary ``items()`` method, except this uses the - same last-value logic as ``__getitem__()``. For example:: - - >>> q = QueryDict('a=1&a=2&a=3') - >>> q.items() - [(u'a', u'3')] - -.. method:: QueryDict.iteritems() - - Just like the standard dictionary ``iteritems()`` method. Like - :meth:`QueryDict.items()` this uses the same last-value logic as - :meth:`QueryDict.__getitem__()`. - -.. method:: QueryDict.iterlists() - - Like :meth:`QueryDict.iteritems()` except it includes all values, as a list, - for each member of the dictionary. - -.. method:: QueryDict.values() - - Just like the standard dictionary ``values()`` method, except this uses the - same last-value logic as ``__getitem__()``. For example:: - - >>> q = QueryDict('a=1&a=2&a=3') - >>> q.values() - [u'3'] - -.. method:: QueryDict.itervalues() - - Just like :meth:`QueryDict.values()`, except an iterator. - -In addition, ``QueryDict`` has the following methods: - -.. method:: QueryDict.copy() - - Returns a copy of the object, using ``copy.deepcopy()`` from the Python - standard library. The copy will be mutable -- that is, you can change its - values. - -.. method:: QueryDict.getlist(key) - - Returns the data with the requested key, as a Python list. Returns an - empty list if the key doesn't exist. It's guaranteed to return a list of - some sort. - -.. method:: QueryDict.setlist(key, list_) - - Sets the given key to ``list_`` (unlike ``__setitem__()``). - -.. method:: QueryDict.appendlist(key, item) - - Appends an item to the internal list associated with key. - -.. method:: QueryDict.setlistdefault(key, default_list) - - Just like ``setdefault``, except it takes a list of values instead of a - single value. - -.. method:: QueryDict.lists() - - Like :meth:`items()`, except it includes all values, as a list, for each - member of the dictionary. For example:: - - >>> q = QueryDict('a=1&a=2&a=3') - >>> q.lists() - [(u'a', [u'1', u'2', u'3'])] - -.. method:: QueryDict.urlencode() - - Returns a string of the data in query-string format. - Example: ``"a=2&b=3&b=5"``. - -HttpResponse objects -==================== - -.. class:: HttpResponse - -In contrast to :class:`HttpRequest` objects, which are created automatically by -Django, :class:`HttpResponse` objects are your responsibility. Each view you -write is responsible for instantiating, populating and returning an -:class:`HttpResponse`. - -The :class:`HttpResponse` class lives in the :mod:`django.http` module. - -Usage ------ - -Passing strings -~~~~~~~~~~~~~~~ - -Typical usage is to pass the contents of the page, as a string, to the -:class:`HttpResponse` constructor:: - - >>> response = HttpResponse("Here's the text of the Web page.") - >>> response = HttpResponse("Text only, please.", mimetype="text/plain") - -But if you want to add content incrementally, you can use ``response`` as a -file-like object:: - - >>> response = HttpResponse() - >>> response.write("<p>Here's the text of the Web page.</p>") - >>> response.write("<p>Here's another paragraph.</p>") - -Passing iterators -~~~~~~~~~~~~~~~~~ - -Finally, you can pass ``HttpResponse`` an iterator rather than passing it -hard-coded strings. If you use this technique, follow these guidelines: - - * The iterator should return strings. - * If an :class:`HttpResponse` has been initialized with an iterator as its - content, you can't use the class:`HttpResponse` instance as a file-like - object. Doing so will raise ``Exception``. - -Setting headers -~~~~~~~~~~~~~~~ - -To set or remove a header in your response, treat it like a dictionary:: - - >>> response = HttpResponse() - >>> response['Cache-Control'] = 'no-cache' - >>> del response['Cache-Control'] - -Note that unlike a dictionary, ``del`` doesn't raise ``KeyError`` if the header -doesn't exist. - -.. versionadded:: 1.1 - -HTTP headers cannot contain newlines. An attempt to set a header containing a -newline character (CR or LF) will raise ``BadHeaderError`` - -Telling the browser to treat the response as a file attachment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To tell the browser to treat the response as a file attachment, use the -``mimetype`` argument and set the ``Content-Disposition`` header. For example, -this is how you might return a Microsoft Excel spreadsheet:: - - >>> response = HttpResponse(my_data, mimetype='application/vnd.ms-excel') - >>> response['Content-Disposition'] = 'attachment; filename=foo.xls' - -There's nothing Django-specific about the ``Content-Disposition`` header, but -it's easy to forget the syntax, so we've included it here. - -Attributes ----------- - -.. attribute:: HttpResponse.content - - A normal Python string representing the content, encoded from a Unicode - object if necessary. - -.. attribute:: HttpResponse.status_code - - The `HTTP Status code`_ for the response. - -Methods -------- - -.. method:: HttpResponse.__init__(content='', mimetype=None, status=200, content_type=DEFAULT_CONTENT_TYPE) - - Instantiates an ``HttpResponse`` object with the given page content (a - string) and MIME type. The :setting:`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 - content of the response. - - ``status`` is the `HTTP Status code`_ for the response. - - ``content_type`` is an alias for ``mimetype``. Historically, this parameter - was only called ``mimetype``, but since this is actually the value included - in the HTTP ``Content-Type`` header, it can also include the character set - encoding, which makes it more than just a MIME type specification. - If ``mimetype`` is specified (not ``None``), that value is used. - Otherwise, ``content_type`` is used. If neither is given, the - :setting:`DEFAULT_CONTENT_TYPE` setting is used. - -.. method:: HttpResponse.__setitem__(header, value) - - Sets the given header name to the given value. Both ``header`` and - ``value`` should be strings. - -.. method:: HttpResponse.__delitem__(header) - - Deletes the header with the given name. Fails silently if the header - doesn't exist. Case-insensitive. - -.. method:: HttpResponse.__getitem__(header) - - Returns the value for the given header name. Case-insensitive. - -.. method:: HttpResponse.has_header(header) - - Returns ``True`` or ``False`` based on a case-insensitive check for a - header with the given name. - -.. method:: HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None) - - Sets a cookie. The parameters are the same as in the `cookie Morsel`_ - object in the Python standard library. - - * ``max_age`` should be a number of seconds, or ``None`` (default) if - the cookie should last only as long as the client's browser session. - * ``expires`` should be a string in the format - ``"Wdy, DD-Mon-YY HH:MM:SS GMT"``. - * Use ``domain`` if you want to set a cross-domain cookie. For example, - ``domain=".lawrence.com"`` will set a cookie that is readable by - the domains www.lawrence.com, blogs.lawrence.com and - calendars.lawrence.com. Otherwise, a cookie will only be readable by - the domain that set it. - - .. _`cookie Morsel`: http://docs.python.org/library/cookie.html#Cookie.Morsel - -.. method:: HttpResponse.delete_cookie(key, path='/', domain=None) - - Deletes the cookie with the given key. Fails silently if the key doesn't - exist. - - 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. - -.. method:: HttpResponse.write(content) - - This method makes an :class:`HttpResponse` instance a file-like object. - -.. method:: HttpResponse.flush() - - This method makes an :class:`HttpResponse` instance a file-like object. - -.. method:: HttpResponse.tell() - - This method makes an :class:`HttpResponse` instance a file-like object. - -.. _HTTP Status code: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10 - - -.. _ref-httpresponse-subclasses: - -HttpResponse subclasses ------------------------ - -Django includes a number of ``HttpResponse`` subclasses that handle different -types of HTTP responses. Like ``HttpResponse``, these subclasses live in -:mod:`django.http`. - -.. class:: HttpResponseRedirect - - The constructor takes a single argument -- the path to redirect to. This - can be a fully qualified URL (e.g. ``'http://www.yahoo.com/search/'``) or - an absolute path with no domain (e.g. ``'/search/'``). Note that this - returns an HTTP status code 302. - -.. class:: HttpResponsePermanentRedirect - - Like :class:`HttpResponseRedirect`, but it returns a permanent redirect - (HTTP status code 301) instead of a "found" redirect (status code 302). - -.. class:: HttpResponseNotModified - - The constructor doesn't take any arguments. Use this to designate that a - page hasn't been modified since the user's last request (status code 304). - -.. class:: HttpResponseBadRequest - - Acts just like :class:`HttpResponse` but uses a 400 status code. - -.. class:: HttpResponseNotFound - - Acts just like :class:`HttpResponse` but uses a 404 status code. - -.. class:: HttpResponseForbidden - - Acts just like :class:`HttpResponse` but uses a 403 status code. - -.. class:: HttpResponseNotAllowed - - Like :class:`HttpResponse`, but uses a 405 status code. Takes a single, - required argument: a list of permitted methods (e.g. ``['GET', 'POST']``). - -.. class:: HttpResponseGone - - Acts just like :class:`HttpResponse` but uses a 410 status code. - -.. class:: HttpResponseServerError - - Acts just like :class:`HttpResponse` but uses a 500 status code. diff --git a/parts/django/docs/ref/settings.txt b/parts/django/docs/ref/settings.txt deleted file mode 100644 index ab1f28c..0000000 --- a/parts/django/docs/ref/settings.txt +++ /dev/null @@ -1,1836 +0,0 @@ -======== -Settings -======== - -.. contents:: - :local: - :depth: 1 - -Available settings -================== - -Here's a full list of all available settings, in alphabetical order, and their -default values. - -.. setting:: ABSOLUTE_URL_OVERRIDES - -ABSOLUTE_URL_OVERRIDES ----------------------- - -Default: ``{}`` (Empty dictionary) - -A dictionary mapping ``"app_label.model_name"`` strings to functions that take -a model object and return its URL. This is a way of overriding -``get_absolute_url()`` methods on a per-installation basis. Example:: - - ABSOLUTE_URL_OVERRIDES = { - 'blogs.weblog': lambda o: "/blogs/%s/" % o.slug, - 'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug), - } - -Note that the model name used in this setting should be all lower-case, regardless -of the case of the actual model class name. - -.. setting:: ADMIN_FOR - -ADMIN_FOR ---------- - -Default: ``()`` (Empty tuple) - -Used for admin-site settings modules, this should be a tuple of settings -modules (in the format ``'foo.bar.baz'``) for which this site is an admin. - -The admin site uses this in its automatically-introspected documentation of -models, views and template tags. - -.. setting:: ADMIN_MEDIA_PREFIX - -ADMIN_MEDIA_PREFIX ------------------- - -Default: ``'/media/'`` - -The URL prefix for admin media -- CSS, JavaScript and images used by -the Django administrative interface. Make sure to use a trailing -slash, and to have this be different from the ``MEDIA_URL`` setting -(since the same URL cannot be mapped onto two different sets of -files). - -.. setting:: ADMINS - -ADMINS ------- - -Default: ``()`` (Empty tuple) - -A tuple that lists people who get code error notifications. When -``DEBUG=False`` and a view raises an exception, Django will e-mail these people -with the full exception information. Each member of the tuple should be a tuple -of (Full name, e-mail address). Example:: - - (('John', 'john@example.com'), ('Mary', 'mary@example.com')) - -Note that Django will e-mail *all* of these people whenever an error happens. -See :doc:`/howto/error-reporting` for more information. - -.. setting:: ALLOWED_INCLUDE_ROOTS - -ALLOWED_INCLUDE_ROOTS ---------------------- - -Default: ``()`` (Empty tuple) - -A tuple of strings representing allowed prefixes for the ``{% ssi %}`` template -tag. This is a security measure, so that template authors can't access files -that they shouldn't be accessing. - -For example, if ``ALLOWED_INCLUDE_ROOTS`` is ``('/home/html', '/var/www')``, -then ``{% ssi /home/html/foo.txt %}`` would work, but ``{% ssi /etc/passwd %}`` -wouldn't. - -.. setting:: APPEND_SLASH - -APPEND_SLASH ------------- - -Default: ``True`` - -When set to ``True``, if the request URL does not match any of the patterns -in the URLconf and it doesn't end in a slash, an HTTP redirect is issued to the -same URL with a slash appended. Note that the redirect may cause any data -submitted in a POST request to be lost. - -The ``APPEND_SLASH`` setting is only used if -:class:`~django.middleware.common.CommonMiddleware` is installed -(see :doc:`/topics/http/middleware`). See also :setting:`PREPEND_WWW`. - -.. setting:: AUTHENTICATION_BACKENDS - -AUTHENTICATION_BACKENDS ------------------------ - -Default: ``('django.contrib.auth.backends.ModelBackend',)`` - -A tuple of authentication backend classes (as strings) to use when attempting to -authenticate a user. See the :doc:`authentication backends documentation -</ref/authbackends>` for details. - -.. setting:: AUTH_PROFILE_MODULE - -AUTH_PROFILE_MODULE -------------------- - -Default: Not defined - -The site-specific user profile model used by this site. See -:ref:`auth-profiles`. - -.. setting:: CACHE_BACKEND - -CACHE_BACKEND -------------- - -Default: ``'locmem://'`` - -The cache backend to use. See :doc:`/topics/cache`. - -.. setting:: CACHE_MIDDLEWARE_ANONYMOUS_ONLY - -CACHE_MIDDLEWARE_ANONYMOUS_ONLY -------------------------------- - -Default: ``False`` - -If the value of this setting is ``True``, only anonymous requests (i.e., not -those made by a logged-in user) will be cached. Otherwise, the middleware -caches every page that doesn't have GET or POST parameters. - -If you set the value of this setting to ``True``, you should make sure you've -activated ``AuthenticationMiddleware``. - -See the :doc:`cache documentation </topics/cache>` for more information. - -.. setting:: CACHE_MIDDLEWARE_KEY_PREFIX - -CACHE_MIDDLEWARE_KEY_PREFIX ---------------------------- - -Default: ``''`` (Empty string) - -The cache key prefix that the cache middleware should use. See -:doc:`/topics/cache`. - -.. setting:: CACHE_MIDDLEWARE_SECONDS - -CACHE_MIDDLEWARE_SECONDS ------------------------- - -Default: ``600`` - -The default number of seconds to cache a page when the caching middleware or -``cache_page()`` decorator is used. - -.. setting:: CSRF_COOKIE_DOMAIN - -CSRF_COOKIE_DOMAIN ------------------- - -.. versionadded:: 1.2 - -Default: ``None`` - -The domain to be used when setting the CSRF cookie. This can be useful for -allowing cross-subdomain requests to be exluded from the normal cross site -request forgery protection. It should be set to a string such as -``".lawrence.com"`` to allow a POST request from a form on one subdomain to be -accepted by accepted by a view served from another subdomain. - -.. setting:: CSRF_COOKIE_NAME - -CSRF_COOKIE_NAME ----------------- - -.. versionadded:: 1.2 - -Default: ``'csrftoken'`` - -The name of the cookie to use for the CSRF authentication token. This can be whatever you -want. See :doc:`/ref/contrib/csrf`. - -.. setting:: CSRF_FAILURE_VIEW - -CSRF_FAILURE_VIEW ------------------ - -.. versionadded:: 1.2 - -Default: ``'django.views.csrf.csrf_failure'`` - -A dotted path to the view function to be used when an incoming request -is rejected by the CSRF protection. The function should have this signature:: - - def csrf_failure(request, reason="") - -where ``reason`` is a short message (intended for developers or logging, not for -end users) indicating the reason the request was rejected. See -:doc:`/ref/contrib/csrf`. - - -.. setting:: DATABASES - -DATABASES ---------- - -.. versionadded:: 1.2 - -Default: ``{}`` (Empty dictionary) - -A dictionary containing the settings for all databases to be used with -Django. It is a nested dictionary whose contents maps database aliases -to a dictionary containing the options for an individual database. - -The :setting:`DATABASES` setting must configure a ``default`` database; -any number of additional databases may also be specified. - -The simplest possible settings file is for a single-database setup using -SQLite. This can be configured using the following:: - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.sqlite3', - 'NAME': 'mydatabase' - } - } - -For other database backends, or more complex SQLite configurations, other options -will be required. The following inner options are available. - -.. setting:: ENGINE - -ENGINE -~~~~~~ - -Default: ``''`` (Empty string) - -The database backend to use. The built-in database backends are: - - * ``'django.db.backends.postgresql_psycopg2'`` - * ``'django.db.backends.postgresql'`` - * ``'django.db.backends.mysql'`` - * ``'django.db.backends.sqlite3'`` - * ``'django.db.backends.oracle'`` - -You can use a database backend that doesn't ship with Django by setting -``ENGINE`` to a fully-qualified path (i.e. -``mypackage.backends.whatever``). Writing a whole new database backend from -scratch is left as an exercise to the reader; see the other backends for -examples. - -.. note:: - Prior to Django 1.2, you could use a short version of the backend name - to reference the built-in database backends (e.g., you could use - ``'sqlite3'`` to refer to the SQLite backend). This format has been - deprecated, and will be removed in Django 1.4. - -.. setting:: HOST - -HOST -~~~~ - -Default: ``''`` (Empty string) - -Which host to use when connecting to the database. An empty string means -localhost. Not used with SQLite. - -If this value starts with a forward slash (``'/'``) and you're using MySQL, -MySQL will connect via a Unix socket to the specified socket. For example:: - - "HOST": '/var/run/mysql' - -If you're using MySQL and this value *doesn't* start with a forward slash, then -this value is assumed to be the host. - -If you're using PostgreSQL, an empty string means to use a Unix domain socket -for the connection, rather than a network connection to localhost. If you -explicitly need to use a TCP/IP connection on the local machine with -PostgreSQL, specify ``localhost`` here. - -.. setting:: NAME - -NAME -~~~~ - -Default: ``''`` (Empty string) - -The name of the database to use. For SQLite, it's the full path to the database -file. When specifying the path, always use forward slashes, even on Windows -(e.g. ``C:/homes/user/mysite/sqlite3.db``). - -.. setting:: OPTIONS - -OPTIONS -~~~~~~~ - -Default: ``{}`` (Empty dictionary) - -Extra parameters to use when connecting to the database. Available parameters -vary depending on your database backend. - -Some information on available parameters can be found in the -:doc:`Database Backends </ref/databases>` documentation. For more information, -consult your backend module's own documentation. - -.. setting:: PASSWORD - -PASSWORD -~~~~~~~~ - -Default: ``''`` (Empty string) - -The password to use when connecting to the database. Not used with SQLite. - -.. setting:: PORT - -PORT -~~~~ - -Default: ``''`` (Empty string) - -The port to use when connecting to the database. An empty string means the -default port. Not used with SQLite. - -.. setting:: USER - -USER -~~~~ - -Default: ``''`` (Empty string) - -The username to use when connecting to the database. Not used with SQLite. - -.. setting:: TEST_CHARSET - -TEST_CHARSET -~~~~~~~~~~~~ - -Default: ``None`` - -The character set encoding used to create the test database. The value of this -string is passed directly through to the database, so its format is -backend-specific. - -Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and -MySQL_ (``mysql``) backends. - -.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html -.. _MySQL: http://dev.mysql.com/doc/refman/5.0/en/charset-database.html - -.. setting:: TEST_COLLATION - -TEST_COLLATION -~~~~~~~~~~~~~~ - -Default: ``None`` - -The collation order to use when creating the test database. This value is -passed directly to the backend, so its format is backend-specific. - -Only supported for the ``mysql`` backend (see the `MySQL manual`_ for details). - -.. _MySQL manual: MySQL_ - -.. setting:: TEST_DEPENDENCIES - -TEST_DEPENDENCIES -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.2.4 - -Default: ``['default']``, for all databases other than ``default``, -which has no dependencies. - -The creation-order dependencies of the database. See the documentation -on :ref:`controlling the creation order of test databases -<topics-testing-creation-dependencies>` for details. - -.. setting:: TEST_MIRROR - -TEST_MIRROR -~~~~~~~~~~~ - -Default: ``None`` - -The alias of the database that this database should mirror during -testing. - -This setting exists to allow for testing of master/slave -configurations of multiple databases. See the documentation on -:ref:`testing master/slave configurations -<topics-testing-masterslave>` for details. - -.. setting:: TEST_NAME - -TEST_NAME -~~~~~~~~~ - -Default: ``None`` - -The name of database to use when running the test suite. - -If the default value (``None``) is used with the SQLite database engine, the -tests will use a memory resident database. For all other database engines the -test database will use the name ``'test_' + DATABASE_NAME``. - -See :doc:`/topics/testing`. - -.. setting:: TEST_USER - -TEST_USER -~~~~~~~~~ - -Default: ``None`` - -This is an Oracle-specific setting. - -The username to use when connecting to the Oracle database that will be used -when running tests. - -.. setting:: DATABASE_ROUTERS - -DATABASE_ROUTERS ----------------- - -.. versionadded:: 1.2 - -Default: ``[]`` (Empty list) - -The list of routers that will be used to determine which database -to use when performing a database queries. - -See the documentation on :ref:`automatic database routing in multi -database configurations <topics-db-multi-db-routing>`. - -.. setting:: DATE_FORMAT - -DATE_FORMAT ------------ - -Default: ``'N j, Y'`` (e.g. ``Feb. 4, 2003``) - -The default formatting to use for displaying date fields in any part of the -system. Note that if :setting:`USE_L10N` is set to ``True``, then the -locale-dictated format has higher precedence and will be applied instead. See -:tfilter:`allowed date format strings <date>`. - -.. versionchanged:: 1.2 - This setting can now be overriden by setting ``USE_L10N`` to ``True``. - -See also ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATE_FORMAT``. - -.. setting:: DATE_INPUT_FORMATS - -DATE_INPUT_FORMATS ------------------- - -.. versionadded:: 1.2 - -Default:: - - ('%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', '%b %d %Y', - '%b %d, %Y', '%d %b %Y', '%d %b, %Y', '%B %d %Y', - '%B %d, %Y', '%d %B %Y', '%d %B, %Y') - -A tuple of formats that will be accepted when inputting data on a date -field. Formats will be tried in order, using the first valid. -Note that these format strings are specified in Python's datetime_ module -syntax, that is different from the one used by Django for formatting dates -to be displayed. - -See also ``DATETIME_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``. - -.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior - -.. setting:: DATETIME_FORMAT - -DATETIME_FORMAT ---------------- - -Default: ``'N j, Y, P'`` (e.g. ``Feb. 4, 2003, 4 p.m.``) - -The default formatting to use for displaying datetime fields in any part of the -system. Note that if :setting:`USE_L10N` is set to ``True``, then the -locale-dictated format has higher precedence and will be applied instead. See -:tfilter:`allowed date format strings <date>`. - -.. versionchanged:: 1.2 - This setting can now be overriden by setting ``USE_L10N`` to ``True``. - -See also ``DATE_FORMAT``, ``TIME_FORMAT`` and ``SHORT_DATETIME_FORMAT``. - -.. setting:: DATETIME_INPUT_FORMATS - -DATETIME_INPUT_FORMATS ----------------------- - -.. versionadded:: 1.2 - -Default:: - - ('%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d', - '%m/%d/%Y %H:%M:%S', '%m/%d/%Y %H:%M', '%m/%d/%Y', - '%m/%d/%y %H:%M:%S', '%m/%d/%y %H:%M', '%m/%d/%y') - -A tuple of formats that will be accepted when inputting data on a datetime -field. Formats will be tried in order, using the first valid. -Note that these format strings are specified in Python's datetime_ module -syntax, that is different from the one used by Django for formatting dates -to be displayed. - -See also ``DATE_INPUT_FORMATS`` and ``TIME_INPUT_FORMATS``. - -.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior - -.. setting:: DEBUG - -DEBUG ------ - -Default: ``False`` - -A boolean that turns on/off debug mode. - -If you define custom settings, `django/views/debug.py`_ has a ``HIDDEN_SETTINGS`` -regular expression which will hide from the DEBUG view anything that contains -``'SECRET'``, ``'PASSWORD'``, ``'PROFANITIES'``, or ``'SIGNATURE'``. This allows -untrusted users to be able to give backtraces without seeing sensitive (or -offensive) settings. - -Still, note that there are always going to be sections of your debug output that -are inappropriate for public consumption. File paths, configuration options, and -the like all give attackers extra information about your server. - -It is also important to remember that when running with ``DEBUG`` turned on, Django -will remember every SQL query it executes. This is useful when you are debugging, -but on a production server, it will rapidly consume memory. - -Never deploy a site into production with ``DEBUG`` turned on. - -.. _django/views/debug.py: http://code.djangoproject.com/browser/django/trunk/django/views/debug.py - -DEBUG_PROPAGATE_EXCEPTIONS --------------------------- - -.. versionadded:: 1.0 - -Default: ``False`` - -If set to True, Django's normal exception handling of view functions -will be suppressed, and exceptions will propagate upwards. This can -be useful for some test setups, and should never be used on a live -site. - -.. setting:: DECIMAL_SEPARATOR - -DECIMAL_SEPARATOR ------------------ - -.. versionadded:: 1.2 - -Default: ``'.'`` (Dot) - -Default decimal separator used when formatting decimal numbers. - -.. setting:: DEFAULT_CHARSET - -DEFAULT_CHARSET ---------------- - -Default: ``'utf-8'`` - -Default charset to use for all ``HttpResponse`` objects, if a MIME type isn't -manually specified. Used with ``DEFAULT_CONTENT_TYPE`` to construct the -``Content-Type`` header. - -.. setting:: DEFAULT_CONTENT_TYPE - -DEFAULT_CONTENT_TYPE --------------------- - -Default: ``'text/html'`` - -Default content type to use for all ``HttpResponse`` objects, if a MIME type -isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the -``Content-Type`` header. - -.. setting:: DEFAULT_FILE_STORAGE - -DEFAULT_FILE_STORAGE --------------------- - -Default: :class:`django.core.files.storage.FileSystemStorage` - -Default file storage class to be used for any file-related operations that don't -specify a particular storage system. See :doc:`/topics/files`. - -.. setting:: DEFAULT_FROM_EMAIL - -DEFAULT_FROM_EMAIL ------------------- - -Default: ``'webmaster@localhost'`` - -Default e-mail address to use for various automated correspondence from the -site manager(s). - -.. setting:: DEFAULT_INDEX_TABLESPACE - -DEFAULT_INDEX_TABLESPACE ------------------------- - -.. versionadded:: 1.0 - -Default: ``''`` (Empty string) - -Default tablespace to use for indexes on fields that don't specify -one, if the backend supports it. - -.. setting:: DEFAULT_TABLESPACE - -DEFAULT_TABLESPACE ------------------- - -.. versionadded:: 1.0 - -Default: ``''`` (Empty string) - -Default tablespace to use for models that don't specify one, if the -backend supports it. - -.. setting:: DISALLOWED_USER_AGENTS - -DISALLOWED_USER_AGENTS ----------------------- - -Default: ``()`` (Empty tuple) - -List of compiled regular expression objects representing User-Agent strings that -are not allowed to visit any page, systemwide. Use this for bad robots/crawlers. -This is only used if ``CommonMiddleware`` is installed (see -:doc:`/topics/http/middleware`). - -.. setting:: EMAIL_BACKEND - -EMAIL_BACKEND -------------- - -.. versionadded:: 1.2 - -Default: ``'django.core.mail.backends.smtp.EmailBackend'`` - -The backend to use for sending emails. For the list of available backends see -:doc:`/topics/email`. - -.. setting:: EMAIL_FILE_PATH - -EMAIL_FILE_PATH ---------------- - -.. versionadded:: 1.2 - -Default: Not defined - -The directory used by the ``file`` email backend to store output files. - -.. setting:: EMAIL_HOST - -EMAIL_HOST ----------- - -Default: ``'localhost'`` - -The host to use for sending e-mail. - -See also ``EMAIL_PORT``. - -.. setting:: EMAIL_HOST_PASSWORD - -EMAIL_HOST_PASSWORD -------------------- - -Default: ``''`` (Empty string) - -Password to use for the SMTP server defined in ``EMAIL_HOST``. This setting is -used in conjunction with ``EMAIL_HOST_USER`` when authenticating to the SMTP -server. If either of these settings is empty, Django won't attempt -authentication. - -See also ``EMAIL_HOST_USER``. - -.. setting:: EMAIL_HOST_USER - -EMAIL_HOST_USER ---------------- - -Default: ``''`` (Empty string) - -Username to use for the SMTP server defined in ``EMAIL_HOST``. If empty, -Django won't attempt authentication. - -See also ``EMAIL_HOST_PASSWORD``. - -.. setting:: EMAIL_PORT - -EMAIL_PORT ----------- - -Default: ``25`` - -Port to use for the SMTP server defined in ``EMAIL_HOST``. - -.. setting:: EMAIL_SUBJECT_PREFIX - -EMAIL_SUBJECT_PREFIX --------------------- - -Default: ``'[Django] '`` - -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. - -.. setting:: EMAIL_USE_TLS - -EMAIL_USE_TLS -------------- - -.. versionadded:: 1.0 - -Default: ``False`` - -Whether to use a TLS (secure) connection when talking to the SMTP server. - -.. setting:: FILE_CHARSET - -FILE_CHARSET ------------- - -.. versionadded:: 1.0 - -Default: ``'utf-8'`` - -The character encoding used to decode any files read from disk. This includes -template files and initial SQL data files. - -.. setting:: FILE_UPLOAD_HANDLERS - -FILE_UPLOAD_HANDLERS --------------------- - -.. versionadded:: 1.0 - -Default:: - - ("django.core.files.uploadhandler.MemoryFileUploadHandler", - "django.core.files.uploadhandler.TemporaryFileUploadHandler",) - -A tuple of handlers to use for uploading. See :doc:`/topics/files` for details. - -.. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE - -FILE_UPLOAD_MAX_MEMORY_SIZE ---------------------------- - -.. versionadded:: 1.0 - -Default: ``2621440`` (i.e. 2.5 MB). - -The maximum size (in bytes) that an upload will be before it gets streamed to -the file system. See :doc:`/topics/files` for details. - -.. setting:: FILE_UPLOAD_PERMISSIONS - -FILE_UPLOAD_PERMISSIONS ------------------------ - -Default: ``None`` - -The numeric mode (i.e. ``0644``) to set newly uploaded files to. For -more information about what these modes mean, see the `documentation for -os.chmod`_ - -If this isn't given or is ``None``, you'll get operating-system -dependent behavior. On most platforms, temporary files will have a mode -of ``0600``, and files saved from memory will be saved using the -system's standard umask. - -.. warning:: - - **Always prefix the mode with a 0.** - - If you're not familiar with file modes, please note that the leading - ``0`` is very important: it indicates an octal number, which is the - way that modes must be specified. If you try to use ``644``, you'll - get totally incorrect behavior. - - -.. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod - -.. setting:: FILE_UPLOAD_TEMP_DIR - -FILE_UPLOAD_TEMP_DIR --------------------- - -.. versionadded:: 1.0 - -Default: ``None`` - -The directory to store data temporarily while uploading files. If ``None``, -Django will use the standard temporary directory for the operating system. For -example, this will default to '/tmp' on \*nix-style operating systems. - -See :doc:`/topics/files` for details. - -.. setting:: FIRST_DAY_OF_WEEK - -FIRST_DAY_OF_WEEK ------------------ - -.. versionadded:: 1.2 - -Default: ``0`` (Sunday) - -Number representing the first day of the week. This is especially useful -when displaying a calendar. This value is only used when not using -format internationalization, or when a format cannot be found for the -current locale. - -The value must be an integer from 0 to 6, where 0 means Sunday, 1 means -Monday and so on. - -.. setting:: FIXTURE_DIRS - -FIXTURE_DIRS -------------- - -Default: ``()`` (Empty tuple) - -List of locations of the fixture data files, in search order. Note that -these paths should use Unix-style forward slashes, even on Windows. See -:doc:`/topics/testing`. - -FORCE_SCRIPT_NAME ------------------- - -Default: ``None`` - -If not ``None``, this will be used as the value of the ``SCRIPT_NAME`` -environment variable in any HTTP request. This setting can be used to override -the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version -of the preferred value or not supplied at all. - -.. setting:: FORMAT_MODULE_PATH - -FORMAT_MODULE_PATH ------------------- - -.. versionadded:: 1.2 - -Default: ``None`` - -A full Python path to a Python package that contains format definitions for -project locales. If not ``None``, Django will check for a ``formats.py`` -file, under the directory named as the current locale, and will use the -formats defined on this file. - -For example, if ``FORMAT_MODULE_PATH`` is set to ``mysite.formats``, and -current language is ``en`` (English), Django will expect a directory tree -like:: - - mysite/ - formats/ - __init__.py - en/ - __init__.py - formats.py - -Available formats are ``DATE_FORMAT``, ``TIME_FORMAT``, ``DATETIME_FORMAT``, -``YEAR_MONTH_FORMAT``, ``MONTH_DAY_FORMAT``, ``SHORT_DATE_FORMAT``, -``SHORT_DATETIME_FORMAT``, ``FIRST_DAY_OF_WEEK``, ``DECIMAL_SEPARATOR``, -``THOUSAND_SEPARATOR`` and ``NUMBER_GROUPING``. - -.. setting:: IGNORABLE_404_ENDS - -IGNORABLE_404_ENDS ------------------- - -Default: ``('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')`` - -See also ``IGNORABLE_404_STARTS`` and ``Error reporting via e-mail``. - -.. setting:: IGNORABLE_404_STARTS - -IGNORABLE_404_STARTS --------------------- - -Default: ``('/cgi-bin/', '/_vti_bin', '/_vti_inf')`` - -A tuple of strings that specify beginnings of URLs that should be ignored by -the 404 e-mailer. See ``SEND_BROKEN_LINK_EMAILS``, ``IGNORABLE_404_ENDS`` and -the :doc:`/howto/error-reporting`. - -.. setting:: INSTALLED_APPS - -INSTALLED_APPS --------------- - -Default: ``()`` (Empty tuple) - -A tuple of strings designating all applications that are enabled in this Django -installation. Each string should be a full Python path to a Python package that -contains a Django application, as created by :djadmin:`django-admin.py startapp -<startapp>`. - -.. admonition:: App names must be unique - - The application names (that is, the final dotted part of the - path to the module containing ``models.py``) defined in - :setting:`INSTALLED_APPS` *must* be unique. For example, you can't - include both ``django.contrib.auth`` and ``myproject.auth`` in - INSTALLED_APPS. - -.. setting:: INTERNAL_IPS - -INTERNAL_IPS ------------- - -Default: ``()`` (Empty tuple) - -A tuple of IP addresses, as strings, that: - - * See debug comments, when ``DEBUG`` is ``True`` - * Receive X headers if the ``XViewMiddleware`` is installed (see - :doc:`/topics/http/middleware`) - -.. setting:: LANGUAGE_CODE - -LANGUAGE_CODE -------------- - -Default: ``'en-us'`` - -A string representing the language code for this installation. This should be in -standard :term:`language format<language code>`. For example, U.S. English is -``"en-us"``. See :doc:`/topics/i18n/index`. - -.. setting:: LANGUAGE_COOKIE_NAME - -LANGUAGE_COOKIE_NAME --------------------- - -.. versionadded:: 1.0 - -Default: ``'django_language'`` - -The name of the cookie to use for the language cookie. This can be whatever you -want (but should be different from ``SESSION_COOKIE_NAME``). See -:doc:`/topics/i18n/index`. - -.. setting:: LANGUAGES - -LANGUAGES ---------- - -Default: A tuple of all available languages. This list is continually growing -and including a copy here would inevitably become rapidly out of date. You can -see the current list of translated languages by looking in -``django/conf/global_settings.py`` (or view the `online source`_). - -.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py - -The list is a tuple of two-tuples in the format ``(language code, language -name)``, the ``language code`` part should be a -:term:`language name<language code>` -- for example, ``('ja', 'Japanese')``. -This specifies which languages are available for language selection. See -:doc:`/topics/i18n/index`. - -Generally, the default value should suffice. Only set this setting if you want -to restrict language selection to a subset of the Django-provided languages. - -If you define a custom ``LANGUAGES`` setting, it's OK to mark the languages as -translation strings (as in the default value referred to above) -- but use a -"dummy" ``gettext()`` function, not the one in ``django.utils.translation``. -You should *never* import ``django.utils.translation`` from within your -settings file, because that module in itself depends on the settings, and that -would cause a circular import. - -The solution is to use a "dummy" ``gettext()`` function. Here's a sample -settings file:: - - gettext = lambda s: s - - LANGUAGES = ( - ('de', gettext('German')), - ('en', gettext('English')), - ) - -With this arrangement, ``django-admin.py makemessages`` will still find and -mark these strings for translation, but the translation won't happen at -runtime -- so you'll have to remember to wrap the languages in the *real* -``gettext()`` in any code that uses ``LANGUAGES`` at runtime. - -.. setting:: LOCALE_PATHS - -LOCALE_PATHS ------------- - -Default: ``()`` (Empty tuple) - -A tuple of directories where Django looks for translation files. -See :ref:`using-translations-in-your-own-projects`. - -.. setting:: LOGIN_REDIRECT_URL - -LOGIN_REDIRECT_URL ------------------- - -.. versionadded:: 1.0 - -Default: ``'/accounts/profile/'`` - -The URL where requests are redirected after login when the -``contrib.auth.login`` view gets no ``next`` parameter. - -This is used by the :func:`~django.contrib.auth.decorators.login_required` -decorator, for example. - -.. setting:: LOGIN_URL - -LOGIN_URL ---------- - -.. versionadded:: 1.0 - -Default: ``'/accounts/login/'`` - -The URL where requests are redirected for login, especially when using the -:func:`~django.contrib.auth.decorators.login_required` decorator. - -.. setting:: LOGOUT_URL - -LOGOUT_URL ----------- - -.. versionadded:: 1.0 - -Default: ``'/accounts/logout/'`` - -LOGIN_URL counterpart. - -.. setting:: MANAGERS - -MANAGERS --------- - -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``. - -.. setting:: MEDIA_ROOT - -MEDIA_ROOT ----------- - -Default: ``''`` (Empty string) - -Absolute path to the directory that holds media for this installation. -Example: ``"/home/media/media.lawrence.com/"`` See also ``MEDIA_URL``. - -.. setting:: MEDIA_URL - -MEDIA_URL ---------- - -Default: ``''`` (Empty string) - -URL that handles the media served from ``MEDIA_ROOT``. -Example: ``"http://media.lawrence.com"`` - -Note that this should have a trailing slash if it has a path component. - -Good: ``"http://www.example.com/static/"`` -Bad: ``"http://www.example.com/static"`` - -.. setting:: MIDDLEWARE_CLASSES - -MESSAGE_LEVEL -------------- - -.. versionadded:: 1.2 - -Default: `messages.INFO` - -Sets the minimum message level that will be recorded by the messages -framework. See the :doc:`messages documentation </ref/contrib/messages>` for -more details. - -MESSAGE_STORAGE ---------------- - -.. versionadded:: 1.2 - -Default: ``'django.contrib.messages.storage.user_messages.LegacyFallbackStorage'`` - -Controls where Django stores message data. See the -:doc:`messages documentation </ref/contrib/messages>` for more details. - -MESSAGE_TAGS ------------- - -.. versionadded:: 1.2 - -Default:: - - {messages.DEBUG: 'debug', - messages.INFO: 'info', - messages.SUCCESS: 'success', - messages.WARNING: 'warning', - messages.ERROR: 'error',} - -Sets the mapping of message levels to message tags. See the -:doc:`messages documentation </ref/contrib/messages>` for more details. - -MIDDLEWARE_CLASSES ------------------- - -Default:: - - ('django.middleware.common.CommonMiddleware', - 'django.contrib.sessions.middleware.SessionMiddleware', - 'django.middleware.csrf.CsrfViewMiddleware', - 'django.contrib.auth.middleware.AuthenticationMiddleware', - 'django.contrib.messages.middleware.MessageMiddleware',) - -A tuple of middleware classes to use. See :doc:`/topics/http/middleware`. - -.. versionchanged:: 1.2 - ``'django.contrib.messages.middleware.MessageMiddleware'`` was added to the - default. For more information, see the :doc:`messages documentation - </ref/contrib/messages>`. - -.. setting:: MONTH_DAY_FORMAT - -MONTH_DAY_FORMAT ----------------- - -Default: ``'F j'`` - -The default formatting to use for date fields on Django admin change-list -pages -- and, possibly, by other parts of the system -- in cases when only the -month and day are displayed. - -For example, when a Django admin change-list page is being filtered by a date -drilldown, the header for a given day displays the day and month. Different -locales have different formats. For example, U.S. English would say -"January 1," whereas Spanish might say "1 Enero." - -See :tfilter:`allowed date format strings <date>`. See also ``DATE_FORMAT``, -``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``YEAR_MONTH_FORMAT``. - -.. setting:: NUMBER_GROUPING - -NUMBER_GROUPING ----------------- - -.. versionadded:: 1.2 - -Default: ``0`` - -Number of digits grouped together on the integer part of a number. Common use -is to display a thousand separator. If this setting is ``0``, then, no grouping -will be applied to the number. If this setting is greater than ``0`` then the -setting :setting:`THOUSAND_SEPARATOR` will be used as the separator between those -groups. - -See also :setting:`THOUSAND_SEPARATOR` and :setting:`USE_THOUSAND_SEPARATOR`. - -.. setting:: PASSWORD_RESET_TIMEOUT_DAYS - -PASSWORD_RESET_TIMEOUT_DAYS ---------------------------- - -Default: ``3`` - -The number of days a password reset link is valid for. Used by the -:mod:`django.contrib.auth` password reset mechanism. - -.. setting:: PREPEND_WWW - -PREPEND_WWW ------------ - -Default: ``False`` - -Whether to prepend the "www." subdomain to URLs that don't have it. This is only -used if :class:`~django.middleware.common.CommonMiddleware` is installed -(see :doc:`/topics/http/middleware`). See also :setting:`APPEND_SLASH`. - -.. setting:: PROFANITIES_LIST - -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`_. - -.. _django/conf/global_settings.py: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py - -.. setting:: RESTRUCTUREDTEXT_FILTER_SETTINGS - -RESTRUCTUREDTEXT_FILTER_SETTINGS --------------------------------- - -Default: ``{}`` - -A dictionary containing settings for the ``restructuredtext`` markup filter from -the :doc:`django.contrib.markup application </ref/contrib/markup>`. They override -the default writer settings. See the Docutils restructuredtext `writer settings -docs`_ for details. - -.. _writer settings docs: http://docutils.sourceforge.net/docs/user/config.html#html4css1-writer - -.. setting:: ROOT_URLCONF - -ROOT_URLCONF ------------- - -Default: Not defined - -A string representing the full Python import path to your root URLconf. For example: -``"mydjangoapps.urls"``. Can be overridden on a per-request basis by -setting the attribute ``urlconf`` on the incoming ``HttpRequest`` -object. See :ref:`how-django-processes-a-request` for details. - -.. setting:: SECRET_KEY - -SECRET_KEY ----------- - -Default: ``''`` (Empty string) - -A secret key for this particular Django installation. Used to provide a seed in -secret-key hashing algorithms. Set this to a random string -- the longer, the -better. ``django-admin.py startproject`` creates one automatically. - -.. setting:: SEND_BROKEN_LINK_EMAILS - -SEND_BROKEN_LINK_EMAILS ------------------------ - -Default: ``False`` - -Whether to send an e-mail to the ``MANAGERS`` each time somebody visits a -Django-powered page that is 404ed with a non-empty referer (i.e., a broken -link). This is only used if ``CommonMiddleware`` is installed (see -:doc:`/topics/http/middleware`. See also ``IGNORABLE_404_STARTS``, -``IGNORABLE_404_ENDS`` and :doc:`/howto/error-reporting`. - -.. setting:: SERIALIZATION_MODULES - -SERIALIZATION_MODULES ---------------------- - -Default: Not defined. - -A dictionary of modules containing serializer definitions (provided as -strings), keyed by a string identifier for that serialization type. For -example, to define a YAML serializer, use:: - - SERIALIZATION_MODULES = { 'yaml' : 'path.to.yaml_serializer' } - -.. setting:: SERVER_EMAIL - -SERVER_EMAIL ------------- - -Default: ``'root@localhost'`` - -The e-mail address that error messages come from, such as those sent to -``ADMINS`` and ``MANAGERS``. - -.. setting:: SESSION_COOKIE_AGE - -SESSION_COOKIE_AGE ------------------- - -Default: ``1209600`` (2 weeks, in seconds) - -The age of session cookies, in seconds. See :doc:`/topics/http/sessions`. - -.. setting:: SESSION_COOKIE_DOMAIN - -SESSION_COOKIE_DOMAIN ---------------------- - -Default: ``None`` - -The domain to use for session cookies. Set this to a string such as -``".lawrence.com"`` for cross-domain cookies, or use ``None`` for a standard -domain cookie. See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_COOKIE_NAME - -SESSION_COOKIE_NAME -------------------- - -Default: ``'sessionid'`` - -The name of the cookie to use for sessions. This can be whatever you want (but -should be different from ``LANGUAGE_COOKIE_NAME``). See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_COOKIE_PATH - -SESSION_COOKIE_PATH -------------------- - -.. versionadded:: 1.0 - -Default: ``'/'`` - -The path set on the session cookie. This should either match the URL path of your -Django installation or be parent of that path. - -This is useful if you have multiple Django instances running under the same -hostname. They can use different cookie paths, and each instance will only see -its own session cookie. - -.. setting:: SESSION_COOKIE_SECURE - -SESSION_COOKIE_SECURE ---------------------- - -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 :doc:`/topics/http/sessions`. - -.. setting:: SESSION_ENGINE - -SESSION_ENGINE --------------- - -.. versionadded:: 1.0 - -.. versionchanged:: 1.1 - The ``cached_db`` backend was added - -Default: ``django.contrib.sessions.backends.db`` - -Controls where Django stores session data. Valid values are: - - * ``'django.contrib.sessions.backends.db'`` - * ``'django.contrib.sessions.backends.file'`` - * ``'django.contrib.sessions.backends.cache'`` - * ``'django.contrib.sessions.backends.cached_db'`` - -See :doc:`/topics/http/sessions`. - -.. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE - -SESSION_EXPIRE_AT_BROWSER_CLOSE -------------------------------- - -Default: ``False`` - -Whether to expire the session when the user closes his or her browser. -See the :doc:`/topics/http/sessions`. - -.. setting:: SESSION_FILE_PATH - -SESSION_FILE_PATH ------------------ - -.. versionadded:: 1.0 - -Default: ``None`` - -If you're using file-based session storage, this sets the directory in -which Django will store session data. See :doc:`/topics/http/sessions`. When -the default value (``None``) is used, Django will use the standard temporary -directory for the system. - -.. setting:: SESSION_SAVE_EVERY_REQUEST - -SESSION_SAVE_EVERY_REQUEST --------------------------- - -Default: ``False`` - -Whether to save the session data on every request. See -:doc:`/topics/http/sessions`. - -.. setting:: SHORT_DATE_FORMAT - -SHORT_DATE_FORMAT ------------------ - -.. versionadded:: 1.2 - -Default: ``m/d/Y`` (e.g. ``12/31/2003``) - -An available formatting that can be used for displaying date fields on -templates. Note that if :setting:`USE_L10N` is set to ``True``, then the -corresponding locale-dictated format has higher precedence and will be applied. -See :tfilter:`allowed date format strings <date>`. - -See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``. - -.. setting:: SHORT_DATETIME_FORMAT - -SHORT_DATETIME_FORMAT ---------------------- - -.. versionadded:: 1.2 - -Default: ``m/d/Y P`` (e.g. ``12/31/2003 4 p.m.``) - -An available formatting that can be used for displaying datetime fields on -templates. Note that if :setting:`USE_L10N` is set to ``True``, then the -corresponding locale-dictated format has higher precedence and will be applied. -See :tfilter:`allowed date format strings <date>`. - -See also ``DATE_FORMAT`` and ``SHORT_DATETIME_FORMAT``. - -.. setting:: SITE_ID - -SITE_ID -------- - -Default: Not defined - -The ID, as an integer, of the current site in the ``django_site`` database -table. This is used so that application data can hook into specific site(s) -and a single database can manage content for multiple sites. - -See :doc:`/ref/contrib/sites`. - -.. _site framework docs: ../sites/ - -.. setting:: TEMPLATE_CONTEXT_PROCESSORS - -TEMPLATE_CONTEXT_PROCESSORS ---------------------------- - -Default:: - - ("django.contrib.auth.context_processors.auth", - "django.core.context_processors.debug", - "django.core.context_processors.i18n", - "django.core.context_processors.media", - "django.contrib.messages.context_processors.messages") - -A tuple of callables that are used to populate the context in ``RequestContext``. -These callables take a request object as their argument and return a dictionary -of items to be merged into the context. - -.. versionchanged:: 1.2 - ``"django.contrib.messages.context_processors.messages"`` was added to the - default. For more information, see the :doc:`messages documentation - </ref/contrib/messages>`. - -.. versionchanged:: 1.2 - The auth context processor was moved in this release from its old location - ``django.core.context_processors.auth`` to - ``django.contrib.auth.context_processors.auth``. - -.. setting:: TEMPLATE_DEBUG - -TEMPLATE_DEBUG --------------- - -Default: ``False`` - -A boolean that turns on/off template debug mode. If this is ``True``, the fancy -error page will display a detailed report for any ``TemplateSyntaxError``. This -report contains the relevant snippet of the template, with the appropriate line -highlighted. - -Note that Django only displays fancy error pages if ``DEBUG`` is ``True``, so -you'll want to set that to take advantage of this setting. - -See also ``DEBUG``. - -.. setting:: TEMPLATE_DIRS - -TEMPLATE_DIRS -------------- - -Default: ``()`` (Empty tuple) - -List of locations of the template source files, in search order. Note that -these paths should use Unix-style forward slashes, even on Windows. - -See :doc:`/topics/templates`. - -.. setting:: TEMPLATE_LOADERS - -TEMPLATE_LOADERS ----------------- - -Default:: - - ('django.template.loaders.filesystem.Loader', - 'django.template.loaders.app_directories.Loader') - -A tuple of template loader classes, specified as strings. Each ``Loader`` class -knows how to import templates from a particular source. Optionally, a tuple can be -used instead of a string. The first item in the tuple should be the ``Loader``'s -module, subsequent items are passed to the ``Loader`` during initialization. See -:doc:`/ref/templates/api`. - -.. setting:: TEMPLATE_STRING_IF_INVALID - -TEMPLATE_STRING_IF_INVALID --------------------------- - -Default: ``''`` (Empty string) - -Output, as a string, that the template system should use for invalid (e.g. -misspelled) variables. See :ref:`invalid-template-variables`.. - -.. setting:: TEST_RUNNER - -TEST_RUNNER ------------ - -Default: ``'django.test.simple.DjangoTestSuiteRunner'`` - -.. versionchanged:: 1.2 - Prior to 1.2, test runners were a function, not a class. - -The name of the class to use for starting the test suite. See -:doc:`/topics/testing`. - -.. _Testing Django Applications: ../testing/ - -.. setting:: THOUSAND_SEPARATOR - -THOUSAND_SEPARATOR ------------------- - -.. versionadded:: 1.2 - -Default ``,`` (Comma) - -Default thousand separator used when formatting numbers. This setting is -used only when ``NUMBER_GROUPING`` and ``USE_THOUSAND_SEPARATOR`` are set. - -See also :setting:`NUMBER_GROUPING`, :setting:`DECIMAL_SEPARATOR` and -:setting:`USE_THOUSAND_SEPARATOR`. - -.. setting:: TIME_FORMAT - -TIME_FORMAT ------------ - -Default: ``'P'`` (e.g. ``4 p.m.``) - -The default formatting to use for displaying time fields in any part of the -system. Note that if :setting:`USE_L10N` is set to ``True``, then the -locale-dictated format has higher precedence and will be applied instead. See -:tfilter:`allowed date format strings <date>`. - -.. versionchanged:: 1.2 - This setting can now be overriden by setting ``USE_L10N`` to ``True``. - -See also ``DATE_FORMAT`` and ``DATETIME_FORMAT``. - -.. setting:: TIME_INPUT_FORMATS - -TIME_INPUT_FORMATS ------------------- - -.. versionadded:: 1.2 - -Default: ``('%H:%M:%S', '%H:%M')`` - -A tuple of formats that will be accepted when inputting data on a time -field. Formats will be tried in order, using the first valid. -Note that these format strings are specified in Python's datetime_ module -syntax, that is different from the one used by Django for formatting dates -to be displayed. - -See also ``DATE_INPUT_FORMATS`` and ``DATETIME_INPUT_FORMATS``. - -.. _datetime: http://docs.python.org/library/datetime.html#strftime-strptime-behavior - -.. setting:: TIME_ZONE - -TIME_ZONE ---------- - -Default: ``'America/Chicago'`` - -.. versionchanged:: 1.2 - ``None`` was added as an allowed value. - -A string representing the time zone for this installation, or -``None``. `See available choices`_. (Note that list of available -choices lists more than one on the same line; you'll want to use just -one of the choices for a given time zone. For instance, one line says -``'Europe/London GB GB-Eire'``, but you should use the first bit of -that -- ``'Europe/London'`` -- as your ``TIME_ZONE`` setting.) - -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, Django won't set the ``TZ`` environment variable under the -following conditions: - - * If you're using the manual configuration option as described in - :ref:`manually configuring settings - <settings-without-django-settings-module>`, or - - * If you specify ``TIME_ZONE = None``. This will cause Django to fall - back to using the system timezone. - -If Django doesn't set the ``TZ`` environment variable, it's up to you -to ensure your processes are running in the correct environment. - -.. note:: - Django cannot reliably use alternate time zones in a Windows - environment. If you're running Django on Windows, this variable - must be set to match the system timezone. - - -.. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE - -.. setting:: URL_VALIDATOR_USER_AGENT - -URL_VALIDATOR_USER_AGENT ------------------------- - -Default: ``Django/<version> (http://www.djangoproject.com/)`` - -The string to use as the ``User-Agent`` header when checking to see if URLs -exist (see the ``verify_exists`` option on :class:`~django.db.models.URLField`). - -.. setting:: USE_ETAGS - -USE_ETAGS ---------- - -Default: ``False`` - -A boolean that specifies whether to output the "Etag" header. This saves -bandwidth but slows down performance. This is only used if ``CommonMiddleware`` -is installed (see :doc:`/topics/http/middleware`). - -.. setting:: USE_I18N - -USE_I18N --------- - -Default: ``True`` - -A boolean that specifies whether Django's internationalization system should be -enabled. This provides an easy way to turn it off, for performance. If this is -set to ``False``, Django will make some optimizations so as not to load the -internationalization machinery. - -See also ``USE_L10N`` - -.. setting:: USE_L10N - -USE_L10N --------- - -.. versionadded:: 1.2 - -Default ``False`` - -A boolean that specifies if data will be localized by default or not. If this -is set to ``True``, e.g. Django will display numbers and dates using the -format of the current locale. - -See also ``USE_I18N`` and ``LANGUAGE_CODE`` - -.. setting:: USE_THOUSAND_SEPARATOR - -USE_THOUSAND_SEPARATOR ----------------------- - -.. versionadded:: 1.2 - -Default ``False`` - -A boolean that specifies wheter to display numbers using a thousand separator. -If this is set to ``True``, Django will use values from ``THOUSAND_SEPARATOR`` -and ``NUMBER_GROUPING`` from current locale, to format the number. -``USE_L10N`` must be set to ``True``, in order to format numbers. - -See also ``THOUSAND_SEPARATOR`` and ``NUMBER_GROUPING``. - -.. setting:: YEAR_MONTH_FORMAT - -YEAR_MONTH_FORMAT ------------------ - -Default: ``'F Y'`` - -The default formatting to use for date fields on Django admin change-list -pages -- and, possibly, by other parts of the system -- in cases when only the -year and month are displayed. - -For example, when a Django admin change-list page is being filtered by a date -drilldown, the header for a given month displays the month and the year. -Different locales have different formats. For example, U.S. English would say -"January 2006," whereas another locale might say "2006/January." - -See :tfilter:`allowed date format strings <date>`. See also ``DATE_FORMAT``, -``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``MONTH_DAY_FORMAT``. - -Deprecated settings -=================== - -.. setting:: DATABASE_ENGINE - -DATABASE_ENGINE ---------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`ENGINE` in - :setting:`DATABASES`. - -.. setting:: DATABASE_HOST - -DATABASE_HOST -------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`HOST` in - :setting:`DATABASES`. - -.. setting:: DATABASE_NAME - -DATABASE_NAME -------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`NAME` in - :setting:`DATABASES`. - -.. setting:: DATABASE_OPTIONS - -DATABASE_OPTIONS ----------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`OPTIONS` in - :setting:`DATABASES`. - -.. setting:: DATABASE_PASSWORD - -DATABASE_PASSWORD ------------------ - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`PASSWORD` in - :setting:`DATABASES`. - -.. setting:: DATABASE_PORT - -DATABASE_PORT -------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`PORT` in - :setting:`DATABASES`. - -.. setting:: DATABASE_USER - -DATABASE_USER -------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`USER` in - :setting:`DATABASES`. - -.. setting:: TEST_DATABASE_CHARSET - -TEST_DATABASE_CHARSET ---------------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`TEST_CHARSET` in - :setting:`DATABASES`. - -.. setting:: TEST_DATABASE_COLLATION - -TEST_DATABASE_COLLATION ------------------------ - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`TEST_COLLATION` in - :setting:`DATABASES`. - -.. setting:: TEST_DATABASE_NAME - -TEST_DATABASE_NAME ------------------- - -.. deprecated:: 1.2 - This setting has been replaced by :setting:`TEST_NAME` in - :setting:`DATABASES`. - diff --git a/parts/django/docs/ref/signals.txt b/parts/django/docs/ref/signals.txt deleted file mode 100644 index 4bc1f3f..0000000 --- a/parts/django/docs/ref/signals.txt +++ /dev/null @@ -1,475 +0,0 @@ -======= -Signals -======= - -A list of all the signals that Django sends. - -.. seealso:: - - See the documentation on the :doc:`signal dispatcher </topics/signals>` for - information regarding how to register for and receive signals. - - The :doc:`comment framework </ref/contrib/comments/index>` sends a :doc:`set - of comment-related signals </ref/contrib/comments/signals>`. - -Model signals -============= - -.. module:: django.db.models.signals - :synopsis: Signals sent by the model system. - -The :mod:`django.db.models.signals` module defines a set of signals sent by the -module system. - -.. warning:: - - Many of these signals are sent by various model methods like - :meth:`~django.db.models.Model.__init__` or - :meth:`~django.db.models.Model.save` that you can overwrite in your own - code. - - If you override these methods on your model, you must call the parent class' - methods for this signals to be sent. - - Note also that Django stores signal handlers as weak references by default, - so if your handler is a local function, it may be garbage collected. To - prevent this, pass ``weak=False`` when you call the signal's :meth:`~django.dispatch.Signal.connect`. - -pre_init --------- - -.. attribute:: django.db.models.signals.pre_init - :module: - -.. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module. - -Whenever you instantiate a Django model,, this signal is sent at the beginning -of the model's :meth:`~django.db.models.Model.__init__` method. - -Arguments sent with this signal: - - ``sender`` - The model class that just had an instance created. - - ``args`` - A list of positional arguments passed to - :meth:`~django.db.models.Model.__init__`: - - ``kwargs`` - A dictionary of keyword arguments passed to - :meth:`~django.db.models.Model.__init__`:. - -For example, the :doc:`tutorial </intro/tutorial01>` has this line: - -.. code-block:: python - - p = Poll(question="What's up?", pub_date=datetime.now()) - -The arguments sent to a :data:`pre_init` handler would be: - - ========== =============================================================== - Argument Value - ========== =============================================================== - ``sender`` ``Poll`` (the class itself) - - ``args`` ``[]`` (an empty list because there were no positional - arguments passed to ``__init__``.) - - ``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}`` - ========== =============================================================== - -post_init ---------- - -.. data:: django.db.models.signals.post_init - :module: - -Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes. - -Arguments sent with this signal: - - ``sender`` - As above: the model class that just had an instance created. - - ``instance`` - The actual instance of the model that's just been created. - -pre_save --------- - -.. data:: django.db.models.signals.pre_save - :module: - -This is sent at the beginning of a model's :meth:`~django.db.models.Model.save` -method. - -Arguments sent with this signal: - - ``sender`` - The model class. - - ``instance`` - The actual instance being saved. - -post_save ---------- - -.. data:: django.db.models.signals.post_save - :module: - -Like :data:`pre_save`, but sent at the end of the -:meth:`~django.db.models.Model.save` method. - -Arguments sent with this signal: - - ``sender`` - The model class. - - ``instance`` - The actual instance being saved. - - ``created`` - A boolean; ``True`` if a new record was created. - -pre_delete ----------- - -.. data:: django.db.models.signals.pre_delete - :module: - -Sent at the beginning of a model's :meth:`~django.db.models.Model.delete` -method. - -Arguments sent with this signal: - - ``sender`` - The model class. - - ``instance`` - The actual instance being deleted. - -post_delete ------------ - -.. data:: django.db.models.signals.post_delete - :module: - -Like :data:`pre_delete`, but sent at the end of the -:meth:`~django.db.models.Model.delete` method. - -Arguments sent with this signal: - - ``sender`` - The model class. - - ``instance`` - The actual instance being deleted. - - Note that the object will no longer be in the database, so be very - careful what you do with this instance. - -m2m_changed ------------ - -.. data:: django.db.models.signals.m2m_changed - :module: - -.. versionadded:: 1.2 - -Sent when a :class:`ManyToManyField` is changed on a model instance. -Strictly speaking, this is not a model signal since it is sent by the -:class:`ManyToManyField`, but since it complements the -:data:`pre_save`/:data:`post_save` and :data:`pre_delete`/:data:`post_delete` -when it comes to tracking changes to models, it is included here. - -Arguments sent with this signal: - - ``sender`` - The intermediate model class describing the :class:`ManyToManyField`. - This class is automatically created when a many-to-many field is - defined; you can access it using the ``through`` attribute on the - many-to-many field. - - ``instance`` - The instance whose many-to-many relation is updated. This can be an - instance of the ``sender``, or of the class the :class:`ManyToManyField` - is related to. - - ``action`` - A string indicating the type of update that is done on the relation. - This can be one of the following: - - ``"pre_add"`` - Sent *before* one or more objects are added to the relation - ``"post_add"`` - Sent *after* one or more objects are added to the relation - ``"pre_remove"`` - Sent *after* one or more objects are removed from the relation - ``"post_remove"`` - Sent *after* one or more objects are removed from the relation - ``"pre_clear"`` - Sent *before* the relation is cleared - ``"post_clear"`` - Sent *after* the relation is cleared - - ``reverse`` - Indicates which side of the relation is updated (i.e., if it is the - forward or reverse relation that is being modified). - - ``model`` - The class of the objects that are added to, removed from or cleared - from the relation. - - ``pk_set`` - For the ``pre_add``, ``post_add``, ``pre_remove`` and ``post_remove`` - actions, this is a list of primary key values that have been added to - or removed from the relation. - - For the ``pre_clear`` and ``post_clear`` actions, this is ``None``. - -For example, if a ``Pizza`` can have multiple ``Topping`` objects, modeled -like this: - -.. code-block:: python - - class Topping(models.Model): - # ... - - class Pizza(models.Model): - # ... - toppings = models.ManyToManyField(Topping) - -If we would do something like this: - -.. code-block:: python - - >>> p = Pizza.object.create(...) - >>> t = Topping.objects.create(...) - >>> p.toppings.add(t) - -the arguments sent to a :data:`m2m_changed` handler would be: - - ============== ============================================================ - Argument Value - ============== ============================================================ - ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) - - ``instance`` ``p`` (the ``Pizza`` instance being modified) - - ``action`` ``"pre_add"`` (followed by a separate signal with ``"post_add"``) - - ``reverse`` ``False`` (``Pizza`` contains the :class:`ManyToManyField`, - so this call modifies the forward relation) - - ``model`` ``Topping`` (the class of the objects added to the - ``Pizza``) - - ``pk_set`` ``[t.id]`` (since only ``Topping t`` was added to the relation) - ============== ============================================================ - -And if we would then do something like this: - -.. code-block:: python - - >>> t.pizza_set.remove(p) - -the arguments sent to a :data:`m2m_changed` handler would be: - - ============== ============================================================ - Argument Value - ============== ============================================================ - ``sender`` ``Pizza.toppings.through`` (the intermediate m2m class) - - ``instance`` ``t`` (the ``Topping`` instance being modified) - - ``action`` ``"pre_remove"`` (followed by a separate signal with ``"post_remove"``) - - ``reverse`` ``True`` (``Pizza`` contains the :class:`ManyToManyField`, - so this call modifies the reverse relation) - - ``model`` ``Pizza`` (the class of the objects removed from the - ``Topping``) - - ``pk_set`` ``[p.id]`` (since only ``Pizza p`` was removed from the - relation) - ============== ============================================================ - -class_prepared --------------- - -.. data:: django.db.models.signals.class_prepared - :module: - -Sent whenever a model class has been "prepared" -- that is, once model has -been defined and registered with Django's model system. Django uses this -signal internally; it's not generally used in third-party applications. - -Arguments that are sent with this signal: - -``sender`` - The model class which was just prepared. - -Management signals -================== - -Signals sent by :doc:`django-admin </ref/django-admin>`. - -post_syncdb ------------ - -.. data:: django.db.models.signals.post_syncdb - :module: - -Sent by :djadmin:`syncdb` after it installs an application. - -Any handlers that listen to this signal need to be written in a particular -place: a ``management`` module in one of your :setting:`INSTALLED_APPS`. If -handlers are registered anywhere else they may not be loaded by -:djadmin:`syncdb`. - -Arguments sent with this signal: - - ``sender`` - The ``models`` module that was just installed. That is, if - :djadmin:`syncdb` just installed an app called ``"foo.bar.myapp"``, - ``sender`` will be the ``foo.bar.myapp.models`` module. - - ``app`` - Same as ``sender``. - - ``created_models`` - A list of the model classes from any app which :djadmin:`syncdb` has - created so far. - - ``verbosity`` - Indicates how much information manage.py is printing on screen. See - the :djadminopt:`--verbosity` flag for details. - - Functions which listen for :data:`post_syncdb` should adjust what they - output to the screen based on the value of this argument. - - ``interactive`` - If ``interactive`` is ``True``, it's safe to prompt the user to input - things on the command line. If ``interactive`` is ``False``, functions - which listen for this signal should not try to prompt for anything. - - For example, the :mod:`django.contrib.auth` app only prompts to create a - superuser when ``interactive`` is ``True``. - -Request/response signals -======================== - -.. module:: django.core.signals - :synopsis: Core signals sent by the request/response system. - -Signals sent by the core framework when processing a request. - -request_started ---------------- - -.. data:: django.core.signals.request_started - :module: - -Sent when Django begins processing an HTTP request. - -Arguments sent with this signal: - - ``sender`` - The handler class -- i.e. - :class:`django.core.handlers.modpython.ModPythonHandler` or - :class:`django.core.handlers.wsgi.WsgiHandler` -- that handled - the request. - -request_finished ----------------- - -.. data:: django.core.signals.request_finished - :module: - -Sent when Django finishes processing an HTTP request. - -Arguments sent with this signal: - - ``sender`` - The handler class, as above. - -got_request_exception ---------------------- - -.. data:: django.core.signals.got_request_exception - :module: - -This signal is sent whenever Django encounters an exception while processing an incoming HTTP request. - -Arguments sent with this signal: - - ``sender`` - The handler class, as above. - - ``request`` - The :class:`~django.http.HttpRequest` object. - -Test signals -============ - -.. module:: django.test.signals - :synopsis: Signals sent during testing. - -Signals only sent when :doc:`running tests </topics/testing>`. - -template_rendered ------------------ - -.. data:: django.test.signals.template_rendered - :module: - -Sent when the test system renders a template. This signal is not emitted during -normal operation of a Django server -- it is only available during testing. - -Arguments sent with this signal: - - sender - The :class:`~django.template.Template` object which was rendered. - - template - Same as sender - - context - The :class:`~django.template.Context` with which the template was - rendered. - -Database Wrappers -================= - -.. module:: django.db.backends - :synopsis: Core signals sent by the database wrapper. - -Signals sent by the database wrapper when a database connection is -initiated. - -connection_created ------------------- - -.. data:: django.db.backends.signals.connection_created - :module: - -.. versionadded:: 1.1 - -.. versionchanged:: 1.2 - The connection argument was added - -Sent when the database wrapper makes the initial connection to the -database. This is particularly useful if you'd like to send any post -connection commands to the SQL backend. - -Arguments sent with this signal: - - sender - The database wrapper class -- i.e. - :class: `django.db.backends.postgresql_psycopg2.DatabaseWrapper` or - :class: `django.db.backends.mysql.DatabaseWrapper`, etc. - - connection - The database connection that was opened. This can be used in a - multiple-database configuration to differentiate connection signals - from different databases. diff --git a/parts/django/docs/ref/templates/api.txt b/parts/django/docs/ref/templates/api.txt deleted file mode 100644 index 1111869..0000000 --- a/parts/django/docs/ref/templates/api.txt +++ /dev/null @@ -1,815 +0,0 @@ -==================================================== -The Django template language: For Python programmers -==================================================== - -This document explains the Django template system from a technical -perspective -- how it works and how to extend it. If you're just looking for -reference on the language syntax, see :doc:`/topics/templates`. - -If you're looking to use the Django template system as part of another -application -- i.e., without the rest of the framework -- make sure to read -the `configuration`_ section later in this document. - -.. _configuration: `configuring the template system in standalone mode`_ - -Basics -====== - -A **template** is a text document, or a normal Python string, that is marked-up -using the Django template language. A template can contain **block tags** or -**variables**. - -A **block tag** is a symbol within a template that does something. - -This definition is deliberately vague. For example, a block tag can output -content, serve as a control structure (an "if" statement or "for" loop), grab -content from a database or enable access to other template tags. - -Block tags are surrounded by ``"{%"`` and ``"%}"``. - -Example template with block tags: - -.. code-block:: html+django - - {% if is_logged_in %}Thanks for logging in!{% else %}Please log in.{% endif %} - -A **variable** is a symbol within a template that outputs a value. - -Variable tags are surrounded by ``"{{"`` and ``"}}"``. - -Example template with variables: - -.. code-block:: html+django - - My first name is {{ first_name }}. My last name is {{ last_name }}. - -A **context** is a "variable name" -> "variable value" mapping that is passed -to a template. - -A template **renders** a context by replacing the variable "holes" with values -from the context and executing all block tags. - -Using the template system -========================= - -.. class:: django.template.Template - -Using the template system in Python is a two-step process: - - * First, you compile the raw template code into a ``Template`` object. - * Then, you call the ``render()`` method of the ``Template`` object with a - given context. - -Compiling a string ------------------- - -The easiest way to create a ``Template`` object is by instantiating it -directly. The class lives at :class:`django.template.Template`. The constructor -takes one argument -- the raw template code:: - - >>> from django.template import Template - >>> t = Template("My name is {{ my_name }}.") - >>> print t - <django.template.Template instance> - -.. admonition:: Behind the scenes - - The system only parses your raw template code once -- when you create the - ``Template`` object. From then on, it's stored internally as a "node" - structure for performance. - - Even the parsing itself is quite fast. Most of the parsing happens via a - single call to a single, short, regular expression. - -Rendering a context -------------------- - -.. method:: render(context) - -Once you have a compiled ``Template`` object, you can render a context -- or -multiple contexts -- with it. The ``Context`` class lives at -:class:`django.template.Context`, and the constructor takes two (optional) -arguments: - - * A dictionary mapping variable names to variable values. - - * The name of the current application. This application name is used - to help :ref:`resolve namespaced URLs<topics-http-reversing-url-namespaces>`. - If you're not using namespaced URLs, you can ignore this argument. - -Call the ``Template`` object's ``render()`` method with the context to "fill" the -template:: - - >>> from django.template import Context, Template - >>> t = Template("My name is {{ my_name }}.") - - >>> c = Context({"my_name": "Adrian"}) - >>> t.render(c) - "My name is Adrian." - - >>> c = Context({"my_name": "Dolores"}) - >>> t.render(c) - "My name is Dolores." - -Variable names must consist of any letter (A-Z), any digit (0-9), an underscore -or a dot. - -Dots have a special meaning in template rendering. A dot in a variable name -signifies **lookup**. Specifically, when the template system encounters a dot -in a variable name, it tries the following lookups, in this order: - - * Dictionary lookup. Example: ``foo["bar"]`` - * Attribute lookup. Example: ``foo.bar`` - * Method call. Example: ``foo.bar()`` - * List-index lookup. Example: ``foo[bar]`` - -The template system uses the first lookup type that works. It's short-circuit -logic. - -Here are a few examples:: - - >>> from django.template import Context, Template - >>> t = Template("My name is {{ person.first_name }}.") - >>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}} - >>> t.render(Context(d)) - "My name is Joe." - - >>> class PersonClass: pass - >>> p = PersonClass() - >>> p.first_name = "Ron" - >>> p.last_name = "Nasty" - >>> t.render(Context({"person": p})) - "My name is Ron." - - >>> class PersonClass2: - ... def first_name(self): - ... return "Samantha" - >>> p = PersonClass2() - >>> t.render(Context({"person": p})) - "My name is Samantha." - - >>> t = Template("The first stooge in the list is {{ stooges.0 }}.") - >>> c = Context({"stooges": ["Larry", "Curly", "Moe"]}) - >>> t.render(c) - "The first stooge in the list is Larry." - -Method lookups are slightly more complex than the other lookup types. Here are -some things to keep in mind: - - * If, during the method lookup, a method raises an exception, the exception - will be propagated, unless the exception has an attribute - ``silent_variable_failure`` whose value is ``True``. If the exception - *does* have a ``silent_variable_failure`` attribute, the variable will - render as an empty string. Example:: - - >>> t = Template("My name is {{ person.first_name }}.") - >>> class PersonClass3: - ... def first_name(self): - ... raise AssertionError, "foo" - >>> p = PersonClass3() - >>> t.render(Context({"person": p})) - Traceback (most recent call last): - ... - AssertionError: foo - - >>> class SilentAssertionError(Exception): - ... silent_variable_failure = True - >>> class PersonClass4: - ... def first_name(self): - ... raise SilentAssertionError - >>> p = PersonClass4() - >>> t.render(Context({"person": p})) - "My name is ." - - Note that :exc:`django.core.exceptions.ObjectDoesNotExist`, which is the - base class for all Django database API ``DoesNotExist`` exceptions, has - ``silent_variable_failure = True``. So if you're using Django templates - with Django model objects, any ``DoesNotExist`` exception will fail - silently. - - * A method call will only work if the method has no required arguments. - Otherwise, the system will move to the next lookup type (list-index - lookup). - - * Obviously, some methods have side effects, and it'd be either foolish or - a security hole to allow the template system to access them. - - A good example is the :meth:`~django.db.models.Model.delete` method on - each Django model object. The template system shouldn't be allowed to do - something like this:: - - I will now delete this valuable data. {{ data.delete }} - - To prevent this, set a function attribute ``alters_data`` on the method. - The template system won't execute a method if the method has - ``alters_data=True`` set. The dynamically-generated - :meth:`~django.db.models.Model.delete` and - :meth:`~django.db.models.Model.save` methods on Django model objects get - ``alters_data=True`` automatically. Example:: - - def sensitive_function(self): - self.database_record.delete() - sensitive_function.alters_data = True - -.. _invalid-template-variables: - -How invalid variables are handled -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Generally, if a variable doesn't exist, the template system inserts the -value of the :setting:`TEMPLATE_STRING_IF_INVALID` setting, which is set to -``''`` (the empty string) by default. - -Filters that are applied to an invalid variable will only be applied if -:setting:`TEMPLATE_STRING_IF_INVALID` is set to ``''`` (the empty string). If -:setting:`TEMPLATE_STRING_IF_INVALID` is set to any other value, variable -filters will be ignored. - -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 :setting:`TEMPLATE_STRING_IF_INVALID` contains a ``'%s'``, the format marker will -be replaced with the name of the invalid variable. - -.. admonition:: For debug purposes only! - - While :setting:`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 - :setting:`TEMPLATE_STRING_IF_INVALID`, you will experience rendering - problems with these templates and sites. - - Generally, :setting:`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 ----------------------------- - -.. class:: django.template.Context - -Most of the time, you'll instantiate ``Context`` objects by passing in a -fully-populated dictionary to ``Context()``. But you can add and delete items -from a ``Context`` object once it's been instantiated, too, using standard -dictionary syntax:: - - >>> c = Context({"foo": "bar"}) - >>> c['foo'] - 'bar' - >>> del c['foo'] - >>> c['foo'] - '' - >>> c['newvariable'] = 'hello' - >>> c['newvariable'] - 'hello' - -.. method:: pop() -.. method:: push() -.. exception:: django.template.ContextPopException - -A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it. -If you ``pop()`` too much, it'll raise -``django.template.ContextPopException``:: - - >>> c = Context() - >>> c['foo'] = 'first level' - >>> c.push() - >>> c['foo'] = 'second level' - >>> c['foo'] - 'second level' - >>> c.pop() - >>> c['foo'] - 'first level' - >>> c['foo'] = 'overwritten' - >>> c['foo'] - 'overwritten' - >>> c.pop() - Traceback (most recent call last): - ... - django.template.ContextPopException - -.. method:: update(other_dict) - -In addition to ``push()`` and ``pop()``, the ``Context`` -object also defines an ``update()`` method. This works like ``push()`` -but takes a dictionary as an argument and pushes that dictionary onto -the stack instead of an empty one. - - >>> c = Context() - >>> c['foo'] = 'first level' - >>> c.update({'foo': 'updated'}) - {'foo': 'updated'} - >>> c['foo'] - 'updated' - >>> c.pop() - {'foo': 'updated'} - >>> c['foo'] - 'first level' - -Using a ``Context`` as a stack comes in handy in some custom template tags, as -you'll see below. - -.. _subclassing-context-requestcontext: - -Subclassing Context: RequestContext ------------------------------------ - -Django comes with a special ``Context`` class, -``django.template.RequestContext``, that acts slightly differently than the -normal ``django.template.Context``. The first difference is that it takes an -:class:`~django.http.HttpRequest` as its first argument. For example:: - - c = RequestContext(request, { - 'foo': 'bar', - }) - -The second difference is that it automatically populates the context with a few -variables, according to your :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. - -The :setting:`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, -:setting:`TEMPLATE_CONTEXT_PROCESSORS` is set to:: - - ("django.contrib.auth.context_processors.auth", - "django.core.context_processors.debug", - "django.core.context_processors.i18n", - "django.core.context_processors.media", - "django.contrib.messages.context_processors.messages") - -.. versionadded:: 1.2 - In addition to these, ``RequestContext`` always uses - ``django.core.context_processors.csrf``. This is a security - related context processor required by the admin and other contrib apps, and, - in case of accidental misconfiguration, it is deliberately hardcoded in and - cannot be turned off by the :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. - -.. versionadded:: 1.2 - The ``'messages'`` context processor was added. For more information, see - the :doc:`messages documentation </ref/contrib/messages>`. - -.. versionchanged:: 1.2 - The auth context processor was moved in this release from its old location - ``django.core.context_processors.auth`` to - ``django.contrib.auth.context_processors.auth``. - -Each processor is applied in order. That means, if one processor adds a -variable to the context and a second processor adds a variable with the same -name, the second will override the first. The default processors are explained -below. - -.. admonition:: When context processors are applied - - When you use ``RequestContext``, the variables you supply directly - are added first, followed any variables supplied by context - processors. This means that a context processor may overwrite a - variable you've supplied, so take care to avoid variable names - which overlap with those supplied by your context processors. - -Also, you can give ``RequestContext`` a list of additional processors, using the -optional, third positional argument, ``processors``. In this example, the -``RequestContext`` instance gets a ``ip_address`` variable:: - - def ip_address_processor(request): - return {'ip_address': request.META['REMOTE_ADDR']} - - def some_view(request): - # ... - c = RequestContext(request, { - 'foo': 'bar', - }, [ip_address_processor]) - return HttpResponse(t.render(c)) - -.. 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: - -django.contrib.auth.context_processors.auth -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every -``RequestContext`` will contain these three variables: - - * ``user`` -- An ``auth.User`` instance representing the currently - logged-in user (or an ``AnonymousUser`` instance, if the client isn't - logged in). - - * ``messages`` -- A list of messages (as strings) that have been set - via the :doc:`messages framework </ref/contrib/messages>`. - - * ``perms`` -- An instance of - ``django.core.context_processors.PermWrapper``, representing the - permissions that the currently logged-in user has. - -.. versionchanged:: 1.2 - This context processor was moved in this release from - ``django.core.context_processors.auth`` to its current location. - -.. versionchanged:: 1.2 - Prior to version 1.2, the ``messages`` variable was a lazy accessor for - ``user.get_and_delete_messages()``. It has been changed to include any - messages added via the :doc:`messages framework </ref/contrib/messages>`. - -django.core.context_processors.debug -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every -``RequestContext`` will contain these two variables -- but only if your -:setting:`DEBUG` setting is set to ``True`` and the request's IP address -(``request.META['REMOTE_ADDR']``) is in the :setting:`INTERNAL_IPS` setting: - - * ``debug`` -- ``True``. You can use this in templates to test whether - you're in :setting:`DEBUG` mode. - * ``sql_queries`` -- A list of ``{'sql': ..., 'time': ...}`` dictionaries, - representing every SQL query that has happened so far during the request - and how long it took. The list is in order by query. - -django.core.context_processors.i18n -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every -``RequestContext`` will contain these two variables: - - * ``LANGUAGES`` -- The value of the :setting:`LANGUAGES` setting. - * ``LANGUAGE_CODE`` -- ``request.LANGUAGE_CODE``, if it exists. Otherwise, - the value of the :setting:`LANGUAGE_CODE` setting. - -See :doc:`/topics/i18n/index` for more. - -django.core.context_processors.media -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every -``RequestContext`` will contain a variable ``MEDIA_URL``, providing the -value of the :setting:`MEDIA_URL` setting. - -django.core.context_processors.csrf -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 1.2 - -This processor adds a token that is needed by the ``csrf_token`` template tag -for protection against :doc:`Cross Site Request Forgeries </ref/contrib/csrf>`. - -django.core.context_processors.request -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every -``RequestContext`` will contain a variable ``request``, which is the current -:class:`~django.http.HttpRequest`. Note that this processor is not enabled by default; -you'll have to activate it. - -django.contrib.messages.context_processors.messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If :setting:`TEMPLATE_CONTEXT_PROCESSORS` contains this processor, every -``RequestContext`` will contain a single additional variable: - - * ``messages`` -- A list of messages (as strings) that have been set - via the user model (using ``user.message_set.create``) or through - the :doc:`messages framework </ref/contrib/messages>`. - -.. versionadded:: 1.2 - This template context variable was previously supplied by the ``'auth'`` - context processor. For backwards compatibility the ``'auth'`` context - processor will continue to supply the ``messages`` variable until Django - 1.4. If you use the ``messages`` variable, your project will work with - either (or both) context processors, but it is recommended to add - ``django.contrib.messages.context_processors.messages`` so your project - will be prepared for the future upgrade. - -Writing your own context processors -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A context processor has a very simple interface: It's just a Python function -that takes one argument, an :class:`~django.http.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 -:setting:`TEMPLATE_CONTEXT_PROCESSORS` setting. - -Loading templates ------------------ - -Generally, you'll store templates in files on your filesystem rather than using -the low-level ``Template`` API yourself. Save templates in a directory -specified as a **template directory**. - -Django searches for template directories in a number of places, depending on -your template-loader settings (see "Loader types" below), but the most basic -way of specifying template directories is by using the :setting:`TEMPLATE_DIRS` -setting. - -The TEMPLATE_DIRS setting -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tell Django what your template directories are by using the -:setting:`TEMPLATE_DIRS` setting in your settings file. This should be set to a -list or tuple of strings that contain full paths to your template -directory(ies). Example:: - - TEMPLATE_DIRS = ( - "/home/html/templates/lawrence.com", - "/home/html/templates/default", - ) - -Your templates can go anywhere you want, as long as the directories and -templates are readable by the Web server. They can have any extension you want, -such as ``.html`` or ``.txt``, or they can have no extension at all. - -Note that these paths should use Unix-style forward slashes, even on Windows. - -.. _ref-templates-api-the-python-api: - -The Python API -~~~~~~~~~~~~~~ - -Django has two ways to load templates from files: - -.. function:: django.template.loader.get_template(template_name) - - ``get_template`` returns the compiled template (a ``Template`` object) for - the template with the given name. If the template doesn't exist, it raises - ``django.template.TemplateDoesNotExist``. - -.. function:: django.template.loader.select_template(template_name_list) - - ``select_template`` is just like ``get_template``, except it takes a list - of template names. Of the list, it returns the first template that exists. - -For example, if you call ``get_template('story_detail.html')`` and have the -above :setting:`TEMPLATE_DIRS` setting, here are the files Django will look for, -in order: - - * ``/home/html/templates/lawrence.com/story_detail.html`` - * ``/home/html/templates/default/story_detail.html`` - -If you call ``select_template(['story_253_detail.html', 'story_detail.html'])``, -here's what Django will look for: - - * ``/home/html/templates/lawrence.com/story_253_detail.html`` - * ``/home/html/templates/default/story_253_detail.html`` - * ``/home/html/templates/lawrence.com/story_detail.html`` - * ``/home/html/templates/default/story_detail.html`` - -When Django finds a template that exists, it stops looking. - -.. admonition:: Tip - - You can use ``select_template()`` for super-flexible "templatability." For - example, if you've written a news story and want some stories to have - custom templates, use something like - ``select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])``. - That'll allow you to use a custom template for an individual story, with a - fallback template for stories that don't have custom templates. - -Using subdirectories -~~~~~~~~~~~~~~~~~~~~ - -It's possible -- and preferable -- to organize templates in subdirectories of -the template directory. The convention is to make a subdirectory for each -Django app, with subdirectories within those subdirectories as needed. - -Do this for your own sanity. Storing all templates in the root level of a -single directory gets messy. - -To load a template that's within a subdirectory, just use a slash, like so:: - - get_template('news/story_detail.html') - -Using the same :setting:`TEMPLATE_DIRS` setting from above, this example -``get_template()`` call will attempt to load the following templates: - - * ``/home/html/templates/lawrence.com/news/story_detail.html`` - * ``/home/html/templates/default/news/story_detail.html`` - -.. _template-loaders: - -Loader types -~~~~~~~~~~~~ - -By default, Django uses a filesystem-based template loader, but Django comes -with a few other template loaders, which know how to load templates from other -sources. - -Some of these other loaders are disabled by default, but you can activate them -by editing your :setting:`TEMPLATE_LOADERS` setting. :setting:`TEMPLATE_LOADERS` -should be a tuple of strings, where each string represents a template loader. -Here are the template loaders that come with Django: - -``django.template.loaders.filesystem.Loader`` - Loads templates from the filesystem, according to :setting:`TEMPLATE_DIRS`. - This loader is enabled by default. - -``django.template.loaders.app_directories.Loader`` - Loads templates from Django apps on the filesystem. For each app in - :setting:`INSTALLED_APPS`, the loader looks for a ``templates`` - subdirectory. If the directory exists, Django looks for templates in there. - - This means you can store templates with your individual apps. This also - makes it easy to distribute Django apps with default templates. - - For example, for this setting:: - - INSTALLED_APPS = ('myproject.polls', 'myproject.music') - - ...then ``get_template('foo.html')`` will look for templates in these - directories, in this order: - - * ``/path/to/myproject/polls/templates/foo.html`` - * ``/path/to/myproject/music/templates/foo.html`` - - Note that the loader performs an optimization when it is first imported: It - caches a list of which :setting:`INSTALLED_APPS` packages have a - ``templates`` subdirectory. - - This loader is enabled by default. - -``django.template.loaders.eggs.Loader`` - Just like ``app_directories`` above, but it loads templates from Python - eggs rather than from the filesystem. - - This loader is disabled by default. - -``django.template.loaders.cached.Loader`` - By default, the templating system will read and compile your templates every - time they need to be rendered. While the Django templating system is quite - fast, the overhead from reading and compiling templates can add up. - - The cached template loader is a class-based loader that you configure with - a list of other loaders that it should wrap. The wrapped loaders are used to - locate unknown templates when they are first encountered. The cached loader - then stores the compiled ``Template`` in memory. The cached ``Template`` - instance is returned for subsequent requests to load the same template. - - For example, to enable template caching with the ``filesystem`` and - ``app_directories`` template loaders you might use the following settings:: - - TEMPLATE_LOADERS = ( - ('django.template.loaders.cached.Loader', ( - 'django.template.loaders.filesystem.Loader', - 'django.template.loaders.app_directories.Loader', - )), - ) - - .. note:: - All of the built-in Django template tags are safe to use with the cached - loader, but if you're using custom template tags that come from third - party packages, or that you wrote yourself, you should ensure that the - ``Node`` implementation for each tag is thread-safe. For more - information, see - :ref:`template tag thread safety considerations<template_tag_thread_safety>`. - - This loader is disabled by default. - -Django uses the template loaders in order according to the -:setting:`TEMPLATE_LOADERS` setting. It uses each loader until a loader finds a -match. - -The ``render_to_string`` shortcut -=================================== - -.. function:: django.template.loader.render_to_string(template_name, dictionary=None, context_instance=None) - -To cut down on the repetitive nature of loading and rendering -templates, Django provides a shortcut function which largely -automates the process: ``render_to_string()`` in -:mod:`django.template.loader`, which loads a template, renders it and -returns the resulting string:: - - from django.template.loader import render_to_string - rendered = render_to_string('my_template.html', { 'foo': 'bar' }) - -The ``render_to_string`` shortcut takes one required argument -- -``template_name``, which should be the name of the template to load -and render (or a list of template names, in which case Django will use -the first template in the list that exists) -- and two optional arguments: - - dictionary - A dictionary to be used as variables and values for the - template's context. This can also be passed as the second - positional argument. - - context_instance - An instance of ``Context`` or a subclass (e.g., an instance of - ``RequestContext``) to use as the template's context. This can - also be passed as the third positional argument. - -See also the :func:`~django.shortcuts.render_to_response()` shortcut, which -calls ``render_to_string`` and feeds the result into an :class:`~django.http.HttpResponse` -suitable for returning directly from a view. - -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're using the - template system as part of a Django application, nothing here applies to - you. - -Normally, Django will load all the configuration information it needs from its -own default configuration file, combined with the settings in the module given -in the :envvar:`DJANGO_SETTINGS_MODULE` environment variable. But if you're -using the template system independently of the rest of Django, the environment -variable approach isn't very convenient, because you probably want to configure -the template system in line with the rest of your application rather than -dealing with settings files and pointing to them via environment variables. - -To solve this problem, you need to use the manual configuration option described -in :ref:`settings-without-django-settings-module`. Simply import the appropriate -pieces of the templating system and then, *before* you call any of the -templating functions, call :func:`django.conf.settings.configure()` with any -settings you wish to specify. You might want to consider setting at least -:setting:`TEMPLATE_DIRS` (if you're going to use template loaders), -:setting:`DEFAULT_CHARSET` (although the default of ``utf-8`` is probably fine) -and :setting:`TEMPLATE_DEBUG`. All available settings are described in the -:doc:`settings documentation </ref/settings>`, and any setting starting with -``TEMPLATE_`` is of obvious interest. - -.. _topic-template-alternate-language: - -Using an alternative template language -====================================== - -.. versionadded:: 1.2 - -The Django ``Template`` and ``Loader`` classes implement a simple API for -loading and rendering templates. By providing some simple wrapper classes that -implement this API we can use third party template systems like `Jinja2 -<http://jinja.pocoo.org/2/>`_ or `Cheetah <http://www.cheetahtemplate.org/>`_. This -allows us to use third-party template libraries without giving up useful Django -features like the Django ``Context`` object and handy shortcuts like -``render_to_response()``. - -The core component of the Django templating system is the ``Template`` class. -This class has a very simple interface: it has a constructor that takes a single -positional argument specifying the template string, and a ``render()`` method -that takes a :class:`~django.template.Context` object and returns a string -containing the rendered response. - -Suppose we're using a template language that defines a ``Template`` object with -a ``render()`` method that takes a dictionary rather than a ``Context`` object. -We can write a simple wrapper that implements the Django ``Template`` interface:: - - import some_template_language - class Template(some_template_language.Template): - def render(self, context): - # flatten the Django Context into a single dictionary. - context_dict = {} - for d in context.dicts: - context_dict.update(d) - return super(Template, self).render(context_dict) - -That's all that's required to make our fictional ``Template`` class compatible -with the Django loading and rendering system! - -The next step is to write a ``Loader`` class that returns instances of our custom -template class instead of the default :class:`~django.template.Template`. Custom ``Loader`` -classes should inherit from ``django.template.loader.BaseLoader`` and override -the ``load_template_source()`` method, which takes a ``template_name`` argument, -loads the template from disk (or elsewhere), and returns a tuple: -``(template_string, template_origin)``. - -The ``load_template()`` method of the ``Loader`` class retrieves the template -string by calling ``load_template_source()``, instantiates a ``Template`` from -the template source, and returns a tuple: ``(template, template_origin)``. Since -this is the method that actually instantiates the ``Template``, we'll need to -override it to use our custom template class instead. We can inherit from the -builtin :class:`django.template.loaders.app_directories.Loader` to take advantage -of the ``load_template_source()`` method implemented there:: - - from django.template.loaders import app_directories - class Loader(app_directories.Loader): - is_usable = True - - def load_template(self, template_name, template_dirs=None): - source, origin = self.load_template_source(template_name, template_dirs) - template = Template(source) - return template, origin - -Finally, we need to modify our project settings, telling Django to use our custom -loader. Now we can write all of our templates in our alternative template -language while continuing to use the rest of the Django templating system. diff --git a/parts/django/docs/ref/templates/builtins.txt b/parts/django/docs/ref/templates/builtins.txt deleted file mode 100644 index 44bbc37..0000000 --- a/parts/django/docs/ref/templates/builtins.txt +++ /dev/null @@ -1,2107 +0,0 @@ -================================== -Built-in template tags and filters -================================== - -This document describes Django's built-in template tags and filters. It is -recommended that you use the :doc:`automatic documentation -</ref/contrib/admin/admindocs>`, if available, as this will also include -documentation for any custom tags or filters installed. - -.. _ref-templates-builtins-tags: - -Built-in tag reference ----------------------- - -.. highlightlang:: html+django - -.. templatetag:: autoescape - -autoescape -~~~~~~~~~~ - -.. versionadded:: 1.0 - -Control the current auto-escaping behavior. This tag takes either ``on`` or -``off`` as an argument and that determines whether auto-escaping is in effect -inside the block. The block is closed with an ``endautoescape`` ending tag. - -When auto-escaping is in effect, all variable content has HTML escaping applied -to it before placing the result into the output (but after any filters have -been applied). This is equivalent to manually applying the ``escape`` filter -to each variable. - -The only exceptions are variables that are already marked as "safe" from -escaping, either by the code that populated the variable, or because it has had -the ``safe`` or ``escape`` filters applied. - -Sample usage:: - - {% autoescape on %} - {{ body }} - {% endautoescape %} - -.. templatetag:: block - -block -~~~~~ - -Define a block that can be overridden by child templates. See -:ref:`Template inheritance <template-inheritance>` for more information. - -.. templatetag:: comment - -comment -~~~~~~~ - -Ignore everything between ``{% comment %}`` and ``{% endcomment %}`` - -.. templatetag:: csrf_token - -csrf_token -~~~~~~~~~~ - -.. versionadded:: 1.1.2 - -In the Django 1.1.X series, this is a no-op tag that returns an empty string for -future compatibility purposes. In Django 1.2 and later, it is used for CSRF -protection, as described in the documentation for :doc:`Cross Site Request -Forgeries </ref/contrib/csrf>`. - -.. templatetag:: cycle - -cycle -~~~~~ - -.. versionchanged:: 1.0 - Cycle among the given strings or variables each time this tag is encountered. - -Within a loop, cycles among the given strings each time through the -loop:: - - {% for o in some_list %} - <tr class="{% cycle 'row1' 'row2' %}"> - ... - </tr> - {% endfor %} - -You can use variables, too. For example, if you have two template variables, -``rowvalue1`` and ``rowvalue2``, you can cycle between their values like this:: - - {% for o in some_list %} - <tr class="{% cycle rowvalue1 rowvalue2 %}"> - ... - </tr> - {% endfor %} - -Yes, you can mix variables and strings:: - - {% for o in some_list %} - <tr class="{% cycle 'row1' rowvalue2 'row3' %}"> - ... - </tr> - {% endfor %} - -In some cases you might want to refer to the next value of a cycle from -outside of a loop. To do this, just give the ``{% cycle %}`` tag a name, using -"as", like this:: - - {% cycle 'row1' 'row2' as rowcolors %} - -From then on, you can insert the current value of the cycle wherever you'd like -in your template:: - - <tr class="{% cycle rowcolors %}">...</tr> - <tr class="{% cycle rowcolors %}">...</tr> - -You can use any number of values in a ``{% cycle %}`` tag, separated by spaces. -Values enclosed in single (``'``) or double quotes (``"``) are treated as -string literals, while values without quotes are treated as template variables. - -Note that the variables included in the cycle will not be escaped. -This is because template tags do not escape their content. Any HTML or -Javascript code contained in the printed variable will be rendered -as-is, which could potentially lead to security issues. - -If you need to escape the variables in the cycle, you must do so -explicitly:: - - {% filter force_escape %} - {% cycle var1 var2 var3 %} - {% endfilter %} - -For backwards compatibility, the ``{% cycle %}`` tag supports the much inferior -old syntax from previous Django versions. You shouldn't use this in any new -projects, but for the sake of the people who are still using it, here's what it -looks like:: - - {% cycle row1,row2,row3 %} - -In this syntax, each value gets interpreted as a literal string, and there's no -way to specify variable values. Or literal commas. Or spaces. Did we mention -you shouldn't use this syntax in any new projects? - -.. templatetag:: debug - -debug -~~~~~ - -Output a whole load of debugging information, including the current context and -imported modules. - -.. templatetag:: extends - -extends -~~~~~~~ - -Signal that this template extends a parent template. - -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 :ref:`template-inheritance` for more information. - -.. templatetag:: filter - -filter -~~~~~~ - -Filter the contents of the variable through variable filters. - -Filters can also be piped through each other, and they can have arguments -- -just like in variable syntax. - -Sample usage:: - - {% filter force_escape|lower %} - This text will be HTML-escaped, and will appear in all lowercase. - {% endfilter %} - -.. templatetag:: firstof - -firstof -~~~~~~~ - -Outputs the first variable passed that is not False, without escaping. - -Outputs nothing if all the passed variables are False. - -Sample usage:: - - {% firstof var1 var2 var3 %} - -This is equivalent to:: - - {% if var1 %} - {{ var1|safe }} - {% else %}{% if var2 %} - {{ var2|safe }} - {% else %}{% if var3 %} - {{ var3|safe }} - {% endif %}{% endif %}{% endif %} - -You can also use a literal string as a fallback value in case all -passed variables are False:: - - {% firstof var1 var2 var3 "fallback value" %} - -Note that the variables included in the firstof tag will not be -escaped. This is because template tags do not escape their content. -Any HTML or Javascript code contained in the printed variable will be -rendered as-is, which could potentially lead to security issues. - -If you need to escape the variables in the firstof tag, you must do so -explicitly:: - - {% filter force_escape %} - {% firstof var1 var2 var3 "fallback value" %} - {% endfilter %} - -.. templatetag:: for - -for -~~~ - -Loop over each item in an array. For example, to display a list of athletes -provided in ``athlete_list``:: - - <ul> - {% for athlete in athlete_list %} - <li>{{ athlete.name }}</li> - {% endfor %} - </ul> - -You can loop over a list in reverse by using ``{% for obj in list reversed %}``. - -.. versionadded:: 1.0 - -If you need to loop over a list of lists, you can unpack the values -in each sub-list into individual variables. For example, if your context -contains a list of (x,y) coordinates called ``points``, you could use the -following to output the list of points:: - - {% for x, y in points %} - There is a point at {{ x }},{{ y }} - {% endfor %} - -This can also be useful if you need to access the items in a dictionary. -For example, if your context contained a dictionary ``data``, the following -would display the keys and values of the dictionary:: - - {% for key, value in data.items %} - {{ key }}: {{ value }} - {% endfor %} - -The for loop sets a number of variables available within the loop: - - ========================== ================================================ - Variable Description - ========================== ================================================ - ``forloop.counter`` The current iteration of the loop (1-indexed) - ``forloop.counter0`` The current iteration of the loop (0-indexed) - ``forloop.revcounter`` The number of iterations from the end of the - loop (1-indexed) - ``forloop.revcounter0`` The number of iterations from the end of the - loop (0-indexed) - ``forloop.first`` True if this is the first time through the loop - ``forloop.last`` True if this is the last time through the loop - ``forloop.parentloop`` For nested loops, this is the loop "above" the - current one - ========================== ================================================ - -for ... empty -^^^^^^^^^^^^^ - -.. versionadded:: 1.1 - -The ``for`` tag can take an optional ``{% empty %}`` clause that will be -displayed if the given array is empty or could not be found:: - - <ul> - {% for athlete in athlete_list %} - <li>{{ athlete.name }}</li> - {% empty %} - <li>Sorry, no athlete in this list!</li> - {% endfor %} - <ul> - -The above is equivalent to -- but shorter, cleaner, and possibly faster -than -- the following:: - - <ul> - {% if athlete_list %} - {% for athlete in athlete_list %} - <li>{{ athlete.name }}</li> - {% endfor %} - {% else %} - <li>Sorry, no athletes in this list.</li> - {% endif %} - </ul> - -.. templatetag:: if - -if -~~ - -The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. -exists, is not empty, and is not a false boolean value) the contents of the -block are output:: - - {% if athlete_list %} - Number of athletes: {{ athlete_list|length }} - {% else %} - No athletes. - {% endif %} - -In the above, if ``athlete_list`` is not empty, the number of athletes will be -displayed by the ``{{ athlete_list|length }}`` variable. - -As you can see, the ``if`` tag can take an optional ``{% else %}`` clause that -will be displayed if the test fails. - -Boolean operators -^^^^^^^^^^^^^^^^^ - -``if`` tags may use ``and``, ``or`` or ``not`` to test a number of variables or -to negate a given variable:: - - {% if athlete_list and coach_list %} - Both athletes and coaches are available. - {% endif %} - - {% if not athlete_list %} - There are no athletes. - {% endif %} - - {% if athlete_list or coach_list %} - There are some athletes or some coaches. - {% endif %} - - {% if not athlete_list or coach_list %} - There are no athletes or there are some coaches (OK, so - writing English translations of boolean logic sounds - stupid; it's not our fault). - {% endif %} - - {% if athlete_list and not coach_list %} - There are some athletes and absolutely no coaches. - {% endif %} - -.. versionchanged:: 1.2 - -Use of both ``and`` and ``or`` clauses within the same tag is allowed, with -``and`` having higher precedence than ``or`` e.g.:: - - {% if athlete_list and coach_list or cheerleader_list %} - -will be interpreted like: - -.. code-block:: python - - if (athlete_list and coach_list) or cheerleader_list - -Use of actual brackets in the ``if`` tag is invalid syntax. If you need them to -indicate precedence, you should use nested ``if`` tags. - -.. versionadded:: 1.2 - - -``if`` tags may also use the operators ``==``, ``!=``, ``<``, ``>``, -``<=``, ``>=`` and ``in`` which work as follows: - - -``==`` operator -^^^^^^^^^^^^^^^ - -Equality. Example:: - - {% if somevar == "x" %} - This appears if variable somevar equals the string "x" - {% endif %} - -``!=`` operator -^^^^^^^^^^^^^^^ - -Inequality. Example:: - - {% if somevar != "x" %} - This appears if variable somevar does not equal the string "x", - or if somevar is not found in the context - {% endif %} - -``<`` operator -^^^^^^^^^^^^^^ - -Less than. Example:: - - {% if somevar < 100 %} - This appears if variable somevar is less than 100. - {% endif %} - -``>`` operator -^^^^^^^^^^^^^^ - -Greater than. Example:: - - {% if somevar > 0 %} - This appears if variable somevar is greater than 0. - {% endif %} - -``<=`` operator -^^^^^^^^^^^^^^^ - -Less than or equal to. Example:: - - {% if somevar <= 100 %} - This appears if variable somevar is less than 100 or equal to 100. - {% endif %} - -``>=`` operator -^^^^^^^^^^^^^^^ - -Greater than or equal to. Example:: - - {% if somevar >= 1 %} - This appears if variable somevar is greater than 1 or equal to 1. - {% endif %} - -``in`` operator -^^^^^^^^^^^^^^^ - -Contained within. This operator is supported by many Python containers to test -whether the given value is in the container. The following are some examples of -how ``x in y`` will be interpreted:: - - {% if "bc" in "abcdef" %} - This appears since "bc" is a substring of "abcdef" - {% endif %} - - {% if "hello" in greetings %} - If greetings is a list or set, one element of which is the string - "hello", this will appear. - {% endif %} - - {% if user in users %} - If users is a QuerySet, this will appear if user is an - instance that belongs to the QuerySet. - {% endif %} - -``not in`` operator -~~~~~~~~~~~~~~~~~~~~ - -Not contained within. This is the negation of the ``in`` operator. - - -The comparison operators cannot be 'chained' like in Python or in mathematical -notation. For example, instead of using:: - - {% if a > b > c %} (WRONG) - -you should use:: - - {% if a > b and b > c %} - - -Filters -^^^^^^^ - -You can also use filters in the ``if`` expression. For example:: - - {% if messages|length >= 100 %} - You have lots of messages today! - {% endif %} - -Complex expressions -^^^^^^^^^^^^^^^^^^^ - -All of the above can be combined to form complex expressions. For such -expressions, it can be important to know how the operators are grouped when the -expression is evaluated - that is, the precedence rules. The precedence of the -operators, from lowest to highest, is as follows: - - * ``or`` - * ``and`` - * ``not`` - * ``in`` - * ``==``, ``!=``, ``<``, ``>``,``<=``, ``>=`` - -(This follows Python exactly). So, for example, the following complex if tag: - - {% if a == b or c == d and e %} - -...will be interpreted as: - -.. code-block:: python - - (a == b) or ((c == d) and e) - -If you need different precedence, you will need to use nested if tags. Sometimes -that is better for clarity anyway, for the sake of those who do not know the -precedence rules. - - -.. templatetag:: ifchanged - -ifchanged -~~~~~~~~~ - -Check if a value has changed from the last iteration of a loop. - -The 'ifchanged' block tag is used within a loop. It has two possible uses. - -1. Checks its own rendered contents against its previous state and only - displays the content if it has changed. For example, this displays a list of - days, only displaying the month if it changes:: - - <h1>Archive for {{ year }}</h1> - - {% for date in days %} - {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{% endifchanged %} - <a href="{{ date|date:"M/d"|lower }}/">{{ date|date:"j" }}</a> - {% endfor %} - -2. If given a variable, check whether that variable has changed. For - example, the following shows the date every time it changes, but - only shows the hour if both the hour and the date has changed:: - - {% for date in days %} - {% ifchanged date.date %} {{ date.date }} {% endifchanged %} - {% ifchanged date.hour date.date %} - {{ date.hour }} - {% endifchanged %} - {% endfor %} - -The ``ifchanged`` tag can also take an optional ``{% else %}`` clause that -will be displayed if the value has not changed:: - - {% for match in matches %} - <div style="background-color: - {% ifchanged match.ballot_id %} - {% cycle "red" "blue" %} - {% else %} - grey - {% endifchanged %} - ">{{ match }}</div> - {% endfor %} - -.. templatetag:: ifequal - -ifequal -~~~~~~~ - -Output the contents of the block if the two arguments equal each other. - -Example:: - - {% ifequal user.id comment.user_id %} - ... - {% endifequal %} - -As in the ``{% if %}`` tag, an ``{% else %}`` clause is optional. - -The arguments can be hard-coded strings, so the following is valid:: - - {% ifequal user.username "adrian" %} - ... - {% 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`` -tag instead. - -.. versionadded:: 1.2 - An alternative to the ``ifequal`` tag is to use the :ttag:`if` tag and the ``==`` operator. - -.. templatetag:: ifnotequal - -ifnotequal -~~~~~~~~~~ - -Just like ``ifequal``, except it tests that the two arguments are not equal. - -.. versionadded:: 1.2 - An alternative to the ``ifnotequal`` tag is to use the :ttag:`if` tag and the ``!=`` operator. - -.. templatetag:: include - -include -~~~~~~~ - -Loads a template and renders it with the current context. This is a way of -"including" other templates within a template. - -The template name can either be a variable or a hard-coded (quoted) string, -in either single or double quotes. - -This example includes the contents of the template ``"foo/bar.html"``:: - - {% include "foo/bar.html" %} - -This example includes the contents of the template whose name is contained in -the variable ``template_name``:: - - {% include template_name %} - -An included template is rendered with the context of the template that's -including it. This example produces the output ``"Hello, John"``: - - * Context: variable ``person`` is set to ``"john"``. - * Template:: - - {% include "name_snippet.html" %} - - * The ``name_snippet.html`` template:: - - Hello, {{ person }} - -See also: ``{% ssi %}``. - -.. note:: - The :ttag:`include` tag should be considered as an implementation of - "render this subtemplate and include the HTML", not as "parse this - subtemplate and include its contents as if it were part of the parent". - This means that there is no shared state between included templates -- - each include is a completely independent rendering process. - -.. templatetag:: load - -load -~~~~ - -Load a custom template tag set. - -See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information. - -.. templatetag:: now - -now -~~~ - -Display the current date and/or time, according to the given string. - -Given format can be one of the predefined ones ``DATE_FORMAT``, -``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, -or a custom format, same as the :tfilter:`date` filter. Note that predefined -formats may vary depending on the current locale. - -Example:: - - It is {% now "jS F Y H:i" %} - -Note that you can backslash-escape a format string if you want to use the -"raw" value. In this example, "f" is backslash-escaped, because otherwise -"f" is a format string that displays the time. The "o" doesn't need to be -escaped, because it's not a format character:: - - It is the {% now "jS o\f F" %} - -This would display as "It is the 4th of September". - -.. templatetag:: regroup - -regroup -~~~~~~~ - -Regroup a list of alike objects by a common attribute. - -This complex tag is best illustrated by use of an example: say that ``people`` -is a list of people represented by dictionaries with ``first_name``, -``last_name``, and ``gender`` keys: - -.. code-block:: python - - people = [ - {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'}, - {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, - {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, - {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, - {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, - ] - -...and you'd like to display a hierarchical list that is ordered by gender, -like this: - - * Male: - * George Bush - * Bill Clinton - * Female: - * Margaret Thatcher - * Condoleezza Rice - * Unknown: - * Pat Smith - -You can use the ``{% regroup %}`` tag to group the list of people by gender. -The following snippet of template code would accomplish this:: - - {% regroup people by gender as gender_list %} - - <ul> - {% for gender in gender_list %} - <li>{{ gender.grouper }} - <ul> - {% for item in gender.list %} - <li>{{ item.first_name }} {{ item.last_name }}</li> - {% endfor %} - </ul> - </li> - {% endfor %} - </ul> - -Let's walk through this example. ``{% regroup %}`` takes three arguments: the -list you want to regroup, the attribute to group by, and the name of the -resulting list. Here, we're regrouping the ``people`` list by the ``gender`` -attribute and calling the result ``gender_list``. - -``{% regroup %}`` produces a list (in this case, ``gender_list``) of -**group objects**. Each group object has two attributes: - - * ``grouper`` -- the item that was grouped by (e.g., the string "Male" or - "Female"). - * ``list`` -- a list of all items in this group (e.g., a list of all people - with gender='Male'). - -Note that ``{% regroup %}`` does not order its input! Our example relies on -the fact that the ``people`` list was ordered by ``gender`` in the first place. -If the ``people`` list did *not* order its members by ``gender``, the regrouping -would naively display more than one group for a single gender. For example, -say the ``people`` list was set to this (note that the males are not grouped -together): - -.. code-block:: python - - people = [ - {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'}, - {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'}, - {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'}, - {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'}, - {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'}, - ] - -With this input for ``people``, the example ``{% regroup %}`` template code -above would result in the following output: - - * Male: - * Bill Clinton - * Unknown: - * Pat Smith - * Female: - * Margaret Thatcher - * Male: - * George Bush - * Female: - * Condoleezza Rice - -The easiest solution to this gotcha is to make sure in your view code that the -data is ordered according to how you want to display it. - -Another solution is to sort the data in the template using the ``dictsort`` -filter, if your data is in a list of dictionaries:: - - {% regroup people|dictsort:"gender" by gender as gender_list %} - -.. templatetag:: spaceless - -spaceless -~~~~~~~~~ - -Removes whitespace between HTML tags. This includes tab -characters and newlines. - -Example usage:: - - {% spaceless %} - <p> - <a href="foo/">Foo</a> - </p> - {% endspaceless %} - -This example would return this HTML:: - - <p><a href="foo/">Foo</a></p> - -Only space between *tags* is removed -- not space between tags and text. In -this example, the space around ``Hello`` won't be stripped:: - - {% spaceless %} - <strong> - Hello - </strong> - {% endspaceless %} - -.. templatetag:: ssi - -ssi -~~~ - -Output the contents of a given file into the page. - -Like a simple "include" tag, ``{% ssi %}`` includes the contents of another -file -- which must be specified using an absolute path -- in the current -page:: - - {% ssi /home/html/ljworld.com/includes/right_generic.html %} - -If the optional "parsed" parameter is given, the contents of the included -file are evaluated as template code, within the current context:: - - {% ssi /home/html/ljworld.com/includes/right_generic.html parsed %} - -Note that if you use ``{% ssi %}``, you'll need to define -:setting:`ALLOWED_INCLUDE_ROOTS` in your Django settings, as a security measure. - -See also: ``{% include %}``. - -.. templatetag:: templatetag - -templatetag -~~~~~~~~~~~ - -Output one of the syntax characters used to compose template tags. - -Since the template system has no concept of "escaping", to display one of the -bits used in template tags, you must use the ``{% templatetag %}`` tag. - -The argument tells which template bit to output: - - ================== ======= - Argument Outputs - ================== ======= - ``openblock`` ``{%`` - ``closeblock`` ``%}`` - ``openvariable`` ``{{`` - ``closevariable`` ``}}`` - ``openbrace`` ``{`` - ``closebrace`` ``}`` - ``opencomment`` ``{#`` - ``closecomment`` ``#}`` - ================== ======= - -.. templatetag:: url - -url -~~~ - -Returns an absolute path reference (a URL without the domain name) matching a -given view function and optional parameters. This is a way to output links -without violating the DRY principle by having to hard-code URLs in your -templates:: - - {% url path.to.some_view v1 v2 %} - -The first argument is a path to a view function in the format -``package.package.module.function``. Additional arguments are optional and -should be space-separated values that will be used as arguments in the URL. -The example above shows passing positional arguments. Alternatively you may -use keyword syntax:: - - {% url path.to.some_view arg1=v1 arg2=v2 %} - -Do not mix both positional and keyword syntax in a single call. All arguments -required by the URLconf should be present. - -For example, suppose you have a view, ``app_views.client``, whose URLconf -takes a client ID (here, ``client()`` is a method inside the views file -``app_views.py``). The URLconf line might look like this: - -.. code-block:: python - - ('^client/(\d+)/$', 'app_views.client') - -If this app's URLconf is included into the project's URLconf under a path -such as this: - -.. code-block:: python - - ('^clients/', include('project_name.app_name.urls')) - -...then, in a template, you can create a link to this view like this:: - - {% url app_views.client client.id %} - -The template tag will output the string ``/clients/client/123/``. - -.. versionadded:: 1.0 - -If you're using :ref:`named URL patterns <naming-url-patterns>`, you can -refer to the name of the pattern in the ``url`` tag instead of using the -path to the view. - -Note that if the URL you're reversing doesn't exist, you'll get an -:exc:`NoReverseMatch` exception raised, which will cause your site to display an -error page. - -.. versionadded:: 1.0 - -If you'd like to retrieve a URL without displaying it, you can use a slightly -different call:: - - - {% url path.to.view arg arg2 as the_url %} - - <a href="{{ the_url }}">I'm linking to {{ the_url }}</a> - -This ``{% url ... as var %}`` syntax will *not* cause an error if the view is -missing. In practice you'll use this to link to views that are optional:: - - {% url path.to.view as the_url %} - {% if the_url %} - <a href="{{ the_url }}">Link to optional stuff</a> - {% endif %} - -.. versionadded:: 1.1 - -If you'd like to retrieve a namespaced URL, specify the fully qualified name:: - - {% url myapp:view-name %} - -This will follow the normal :ref:`namespaced URL resolution strategy -<topics-http-reversing-url-namespaces>`, including using any hints provided -by the context as to the current application. - -.. versionchanged:: 1.2 - -For backwards compatibility, the ``{% url %}`` tag also supports the -use of commas to separate arguments. You shouldn't use this in any new -projects, but for the sake of the people who are still using it, -here's what it looks like:: - - {% url path.to.view arg,arg2 %} - {% url path.to.view arg, arg2 %} - -This syntax doesn't support the use of literal commas, or or equals -signs. Did we mention you shouldn't use this syntax in any new -projects? - -.. templatetag:: widthratio - -widthratio -~~~~~~~~~~ - -For creating bar charts and such, this tag calculates the ratio of a given value -to a maximum value, and then applies that ratio to a constant. - -For example:: - - <img src="bar.gif" height="10" width="{% widthratio this_value max_value 100 %}" /> - -Above, if ``this_value`` is 175 and ``max_value`` is 200, the image in the -above example will be 88 pixels wide (because 175/200 = .875; .875 * 100 = 87.5 -which is rounded up to 88). - -.. templatetag:: with - -with -~~~~ - -.. versionadded:: 1.0 - -Caches a complex variable under a simpler name. This is useful when accessing -an "expensive" method (e.g., one that hits the database) multiple times. - -For example:: - - {% with business.employees.count as total %} - {{ total }} employee{{ total|pluralize }} - {% endwith %} - -The populated variable (in the example above, ``total``) is only available -between the ``{% with %}`` and ``{% endwith %}`` tags. - -.. _ref-templates-builtins-filters: - -Built-in filter reference -------------------------- - -.. templatefilter:: add - -add -~~~ - -Adds the argument to the value. - -For example:: - - {{ value|add:"2" }} - -If ``value`` is ``4``, then the output will be ``6``. - -.. versionchanged:: 1.2 - The following behavior didn't exist in previous Django versions. - -This filter will first try to coerce both values to integers. If this fails, -it'll attempt to add the values together anyway. This will work on some data -types (strings, list, etc.) and fail on others. If it fails, the result will -be an empty string. - -For example, if we have:: - - {{ first|add:second }} - -and ``first`` is ``[1, 2, 3]`` and ``second`` is ``[4, 5, 6]``, then the -output will be ``[1, 2, 3, 4, 5, 6]``. - -.. warning:: - - Strings that can be coerced to integers will be **summed**, not - concatenated, as in the first example above. - -.. templatefilter:: addslashes - -addslashes -~~~~~~~~~~ - -Adds slashes before quotes. Useful for escaping strings in CSV, for example. - -For example:: - - {{ value|addslashes }} - -If ``value`` is ``"I'm using Django"``, the output will be ``"I\'m using Django"``. - -.. templatefilter:: capfirst - -capfirst -~~~~~~~~ - -Capitalizes the first character of the value. - -For example:: - - {{ value|capfirst }} - -If ``value`` is ``"django"``, the output will be ``"Django"``. - -.. templatefilter:: center - -center -~~~~~~ - -Centers the value in a field of a given width. - -For example:: - - "{{ value|center:"15" }}" - -If ``value`` is ``"Django"``, the output will be ``" Django "``. - -.. templatefilter:: cut - -cut -~~~ - -Removes all values of arg from the given string. - -For example:: - - {{ value|cut:" "}} - -If ``value`` is ``"String with spaces"``, the output will be ``"Stringwithspaces"``. - -.. templatefilter:: date - -date -~~~~ - -Formats a date according to the given format. - -Uses the same format as PHP's ``date()`` function (http://php.net/date) -with some custom extensions. - -Available format strings: - - ================ ======================================== ===================== - Format character Description Example output - ================ ======================================== ===================== - a ``'a.m.'`` or ``'p.m.'`` (Note that ``'a.m.'`` - this is slightly different than PHP's - output, because this includes periods - to match Associated Press style.) - A ``'AM'`` or ``'PM'``. ``'AM'`` - b Month, textual, 3 letters, lowercase. ``'jan'`` - B Not implemented. - c ISO 8601 Format. ``2008-01-02T10:30:00.000123`` - d Day of the month, 2 digits with ``'01'`` to ``'31'`` - leading zeros. - D Day of the week, textual, 3 letters. ``'Fri'`` - f Time, in 12-hour hours and minutes, ``'1'``, ``'1:30'`` - with minutes left off if they're zero. - Proprietary extension. - F Month, textual, long. ``'January'`` - g Hour, 12-hour format without leading ``'1'`` to ``'12'`` - zeros. - G Hour, 24-hour format without leading ``'0'`` to ``'23'`` - zeros. - h Hour, 12-hour format. ``'01'`` to ``'12'`` - H Hour, 24-hour format. ``'00'`` to ``'23'`` - i Minutes. ``'00'`` to ``'59'`` - I Not implemented. - j Day of the month without leading ``'1'`` to ``'31'`` - zeros. - l Day of the week, textual, long. ``'Friday'`` - L Boolean for whether it's a leap year. ``True`` or ``False`` - m Month, 2 digits with leading zeros. ``'01'`` to ``'12'`` - M Month, textual, 3 letters. ``'Jan'`` - n Month without leading zeros. ``'1'`` to ``'12'`` - N Month abbreviation in Associated Press ``'Jan.'``, ``'Feb.'``, ``'March'``, ``'May'`` - style. Proprietary extension. - O Difference to Greenwich time in hours. ``'+0200'`` - P Time, in 12-hour hours, minutes and ``'1 a.m.'``, ``'1:30 p.m.'``, ``'midnight'``, ``'noon'``, ``'12:30 p.m.'`` - 'a.m.'/'p.m.', with minutes left off - if they're zero and the special-case - strings 'midnight' and 'noon' if - appropriate. Proprietary extension. - r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` - s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` - S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` - month, 2 characters. - t Number of days in the given month. ``28`` to ``31`` - T Time zone of this machine. ``'EST'``, ``'MDT'`` - u Microseconds. ``0`` to ``999999`` - U Seconds since the Unix Epoch - (January 1 1970 00:00:00 UTC). - w Day of the week, digits without ``'0'`` (Sunday) to ``'6'`` (Saturday) - leading zeros. - W ISO-8601 week number of year, with ``1``, ``53`` - weeks starting on Monday. - y Year, 2 digits. ``'99'`` - Y Year, 4 digits. ``'1999'`` - z Day of the year. ``0`` to ``365`` - Z Time zone offset in seconds. The ``-43200`` to ``43200`` - offset for timezones west of UTC is - always negative, and for those east of - UTC is always positive. - ================ ======================================== ===================== - -.. versionadded:: 1.2 - -The ``c`` and ``u`` format specification characters were added in Django 1.2. - -For example:: - - {{ value|date:"D d M Y" }} - -If ``value`` is a ``datetime`` object (e.g., the result of -``datetime.datetime.now()``), the output will be the string -``'Wed 09 Jan 2008'``. - -The format passed can be one of the predefined ones ``DATE_FORMAT``, -``DATETIME_FORMAT``, ``SHORT_DATE_FORMAT`` or ``SHORT_DATETIME_FORMAT``, or a -custom format that uses the format specifiers shown in the table above. Note -that predefined formats may vary depending on the current locale. - -Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, -for example, ``"es"``, then for:: - - {{ value|date:"SHORT_DATE_FORMAT" }} - -the output would be the string ``"09/01/2008"`` (the ``"SHORT_DATE_FORMAT"`` -format specifier for the ``es`` locale as shipped with Django is ``"d/m/Y"``). - -When used without a format string:: - - {{ value|date }} - -...the formatting string defined in the :setting:`DATE_FORMAT` setting will be -used, without applying any localization. - -.. versionchanged:: 1.2 - Predefined formats can now be influenced by the current locale. - -.. templatefilter:: default - -default -~~~~~~~ - -If value evaluates to ``False``, use given default. Otherwise, use the value. - -For example:: - - {{ value|default:"nothing" }} - -If ``value`` is ``""`` (the empty string), the output will be ``nothing``. - -.. templatefilter:: default_if_none - -default_if_none -~~~~~~~~~~~~~~~ - -If (and only if) value is ``None``, use given default. Otherwise, use the -value. - -Note that if an empty string is given, the default value will *not* be used. -Use the ``default`` filter if you want to fallback for empty strings. - -For example:: - - {{ value|default_if_none:"nothing" }} - -If ``value`` is ``None``, the output will be the string ``"nothing"``. - -.. templatefilter:: dictsort - -dictsort -~~~~~~~~ - -Takes a list of dictionaries and returns that list sorted by the key given in -the argument. - -For example:: - - {{ value|dictsort:"name" }} - -If ``value`` is: - -.. code-block:: python - - [ - {'name': 'zed', 'age': 19}, - {'name': 'amy', 'age': 22}, - {'name': 'joe', 'age': 31}, - ] - -then the output would be: - -.. code-block:: python - - [ - {'name': 'amy', 'age': 22}, - {'name': 'joe', 'age': 31}, - {'name': 'zed', 'age': 19}, - ] - -.. templatefilter:: dictsortreversed - -dictsortreversed -~~~~~~~~~~~~~~~~ - -Takes a list of dictionaries and returns that list sorted in reverse order by -the key given in the argument. This works exactly the same as the above filter, -but the returned value will be in reverse order. - -.. templatefilter:: divisibleby - -divisibleby -~~~~~~~~~~~ - -Returns ``True`` if the value is divisible by the argument. - -For example:: - - {{ value|divisibleby:"3" }} - -If ``value`` is ``21``, the output would be ``True``. - -.. templatefilter:: escape - -escape -~~~~~~ - -Escapes a string's HTML. Specifically, it makes these replacements: - - * ``<`` is converted to ``<`` - * ``>`` is converted to ``>`` - * ``'`` (single quote) is converted to ``'`` - * ``"`` (double quote) is converted to ``"`` - * ``&`` is converted to ``&`` - -The escaping is only applied when the string is output, so it does not matter -where in a chained sequence of filters you put ``escape``: it will always be -applied as though it were the last filter. If you want escaping to be applied -immediately, use the ``force_escape`` filter. - -Applying ``escape`` to a variable that would normally have auto-escaping -applied to the result will only result in one round of escaping being done. So -it is safe to use this function even in auto-escaping environments. If you want -multiple escaping passes to be applied, use the ``force_escape`` filter. - -.. versionchanged:: 1.0 - Due to auto-escaping, the behavior of this filter has changed slightly. - The replacements are only made once, after - all other filters are applied -- including filters before and after it. - -.. templatefilter:: escapejs - -escapejs -~~~~~~~~ - -.. versionadded:: 1.0 - -Escapes characters for use in JavaScript strings. This does *not* make the -string safe for use in HTML, but does protect you from syntax errors when using -templates to generate JavaScript/JSON. - -For example:: - - {{ value|escapejs }} - -If ``value`` is ``"testing\r\njavascript \'string" <b>escaping</b>"``, -the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u003Cb\\u003Eescaping\\u003C/b\\u003E"``. - -.. templatefilter:: filesizeformat - -filesizeformat -~~~~~~~~~~~~~~ - -Format the value like a 'human-readable' file size (i.e. ``'13 KB'``, -``'4.1 MB'``, ``'102 bytes'``, etc). - -For example:: - - {{ value|filesizeformat }} - -If ``value`` is 123456789, the output would be ``117.7 MB``. - -.. templatefilter:: first - -first -~~~~~ - -Returns the first item in a list. - -For example:: - - {{ value|first }} - -If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``. - -.. templatefilter:: fix_ampersands - -fix_ampersands -~~~~~~~~~~~~~~ - -.. versionchanged:: 1.0 - This is rarely useful as ampersands are now automatically escaped. See escape_ for more information. - -Replaces ampersands with ``&`` entities. - -For example:: - - {{ value|fix_ampersands }} - -If ``value`` is ``Tom & Jerry``, the output will be ``Tom & Jerry``. - -.. templatefilter:: floatformat - -floatformat -~~~~~~~~~~~ - -When used without an argument, rounds a floating-point number to one decimal -place -- but only if there's a decimal part to be displayed. For example: - -============ =========================== ======== -``value`` Template Output -============ =========================== ======== -``34.23234`` ``{{ value|floatformat }}`` ``34.2`` -``34.00000`` ``{{ value|floatformat }}`` ``34`` -``34.26000`` ``{{ value|floatformat }}`` ``34.3`` -============ =========================== ======== - -If used with a numeric integer argument, ``floatformat`` rounds a number to -that many decimal places. For example: - -============ ============================= ========== -``value`` Template Output -============ ============================= ========== -``34.23234`` ``{{ value|floatformat:3 }}`` ``34.232`` -``34.00000`` ``{{ value|floatformat:3 }}`` ``34.000`` -``34.26000`` ``{{ value|floatformat:3 }}`` ``34.260`` -============ ============================= ========== - -If the argument passed to ``floatformat`` is negative, it will round a number -to that many decimal places -- but only if there's a decimal part to be -displayed. For example: - -============ ================================ ========== -``value`` Template Output -============ ================================ ========== -``34.23234`` ``{{ value|floatformat:"-3" }}`` ``34.232`` -``34.00000`` ``{{ value|floatformat:"-3" }}`` ``34`` -``34.26000`` ``{{ value|floatformat:"-3" }}`` ``34.260`` -============ ================================ ========== - -Using ``floatformat`` with no argument is equivalent to using ``floatformat`` -with an argument of ``-1``. - -.. templatefilter:: force_escape - -force_escape -~~~~~~~~~~~~ - -.. versionadded:: 1.0 - -Applies HTML escaping to a string (see the ``escape`` filter for details). -This filter is applied *immediately* and returns a new, escaped string. This -is useful in the rare cases where you need multiple escaping or want to apply -other filters to the escaped results. Normally, you want to use the ``escape`` -filter. - -.. templatefilter:: get_digit - -get_digit -~~~~~~~~~ - -Given a whole number, returns the requested digit, where 1 is the right-most -digit, 2 is the second-right-most digit, etc. Returns the original value for -invalid input (if input or argument is not an integer, or if argument is less -than 1). Otherwise, output is always an integer. - -For example:: - - {{ value|get_digit:"2" }} - -If ``value`` is ``123456789``, the output will be ``8``. - -.. templatefilter:: iriencode - -iriencode -~~~~~~~~~ - -Converts an IRI (Internationalized Resource Identifier) to a string that is -suitable for including in a URL. This is necessary if you're trying to use -strings containing non-ASCII characters in a URL. - -It's safe to use this filter on a string that has already gone through the -``urlencode`` filter. - -For example:: - - {{ value|iriencode }} - -If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&me=2"``. - -.. templatefilter:: join - -join -~~~~ - -Joins a list with a string, like Python's ``str.join(list)`` - -For example:: - - {{ value|join:" // " }} - -If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string -``"a // b // c"``. - -.. templatefilter:: last - -last -~~~~ - -.. versionadded:: 1.0 - -Returns the last item in a list. - -For example:: - - {{ value|last }} - -If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output will be the string -``"d"``. - -.. templatefilter:: length - -length -~~~~~~ - -Returns the length of the value. This works for both strings and lists. - -For example:: - - {{ value|length }} - -If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``4``. - -.. templatefilter:: length_is - -length_is -~~~~~~~~~ - -Returns ``True`` if the value's length is the argument, or ``False`` otherwise. - -For example:: - - {{ value|length_is:"4" }} - -If ``value`` is ``['a', 'b', 'c', 'd']``, the output will be ``True``. - -.. templatefilter:: linebreaks - -linebreaks -~~~~~~~~~~ - -Replaces line breaks in plain text with appropriate HTML; a single -newline becomes an HTML line break (``<br />``) and a new line -followed by a blank line becomes a paragraph break (``</p>``). - -For example:: - - {{ value|linebreaks }} - -If ``value`` is ``Joel\nis a slug``, the output will be ``<p>Joel<br />is a -slug</p>``. - -.. templatefilter:: linebreaksbr - -linebreaksbr -~~~~~~~~~~~~ - -Converts all newlines in a piece of plain text to HTML line breaks -(``<br />``). - -For example:: - - {{ value|linebreaksbr }} - -If ``value`` is ``Joel\nis a slug``, the output will be ``Joel<br />is a -slug``. - -.. templatefilter:: linenumbers - -linenumbers -~~~~~~~~~~~ - -Displays text with line numbers. - -For example:: - - {{ value|linenumbers }} - -If ``value`` is:: - - one - two - three - -the output will be:: - - 1. one - 2. two - 3. three - -.. templatefilter:: ljust - -ljust -~~~~~ - -Left-aligns the value in a field of a given width. - -**Argument:** field size - -For example:: - - "{{ value|ljust:"10" }}" - -If ``value`` is ``Django``, the output will be ``"Django "``. - -.. templatefilter:: lower - -lower -~~~~~ - -Converts a string into all lowercase. - -For example:: - - {{ value|lower }} - -If ``value`` is ``Still MAD At Yoko``, the output will be ``still mad at yoko``. - -.. templatefilter:: make_list - -make_list -~~~~~~~~~ - -Returns the value turned into a list. For an integer, it's a list of -digits. For a string, it's a list of characters. - -For example:: - - {{ value|make_list }} - -If ``value`` is the string ``"Joel"``, the output would be the list -``[u'J', u'o', u'e', u'l']``. If ``value`` is ``123``, the output will be the -list ``[1, 2, 3]``. - -.. templatefilter:: phone2numeric - -phone2numeric -~~~~~~~~~~~~~ - -Converts a phone number (possibly containing letters) to its numerical -equivalent. - -The input doesn't have to be a valid phone number. This will happily convert -any string. - -For example:: - - {{ value|phone2numeric }} - -If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``. - -.. templatefilter:: pluralize - -pluralize -~~~~~~~~~ - -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 }}. - -If ``num_messages`` is ``1``, the output will be ``You have 1 message.`` -If ``num_messages`` is ``2`` the output will be ``You have 2 messages.`` - -For words that require a suffix other than ``'s'``, you can provide an alternate -suffix as a parameter to the filter. - -Example:: - - You have {{ num_walruses }} walrus{{ num_walruses|pluralize:"es" }}. - -For words that don't pluralize by simple suffix, you can specify both a -singular and plural suffix, separated by a comma. - -Example:: - - You have {{ num_cherries }} cherr{{ num_cherries|pluralize:"y,ies" }}. - -.. templatefilter:: pprint - -pprint -~~~~~~ - -A wrapper around `pprint.pprint`__ -- for debugging, really. - -__ http://docs.python.org/library/pprint.html - -.. templatefilter:: random - -random -~~~~~~ - -Returns a random item from the given list. - -For example:: - - {{ value|random }} - -If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``. - -.. templatefilter:: removetags - -removetags -~~~~~~~~~~ - -Removes a space-separated list of [X]HTML tags from the output. - -For example:: - - {{ value|removetags:"b span"|safe }} - -If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"`` the -output will be ``"Joel <button>is</button> a slug"``. - -Note that this filter is case-sensitive. - -If ``value`` is ``"<B>Joel</B> <button>is</button> a <span>slug</span>"`` the -output will be ``"<B>Joel</B> <button>is</button> a slug"``. - -.. templatefilter:: rjust - -rjust -~~~~~ - -Right-aligns the value in a field of a given width. - -**Argument:** field size - -For example:: - - "{{ value|rjust:"10" }}" - -If ``value`` is ``Django``, the output will be ``" Django"``. - -.. templatefilter:: safe - -safe -~~~~ - -Marks a string as not requiring further HTML escaping prior to output. When -autoescaping is off, this filter has no effect. - -.. note:: - - If you are chaining filters, a filter applied after ``safe`` can - make the contents unsafe again. For example, the following code - prints the variable as is, unescaped: - - .. code-block:: html+django - - {{ var|safe|escape }} - -.. templatefilter:: safeseq - -safeseq -~~~~~~~ - -Applies the :tfilter:`safe` filter to each element of a sequence. Useful in -conjunction with other filters that operate on sequences, such as -:tfilter:`join`. For example:: - - {{ some_list|safeseq|join:", " }} - -You couldn't use the :tfilter:`safe` filter directly in this case, as it would -first convert the variable into a string, rather than working with the -individual elements of the sequence. - -.. templatefilter:: slice - -slice -~~~~~ - -Returns a slice of the list. - -Uses the same syntax as Python's list slicing. See -http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice -for an introduction. - -Example:: - - {{ some_list|slice:":2" }} - -If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``. - -.. templatefilter:: slugify - -slugify -~~~~~~~ - -Converts to lowercase, removes non-word characters (alphanumerics and -underscores) and converts spaces to hyphens. Also strips leading and trailing -whitespace. - -For example:: - - {{ value|slugify }} - -If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``. - -.. templatefilter:: stringformat - -stringformat -~~~~~~~~~~~~ - -Formats the variable according to the argument, a string formatting specifier. -This specifier uses Python string formatting syntax, with the exception that -the leading "%" is dropped. - -See http://docs.python.org/library/stdtypes.html#string-formatting-operations -for documentation of Python string formatting - -For example:: - - {{ value|stringformat:"s" }} - -If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is a slug"``. - -.. templatefilter:: striptags - -striptags -~~~~~~~~~ - -Strips all [X]HTML tags. - -For example:: - - {{ value|striptags }} - -If ``value`` is ``"<b>Joel</b> <button>is</button> a <span>slug</span>"``, the -output will be ``"Joel is a slug"``. - -.. templatefilter:: time - -time -~~~~ - -Formats a time according to the given format. - -Given format can be the predefined one ``TIME_FORMAT``, or a custom format, -same as the :tfilter:`date` filter. Note that the predefined format is locale- -dependant. - -The time filter will only accept parameters in the format string that relate -to the time of day, not the date (for obvious reasons). If you need to -format a date, use the :tfilter:`date` filter. - -For example:: - - {{ value|time:"H:i" }} - -If ``value`` is equivalent to ``datetime.datetime.now()``, the output will be -the string ``"01:23"``. - -Another example: - -Assuming that :setting:`USE_L10N` is ``True`` and :setting:`LANGUAGE_CODE` is, -for example, ``"de"``, then for:: - - {{ value|time:"TIME_FORMAT" }} - -the output will be the string ``"01:23:00"`` (The ``"TIME_FORMAT"`` format -specifier for the ``de`` locale as shipped with Django is ``"H:i:s"``). - -When used without a format string:: - - {{ value|time }} - -...the formatting string defined in the :setting:`TIME_FORMAT` setting will be -used, without applying any localization. - -.. versionchanged:: 1.2 - Predefined formats can now be influenced by the current locale. - -.. templatefilter:: timesince - -timesince -~~~~~~~~~ - -Formats a date as the time since that date (e.g., "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 instance for 08:00 on 1 June 2006, -then ``{{ blog_date|timesince:comment_date }}`` would return "8 hours". - -Comparing offset-naive and offset-aware datetimes will return an empty string. - -Minutes is the smallest unit used, and "0 minutes" will be returned for any -date that is in the future relative to the comparison point. - -.. templatefilter:: timeuntil - -timeuntil -~~~~~~~~~ - -Similar to ``timesince``, except that it measures the time from now until the -given date or datetime. For example, if today is 1 June 2006 and -``conference_date`` is a date instance holding 29 June 2006, then -``{{ conference_date|timeuntil }}`` will return "4 weeks". - -Takes an optional argument that is a variable containing the date to use as -the comparison point (instead of *now*). If ``from_date`` contains 22 June -2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "1 week". - -Comparing offset-naive and offset-aware datetimes will return an empty string. - -Minutes is the smallest unit used, and "0 minutes" will be returned for any -date that is in the past relative to the comparison point. - -.. templatefilter:: title - -title -~~~~~ - -Converts a string into titlecase. - -For example:: - - {{ value|title }} - -If ``value`` is ``"my first post"``, the output will be ``"My First Post"``. - -.. templatefilter:: truncatewords - -truncatewords -~~~~~~~~~~~~~ - -Truncates a string after a certain number of words. - -**Argument:** Number of words to truncate after - -For example:: - - {{ value|truncatewords:2 }} - -If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel is ..."``. - -Newlines within the string will be removed. - -.. templatefilter:: truncatewords_html - -truncatewords_html -~~~~~~~~~~~~~~~~~~ - -Similar to ``truncatewords``, except that it is aware of HTML tags. Any tags -that are opened in the string and not closed before the truncation point, are -closed immediately after the truncation. - -This is less efficient than ``truncatewords``, so should only be used when it -is being passed HTML text. - -For example:: - - {{ value|truncatewords_html:2 }} - -If ``value`` is ``"<p>Joel is a slug</p>"``, the output will be -``"<p>Joel is ...</p>"``. - -Newlines in the HTML content will be preserved. - -.. templatefilter:: unordered_list - -unordered_list -~~~~~~~~~~~~~~ - -Recursively takes a self-nested list and returns an HTML unordered list -- -WITHOUT opening and closing <ul> tags. - -.. versionchanged:: 1.0 - The format accepted by ``unordered_list`` has changed to be easier to understand. - -The list is assumed to be in the proper format. For example, if ``var`` contains -``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then -``{{ var|unordered_list }}`` would return:: - - <li>States - <ul> - <li>Kansas - <ul> - <li>Lawrence</li> - <li>Topeka</li> - </ul> - </li> - <li>Illinois</li> - </ul> - </li> - -Note: the previous more restrictive and verbose format is still supported: -``['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]]``, - -.. templatefilter:: upper - -upper -~~~~~ - -Converts a string into all uppercase. - -For example:: - - {{ value|upper }} - -If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``. - -.. templatefilter:: urlencode - -urlencode -~~~~~~~~~ - -Escapes a value for use in a URL. - -For example:: - - {{ value|urlencode }} - -If ``value`` is ``"http://www.example.org/foo?a=b&c=d"``, the output will be -``"http%3A//www.example.org/foo%3Fa%3Db%26c%3Dd"``. - -.. templatefilter:: urlize - -urlize -~~~~~~ - -Converts URLs in plain text into clickable links. - -Note that if ``urlize`` is applied to text that already contains HTML markup, -things won't work as expected. Apply this filter only to *plain* text. - -For example:: - - {{ value|urlize }} - -If ``value`` is ``"Check out www.djangoproject.com"``, the output will be -``"Check out <a -href="http://www.djangoproject.com">www.djangoproject.com</a>"``. - -.. templatefilter:: urlizetrunc - -urlizetrunc -~~~~~~~~~~~ - -Converts URLs into clickable links, truncating URLs longer than the given -character limit. - -As with urlize_, this filter should only be applied to *plain* text. - -**Argument:** Length to truncate URLs to - -For example:: - - {{ value|urlizetrunc:15 }} - -If ``value`` is ``"Check out www.djangoproject.com"``, the output would be -``'Check out <a -href="http://www.djangoproject.com">www.djangopr...</a>'``. - -.. templatefilter:: wordcount - -wordcount -~~~~~~~~~ - -Returns the number of words. - -For example:: - - {{ value|wordcount }} - -If ``value`` is ``"Joel is a slug"``, the output will be ``4``. - -.. templatefilter:: wordwrap - -wordwrap -~~~~~~~~ - -Wraps words at specified line length. - -**Argument:** number of characters at which to wrap the text - -For example:: - - {{ value|wordwrap:5 }} - -If ``value`` is ``Joel is a slug``, the output would be:: - - Joel - is a - slug - -.. templatefilter:: yesno - -yesno -~~~~~ - -Given a string mapping values for true, false and (optionally) None, -returns one of those strings according to the value: - -For example:: - - {{ value|yesno:"yeah,no,maybe" }} - -========== ====================== ================================== -Value Argument Outputs -========== ====================== ================================== -``True`` ``"yeah,no,maybe"`` ``yeah`` -``False`` ``"yeah,no,maybe"`` ``no`` -``None`` ``"yeah,no,maybe"`` ``maybe`` -``None`` ``"yeah,no"`` ``"no"`` (converts None to False - if no mapping for None is given) -========== ====================== ================================== - -Other tags and filter libraries -------------------------------- - -Django comes with a couple of other template-tag libraries that you have to -enable explicitly in your ``INSTALLED_APPS`` setting and enable in your -template with the ``{% load %}`` tag. - -django.contrib.humanize -~~~~~~~~~~~~~~~~~~~~~~~ - -A set of Django template filters useful for adding a "human touch" to data. See -:doc:`/ref/contrib/humanize`. - -django.contrib.markup -~~~~~~~~~~~~~~~~~~~~~ - -A collection of template filters that implement these common markup languages: - - * Textile - * Markdown - * reST (reStructuredText) - -See the :doc:`markup documentation </ref/contrib/markup>`. - -django.contrib.webdesign -~~~~~~~~~~~~~~~~~~~~~~~~ - -A collection of template tags that can be useful while designing a Web site, -such as a generator of Lorem Ipsum text. See :doc:`/ref/contrib/webdesign`. - -i18n -~~~~ - -Provides a couple of templatetags that allow specifying translatable text in -Django templates. It is slightly different from the libraries described -above because you don't need to add any application to the ``INSTALLED_APPS`` -setting but rather set :setting:`USE_I18N` to True, then loading it with -``{% load i18n %}``. See :ref:`specifying-translation-strings-in-template-code`. diff --git a/parts/django/docs/ref/templates/index.txt b/parts/django/docs/ref/templates/index.txt deleted file mode 100644 index 0aa4798..0000000 --- a/parts/django/docs/ref/templates/index.txt +++ /dev/null @@ -1,19 +0,0 @@ -========= -Templates -========= - -Django's template engine provides a powerful mini-language for defining the -user-facing layer of your application, encouraging a clean separation of -application and presentation logic. Templates can be maintained by anyone with -an understanding of HTML; no knowledge of Python is required. - -.. toctree:: - :maxdepth: 2 - - builtins - api - -.. seealso:: - - For information on writing your own custom tags and filters, see - :doc:`/howto/custom-template-tags`. diff --git a/parts/django/docs/ref/unicode.txt b/parts/django/docs/ref/unicode.txt deleted file mode 100644 index 8e110af..0000000 --- a/parts/django/docs/ref/unicode.txt +++ /dev/null @@ -1,362 +0,0 @@ -============ -Unicode data -============ - -.. versionadded:: 1.0 - -Django natively supports Unicode data everywhere. Providing your database can -somehow store the data, you can safely pass around Unicode strings to -templates, models and the database. - -This document tells you what you need to know if you're writing applications -that use data or templates that are encoded in something other than ASCII. - -Creating the database -===================== - -Make sure your database is configured to be able to store arbitrary string -data. Normally, this means giving it an encoding of UTF-8 or UTF-16. If you use -a more restrictive encoding -- for example, latin1 (iso8859-1) -- you won't be -able to store certain characters in the database, and information will be lost. - - * MySQL users, refer to the `MySQL manual`_ (section 9.1.3.2 for MySQL 5.1) - for details on how to set or alter the database character set encoding. - - * PostgreSQL users, refer to the `PostgreSQL manual`_ (section 21.2.2 in - PostgreSQL 8) for details on creating databases with the correct encoding. - - * SQLite users, there is nothing you need to do. SQLite always uses UTF-8 - for internal encoding. - -.. _MySQL manual: http://dev.mysql.com/doc/refman/5.1/en/charset-database.html -.. _PostgreSQL manual: http://www.postgresql.org/docs/8.2/static/multibyte.html#AEN24104 - -All of Django's database backends automatically convert Unicode strings into -the appropriate encoding for talking to the database. They also automatically -convert strings retrieved from the database into Python Unicode strings. You -don't even need to tell Django what encoding your database uses: that is -handled transparently. - -For more, see the section "The database API" below. - -General string handling -======================= - -Whenever you use strings with Django -- e.g., in database lookups, template -rendering or anywhere else -- you have two choices for encoding those strings. -You can use Unicode strings, or you can use normal strings (sometimes called -"bytestrings") that are encoded using UTF-8. - -.. admonition:: Warning - - A bytestring does not carry any information with it about its encoding. - For that reason, we have to make an assumption, and Django assumes that all - bytestrings are in UTF-8. - - If you pass a string to Django that has been encoded in some other format, - things will go wrong in interesting ways. Usually, Django will raise a - ``UnicodeDecodeError`` at some point. - -If your code only uses ASCII data, it's safe to use your normal strings, -passing them around at will, because ASCII is a subset of UTF-8. - -Don't be fooled into thinking that if your :setting:`DEFAULT_CHARSET` setting is set -to something other than ``'utf-8'`` you can use that other encoding in your -bytestrings! :setting:`DEFAULT_CHARSET` only applies to the strings generated as -the result of template rendering (and e-mail). Django will always assume UTF-8 -encoding for internal bytestrings. The reason for this is that the -:setting:`DEFAULT_CHARSET` setting is not actually under your control (if you are the -application developer). It's under the control of the person installing and -using your application -- and if that person chooses a different setting, your -code must still continue to work. Ergo, it cannot rely on that setting. - -In most cases when Django is dealing with strings, it will convert them to -Unicode strings before doing anything else. So, as a general rule, if you pass -in a bytestring, be prepared to receive a Unicode string back in the result. - -Translated strings ------------------- - -Aside from Unicode strings and bytestrings, there's a third type of string-like -object you may encounter when using Django. The framework's -internationalization features introduce the concept of a "lazy translation" -- -a string that has been marked as translated but whose actual translation result -isn't determined until the object is used in a string. This feature is useful -in cases where the translation locale is unknown until the string is used, even -though the string might have originally been created when the code was first -imported. - -Normally, you won't have to worry about lazy translations. Just be aware that -if you examine an object and it claims to be a -``django.utils.functional.__proxy__`` object, it is a lazy translation. -Calling ``unicode()`` with the lazy translation as the argument will generate a -Unicode string in the current locale. - -For more details about lazy translation objects, refer to the -:doc:`internationalization </topics/i18n/index>` documentation. - -Useful utility functions ------------------------- - -Because some string operations come up again and again, Django ships with a few -useful functions that should make working with Unicode and bytestring objects -a bit easier. - -Conversion functions -~~~~~~~~~~~~~~~~~~~~ - -The ``django.utils.encoding`` module contains a few functions that are handy -for converting back and forth between Unicode and bytestrings. - - * ``smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')`` - converts its input to a Unicode string. The ``encoding`` parameter - specifies the input encoding. (For example, Django uses this internally - when processing form input data, which might not be UTF-8 encoded.) The - ``strings_only`` parameter, if set to True, will result in Python - numbers, booleans and ``None`` not being converted to a string (they keep - their original types). The ``errors`` parameter takes any of the values - that are accepted by Python's ``unicode()`` function for its error - handling. - - If you pass ``smart_unicode()`` an object that has a ``__unicode__`` - method, it will use that method to do the conversion. - - * ``force_unicode(s, encoding='utf-8', strings_only=False, - errors='strict')`` is identical to ``smart_unicode()`` in almost all - cases. The difference is when the first argument is a :ref:`lazy - translation <lazy-translations>` instance. While ``smart_unicode()`` - preserves lazy translations, ``force_unicode()`` forces those objects to a - Unicode string (causing the translation to occur). Normally, you'll want - to use ``smart_unicode()``. However, ``force_unicode()`` is useful in - template tags and filters that absolutely *must* have a string to work - with, not just something that can be converted to a string. - - * ``smart_str(s, encoding='utf-8', strings_only=False, errors='strict')`` - is essentially the opposite of ``smart_unicode()``. It forces the first - argument to a bytestring. The ``strings_only`` parameter has the same - behavior as for ``smart_unicode()`` and ``force_unicode()``. This is - slightly different semantics from Python's builtin ``str()`` function, - but the difference is needed in a few places within Django's internals. - -Normally, you'll only need to use ``smart_unicode()``. Call it as early as -possible on any input data that might be either Unicode or a bytestring, and -from then on, you can treat the result as always being Unicode. - -URI and IRI handling -~~~~~~~~~~~~~~~~~~~~ - -Web frameworks have to deal with URLs (which are a type of IRI_). One -requirement of URLs is that they are encoded using only ASCII characters. -However, in an international environment, you might need to construct a -URL from an IRI_ -- very loosely speaking, a URI that can contain Unicode -characters. Quoting and converting an IRI to URI can be a little tricky, so -Django provides some assistance. - - * The function ``django.utils.encoding.iri_to_uri()`` implements the - conversion from IRI to URI as required by the specification (`RFC - 3987`_). - - * The functions ``django.utils.http.urlquote()`` and - ``django.utils.http.urlquote_plus()`` are versions of Python's standard - ``urllib.quote()`` and ``urllib.quote_plus()`` that work with non-ASCII - characters. (The data is converted to UTF-8 prior to encoding.) - -These two groups of functions have slightly different purposes, and it's -important to keep them straight. Normally, you would use ``urlquote()`` on the -individual portions of the IRI or URI path so that any reserved characters -such as '&' or '%' are correctly encoded. Then, you apply ``iri_to_uri()`` to -the full IRI and it converts any non-ASCII characters to the correct encoded -values. - -.. note:: - Technically, it isn't correct to say that ``iri_to_uri()`` implements the - full algorithm in the IRI specification. It doesn't (yet) perform the - international domain name encoding portion of the algorithm. - -The ``iri_to_uri()`` function will not change ASCII characters that are -otherwise permitted in a URL. So, for example, the character '%' is not -further encoded when passed to ``iri_to_uri()``. This means you can pass a -full URL to this function and it will not mess up the query string or anything -like that. - -An example might clarify things here:: - - >>> urlquote(u'Paris & Orléans') - u'Paris%20%26%20Orl%C3%A9ans' - >>> iri_to_uri(u'/favorites/François/%s' % urlquote(u'Paris & Orléans')) - '/favorites/Fran%C3%A7ois/Paris%20%26%20Orl%C3%A9ans' - -If you look carefully, you can see that the portion that was generated by -``urlquote()`` in the second example was not double-quoted when passed to -``iri_to_uri()``. This is a very important and useful feature. It means that -you can construct your IRI without worrying about whether it contains -non-ASCII characters and then, right at the end, call ``iri_to_uri()`` on the -result. - -The ``iri_to_uri()`` function is also idempotent, which means the following is -always true:: - - iri_to_uri(iri_to_uri(some_string)) = iri_to_uri(some_string) - -So you can safely call it multiple times on the same IRI without risking -double-quoting problems. - -.. _URI: http://www.ietf.org/rfc/rfc2396.txt -.. _IRI: http://www.ietf.org/rfc/rfc3987.txt -.. _RFC 3987: IRI_ - -Models -====== - -Because all strings are returned from the database as Unicode strings, model -fields that are character based (CharField, TextField, URLField, etc) will -contain Unicode values when Django retrieves data from the database. This -is *always* the case, even if the data could fit into an ASCII bytestring. - -You can pass in bytestrings when creating a model or populating a field, and -Django will convert it to Unicode when it needs to. - -Choosing between ``__str__()`` and ``__unicode__()`` ----------------------------------------------------- - -One consequence of using Unicode by default is that you have to take some care -when printing data from the model. - -In particular, rather than giving your model a ``__str__()`` method, we -recommended you implement a ``__unicode__()`` method. In the ``__unicode__()`` -method, you can quite safely return the values of all your fields without -having to worry about whether they fit into a bytestring or not. (The way -Python works, the result of ``__str__()`` is *always* a bytestring, even if you -accidentally try to return a Unicode object). - -You can still create a ``__str__()`` method on your models if you want, of -course, but you shouldn't need to do this unless you have a good reason. -Django's ``Model`` base class automatically provides a ``__str__()`` -implementation that calls ``__unicode__()`` and encodes the result into UTF-8. -This means you'll normally only need to implement a ``__unicode__()`` method -and let Django handle the coercion to a bytestring when required. - -Taking care in ``get_absolute_url()`` -------------------------------------- - -URLs can only contain ASCII characters. If you're constructing a URL from -pieces of data that might be non-ASCII, be careful to encode the results in a -way that is suitable for a URL. The ``django.db.models.permalink()`` decorator -handles this for you automatically. - -If you're constructing a URL manually (i.e., *not* using the ``permalink()`` -decorator), you'll need to take care of the encoding yourself. In this case, -use the ``iri_to_uri()`` and ``urlquote()`` functions that were documented -above_. For example:: - - from django.utils.encoding import iri_to_uri - from django.utils.http import urlquote - - def get_absolute_url(self): - url = u'/person/%s/?x=0&y=0' % urlquote(self.location) - return iri_to_uri(url) - -This function returns a correctly encoded URL even if ``self.location`` is -something like "Jack visited Paris & Orléans". (In fact, the ``iri_to_uri()`` -call isn't strictly necessary in the above example, because all the -non-ASCII characters would have been removed in quoting in the first line.) - -.. _above: `URI and IRI handling`_ - -The database API -================ - -You can pass either Unicode strings or UTF-8 bytestrings as arguments to -``filter()`` methods and the like in the database API. The following two -querysets are identical:: - - qs = People.objects.filter(name__contains=u'Å') - qs = People.objects.filter(name__contains='\xc3\x85') # UTF-8 encoding of Å - -Templates -========= - -You can use either Unicode or bytestrings when creating templates manually:: - - from django.template import Template - t1 = Template('This is a bytestring template.') - t2 = Template(u'This is a Unicode template.') - -But the common case is to read templates from the filesystem, and this creates -a slight complication: not all filesystems store their data encoded as UTF-8. -If your template files are not stored with a UTF-8 encoding, set the :setting:`FILE_CHARSET` -setting to the encoding of the files on disk. When Django reads in a template -file, it will convert the data from this encoding to Unicode. (:setting:`FILE_CHARSET` -is set to ``'utf-8'`` by default.) - -The :setting:`DEFAULT_CHARSET` setting controls the encoding of rendered templates. -This is set to UTF-8 by default. - -Template tags and filters -------------------------- - -A couple of tips to remember when writing your own template tags and filters: - - * Always return Unicode strings from a template tag's ``render()`` method - and from template filters. - - * Use ``force_unicode()`` in preference to ``smart_unicode()`` in these - places. Tag rendering and filter calls occur as the template is being - rendered, so there is no advantage to postponing the conversion of lazy - translation objects into strings. It's easier to work solely with Unicode - strings at that point. - -E-mail -====== - -Django's e-mail framework (in ``django.core.mail``) supports Unicode -transparently. You can use Unicode data in the message bodies and any headers. -However, you're still obligated to respect the requirements of the e-mail -specifications, so, for example, e-mail addresses should use only ASCII -characters. - -The following code example demonstrates that everything except e-mail addresses -can be non-ASCII:: - - from django.core.mail import EmailMessage - - subject = u'My visit to Sør-Trøndelag' - sender = u'Arnbjörg Ráðormsdóttir <arnbjorg@example.com>' - recipients = ['Fred <fred@example.com'] - body = u'...' - EmailMessage(subject, body, sender, recipients).send() - -Form submission -=============== - -HTML form submission is a tricky area. There's no guarantee that the -submission will include encoding information, which means the framework might -have to guess at the encoding of submitted data. - -Django adopts a "lazy" approach to decoding form data. The data in an -``HttpRequest`` object is only decoded when you access it. In fact, most of -the data is not decoded at all. Only the ``HttpRequest.GET`` and -``HttpRequest.POST`` data structures have any decoding applied to them. Those -two fields will return their members as Unicode data. All other attributes and -methods of ``HttpRequest`` return data exactly as it was submitted by the -client. - -By default, the :setting:`DEFAULT_CHARSET` setting is used as the assumed encoding -for form data. If you need to change this for a particular form, you can set -the ``encoding`` attribute on an ``HttpRequest`` instance. For example:: - - def some_view(request): - # We know that the data must be encoded as KOI8-R (for some reason). - request.encoding = 'koi8-r' - ... - -You can even change the encoding after having accessed ``request.GET`` or -``request.POST``, and all subsequent accesses will use the new encoding. - -Most developers won't need to worry about changing form encoding, but this is -a useful feature for applications that talk to legacy systems whose encoding -you cannot control. - -Django does not decode the data of file uploads, because that data is normally -treated as collections of bytes, rather than strings. Any automatic decoding -there would alter the meaning of the stream of bytes. diff --git a/parts/django/docs/ref/utils.txt b/parts/django/docs/ref/utils.txt deleted file mode 100644 index e4ce7c4..0000000 --- a/parts/django/docs/ref/utils.txt +++ /dev/null @@ -1,504 +0,0 @@ -============ -Django Utils -============ - -.. module:: django.utils - :synopsis: Django's built-in utilities. - -This document covers all stable modules in ``django.utils``. Most of the -modules in ``django.utils`` are designed for internal use and only the -following parts can be considered stable and thus backwards compatible as per -the :ref:`internal release deprecation policy <internal-release-deprecation-policy>`. - -``django.utils.cache`` -====================== - -.. module:: django.utils.cache - :synopsis: Helper functions for controlling caching. - -This module contains helper functions for controlling caching. It does so by -managing the ``Vary`` header of responses. It includes functions to patch the -header of response objects directly and decorators that change functions to do -that header-patching themselves. - -For information on the ``Vary`` header, see `RFC 2616 section 14.44`_. - -.. _RFC 2616 section 14.44: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44 - -Essentially, the ``Vary`` HTTP header defines which headers a cache should take -into account when building its cache key. Requests with the same path but -different header content for headers named in ``Vary`` need to get different -cache keys to prevent delivery of wrong content. - -For example, :doc:`internationalization </topics/i18n/index>` middleware would need -to distinguish caches by the ``Accept-language`` header. - -.. function:: patch_cache_control(response, **kwargs) - -This function patches the ``Cache-Control`` header by adding all keyword -arguments to it. The transformation is as follows: - - * All keyword parameter names are turned to lowercase, and underscores - are converted to hyphens. - * If the value of a parameter is ``True`` (exactly ``True``, not just a - true value), only the parameter name is added to the header. - * All other parameters are added with their value, after applying - ``str()`` to it. - -.. function:: get_max_age(response) - -Returns the max-age from the response Cache-Control header as an integer (or -``None`` if it wasn't found or wasn't an integer). - -.. function:: patch_response_headers(response, cache_timeout=None) - -Adds some useful headers to the given ``HttpResponse`` object: - - * ``ETag`` - * ``Last-Modified`` - * ``Expires`` - * ``Cache-Control`` - -Each header is only added if it isn't already set. - -``cache_timeout`` is in seconds. The ``CACHE_MIDDLEWARE_SECONDS`` setting is -used by default. - -.. function:: add_never_cache_headers(response) - -Adds headers to a response to indicate that a page should never be cached. - -.. function:: patch_vary_headers(response, newheaders) - -Adds (or updates) the ``Vary`` header in the given ``HttpResponse`` object. -``newheaders`` is a list of header names that should be in ``Vary``. Existing -headers in ``Vary`` aren't removed. - -.. function:: get_cache_key(request, key_prefix=None) - -Returns a cache key based on the request path. It can be used in the request -phase because it pulls the list of headers to take into account from the -global path registry and uses those to build a cache key to check against. - -If there is no headerlist stored, the page needs to be rebuilt, so this -function returns ``None``. - -.. function:: learn_cache_key(request, response, cache_timeout=None, key_prefix=None) - -Learns what headers to take into account for some request path from the -response object. It stores those headers in a global path registry so that -later access to that path will know what headers to take into account without -building the response object itself. The headers are named in the ``Vary`` -header of the response, but we want to prevent response generation. - -The list of headers to use for cache key generation is stored in the same cache -as the pages themselves. If the cache ages some data out of the cache, this -just means that we have to build the response once to get at the Vary header -and so at the list of headers to use for the cache key. - -SortedDict -========== - -.. module:: django.utils.datastructures - :synopsis: A dictionary that keeps its keys in the order in which they're inserted. - -.. class:: django.utils.datastructures.SortedDict - -Methods -------- - -Extra methods that ``SortedDict`` adds to the standard Python ``dict`` class. - -.. method:: insert(index, key, value) - -Inserts the key, value pair before the item with the given index. - -.. method:: value_for_index(index) - -Returns the value of the item at the given zero-based index. - -Creating new SortedDict ------------------------ - -Creating a new ``SortedDict`` must be done in a way where ordering is -guaranteed. For example:: - - SortedDict({'b': 1, 'a': 2, 'c': 3}) - -will not work. Passing in a basic Python ``dict`` could produce unreliable -results. Instead do:: - - SortedDict([('b', 1), ('a', 2), ('c', 3)]) - -``django.utils.encoding`` -========================= - -.. module:: django.utils.encoding - :synopsis: A series of helper classes and function to manage character encoding. - -.. class:: StrAndUnicode - -A class whose ``__str__`` returns its ``__unicode__`` as a UTF-8 bytestring. -Useful as a mix-in. - -.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict') - -Returns a ``unicode`` object representing ``s``. Treats bytestrings using the -'encoding' codec. - -If ``strings_only`` is ``True``, don't convert (some) non-string-like objects. - -.. function:: is_protected_type(obj) - -Determine if the object instance is of a protected type. - -Objects of protected types are preserved as-is when passed to -``force_unicode(strings_only=True)``. - -.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict') - -Similar to ``smart_unicode``, except that lazy instances are resolved to strings, -rather than kept as lazy objects. - -If ``strings_only`` is ``True``, don't convert (some) non-string-like objects. - -.. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict') - -Returns a bytestring version of ``s``, encoded as specified in ``encoding``. - -If ``strings_only`` is ``True``, don't convert (some) non-string-like objects. - -.. function:: iri_to_uri(iri) - -Convert an Internationalized Resource Identifier (IRI) portion to a URI portion -that is suitable for inclusion in a URL. - -This is the algorithm from section 3.1 of `RFC 3987`_. However, since we are -assuming input is either UTF-8 or unicode already, we can simplify things a -little from the full method. - -.. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt - -Returns an ASCII string containing the encoded result. - -``django.utils.feedgenerator`` -============================== - -.. module:: django.utils.feedgenerator - :synopsis: Syndication feed generation library -- used for generating RSS, etc. - -Sample usage:: - - >>> from django.utils import feedgenerator - >>> feed = feedgenerator.Rss201rev2Feed( - ... title=u"Poynter E-Media Tidbits", - ... link=u"http://www.poynter.org/column.asp?id=31", - ... description=u"A group Weblog by the sharpest minds in online media/journalism/publishing.", - ... language=u"en", - ... ) - >>> feed.add_item( - ... title="Hello", - ... link=u"http://www.holovaty.com/test/", - ... description="Testing." - ... ) - >>> fp = open('test.rss', 'w') - >>> feed.write(fp, 'utf-8') - >>> fp.close() - -For simplifying the selection of a generator use ``feedgenerator.DefaultFeed`` -which is currently ``Rss201rev2Feed`` - -For definitions of the different versions of RSS, see: -http://diveintomark.org/archives/2004/02/04/incompatible-rss - -.. function:: get_tag_uri(url, date) - -Creates a TagURI. - -See http://diveintomark.org/archives/2004/05/28/howto-atom-id - -SyndicationFeed ---------------- - -.. class:: SyndicationFeed - -Base class for all syndication feeds. Subclasses should provide write(). - -Methods -~~~~~~~ - -.. method:: add_item(title, link, description, [author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs]) - -Adds an item to the feed. All args are expected to be Python ``unicode`` -objects except ``pubdate``, which is a ``datetime.datetime`` object, and -``enclosure``, which is an instance of the ``Enclosure`` class. - -.. method:: num_items() - -.. method:: root_attributes() - -Return extra attributes to place on the root (i.e. feed/channel) element. -Called from write(). - -.. method:: add_root_elements(handler) - -Add elements in the root (i.e. feed/channel) element. Called from write(). - -.. method:: item_attributes(item) - -Return extra attributes to place on each item (i.e. item/entry) element. - -.. method:: add_item_elements(handler, item) - -Add elements on each item (i.e. item/entry) element. - -.. method:: write(outfile, encoding) - -Outputs the feed in the given encoding to ``outfile``, which is a file-like -object. Subclasses should override this. - -.. method:: writeString(encoding) - -Returns the feed in the given encoding as a string. - -.. method:: latest_post_date() - -Returns the latest item's ``pubdate``. If none of them have a ``pubdate``, -this returns the current date/time. - -Enclosure ---------- - -.. class:: Enclosure - -Represents an RSS enclosure - -RssFeed -------- - -.. class:: RssFeed(SyndicationFeed) - -Rss201rev2Feed --------------- - -.. class:: Rss201rev2Feed(RssFeed) - -Spec: http://blogs.law.harvard.edu/tech/rss - -Atom1Feed ---------- - -.. class:: Atom1Feed(SyndicationFeed) - -Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html - -``django.utils.http`` -===================== - -.. module:: django.utils.http - :synopsis: HTTP helper functions. (URL encoding, cookie handling, ...) - -.. function:: urlquote(url, safe='/') - -A version of Python's ``urllib.quote()`` function that can operate on unicode -strings. The url is first UTF-8 encoded before quoting. The returned string -can safely be used as part of an argument to a subsequent ``iri_to_uri()`` -call without double-quoting occurring. Employs lazy execution. - -.. function:: urlquote_plus(url, safe='') - -A version of Python's urllib.quote_plus() function that can operate on unicode -strings. The url is first UTF-8 encoded before quoting. The returned string can -safely be used as part of an argument to a subsequent iri_to_uri() call without -double-quoting occurring. Employs lazy execution. - -.. function:: urlencode(query, doseq=0) - -A version of Python's urllib.urlencode() function that can operate on unicode -strings. The parameters are first case to UTF-8 encoded strings and then -encoded as per normal. - -.. function:: cookie_date(epoch_seconds=None) - -Formats the time to ensure compatibility with Netscape's cookie standard. - -Accepts a floating point number expressed in seconds since the epoch, in UTC - -such as that outputted by ``time.time()``. If set to ``None``, defaults to the current -time. - -Outputs a string in the format ``Wdy, DD-Mon-YYYY HH:MM:SS GMT``. - -.. function:: http_date(epoch_seconds=None) - -Formats the time to match the RFC 1123 date format as specified by HTTP -`RFC 2616`_ section 3.3.1. - -.. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt - -Accepts a floating point number expressed in seconds since the epoch, in UTC - -such as that outputted by ``time.time()``. If set to ``None``, defaults to the current -time. - -Outputs a string in the format ``Wdy, DD Mon YYYY HH:MM:SS GMT``. - -.. function:: base36_to_int(s) - -Converted a base 36 string to an integer - -.. function:: int_to_base36(i) - -Converts an integer to a base36 string - -``django.utils.safestring`` -=========================== - -.. module:: django.utils.safestring - :synopsis: Functions and classes for working with strings that can be displayed safely without further escaping in HTML. - -Functions and classes for working with "safe strings": strings that can be -displayed safely without further escaping in HTML. Marking something as a "safe -string" means that the producer of the string has already turned characters -that should not be interpreted by the HTML engine (e.g. '<') into the -appropriate entities. - -.. class:: SafeString - -A string subclass that has been specifically marked as "safe" (requires no -further escaping) for HTML output purposes. - -.. class:: SafeUnicode - -A unicode subclass that has been specifically marked as "safe" for HTML output -purposes. - -.. function:: mark_safe(s) - -Explicitly mark a string as safe for (HTML) output purposes. The returned -object can be used everywhere a string or unicode object is appropriate. - -Can be called multiple times on a single string. - -.. function:: mark_for_escaping(s) - -Explicitly mark a string as requiring HTML escaping upon output. Has no effect -on ``SafeData`` subclasses. - -Can be called multiple times on a single string (the resulting escaping is only -applied once). - -``django.utils.translation`` -============================ - -.. module:: django.utils.translation - :synopsis: Internationalization support. - -For a complete discussion on the usage of the following see the -:doc:`Internationalization documentation </topics/i18n/internationalization>`. - -.. function:: gettext(message) - -Translates ``message`` and returns it in a UTF-8 bytestring - -.. function:: ugettext(message) - -Translates ``message`` and returns it in a unicode string - -.. function:: gettext_lazy(message) -.. function:: ugettext_lazy(message) - -Same as the non-lazy versions above, but using lazy execution. - -See :ref:`lazy translations documentation <lazy-translations>`. - -.. function:: gettext_noop(message) - -Marks strings for translation but doesn't translate them now. This can be used -to store strings in global variables that should stay in the base language -(because they might be used externally) and will be translated later. - -.. function:: ngettext(singular, plural, number) - -Translates ``singular`` and ``plural`` and returns the appropriate string -based on ``number`` in a UTF-8 bytestring - -.. function:: ungettext(singular, plural, number) - -Translates ``singular`` and ``plural`` and returns the appropriate string based -on ``number`` in a unicode string - -.. function:: ngettext_lazy(singular, plural, number) -.. function:: ungettext_lazy(singular, plural, number) - -Same as the non-lazy versions above, but using lazy execution. - -See :ref:`lazy translations documentation <lazy-translations>`. - -.. function:: string_concat(*strings) - -Lazy variant of string concatenation, needed for translations that are -constructed from multiple parts. - -.. function:: activate(language) - -Fetches the translation object for a given tuple of application name and -language and installs it as the current translation object for the current -thread. - -.. function:: deactivate() - -De-installs the currently active translation object so that further _ calls will -resolve against the default translation object, again. - -.. function:: deactivate_all() - -Makes the active translation object a NullTranslations() instance. This is -useful when we want delayed translations to appear as the original string for -some reason. - -.. function:: get_language() - -Returns the currently selected language code. - -.. function:: get_language_bidi() - -Returns selected language's BiDi layout: - - * ``False`` = left-to-right layout - * ``True`` = right-to-left layout - -.. function:: get_date_formats() - -Checks whether translation files provide a translation for some technical -message ID to store date and time formats. If it doesn't contain one, the -formats provided in the settings will be used. - -.. function:: get_language_from_request(request) - -Analyzes the request to find what language the user wants the system to show. -Only languages listed in settings.LANGUAGES are taken into account. If the user -requests a sublanguage where we have a main language, we send out the main -language. - -.. function:: to_locale(language) - -Turns a language name (en-us) into a locale name (en_US). - -.. function:: templatize(src) - -Turns a Django template into something that is understood by xgettext. It does -so by translating the Django translation tags into standard gettext function -invocations. - -``django.utils.tzinfo`` -======================= - -.. module:: django.utils.tzinfo - :synopsis: Implementation of ``tzinfo`` classes for use with ``datetime.datetime``. - -.. class:: FixedOffset - -Fixed offset in minutes east from UTC. - -.. class:: LocalTimezone - -Proxy timezone information from time module. diff --git a/parts/django/docs/ref/validators.txt b/parts/django/docs/ref/validators.txt deleted file mode 100644 index 0451f65..0000000 --- a/parts/django/docs/ref/validators.txt +++ /dev/null @@ -1,158 +0,0 @@ -========== -Validators -========== - -.. versionadded:: 1.2 -.. module:: django.core.validators - :synopsis: Validation utilities and base classes - -Writing validators -================== - -A validator is a callable that takes a value and raises a -:exc:`~django.core.exceptions.ValidationError` if it doesn't meet some -criteria. Validators can be useful for re-using validation logic between -different types of fields. - -For example, here's a validator that only allows even numbers:: - - from django.core.exceptions import ValidationError - - def validate_even(value): - if value % 2 != 0: - raise ValidationError(u'%s is not an even number' % value) - -You can add this to a model field via the field's :attr:`~django.db.models.Field.validators` -argument:: - - from django.db import models - - class MyModel(models.Model): - even_field = models.IntegerField(validators=[validate_even]) - -Because values are converted to Python before validators are run, you can even -use the same validator with forms:: - - from django import forms - - class MyForm(forms.Form): - even_field = forms.IntegerField(validators=[validate_even]) - -How validators are run -====================== - -See the :doc:`form validation </ref/forms/validation>` for more information on -how validators are run in forms, and :ref:`Validating objects -<validating-objects>` for how they're run in models. Note that validators will -not be run automatically when you save a model, but if you are using a -:class:`~django.forms.ModelForm`, it will run your validators on any fields -that are included in your form. See the -:doc:`ModelForm documentation </topics/forms/modelforms>` for information on -how model validation interacts with forms. - -Built-in validators -=================== - -The :mod:`django.core.validators` module contains a collection of callable -validators for use with model and form fields. They're used internally but -are available for use with your own fields, too. They can be used in addition -to, or in lieu of custom ``field.clean()`` methods. - -``RegexValidator`` ------------------- -.. class:: RegexValidator(regex, [message=None, code=None]) - - .. attribute:: regex - - The regular expression pattern to search for the provided ``value``, - or a pre-compiled regular expression. Raises a - :exc:`~django.core.exceptions.ValidationError` with :attr:`.message` - and :attr:`.code` if no match is found. - - .. attribute:: message - - The error message used by :exc:`~django.core.exceptions.ValidationError` - if validation fails. If no :attr:`.message` is specified, a generic - ``"Enter a valid value"`` message is used. Default value: ``None``. - - .. attribute:: code - - The error code used by :exc:`~django.core.exceptions.ValidationError` - if validation fails. If :attr:`.code` is not specified, ``"invalid"`` - is used. Default value: ``None``. - -``URLValidator`` ----------------- -.. class:: URLValidator([verify_exists=False, validator_user_agent=URL_VALIDATOR_USER_AGENT]) - - A :class:`RegexValidator` that ensures a value looks like a URL and - optionally verifies that the URL actually exists (i.e., doesn't return a - 404 status code). Raises an error code of ``'invalid'`` if it doesn't look - like a URL, and a code of ``'invalid_link'`` if it doesn't exist. - - .. attribute:: verify_exists - - Default value: ``False``. If set to ``True``, this validator checks - that the URL actually exists. - - .. attribute:: validator_user_agent - - If :attr:`.verify_exists` is ``True``, Django uses the value of - :attr:`.validator_user_agent` as the "User-agent" for the request. This - defaults to :setting:`settings.URL_VALIDATOR_USER_AGENT <URL_VALIDATOR_USER_AGENT>`. - -``validate_email`` ------------------- -.. data:: validate_email - - A :class:`RegexValidator` instance that ensures a value looks like an - e-mail address. - -``validate_slug`` ------------------ -.. data:: validate_slug - - A :class:`RegexValidator` instance that ensures a value consists of only - letters, numbers, underscores or hyphens. - -``validate_ipv4_address`` -------------------------- -.. data:: validate_ipv4_address - - A :class:`RegexValidator` instance that ensures a value looks like an IPv4 - address. - -``validate_comma_separated_integer_list`` ------------------------------------------ -.. data:: validate_comma_separated_integer_list - - A :class:`RegexValidator` instance that ensures a value is a - comma-separated list of integers. - -``MaxValueValidator`` ---------------------- -.. class:: MaxValueValidator(max_value) - - Raises a :exc:`~django.core.exceptions.ValidationError` with a code of - ``'max_value'`` if ``value`` is greater than ``max_value``. - -``MinValueValidator`` ---------------------- -.. class:: MinValueValidator(min_value) - - Raises a :exc:`~django.core.exceptions.ValidationError` with a code of - ``'min_value'`` if ``value`` is less than ``min_value``. - -``MaxLengthValidator`` ----------------------- -.. class:: MaxLengthValidator(max_length) - - Raises a :exc:`~django.core.exceptions.ValidationError` with a code of - ``'max_length'`` if the length of ``value`` is greater than ``max_length``. - -``MinLengthValidator`` ----------------------- -.. class:: MinLengthValidator(min_length) - - Raises a :exc:`~django.core.exceptions.ValidationError` with a code of - ``'min_length'`` if the length of ``value`` is less than ``min_length``. |
