Permalink
Browse files

Imported fledgeling Django documentation from private SVN repository

git-svn-id: http://code.djangoproject.com/svn/django/trunk@2 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent d6ded0e commit 07ffc7d605cc96557db28a9e35da69bc0719611b @adrianholovaty adrianholovaty committed Jul 13, 2005
View
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+
+"""
+Script to build the documentation for Django from ReST -> HTML.
+"""
+
+import os
+import sys
+import glob
+import locale
+from docutils.core import publish_parts
+from docutils.writers import html4css1
+
+SETTINGS = {
+ 'initial_header_level': 2
+}
+
+locale.setlocale(locale.LC_ALL, '')
+
+def build(dirs):
+ writer = html4css1.Writer()
+ writer.translator_class = DjangoHTMLTranslator
+ for dir in dirs:
+ for fname in glob.glob1(dir, "*.txt"):
+ in_file = os.path.join(dir, fname)
+ out_file = os.path.join(dir, os.path.splitext(fname)[0] + ".html")
+ print "+++", in_file
+ parts = publish_parts(
+ open(in_file).read(),
+ source_path=in_file,
+ destination_path=out_file,
+ writer=writer,
+ settings_overrides={
+ 'initial_header_level' : 2,
+ }
+ )
+ open(out_file, 'w').write(parts['html_body'])
+
+class DjangoHTMLTranslator(html4css1.HTMLTranslator):
+ """Remove the damn border=1 from the standard HTML writer"""
+ def visit_table(self, node):
+ self.body.append(self.starttag(node, 'table', CLASS='docutils'))
+
+if __name__ == "__main__":
+ if len(sys.argv) > 1:
+ build(sys.argv[1:])
+ else:
+ build([os.getcwd()])
View
@@ -0,0 +1,258 @@
+======================
+Database API reference
+======================
+
+XXX INTRO HERE XXX
+
+Throughout this reference, I'll be referring to the following Poll application::
+
+ class Poll(meta.Model):
+ module_name = 'polls'
+ verbose_name = 'poll'
+ db_table = 'polls'
+ fields = (
+ meta.SlugField('slug', 'slug', unique_for_month='pub_date'),
+ meta.CharField('question', 'question', maxlength=255),
+ meta.DateTimeField('pub_date', 'date published'),
+ meta.DateTimeField('expire_date', 'expiration date'),
+ )
+
+ class Choice(meta.Model):
+ module_name = 'choices'
+ verbose_name = 'choice'
+ db_table = 'poll_choices'
+ fields = (
+ meta.IntegerField('poll_id', 'poll', rel=meta.ManyToOne(Poll, 'poll', 'id',
+ edit_inline=True, edit_inline_type=meta.TABULAR, num_in_admin=10,
+ min_num_in_admin=5)),
+ meta.CharField('choice', 'choice', maxlength=255, core=True),
+ meta.IntegerField('votes', 'votes', editable=False, default=0),
+ )
+
+Basic lookup functions
+======================
+
+Each model exposes three basic functions for lookups: ``get_object``,
+``get_list``, and ``get_count``. These functions all take the same arguments,
+but ``get_object`` assumes that only a single record will be returned (and
+raises an exception if that's not true), ``get_count`` simple returns a count of
+objects matched by the lookup, and ``get_list`` returns the entire list.
+
+Field lookups
+=============
+
+Basic field lookups take the form ``field__lookuptype`` (that's a
+double-underscore). For example::
+
+ polls.get_list(pub_date__lte=datetime.datetime.now())
+
+translates (roughly) into the following SQL:
+
+ SELECT * FROM polls WHERE pub_date < NOW();
+
+The DB API supports the following lookup types:
+
+ ========== ==============================================================
+ Type Description
+ ========== ==============================================================
+ exact Exact match: ``polls.get_object(id__exact=14)``
+ iexact Case-insensitive exact match:
+ ``polls.get_list(slug__iexact="foo")`` matches a slug of ``foo``,
+ ``FOO``, ``fOo``, etc.
+ contains Case-sensitive contains test:
+ ``polls.get_list(question__contains="spam")`` returns all polls
+ that contain "spam" in the question.
+ icontains Case-insensitive contains
+ gt Greater than: ``polls.get_list(id__gt=4)``
+ gte Greater than or equal to
+ lt Less than
+ lte Less than or equal to
+ startswith Case-sensitive starts-with:
+ ``polls.get_list(question_startswith="Would")``
+ endswith Case-sensitive ends-with
+ range Range test:
+ ``polls.get_list(pub_date__range=(start_date, end_date)``
+ returns all polls with a pub_date between ``start_date``
+ and ``end_date`` (inclusive).
+ year For date/datetime fields, exact year match:
+ ``polls.get_count(pub_date__year=2005)``.
+ month For date/datetime fields, exact month match.
+ day For date/datetime fields, exact day match.
+ isnull True/False; does is IF NULL/IF NOT NULL lookup:
+ ``polls.get_list(expire_date__isnull=True)``.
+ ========== ==============================================================
+
+Multiple lookups are of course allowed, and are translated as "ands"::
+
+ polls.get_list(
+ pub_date__year=2005,
+ pub_date__month=1,
+ question__startswith="Would",
+ )
+
+retrieves all polls published in Jan. 2005 whose question starts with "Would."
+
+"Or" lookups are also possible::
+
+ XXX FIXME XXX
+
+Ordering
+========
+
+The results are automatically ordered by the ordering tuple given by the
+``ordering`` key in the model, but the ordering may be explicitly
+provided by the ``order_by`` argument to a lookup::
+
+ polls.get_list(
+ pub_date__year=2005,
+ pub_date__month=1,
+ order_by=(("pub_date", "DESC"), ("question", "ASC")),
+ )
+
+The result set above will be ordered by ``pub_date`` (descending), then
+by ``question`` (ascending). Just like in models, the ``order_by`` clause
+is a list of ordering tuples where the first element is the field and the
+second is "ASC" or "DESC" to order ascending or descending. You may also
+use the tuple ``(None, "RANDOM")`` to order the result set randomly.
+
+Relationships (joins)
+=====================
+
+Joins may implicitly be performed by following relationships:
+``choices.get_list(poll__slug__exact="eggs")`` fetches a list of ``Choice``
+objects where the associated ``Poll`` has a slug of ``eggs``. Multiple levels
+of joins are allowed.
+
+Given an instance of an object, related objects can be looked up directly using
+connivence functions, for example, if ``poll`` is a ``Poll`` instance,
+``poll.get_choice_list()`` will return a list of all associated choices (astute
+readers will note that this is the same as
+``choices.get_list(poll_id__exact=poll.id)``, except clearer).
+
+Each type of relationship creates a set of methods on each object in the
+relationship. These created methods go both ways, so objects that are
+"related-to" need not explicitly define reverse relationships; that happens
+automatically.
+
+One-to-one relations
+--------------------
+
+Each object in a one-to-one relationship will have a ``get_relatedobject()``
+method. For example::
+
+ class Place(meta.Model):
+ ...
+ fields = (
+ ...
+ )
+
+ class Restaurant(meta.Model):
+ ...
+ fields = (
+ meta.IntegerField('id', 'ID', primary_key=True,
+ rel=meta.OneToOne(places.Place, 'place', 'id')),
+ ...
+ )
+
+In the above example, each ``Place`` will have a ``get_restaurant()`` method,
+and each ``Restaurant`` will have a ``get_place()`` method.
+
+Many-to-one relations
+---------------------
+
+In each many-to-one relationship the related object will have a
+``get_relatedobject()`` method, and the related-to object will have
+``get_relatedobject()``, ``get_relatedobject_list()``, and
+``get_relatedobject_count()`` methods (the same as the module-level
+``get_object()``, ``get_list()``, and ``get_count()`` methods).
+
+Thus, for the ``Poll`` example at the top, ``Choice`` objects will have a
+``get_poll()`` method, and ``Poll`` objects will have ``get_choice()``,
+``get_choice_list()``, and ``get_choice_count()`` functions.
+
+Many-to-many relations
+----------------------
+
+Many-to-many relations result in the same set of methods as `Many-to-one relations`_,
+except that the ``get_relatedobjects()`` function on the related object will
+return a list of instances instead of a single instance. So, if the relationship
+between ``Poll`` and ``Choice`` was many-to-many, ``choice.get_polls()`` would
+return a list.
+
+Relationships across applications
+---------------------------------
+
+If a relation spans applications -- if ``Place`` was had a ManyToOne relation to
+a ``geo.City`` object, for example -- the name of the other application will be
+added to the method, i.e. ``place.get_geo_city()`` and
+``city.get_places_place_list()``.
+
+Selecting related objects
+-------------------------
+
+Relations are the bread and butter of databases, so there's an option to "follow"
+all relationships and pre-fill them in a simple cache so that later calls to
+objects with a one-to-many relationship don't have to hit the database. If you pass
+``select_related=True`` to a lookup, this pre-caching of relationships will be performed.
+This results in (sometimes much) larger queries, but it means that later use of
+relationships is much faster.
+
+For example, using the Poll and Choice models from above, if you do the following::
+
+ c = choices.get_object(id__exact=5, select_related=True)
+
+Then subsequent calls to ``c.get_poll()`` won't hit the database.
+
+Limiting selected rows
+======================
+
+The ``limit``, ``offset``, and ``distinct`` keywords can be used to control
+which rows are returned. Both ``limit`` and ``offset`` should be integers which
+will be directly passed to the SQL ``LIMIT``/``OFFSET`` commands.
+
+If ``distinct`` is True, only distinct rows will be returned (this is equivalent
+to a ``SELECT DISTINCT`` SQL clause).
+
+Other lookup options
+====================
+
+There are a few other ways of more directly controlling the generated SQL
+for the lookup. Note that by definition these extra lookups may not be
+portable to different database engines (since you're explicitly writing
+SQL code) and should be avoided where ever possible.:
+
+``params``
+----------
+
+All the extra-SQL params described below may use standard Python string
+formatting codes to indicate parameters that the database engine will
+automatically quote. The ``params`` argument can contain any extra
+parameters to be substituted.
+
+``select``
+----------
+
+The ``select`` keyword allows you to select extra fields. This should be a
+dict mapping field names to a SQL clause to use for that field. For example::
+
+ polls.get_list(
+ select={
+ 'choice_count' : 'SELECT COUNT(*) FROM choices WHERE poll_id = polls.id'
+ }
+ )
+
+Each of the resulting ``Poll`` objects will have an extra ``choice_count`` with
+a count of associated ``Choice`` objects. Note that the parenthesis required by
+most database engines around sub-selects are not required in Django's ``select``
+clauses.
+
+``where`` / ``tables``
+----------------------
+
+If you need to explicitly pass extra ``WHERE`` clauses -- perhaps to perform
+non-explicit joins -- use the ``where`` keyword.. If you need to
+join other tables into your query, you can pass their names to ``tables``.
+
+Creating new objects
+====================
+
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.

0 comments on commit 07ffc7d

Please sign in to comment.