Django

Code

Changeset 2750

Show
Ignore:
Timestamp:
04/27/06 00:51:56 (3 years ago)
Author:
adrian
Message:

magic-removal: More changes to docs/db-api.txt. Not done yet.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/branches/magic-removal/docs/db-api.txt

    r2749 r2750  
    754754   information, see `Keyword Arguments`_ in the official Python tutorial. 
    755755 
     756   .. _`Keyword Arguments`: http://docs.python.org/tut/node6.html#SECTION006720000000000000000 
     757 
     758If you pass an invalid keyword argument, a lookup function will raise 
     759``TypeError``. 
     760 
    756761The database API supports the following lookup types: 
    757762 
    …… 
    937942~~~~ 
    938943 
    939 For date/datetime fields, exact year match. 
     944For date/datetime fields, exact year match. Takes a four-digit year. 
    940945 
    941946Example:: 
    …… 
    949954(The exact SQL syntax varies for each database engine.) 
    950955 
    951  
    952 TODO: Left off here 
    953  
    954     ===========  ============================================================== 
    955     Type         Description 
    956     ===========  ============================================================== 
    957     month        For date/datetime fields, exact month match. 
    958     day          For date/datetime fields, exact day match. 
    959     isnull       True/False; does is IF NULL/IF NOT NULL lookup: 
    960                  ``Poll.objects.filter(expire_date__isnull=True)``. 
    961     ===========  ============================================================== 
     956month 
     957~~~~~ 
     958 
     959For date/datetime fields, exact month match. Takes an integer 1 (January) 
     960through 12 (December). 
     961 
     962Example:: 
     963 
     964    Entry.objects.filter(pub_date__month=12) 
     965 
     966SQL equivalent:: 
     967 
     968    SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12'; 
     969 
     970(The exact SQL syntax varies for each database engine.) 
     971 
     972day 
     973~~~ 
     974 
     975For date/datetime fields, exact day match. 
     976 
     977Example:: 
     978 
     979    Entry.objects.filter(pub_date__day=3) 
     980 
     981SQL equivalent:: 
     982 
     983    SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3'; 
     984 
     985(The exact SQL syntax varies for each database engine.) 
     986 
     987Note this will match any record with a pub_date on the third day of the month, 
     988such as January 3, July 3, etc. 
     989 
     990isnull 
     991~~~~~~ 
     992 
     993``NULL`` or ``IS NOT NULL`` match. Takes either ``True`` or ``False``, which 
     994correspond to ``IS NULL`` and ``IS NOT NULL``, respectively. 
     995 
     996Example:: 
     997 
     998    Entry.objects.filter(pub_date__isnull=True) 
     999 
     1000SQL equivalent:: 
     1001 
     1002    SELECT ... WHERE pub_date IS NULL; 
     1003 
     1004Default lookups are exact 
     1005~~~~~~~~~~~~~~~~~~~~~~~~~ 
     1006 
     1007If you don't provide a lookup type -- that is, if your keyword argument doesn't 
     1008contain a double underscore -- the lookup type is assumed to be ``exact``. 
     1009 
     1010For example, the following two statements are equivalent:: 
     1011 
     1012    Blog.objects.get(id=14) 
     1013    Blog.objects.get(id__exact=14) 
     1014 
     1015This is for convenience, because ``exact`` lookups are the common case. 
     1016 
     1017The pk lookup shortcut 
     1018~~~~~~~~~~~~~~~~~~~~~~ 
     1019 
     1020For convenience, Django provides a ``pk`` lookup type, which stands for 
     1021"primary_key". This is shorthand for "an exact lookup on the primary-key." 
     1022 
     1023In the example ``Blog`` model, the primary key is the ``id`` field, so these 
     1024two statements are equivalent:: 
     1025 
     1026    Blog.objects.get(id__exact=14) 
     1027    Blog.objects.get(pk=14) 
     1028 
     1029``pk`` lookups also work across joins. For example, these two statements are 
     1030equivalent:: 
     1031 
     1032    Entry.objects.filter(blog__id__exact=3) 
     1033    Entry.objects.filter(blog__pk=3) 
    9621034 
    9631035Escaping parenthesis and underscores in LIKE statements 
    9641036~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    9651037 
    966 As you may expect, 
    967  
    968  
    969  
    970  
    971  
    972  
    973 If no lookup type is provided, a type of ``exact`` is assumed. The following 
    974 two statements are equivalent:: 
    975  
    976     Poll.objects.get(id=14) 
    977     Poll.objects.get(id__exact=14) 
    978  
    979 Multiple lookup parameters are allowed. When separated by commans, the list of 
    980 lookup parameters will be "AND"ed together:: 
    981  
    982     Poll.objects.filter( 
    983         pub_date__year=2005, 
    984         pub_date__month=1, 
    985         question__startswith="Would", 
    986     ) 
    987  
    988 ...retrieves all polls published in January 2005 that have a question starting 
    989 with "Would." 
    990  
    991 For convenience, there's a ``pk`` lookup type, which translates into 
    992 ``(primary_key)``. In the polls example, these two statements are 
    993 equivalent:: 
    994  
    995     Poll.objects.get(id__exact=3) 
    996     Poll.objects.get(pk=3) 
    997  
    998 ``pk`` lookups also work across joins. In the polls example, these two 
    999 statements are equivalent:: 
    1000  
    1001     Choice.objects.filter(poll__id=3) 
    1002     Choice.objects.filter(poll__pk=3) 
    1003  
    1004 If you pass an invalid keyword argument, the function will raise ``TypeError``. 
    1005  
    1006 .. _`Keyword Arguments`: http://docs.python.org/tut/node6.html#SECTION006720000000000000000 
     1038The field lookups that equate to ``LIKE`` SQL statements will automatically 
     1039escape the two special characters used in ``LIKE`` statements -- the percent 
     1040sign and the underscore. (In a ``LIKE`` statement, the percent sign signifies 
     1041a multiple-character wildcard and the underscore signifies a single-character 
     1042wildcard.) 
     1043 
     1044This means things should work intuitively, so the abstraction doesn't leak. 
     1045For example, to retrieve all the entries that contain a percent sign, just use 
     1046the percent sign as any other character:: 
     1047 
     1048    Entry.objects.filter(headline__contains='%') 
     1049 
     1050Django takes care of the quoting for you; the resulting SQL will look something 
     1051like this:: 
     1052 
     1053    SELECT ... WHERE headline LIKE '%\%%'; 
     1054 
     1055Same goes for underscores. Both percentage signs and underscores are handled 
     1056for you transparently. 
    10071057 
    10081058Caching and QuerySets 
    …… 
    10371087    print [p.pub_date for p in queryset] # Re-use the cache from the evaluation. 
    10381088 
    1039  
    1040  
    1041 Deleting objects 
    1042 ================ 
    1043  
    1044  
     1089Comparing objects 
     1090================= 
     1091 
     1092To compare two model instances, just use the standard Python comparison operator, 
     1093the double equals sign: ``==``. Behind the scenes, that compares the primary 
     1094key values of two models. 
     1095 
     1096Using the ``Entry`` example above, the following two statements are equivalent:: 
     1097 
     1098    some_entry == other_entry 
     1099    some_entry.id == other_entry.id 
     1100 
     1101If a model's primary key isn't called ``id``, no problem. Comparisons will 
     1102always use the primary key, whatever it's called. For example, if a model's 
     1103primary key field is called ``name``, these two statements are equivalent:: 
     1104 
     1105    some_obj == other_obj 
     1106    some_obj.name == other_obj.name 
     1107 
     1108 
     1109 
     1110 
     1111======================================== 
     1112THE REST OF THIS HAS NOT YET BEEN EDITED 
     1113======================================== 
    10451114 
    10461115 
    …… 
    12701339and conditions required for the SQL query. 
    12711340 
    1272 Creating new objects 
    1273 ==================== 
    1274  
    1275 Creating new objects (i.e. ``INSERT``) is done by creating new instances 
    1276 of objects then calling save() on them:: 
    1277  
    1278     >>> p = Poll(slug="eggs", 
    1279     ...                question="How do you like your eggs?", 
    1280     ...                pub_date=datetime.datetime.now(), 
    1281     ...                expire_date=some_future_date) 
    1282     >>> p.save() 
    1283  
    1284 Calling ``save()`` on an object with a primary key whose value is ``None`` 
    1285 signifies to Django that the object is new and should be inserted. 
     1341Creating new related objects 
     1342============================ 
    12861343 
    12871344Related objects are created using the ``create()`` convenience function on 
    …… 
    13291386 
    13301387    Polls.objects.all().delete() 
    1331  
    1332 Comparing objects 
    1333 ================= 
    1334  
    1335 To compare two model objects, just use the standard Python comparison operator, 
    1336 the double equals sign: ``==``. Behind the scenes, that compares the primary 
    1337 key values of two models. 
    1338  
    1339 Using the ``Poll`` example above, the following two statements are equivalent:: 
    1340  
    1341     some_poll == other_poll 
    1342     some_poll.id == other_poll.id 
    1343  
    1344 If a model's primary key isn't called ID, no problem. Comparisons will always 
    1345 use the primary key, whatever it's called. For example, if a model's primary 
    1346 key field is called ``name``, these two statements are equivalent:: 
    1347  
    1348     some_obj == other_obj 
    1349     some_obj.name == other_obj.name 
    13501388 
    13511389Extra instance methods