Fixed #163 -- Added 'pk' database API option, which is a shorthand for (primary_key)__exact

git-svn-id: http://code.djangoproject.com/svn/django/trunk@316 bcc190cf-cafb-0310-a4f2-bffc1f526a37

4 files changed, 41 insertions, 16 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 401d9d3260..cb5ec4783f 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -97,6 +97,19 @@ Multiple lookups are allowed, of course, and are translated as "AND"s::
 
 ...retrieves all polls published in January 2005 that have a question starting with "Would."
 
+For convenience, there's a ``pk`` lookup type, which translates into
+``(primary_key)__exact``. In the polls example, these two statements are
+equivalent::
+
+    polls.get_object(id__exact=3)
+    polls.get_object(pk=3)
+
+``pk`` lookups also work across joins. In the polls example, these two
+statements are equivalent::
+
+    choices.get_list(poll__id__exact=3)
+    choices.get_list(poll__pk=3)
+
 Ordering
 ========
 
diff --git a/docs/overview.txt b/docs/overview.txt
index 86f089778d..7fba5e1767 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -93,6 +93,12 @@ is created on the fly: No code generation necessary::
         ...
     django.models.news.ReporterDoesNotExist: Reporter does not exist for {'id__exact': 2}
 
+    # Lookup by a primary key is the most common case, so Django provides a
+    # shortcut for primary-key exact lookups.
+    # The following is identical to reporters.get_object(id__exact=1).
+    >>> reporters.get_object(pk=1)
+    John Smith
+
     # Create an article.
     >>> from datetime import datetime
     >>> a = articles.Article(id=None, pub_date=datetime.now(), headline='Django is cool', article='Yeah.', reporter_id=1)
@@ -200,7 +206,7 @@ article_detail from above::
     def article_detail(request, year, month, article_id):
         # Use the Django API to find an object matching the URL criteria.
         try:
-            a = articles.get_object(pub_date__year=year, pub_date__month=month, id__exact=article_id)
+            a = articles.get_object(pub_date__year=year, pub_date__month=month, pk=article_id)
         except articles.ArticleDoesNotExist:
             raise Http404
         t = template_loader.get_template('news/article_detail')
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 4e377bd97d..e92e9c2ccd 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -49,10 +49,10 @@ settings. Let's look at what ``startproject`` created::
 First, edit ``myproject/settings/main.py``. It's a normal Python module with
 module-level variables representing Django settings. Edit the file and change
 these settings to match your database's connection parameters:
-    
-    * ``DATABASE_ENGINE`` -- Either 'postgresql', 'mysql' or 'sqlite3'. 
+
+    * ``DATABASE_ENGINE`` -- Either 'postgresql', 'mysql' or 'sqlite3'.
       More coming soon.
-    * ``DATABASE_NAME`` -- The name of your database, or the full path to 
+    * ``DATABASE_NAME`` -- The name of your database, or the full path to
       the database file if using sqlite.
     * ``DATABASE_USER`` -- Your database username (not used for sqlite).
     * ``DATABASE_PASSWORD`` -- Your database password (not used for sqlite).
@@ -134,7 +134,7 @@ The first step in writing a database Web app in Django is to define your models
 -- essentially, your database layout, with additional metadata.
 
 .. admonition:: Philosophy
-   
+
    A model is the single, definitive source of data about your
    data. It contains the essential fields and behaviors of the data you're
    storing. Django follows the `DRY Principle`_. The goal is to define your
@@ -243,11 +243,11 @@ Note the following:
     * Table names are automatically generated by combining the name of the app
       (polls) with a plural version of the object name (polls and choices). (You
       can override this behavior.)
-      
+
     * Primary keys (IDs) are added automatically. (You can override this, too.)
-    
+
     * The foreign key relationship is made explicit by a ``REFERENCES`` statement.
-    
+
     * It's tailored to the database you're using, so database-specific field types
       such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or ``integer
       primary key`` (SQLite) are handled for you automatically. The author of
@@ -256,16 +256,16 @@ Note the following:
 
 If you're interested, also run the following commands:
 
-    * ``django-admin.py sqlinitialdata polls`` -- Outputs the initial-data 
+    * ``django-admin.py sqlinitialdata polls`` -- Outputs the initial-data
       inserts required for Django's admin framework.
-    
-    * ``django-admin.py sqlclear polls`` -- Outputs the necessary ``DROP 
+
+    * ``django-admin.py sqlclear polls`` -- Outputs the necessary ``DROP
       TABLE`` statements for this app, according to which tables already exist
       in your database (if any).
-      
+
     * ``django-admin.py sqlindexes polls`` -- Outputs the ``CREATE INDEX``
       statements for this app.
-    
+
     * ``django-admin.py sqlall polls`` -- A combination of 'sql' and
       'sqlinitialdata'.
 
@@ -372,14 +372,20 @@ Let's jump back into the Python interactive shell::
     >>> polls.get_list(question__startswith='What')
     [What's up]
 
+    # Lookup by a primary key is the most common case, so Django provides a
+    # shortcut for primary-key exact lookups.
+    # The following is identical to polls.get_object(id__exact=1).
+    >>> polls.get_object(pk=1)
+    What's up
+
     # Make sure our custom method worked.
-    >>> p = polls.get_object(id__exact=1)
+    >>> p = polls.get_object(pk=1)
     >>> p.was_published_today()
     False
 
     # Give the Poll a couple of Choices. Each one of these method calls does an
     # INSERT statement behind the scenes and returns the new Choice object.
-    >>> p = polls.get_object(id__exact=1)
+    >>> p = polls.get_object(pk=1)
     >>> p.add_choice(choice='Not much', votes=0)
     Not much
     >>> p.add_choice(choice='The sky', votes=0)
diff --git a/docs/tutorial03.txt b/docs/tutorial03.txt
index 1c547a670f..3f2f97b7b1 100644
--- a/docs/tutorial03.txt
+++ b/docs/tutorial03.txt
@@ -242,7 +242,7 @@ for a given poll. Here's the view::
     from django.core.exceptions import Http404
     def detail(request, poll_id):
         try:
-            p = polls.get_object(id__exact=poll_id)
+            p = polls.get_object(pk=poll_id)
         except polls.PollDoesNotExist:
             raise Http404
         t = template_loader.get_template('polls/detail')