diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/add_ons.txt | 4 | ||||
| -rw-r--r-- | docs/authentication.txt | 11 | ||||
| -rw-r--r-- | docs/db-api.txt | 60 | ||||
| -rw-r--r-- | docs/faq.txt | 41 | ||||
| -rw-r--r-- | docs/forms.txt | 16 | ||||
| -rw-r--r-- | docs/i18n.txt | 19 | ||||
| -rw-r--r-- | docs/model-api.txt | 27 | ||||
| -rw-r--r-- | docs/request_response.txt | 4 | ||||
| -rw-r--r-- | docs/syndication_feeds.txt | 36 | ||||
| -rw-r--r-- | docs/templates.txt | 30 | ||||
| -rw-r--r-- | docs/templates_python.txt | 5 |
11 files changed, 200 insertions, 53 deletions
diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 9f5dc640da..d72e92b018 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -49,8 +49,8 @@ humanize ======== A set of Django template filters useful for adding a "human touch" to data. -To activate these filters, add ``'django.contrib.english'`` to your -``INSTALLED_APPS`` setting. Once you've done that, use ``{% load english %}`` +To activate these filters, add ``'django.contrib.humanize'`` to your +``INSTALLED_APPS`` setting. Once you've done that, use ``{% load humanize %}`` in a template, and you'll have access to these filters: apnumber diff --git a/docs/authentication.txt b/docs/authentication.txt index c1a1f8494d..3edbc21f7a 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -355,8 +355,8 @@ Here's what ``django.contrib.auth.views.login`` does:: form. It's your responsibility to provide the login form in a template called -``registration/login.html``. This template gets passed three template context -variables: +``registration/login.html`` by default. This template gets passed three +template context variables: * ``form``: A ``FormWrapper`` object representing the login form. See the `forms documentation`_ for more on ``FormWrapper`` objects. @@ -365,6 +365,13 @@ variables: * ``site_name``: The name of the current ``Site``, according to the ``SITE_ID`` setting. See the `site framework docs`_. +If you'd prefer not to call the template ``registration/login.html``, you can +pass the ``template_name`` parameter via the extra arguments to the view in +your URLconf. For example, this URLconf line would use ``myapp/login.html`` +instead:: + + (r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}), + Here's a sample ``registration/login.html`` template you can use as a starting point. It assumes you have a ``base.html`` template that defines a ``content`` block:: diff --git a/docs/db-api.txt b/docs/db-api.txt index 3624620609..5108949184 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -559,7 +559,7 @@ following models:: # ... hometown = models.ForeignKey(City) - class Book(meta.Model): + class Book(models.Model): # ... author = models.ForeignKey(Person) @@ -705,6 +705,64 @@ The ``DoesNotExist`` exception inherits from except ObjectDoesNotExist: print "Either the entry or blog doesn't exist." +``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 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. + +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'}) + +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()`` ~~~~~~~~~~~ diff --git a/docs/faq.txt b/docs/faq.txt index a2c069f0ca..7238a0aef7 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -200,6 +200,23 @@ In the meantime, though, check out this `unofficial Django screencast`_. .. _unofficial Django screencast: http://www.throwingbeans.org/django_screencasts.html +Is Django a content-management-system (CMS)? +-------------------------------------------- + +No, Django is not a CMS, or any sort of "turnkey product" in and of itself. +It's a Web framework; it's a programming tool that lets you build Web sites. + +For example, it doesn't make much sense to compare Django to something like +Drupal_, because Django is something you use to *create* things like Drupal. + +Of course, Django's automatic admin site is fantastic and timesaving -- but +the admin site is one module of Django the framework. Furthermore, although +Django has special conveniences for building "CMS-y" apps, that doesn't mean +it's not just as appropriate for building "non-CMS-y" apps (whatever that +means!). + +.. _Drupal: http://drupal.org/ + When will you release Django 1.0? --------------------------------- @@ -222,7 +239,7 @@ How can I download the Django documentation to read it offline? --------------------------------------------------------------- The Django docs are available in the ``docs`` directory of each Django tarball -release. These docs are in ReST (restructured text) format, and each text file +release. These docs are in ReST (ReStructured Text) format, and each text file corresponds to a Web page on the official Django site. Because the documentation is `stored in revision control`_, you can browse @@ -297,13 +314,16 @@ as long as that server has WSGI_ hooks. See the `server arrangements wiki page`_ How do I install mod_python on Windows? --------------------------------------- - * For Python 2.4, check out this `guide to mod_python & Python 2.3`_. + * For Python 2.4, grab mod_python from `win32 build of mod_python for + Python 2.4`_. + * For Python 2.4, check out this `Django on Windows howto`_. * For Python 2.3, grab mod_python from http://www.modpython.org/ and read `Running mod_python on Apache on Windows2000`_. * Also, try this (not Windows-specific) `guide to getting mod_python working`_. -.. _`guide to mod_python & Python 2.3`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24 +.. _`win32 build of mod_python for Python 2.4`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24 +.. _`Django on Windows howto`: http://thinkhole.org/wp/2006/04/03/django-on-windows-howto/ .. _`Running mod_python on Apache on Windows2000`: http://groups-beta.google.com/group/comp.lang.python/msg/139af8c83a5a9d4f .. _`guide to getting mod_python working`: http://www.dscpl.com.au/articles/modpython-001.html @@ -388,19 +408,12 @@ Using a ``FileField`` or an ``ImageField`` in a model takes a few steps: If I make changes to a model, how do I update the database? ----------------------------------------------------------- -If you don't mind clearing data, just pipe the output of the appropriate -``django-admin.py sqlreset`` command into your database's command-line utility. -For example:: - - django-admin.py sqlreset appname | psql dbname +If you don't mind clearing data, your project's ``manage.py`` utility has an +option to reset the SQL for a particular application:: -That "psql" assumes you're using PostgreSQL. If you're using MySQL, use the -appropriate command-line utility, ``mysql``. + manage.py reset appname -``django-admin.py sqlreset`` outputs SQL that clears the app's database -table(s) and creates new ones. The above command uses a Unix pipe to send the -SQL directly to the PostgreSQL command-line utility, which accepts SQL as -input. +This drops any tables associated with ``appname`` and recreates them. If you do care about deleting data, you'll have to execute the ``ALTER TABLE`` statements manually in your database. That's the way we've always done it, diff --git a/docs/forms.txt b/docs/forms.txt index 2f8a3106fc..5026bc1bab 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -15,6 +15,8 @@ We'll take a top-down approach to examining Django's form validation framework, because much of the time you won't need to use the lower-level APIs. Throughout this document, we'll be working with the following model, a "place" object:: + from django.db import models + PLACE_TYPES = ( (1, 'Bar'), (2, 'Restaurant'), @@ -22,13 +24,13 @@ this document, we'll be working with the following model, a "place" object:: (4, 'Secret Hideout'), ) - class Place(meta.Model): - name = meta.CharField(maxlength=100) - address = meta.CharField(maxlength=100, blank=True) - city = meta.CharField(maxlength=50, blank=True) - state = meta.USStateField() - zip_code = meta.CharField(maxlength=5, blank=True) - place_type = meta.IntegerField(choices=PLACE_TYPES) + class Place(models.Model): + name = models.CharField(maxlength=100) + address = models.CharField(maxlength=100, blank=True) + city = models.CharField(maxlength=50, blank=True) + state = models.USStateField() + zip_code = models.CharField(maxlength=5, blank=True) + place_type = models.IntegerField(choices=PLACE_TYPES) class Admin: pass diff --git a/docs/i18n.txt b/docs/i18n.txt index e6660f939d..1220ea95b3 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -133,8 +133,8 @@ For example, to translate a model's ``help_text``, do the following:: from django.utils.translation import gettext_lazy - class MyThing(meta.Model): - name = meta.CharField(help_text=gettext_lazy('This is the help text')) + class MyThing(models.Model): + name = models.CharField(help_text=gettext_lazy('This is the help text')) In this example, ``gettext_lazy()`` stores a lazy reference to the string -- not the actual translation. The translation itself will be done when the string @@ -145,8 +145,8 @@ If you don't like the verbose name ``gettext_lazy``, you can just alias it as from django.utils.translation import gettext_lazy as _ - class MyThing(meta.Model): - name = meta.CharField(help_text=_('This is the help text')) + class MyThing(models.Model): + name = models.CharField(help_text=_('This is the help text')) Always use lazy translations in `Django models`_. And it's a good idea to add translations for the field names and table names, too. This means writing @@ -155,8 +155,8 @@ class, though:: from django.utils.translation import gettext_lazy as _ - class MyThing(meta.Model): - name = meta.CharField(_('name'), help_text=_('This is the help text')) + class MyThing(models.Model): + name = models.CharField(_('name'), help_text=_('This is the help text')) class Meta: verbose_name = _('my thing') verbose_name_plural = _('mythings') @@ -230,12 +230,17 @@ Each ``RequestContext`` has access to two translation-specific variables: language code and the second is the language name (in that language). * ``LANGUAGE_CODE`` is the current user's preferred language, as a string. Example: ``en-us``. (See "How language preference is discovered", below.) + * ``LANGUAGE_BIDI`` is the current language's direction. If True, it's a + right-to-left language, e.g: Hebrew, Arabic. If False it's a + left-to-right language, e.g: English, French, German etc. + If you don't use the ``RequestContext`` extension, you can get those values with -two tags:: +three tags:: {% get_current_language as LANGUAGE_CODE %} {% get_available_languages as LANGUAGES %} + {% get_current_language_bidi as LANGUAGE_BIDI %} These tags also require a ``{% load i18n %}``. diff --git a/docs/model-api.txt b/docs/model-api.txt index c6707a691b..0dc98416a3 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -445,7 +445,8 @@ empty value. If a field has ``blank=False``, the field will be required. ``choices`` ~~~~~~~~~~~ -A list of 2-tuples to use as choices for this field. +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. @@ -481,6 +482,12 @@ or outside your model class altogether:: class Foo(models.Model): gender = models.CharField(maxlength=1, choices=GENDER_CHOICES) +Finally, note that choices can be any iterable object -- not necessarily a +list or tuple. This lets you construct choices dynamically. But if you find +yourself hacking ``choices`` to be dynamic, you're probably better off using +a proper database table with a ``ForeignKey``. ``choices`` is meant for static +data that doesn't change much, if ever. + ``core`` ~~~~~~~~ @@ -1627,10 +1634,10 @@ to happen whenever you save an object. For example:: name = models.CharField(maxlength=100) tagline = models.TextField() - def save(self): - do_something() - super(Blog, self).save() # Call the "real" save() method. - do_something_else() + def save(self): + do_something() + super(Blog, self).save() # Call the "real" save() method. + do_something_else() You can also prevent saving:: @@ -1638,11 +1645,11 @@ You can also prevent saving:: name = models.CharField(maxlength=100) tagline = models.TextField() - def save(self): - if self.name == "Yoko Ono's blog": - return # Yoko shall never have her own blog! - else: - super(Blog, self).save() # Call the "real" save() method. + def save(self): + if self.name == "Yoko Ono's blog": + return # Yoko shall never have her own blog! + else: + super(Blog, self).save() # Call the "real" save() method. .. _database API docs: http://www.djangoproject.com/documentation/db_api/ diff --git a/docs/request_response.txt b/docs/request_response.txt index 33e5ef4d84..4939cac76f 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -400,6 +400,10 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in ``HttpResponseForbidden`` Acts just like ``HttpResponse`` but uses a 403 status code. +``HttpResponseNotAllowed`` + Like ``HttpResponse``, but uses a 405 status code. Takes a single, + required argument: a list of permitted methods (e.g. ``['GET', 'POST']``). + ``HttpResponseGone`` Acts just like ``HttpResponse`` but uses a 410 status code. diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index b7b0a9047b..4f77c4ff21 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -439,6 +439,23 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas 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. + # ITEMS -- One of the following three is required. The framework looks # for them in this order. @@ -602,6 +619,25 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas 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. + + The low-level framework ======================= diff --git a/docs/templates.txt b/docs/templates.txt index c191b409f4..5f397c5a60 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -454,8 +454,12 @@ displayed by the ``{{ athlete_list|length }}`` variable. As you can see, the ``if`` tag can take an option ``{% else %}`` clause that will be displayed if the test fails. -``if`` tags may use ``or`` or ``not`` to test a number of variables or to negate -a given variable:: +``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. @@ -468,16 +472,24 @@ a given variable:: {% 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 my fault). + stupid; it's not our fault). + {% endif %} + + {% if athlete_list and not coach_list %} + There are some athletes and absolutely no coaches. {% endif %} -For simplicity, ``if`` tags do not allow ``and`` clauses; use nested ``if`` -tags instead:: +``if`` tags don't allow ``and`` and ``or`` clauses within the same tag, because +the order of logic would be ambiguous. For example, this is invalid:: + + {% if athlete_list and coach_list or cheerleader_list %} + +If you need to combine ``and`` and ``or`` to do advanced logic, just use nested +``if`` tags. For example:: {% if athlete_list %} - {% if coach_list %} - Number of athletes: {{ athlete_list|length }}. - Number of coaches: {{ coach_list|length }}. + {% if coach_list or cheerleader_list %} + We have athletes, and either coaches or cheerleaders! {% endif %} {% endif %} @@ -754,6 +766,8 @@ The argument tells which template bit to output: ``closeblock`` ``%}`` ``openvariable`` ``{{`` ``closevariable`` ``}}`` + ``openbrace`` ``{`` + ``closebrace`` ``}`` ================== ======= widthratio diff --git a/docs/templates_python.txt b/docs/templates_python.txt index dea5bcbee6..5e3038ebb4 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -502,12 +502,13 @@ Although the Django template language comes with several default tags and filters, you might want to write your own. It's easy to do. First, create a ``templatetags`` package in the appropriate Django app's -package. It should be on the same level as ``models``, ``views.py``, etc. For +package. It should be on the same level as ``models.py``, ``views.py``, etc. For example:: polls/ - models/ + models.py templatetags/ + views.py Add two files to the ``templatetags`` package: an ``__init__.py`` file and a file that will contain your custom tag/filter definitions. The name of the |