Changeset 2755
- Timestamp:
- 04/27/06 17:12:05 (2 years ago)
- Files:
-
- django/branches/magic-removal/docs/model-api.txt (modified) (18 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/branches/magic-removal/docs/model-api.txt
r2708 r2755 22 22 23 23 The most important part of a model is the list of database fields it defines. 24 Fields are defined by class attributes. 24 Fields are defined by class attributes. 25 25 26 26 In this example, there are two fields, ``first_name`` and ``last_name`` :: … … 56 56 Convention is not to capitalize the first letter of the ``verbose_name``. 57 57 Django will automatically capitalize the first letter where it needs to. 58 59 Field name restrictions 60 ----------------------- 61 62 TODO: Fill this section. 63 64 * Can't be Python reserved word. 65 * Can't have more than one underscore in a row, due to query lookup. 58 66 59 67 General field options … … 492 500 493 501 If you need to create a relationship on a model that has not yet been defined, 494 you can use the name of the model, rather than the model object itself:: 502 you can use the name of the model, rather than the model object itself:: 495 503 496 504 class Place(models.Model): … … 502 510 503 511 The name of a ``ForeignKey`` (``city`` in the example above) generally should 504 be the name of the model, in singular form. Behind the scenes, Django appends 505 "_id" to the field name to create its database column name. However, your code 506 should never have to deal with the database column name, unless you write 512 be the name of the model, in singular form. Behind the scenes, Django appends 513 "_id" to the field name to create its database column name. However, your code 514 should never have to deal with the database column name, unless you write 507 515 custom SQL. 508 516 … … 599 607 600 608 ...which would give ``Category`` objects two Object Set 601 descriptors - one called ``primary_stories`` and one 609 descriptors - one called ``primary_stories`` and one 602 610 called ``secondary_stories``. 603 611 … … 679 687 parameter to change this, which is if you want one model to 680 688 have multiple ``ManyToMany`` relationships to another model. 681 689 682 690 ``symmetrical`` Only used in the definition of ManyToManyFields on self. 683 691 Consider the following model: 684 692 685 693 class Person(models.Model): 686 694 friends = models.ManyToManyField("self") 687 695 688 696 When Django processes this model, it identifies that it has 689 697 a ManyToManyField on itself, and as a result, it doesn't add 690 698 a ``person_set`` attribute to the Person class. Instead, the 691 ManyToManyField is assumed to be symmetrical - that is, if 692 I am your friend, then you are my friend. 693 694 If you do not want symmetry in ManyToMany relationships with 695 self, set ``symmetrical`` to False. This will force Django to 696 add the descriptor for the reverse relationship, allow 697 ManyToMany relationships to be non-symmetrical. 698 699 ManyToManyField is assumed to be symmetrical - that is, if 700 I am your friend, then you are my friend. 701 702 If you do not want symmetry in ManyToMany relationships with 703 self, set ``symmetrical`` to False. This will force Django to 704 add the descriptor for the reverse relationship, allow 705 ManyToMany relationships to be non-symmetrical. 706 699 707 ======================= ============================================================ 700 708 … … 710 718 711 719 ``OneToOneField`` requires a positional argument: The class to which the 712 model is related. 720 model is related. 713 721 714 722 For example, if you're building a database of "places", you would build pretty … … 861 869 ============= 862 870 863 If you want your model to be visible to the automatic Administration 871 If you want your model to be visible to the automatic Administration 864 872 system, your model must have an inner ``"class Admin"``, like so:: 865 873 … … 870 878 # ... 871 879 872 The Admin class gives instructions to Django on how to display the Model 880 The Admin class gives instructions to Django on how to display the Model 873 881 to the Administration system. 874 882 … … 1014 1022 ======== 1015 1023 1016 The Manager is the interface through which database query operations 1024 The Manager is the interface through which database query operations 1017 1025 are provided to Django applications. At least one Manager exists for 1018 1026 every model in a Django application. 1019 1027 1020 By default, Django will add a Manager with the name of ``objects`` to 1028 By default, Django will add a Manager with the name of ``objects`` to 1021 1029 every Django model. However, if you wish to use ``objects`` as a field 1022 1030 name, or if you wish to use a name other than ``objects`` for the Manager, 1023 you can rename the Manager on a per-model basis. To rename the Manager 1024 for a given class, define a class attribute of type models.Manager() 1031 you can rename the Manager on a per-model basis. To rename the Manager 1032 for a given class, define a class attribute of type models.Manager() 1025 1033 on that model. For example:: 1026 1034 1027 1035 from django.db import models 1028 1036 1029 1037 class Person(models.Model): 1030 1038 #... 1031 1039 people = models.Manager() 1032 1040 1033 In this example, ``Person.objects.all()`` will generate an error, but 1041 In this example, ``Person.objects.all()`` will generate an error, but 1034 1042 ``Person.people.all()`` will provide a list of all ``Person`` objects. 1035 1043 1036 1044 Managers can also be customized. This is achieved by extending the 1037 1045 base Manager class, and instantiating the new Manager on your model. 1038 There are two reasons that you may want to customize a Manager: firstly, 1039 to add utility methods to the Manager, and secondly, to modify the 1046 There are two reasons that you may want to customize a Manager: firstly, 1047 to add utility methods to the Manager, and secondly, to modify the 1040 1048 initial Query Set provided by the Manager. 1041 1049 … … 1048 1056 def move_house(self): 1049 1057 # Some logic to help a person move house 1050 1058 1051 1059 # Modify the initial Query Set provided by the manager 1052 1060 def get_query_set(self): 1053 1061 return super(Manager, self).get_query_set().filter(name__startswith="Fred") 1054 1062 1055 1063 class Person(models.Model): 1056 1064 #... … … 1071 1079 def get_query_set(self): 1072 1080 return super(Manager, self).get_query_set().filter(sex='F') 1073 1081 1074 1082 class Person(models.Model): 1075 1083 #... … … 1078 1086 women = FemaleManager() 1079 1087 1080 ... will allow end users to request ``Person.men.all()``, ``Person.women.all()``, 1088 ... will allow end users to request ``Person.men.all()``, ``Person.women.all()``, 1081 1089 and ``Person.people.all()``, yielding predictable results. 1082 1090 1083 1091 If you are going to install a customized Manager, be warned that the first 1084 1092 Manager that Django encounters in a model definition has special status. 1085 Django interprets the first Manager defined in a class as the default Manager. 1086 Certain operations use the default Manager to obtain lists of objects, so it 1093 Django interprets the first Manager defined in a class as the default Manager. 1094 Certain operations use the default Manager to obtain lists of objects, so it 1087 1095 is generally a good idea for the first Manager to be relatively unfiltered. 1088 1096 In the last example, ``people`` is defined first - so the default Manager … … 1148 1156 -------------------- 1149 1157 1150 If you want to add a method to the Model, rather than instances of the model, 1158 If you want to add a method to the Model, rather than instances of the model, 1151 1159 you can use the Python ``staticmethod`` and ``classmethod`` operators. For 1152 1160 example:: … … 1158 1166 return get_list(delivered__exact=False) 1159 1167 get_pizzas_to_deliver = staticmethod(get_pizzas_to_deliver) 1160 1168 1161 1169 Or, using Python 2.4 decorators:: 1162 1170 1163 1171 # ... 1164 1172 @staticmethod 1165 1173 def get_pizzas_to_deliver(): 1166 1174 # ... 1167 1175 1168 1176 This will make the top-level ``pizzas`` module have a ``get_pizzas_to_deliver()`` 1169 1177 method:: … … 1196 1204 Feel free to write custom SQL statements in custom model methods and 1197 1205 module-level methods. The object ``django.db.connection`` object represents 1198 the current database connection. To use it, call ``connection.cursor()`` to 1206 the current database connection. To use it, call ``connection.cursor()`` to 1199 1207 get a cursor object. Then, call ``cursor.execute(sql, [params])`` 1200 1208 to execute the SQL and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return … … 1235 1243 1236 1244 Once you have created your model, you have to tell Django about your new application. 1237 This is done by editing your settings file and adding the name of the module that 1238 contains your models module to the ``INSTALLED_APPS`` tuple. 1239 1240 For example, if the models for your application are contained in the module 1241 ``project.myapp.models`` (the package structure that is created for an application 1245 This is done by editing your settings file and adding the name of the module that 1246 contains your models module to the ``INSTALLED_APPS`` tuple. 1247 1248 For example, if the models for your application are contained in the module 1249 ``project.myapp.models`` (the package structure that is created for an application 1242 1250 by the ``django-admin.py startapp`` script), ``INSTALLED_APPS`` should read, in part:: 1243 1251 … … 1252 1260 1253 1261 It's perfectly OK to relate a model to one from another module. To do this, 1254 just import the model module at the top of your model module. Then, just 1262 just import the model module at the top of your model module. Then, just 1255 1263 refer to the other model class wherever needed. For example:: 1256 1264
