Beefed up docs/db-api.txt, adding a section for each automatic module-level API function -- and optional ones, too
git-svn-id: http://code.djangoproject.com/svn/django/trunk@688 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty
parent
68c0742008
commit
c2e42e1c5c
257
docs/db-api.txt
257
docs/db-api.txt
|
|
@ -2,9 +2,9 @@
|
|||
Database API reference
|
||||
======================
|
||||
|
||||
Once you've created your `data models`_, you'll need to lookup data from the
|
||||
database. This document explains the database abstraction API derived from the
|
||||
models, and how to create, retrieve, and update objects.
|
||||
Once you've created your `data models`_, you'll need to retrieve data from the
|
||||
database. This document explains the database abstraction API derived from the
|
||||
models, and how to create, retrieve and update objects.
|
||||
|
||||
.. _`data models`: http://www.djangoproject.com/documentation/model_api/
|
||||
|
||||
|
|
@ -16,20 +16,121 @@ Throughout this reference, we'll refer to the following Poll application::
|
|||
pub_date = meta.DateTimeField()
|
||||
expire_date = meta.DateTimeField()
|
||||
|
||||
def __repr__(self):
|
||||
return self.question
|
||||
|
||||
class Choice(meta.Model):
|
||||
poll = meta.ForeignKey(Poll, edit_inline=meta.TABULAR,
|
||||
num_in_admin=10, min_num_in_admin=5)
|
||||
choice = meta.CharField(maxlength=255, core=True)
|
||||
votes = meta.IntegerField(editable=False, default=0)
|
||||
|
||||
def __repr__(self):
|
||||
return self.choice
|
||||
|
||||
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 ``AssertionError`` if that's not true), ``get_count`` simply returns a
|
||||
count of objects matched by the lookup, and ``get_list`` returns a list of objects.
|
||||
Each model exposes these module-level functions for lookups:
|
||||
|
||||
get_object(**kwargs)
|
||||
--------------------
|
||||
|
||||
Returns the object matching the given lookup parameters, which should be in
|
||||
the format described in "Field lookups" below. Raises a module-level
|
||||
``*DoesNotExist`` exception if an object wasn't found for the given parameters.
|
||||
Raises ``AssertionError`` if more than one object was found.
|
||||
|
||||
get_list(**kwargs)
|
||||
------------------
|
||||
|
||||
Returns a list of objects matching the given lookup parameters, which should be
|
||||
in the format described in "Field lookups" below. If no objects match the given
|
||||
parameters, it returns an empty list. ``get_list()`` will always return a list.
|
||||
|
||||
get_iterator(**kwargs)
|
||||
----------------------
|
||||
|
||||
Just like ``get_list()``, except it returns an iterator instead of a list. This
|
||||
is more efficient for large result sets. This example shows the difference::
|
||||
|
||||
# get_list() loads all objects into memory.
|
||||
for obj in foos.get_list():
|
||||
print repr(obj)
|
||||
|
||||
# get_iterator() only loads a number of objects into memory at a time.
|
||||
for obj in foos.get_iterator():
|
||||
print repr(obj)
|
||||
|
||||
get_count(**kwargs)
|
||||
-------------------
|
||||
|
||||
Returns an integer representing the number of objects in the database matching
|
||||
the given lookup parameters, which should be in the format described in
|
||||
"Field lookups" below. ``get_count()`` never raises exceptions
|
||||
|
||||
Depending on which database you're using (e.g. PostgreSQL vs. MySQL), this may
|
||||
return a long integer instead of a normal Python integer.
|
||||
|
||||
get_values(**kwargs)
|
||||
--------------------
|
||||
|
||||
Just like ``get_list()``, except it returns a list of dictionaries instead of
|
||||
model-instance objects.
|
||||
|
||||
It accepts an optional parameter, ``fields``, which should be a list or tuple
|
||||
of field names. If you don't specify ``fields``, each dictionary in the list
|
||||
returned by ``get_values()`` will have a key and value for each field in the
|
||||
database table. If you specify ``fields``, each dictionary will have only the
|
||||
field keys/values for the fields you specify. Here's an example, using the
|
||||
``Poll`` model defined above::
|
||||
|
||||
>>> from datetime import datetime
|
||||
>>> p1 = polls.Poll(slug='whatsup', question="What's up?",
|
||||
... pub_date=datetime(2005, 2, 20), expire_date=datetime(2005, 3, 20))
|
||||
>>> p1.save()
|
||||
>>> p2 = polls.Poll(slug='name', question="What's your name?",
|
||||
... pub_date=datetime(2005, 3, 20), expire_date=datetime(2005, 4, 20))
|
||||
>>> p2.save()
|
||||
>>> polls.get_list()
|
||||
[What's up?, What's your name?]
|
||||
>>> polls.get_values()
|
||||
[{'id': 1, 'slug': 'whatsup', 'question': "What's up?", 'pub_date': datetime.datetime(2005, 2, 20), 'expire_date': datetime.datetime(2005, 3, 20)},
|
||||
{'id': 2, 'slug': 'name', 'question': "What's your name?", 'pub_date': datetime.datetime(2005, 3, 20), 'expire_date': datetime.datetime(2005, 4, 20)}]
|
||||
>>> polls.get_values(fields=['id', 'slug'])
|
||||
[{'id': 1, 'slug': 'whatsup'}, {'id': 2, 'slug': 'name'}]
|
||||
|
||||
Use ``get_values()`` when you know you're only going to need a couple of field
|
||||
values 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.
|
||||
|
||||
get_values_iterator(**kwargs)
|
||||
-----------------------------
|
||||
|
||||
Just like ``get_values()``, except it returns an iterator instead of a list.
|
||||
See the section on ``get_iterator()`` above.
|
||||
|
||||
get_in_bulk(id_list, **kwargs)
|
||||
------------------------------
|
||||
|
||||
Takes a list of IDs and returns a dictionary mapping each ID to an instance of
|
||||
the object with the given ID. Also takes optional keyword lookup arguments,
|
||||
which should be in the format described in "Field lookups" below. Here's an
|
||||
example, using the ``Poll`` model defined above::
|
||||
|
||||
>>> from datetime import datetime
|
||||
>>> p1 = polls.Poll(slug='whatsup', question="What's up?",
|
||||
... pub_date=datetime(2005, 2, 20), expire_date=datetime(2005, 3, 20))
|
||||
>>> p1.save()
|
||||
>>> p2 = polls.Poll(slug='name', question="What's your name?",
|
||||
... pub_date=datetime(2005, 3, 20), expire_date=datetime(2005, 4, 20))
|
||||
>>> p2.save()
|
||||
>>> polls.get_list()
|
||||
[What's up?, What's your name?]
|
||||
>>> polls.get_in_bulk([1])
|
||||
{1: What's up?}
|
||||
>>> polls.get_in_bulk([1, 2])
|
||||
{1: What's up?, 2: What's your name?}
|
||||
|
||||
Field lookups
|
||||
=============
|
||||
|
|
@ -115,6 +216,8 @@ statements are equivalent::
|
|||
choices.get_list(poll__id__exact=3)
|
||||
choices.get_list(poll__pk=3)
|
||||
|
||||
If you pass an invalid keyword argument, the function will raise ``TypeError``.
|
||||
|
||||
.. _`Keyword Arguments`: http://docs.python.org/tut/node6.html#SECTION006720000000000000000
|
||||
|
||||
Ordering
|
||||
|
|
@ -337,7 +440,7 @@ of objects then calling save() on them::
|
|||
Calling ``save()`` on an object with an id if ``None`` signifies to
|
||||
Django that the object is new and should be inserted.
|
||||
|
||||
Related objects (i.e. ``Choices``) are created using convience functions::
|
||||
Related objects (e.g. ``Choices``) are created using convenience functions::
|
||||
|
||||
>>> p.add_choice(choice="Over easy", votes=0)
|
||||
>>> p.add_choice(choice="Scrambled", votes=0)
|
||||
|
|
@ -346,12 +449,10 @@ Related objects (i.e. ``Choices``) are created using convience functions::
|
|||
>>> p.get_choice_count()
|
||||
4
|
||||
|
||||
Each of those ``add_choice`` methods is equivilent to (except obviously much
|
||||
Each of those ``add_choice`` methods is equivalent to (except obviously much
|
||||
simpler than)::
|
||||
|
||||
>>> c = polls.Choice(poll_id=p.id,
|
||||
... choice="Over easy",
|
||||
... votes=0)
|
||||
>>> c = polls.Choice(poll_id=p.id, choice="Over easy", votes=0)
|
||||
>>> c.save()
|
||||
|
||||
Note that when using the `add_foo()`` methods, you do not give any value
|
||||
|
|
@ -361,4 +462,132 @@ the relation (``poll_id`` in this case).
|
|||
Deleting objects
|
||||
================
|
||||
|
||||
The delete method, conveniently, is named ``delete()``.
|
||||
The delete method, conveniently, is named ``delete()``. This method immediately
|
||||
deletes the object and has no return value. Example::
|
||||
|
||||
>>> c.delete()
|
||||
|
||||
Extra instance methods
|
||||
======================
|
||||
|
||||
In addition to ``save()``, ``delete()`` and all of the ``add_*`` and ``get_*``
|
||||
related-object methods, a model object might get any or all of the following
|
||||
methods:
|
||||
|
||||
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
|
||||
name = meta.CharField(maxlength=20)
|
||||
gender = meta.CharField(maxlength=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'
|
||||
|
||||
get_next_by_FOO(**kwargs) and 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 "Field lookups" above.
|
||||
|
||||
get_FOO_filename()
|
||||
------------------
|
||||
|
||||
For every ``FileField``, the object will have a ``get_FOO_filename()`` method,
|
||||
where ``FOO`` is the name of the field. This returns the full filesystem path
|
||||
to the file, according to your ``MEDIA_ROOT`` setting.
|
||||
|
||||
Note that ``ImageField`` is technically a subclass of ``FileField``, so every
|
||||
model with an ``ImageField`` will also get this method.
|
||||
|
||||
get_FOO_url()
|
||||
-------------
|
||||
|
||||
For every ``FileField``, the object will have a ``get_FOO_filename()`` method,
|
||||
where ``FOO`` is the name of the field. This returns the full URL to the file,
|
||||
according to your ``MEDIA_URL`` setting. If the value is blank, this method
|
||||
returns an empty string.
|
||||
|
||||
get_FOO_size()
|
||||
--------------
|
||||
|
||||
For every ``FileField``, the object will have a ``get_FOO_filename()`` method,
|
||||
where ``FOO`` is the name of the field. This returns the size of the file, in
|
||||
bytes. (Behind the scenes, it uses ``os.path.getsize``.)
|
||||
|
||||
save_FOO_file(filename, raw_contents)
|
||||
-------------------------------------
|
||||
|
||||
For every ``FileField``, the object will have a ``get_FOO_filename()`` method,
|
||||
where ``FOO`` is the name of the field. This saves the given file to the
|
||||
filesystem, using the given filename. If a file with the given filename already
|
||||
exists, Django adds an underscore to the end of the filename (but before the
|
||||
extension) until the filename is available.
|
||||
|
||||
get_FOO_height() and get_FOO_width()
|
||||
------------------------------------
|
||||
|
||||
For every ``ImageField``, the object will have ``get_FOO_height()`` and
|
||||
``get_FOO_width()`` methods, where ``FOO`` is the name of the field. This
|
||||
returns the height (or width) of the image, as an integer, in pixels.
|
||||
|
||||
Extra module functions
|
||||
======================
|
||||
|
||||
In addition to every function described in "Basic lookup functions" above, a
|
||||
model module might get any or all of the following methods:
|
||||
|
||||
get_FOO_list(kind, **kwargs)
|
||||
----------------------------
|
||||
|
||||
For every ``DateField`` and ``DateTimeField``, the model module will have a
|
||||
``get_FOO_list()`` function, where ``FOO`` is the name of the field. This
|
||||
returns a list of ``datetime.datetime`` objects representing all available
|
||||
dates of the given scope, as defined by the ``kind`` argument. ``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.
|
||||
|
||||
Here's an example, using the ``Poll`` model defined above::
|
||||
|
||||
>>> from datetime import datetime
|
||||
>>> p1 = polls.Poll(slug='whatsup', question="What's up?",
|
||||
... pub_date=datetime(2005, 2, 20), expire_date=datetime(2005, 3, 20))
|
||||
>>> p1.save()
|
||||
>>> p2 = polls.Poll(slug='name', question="What's your name?",
|
||||
... pub_date=datetime(2005, 3, 20), expire_date=datetime(2005, 4, 20))
|
||||
>>> p2.save()
|
||||
>>> polls.get_pub_date_list('year')
|
||||
[datetime.datetime(2005, 1, 1)]
|
||||
>>> polls.get_pub_date_list('month')
|
||||
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
|
||||
>>> polls.get_pub_date_list('day')
|
||||
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
|
||||
|
||||
``get_FOO_list()`` also accepts an optional keyword argument ``order``, which
|
||||
should be either ``"ASC"`` or ``"DESC"``. This specifies how to order the
|
||||
results. Default is ``"ASC"``.
|
||||
|
|
|
|||
Loading…
Reference in New Issue