mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-07-05 02:09:13 +00:00
Code Issues 32 Releases Wiki Activity

magic-removal: Added 'Field name restrictions' section placeholder to docs/model-api.txt

Browse Source 
git-svn-id: http://code.djangoproject.com/svn/django/branches/magic-removal@2755 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2006-04-27 22:12:05 +00:00
parent 62cb0be63b
commit 2a9ed3addf
1 changed files with 52 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/model-api.txt
View File

@ -21,7 +21,7 @@ Field objects
============= =============
The most important part of a model is the list of database fields it defines. The most important part of a model is the list of database fields it defines.
Fields are defined by class attributes. Fields are defined by class attributes.
In this example, there are two fields, ``first_name`` and ``last_name`` :: In this example, there are two fields, ``first_name`` and ``last_name`` ::
@ -56,6 +56,14 @@ specify the human-readable name::
Convention is not to capitalize the first letter of the ``verbose_name``. Convention is not to capitalize the first letter of the ``verbose_name``.
Django will automatically capitalize the first letter where it needs to. Django will automatically capitalize the first letter where it needs to.
Field name restrictions
-----------------------
TODO: Fill this section.
* Can't be Python reserved word.
* Can't have more than one underscore in a row, due to query lookup.
General field options General field options
--------------------- ---------------------
@ -491,7 +499,7 @@ To create a recursive relationship -- an object that has a many-to-one
relationship with itself -- use ``models.ForeignKey("self")``. relationship with itself -- use ``models.ForeignKey("self")``.
If you need to create a relationship on a model that has not yet been defined, 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:: you can use the name of the model, rather than the model object itself::
class Place(models.Model): class Place(models.Model):
# ... # ...
@ -501,9 +509,9 @@ you can use the name of the model, rather than the model object itself::
# ... # ...
The name of a ``ForeignKey`` (``city`` in the example above) generally should The name of a ``ForeignKey`` (``city`` in the example above) generally should
be the name of the model, in singular form. Behind the scenes, Django appends be the name of the model, in singular form. Behind the scenes, Django appends
"_id" to the field name to create its database column name. However, your code "_id" to the field name to create its database column name. However, your code
should never have to deal with the database column name, unless you write should never have to deal with the database column name, unless you write
custom SQL. custom SQL.
See the `Many-to-one relationship model example`_ for a full example. See the `Many-to-one relationship model example`_ for a full example.
@ -598,7 +606,7 @@ relationship should work. All are optional:
models.ForeignKey(Category, related_name="secondary_stories") models.ForeignKey(Category, related_name="secondary_stories")
...which would give ``Category`` objects two Object Set ...which would give ``Category`` objects two Object Set
descriptors - one called ``primary_stories`` and one descriptors - one called ``primary_stories`` and one
called ``secondary_stories``. called ``secondary_stories``.
``to_field`` The field on the related object that the relation ``to_field`` The field on the related object that the relation
@ -678,24 +686,24 @@ the relationship should work. All are optional:
version of the class being linked to. Use the singular version of the class being linked to. Use the singular
parameter to change this, which is if you want one model to parameter to change this, which is if you want one model to
have multiple ``ManyToMany`` relationships to another model. have multiple ``ManyToMany`` relationships to another model.
``symmetrical`` Only used in the definition of ManyToManyFields on self. ``symmetrical`` Only used in the definition of ManyToManyFields on self.
Consider the following model: Consider the following model:
class Person(models.Model): class Person(models.Model):
friends = models.ManyToManyField("self") friends = models.ManyToManyField("self")
When Django processes this model, it identifies that it has When Django processes this model, it identifies that it has
a ManyToManyField on itself, and as a result, it doesn't add a ManyToManyField on itself, and as a result, it doesn't add
a ``person_set`` attribute to the Person class. Instead, the a ``person_set`` attribute to the Person class. Instead, the
ManyToManyField is assumed to be symmetrical - that is, if ManyToManyField is assumed to be symmetrical - that is, if
I am your friend, then you are my friend. I am your friend, then you are my friend.
If you do not want symmetry in ManyToMany relationships with If you do not want symmetry in ManyToMany relationships with
self, set ``symmetrical`` to False. This will force Django to self, set ``symmetrical`` to False. This will force Django to
add the descriptor for the reverse relationship, allow add the descriptor for the reverse relationship, allow
ManyToMany relationships to be non-symmetrical. ManyToMany relationships to be non-symmetrical.
======================= ============================================================ ======================= ============================================================
One-to-one relationships One-to-one relationships
@ -709,7 +717,7 @@ This is most useful on the primary key of an object when that object "extends"
another object in some way. another object in some way.
``OneToOneField`` requires a positional argument: The class to which the ``OneToOneField`` requires a positional argument: The class to which the
model is related. model is related.
For example, if you're building a database of "places", you would build pretty For example, if you're building a database of "places", you would build pretty
standard stuff such as address, phone number, etc. in the database. Then, if you standard stuff such as address, phone number, etc. in the database. Then, if you
@ -860,7 +868,7 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
Admin options Admin options
============= =============
If you want your model to be visible to the automatic Administration If you want your model to be visible to the automatic Administration
system, your model must have an inner ``"class Admin"``, like so:: system, your model must have an inner ``"class Admin"``, like so::
class Foo(models.Model): class Foo(models.Model):
@ -869,7 +877,7 @@ system, your model must have an inner ``"class Admin"``, like so::
class Admin: class Admin:
# ... # ...
The Admin class gives instructions to Django on how to display the Model The Admin class gives instructions to Django on how to display the Model
to the Administration system. to the Administration system.
Here's a list of all possible ``Admin`` options. No options are required. Adding Here's a list of all possible ``Admin`` options. No options are required. Adding
@ -1013,30 +1021,30 @@ Here's a list of all possible ``Admin`` options. No options are required. Adding
Managers Managers
======== ========
The Manager is the interface through which database query operations The Manager is the interface through which database query operations
are provided to Django applications. At least one Manager exists for are provided to Django applications. At least one Manager exists for
every model in a Django application. every model in a Django application.
By default, Django will add a Manager with the name of ``objects`` to By default, Django will add a Manager with the name of ``objects`` to
every Django model. However, if you wish to use ``objects`` as a field every Django model. However, if you wish to use ``objects`` as a field
name, or if you wish to use a name other than ``objects`` for the Manager, name, or if you wish to use a name other than ``objects`` for the Manager,
you can rename the Manager on a per-model basis. To rename the Manager you can rename the Manager on a per-model basis. To rename the Manager
for a given class, define a class attribute of type models.Manager() for a given class, define a class attribute of type models.Manager()
on that model. For example:: on that model. For example::
from django.db import models from django.db import models
class Person(models.Model): class Person(models.Model):
#... #...
people = models.Manager() people = models.Manager()
In this example, ``Person.objects.all()`` will generate an error, but In this example, ``Person.objects.all()`` will generate an error, but
``Person.people.all()`` will provide a list of all ``Person`` objects. ``Person.people.all()`` will provide a list of all ``Person`` objects.
Managers can also be customized. This is achieved by extending the Managers can also be customized. This is achieved by extending the
base Manager class, and instantiating the new Manager on your model. base Manager class, and instantiating the new Manager on your model.
There are two reasons that you may want to customize a Manager: firstly, There are two reasons that you may want to customize a Manager: firstly,
to add utility methods to the Manager, and secondly, to modify the to add utility methods to the Manager, and secondly, to modify the
initial Query Set provided by the Manager. initial Query Set provided by the Manager.
To modify the initial Query Set provided by a Manager, override the To modify the initial Query Set provided by a Manager, override the
@ -1047,11 +1055,11 @@ you require. For example::
# Add some custom behavior to the Manager # Add some custom behavior to the Manager
def move_house(self): def move_house(self):
# Some logic to help a person move house # Some logic to help a person move house
# Modify the initial Query Set provided by the manager # Modify the initial Query Set provided by the manager
def get_query_set(self): def get_query_set(self):
return super(Manager, self).get_query_set().filter(name__startswith="Fred") return super(Manager, self).get_query_set().filter(name__startswith="Fred")
class Person(models.Model): class Person(models.Model):
#... #...
objects = PersonManager() objects = PersonManager()
@ -1070,20 +1078,20 @@ to define common filters types for your models. For example, the model::
class FemaleManager(models.Manager): class FemaleManager(models.Manager):
def get_query_set(self): def get_query_set(self):
return super(Manager, self).get_query_set().filter(sex='F') return super(Manager, self).get_query_set().filter(sex='F')
class Person(models.Model): class Person(models.Model):
#... #...
people = models.Manager() people = models.Manager()
men = MaleManager() men = MaleManager()
women = FemaleManager() women = FemaleManager()
... will allow end users to request ``Person.men.all()``, ``Person.women.all()``, ... will allow end users to request ``Person.men.all()``, ``Person.women.all()``,
and ``Person.people.all()``, yielding predictable results. and ``Person.people.all()``, yielding predictable results.
If you are going to install a customized Manager, be warned that the first If you are going to install a customized Manager, be warned that the first
Manager that Django encounters in a model definition has special status. Manager that Django encounters in a model definition has special status.
Django interprets the first Manager defined in a class as the default Manager. Django interprets the first Manager defined in a class as the default Manager.
Certain operations use the default Manager to obtain lists of objects, so it Certain operations use the default Manager to obtain lists of objects, so it
is generally a good idea for the first Manager to be relatively unfiltered. is generally a good idea for the first Manager to be relatively unfiltered.
In the last example, ``people`` is defined first - so the default Manager In the last example, ``people`` is defined first - so the default Manager
will include everyone. will include everyone.
@ -1147,7 +1155,7 @@ A few object methods have special meaning:
Module-level methods Module-level methods
-------------------- --------------------
If you want to add a method to the Model, rather than instances of the model, If you want to add a method to the Model, rather than instances of the model,
you can use the Python ``staticmethod`` and ``classmethod`` operators. For you can use the Python ``staticmethod`` and ``classmethod`` operators. For
example:: example::
@ -1157,14 +1165,14 @@ example::
def get_pizzas_to_deliver(): def get_pizzas_to_deliver():
return get_list(delivered__exact=False) return get_list(delivered__exact=False)
get_pizzas_to_deliver = staticmethod(get_pizzas_to_deliver) get_pizzas_to_deliver = staticmethod(get_pizzas_to_deliver)
Or, using Python 2.4 decorators:: Or, using Python 2.4 decorators::
# ... # ...
@staticmethod @staticmethod
def get_pizzas_to_deliver(): def get_pizzas_to_deliver():
# ... # ...
This will make the top-level ``pizzas`` module have a ``get_pizzas_to_deliver()`` This will make the top-level ``pizzas`` module have a ``get_pizzas_to_deliver()``
method:: method::
@ -1195,7 +1203,7 @@ Executing custom SQL
Feel free to write custom SQL statements in custom model methods and Feel free to write custom SQL statements in custom model methods and
module-level methods. The object ``django.db.connection`` object represents module-level methods. The object ``django.db.connection`` object represents
the current database connection. To use it, call ``connection.cursor()`` to the current database connection. To use it, call ``connection.cursor()`` to
get a cursor object. Then, call ``cursor.execute(sql, [params])`` get a cursor object. Then, call ``cursor.execute(sql, [params])``
to execute the SQL and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return to execute the SQL and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return
the resulting rows. Example:: the resulting rows. Example::
@ -1234,11 +1242,11 @@ Using models
============ ============
Once you have created your model, you have to tell Django about your new application. Once you have created your model, you have to tell Django about your new application.
This is done by editing your settings file and adding the name of the module that This is done by editing your settings file and adding the name of the module that
contains your models module to the ``INSTALLED_APPS`` tuple. contains your models module to the ``INSTALLED_APPS`` tuple.
For example, if the models for your application are contained in the module For example, if the models for your application are contained in the module
``project.myapp.models`` (the package structure that is created for an application ``project.myapp.models`` (the package structure that is created for an application
by the ``django-admin.py startapp`` script), ``INSTALLED_APPS`` should read, in part:: by the ``django-admin.py startapp`` script), ``INSTALLED_APPS`` should read, in part::
INSTALLED_APPS = ( INSTALLED_APPS = (
@ -1251,7 +1259,7 @@ Models across files
=================== ===================
It's perfectly OK to relate a model to one from another module. To do this, It's perfectly OK to relate a model to one from another module. To do this,
just import the model module at the top of your model module. Then, just just import the model module at the top of your model module. Then, just
refer to the other model class wherever needed. For example:: refer to the other model class wherever needed. For example::
from myproject.otherapp import Site from myproject.otherapp import Site