Added docstrings to shortcuts module and functions.

gdub · gdub · commit d95e91b380a7 · 2007-07-22T03:09:24.000Z
git-svn-id: http://code.djangoproject.com/svn/django/trunk@5744 bcc190cf-cafb-0310-a4f2-bffc1f526a37
diff --git a/django/shortcuts/__init__.py b/django/shortcuts/__init__.py
@@ -1,16 +1,32 @@
-# This module collects helper functions and classes that "span" multiple levels
-# of MVC. In other words, these functions/classes introduce controlled coupling
-# for convenience's sake.
+"""
+This module collects helper functions and classes that "span" multiple levels
+of MVC. In other words, these functions/classes introduce controlled coupling
+for convenience's sake.
+"""
 
 from django.template import loader
 from django.http import HttpResponse, Http404
 from django.db.models.manager import Manager
 
 def render_to_response(*args, **kwargs):
+    """
+    Return a HttpResponse whose content is filled with the result of calling
+    django.template.loader.render_to_string() with the passed arguments.
+    """
     return HttpResponse(loader.render_to_string(*args, **kwargs))
 load_and_render = render_to_response # For backwards compatibility.
 
 def get_object_or_404(klass, *args, **kwargs):
+    """
+    Use get() to return an object, or raise a Http404 exception if the object
+    does not exist.
+
+    klass may be a Model, Manager, or QuerySet object.  All other passed
+    arguments and keyword arguments are used in the get() query.
+
+    Note: Like with get(), an AssertionError will be raised if more than one
+    object is found.
+    """
     if isinstance(klass, Manager):
         manager = klass
         klass = manager.model
@@ -22,6 +38,13 @@ def get_object_or_404(klass, *args, **kwargs):
         raise Http404('No %s matches the given query.' % klass._meta.object_name)
 
 def get_list_or_404(klass, *args, **kwargs):
+    """
+    Use filter() to return a list of objects, or raise a Http404 exception if
+    the list is empty.
+
+    klass may be a Model, Manager, or QuerySet object.  All other passed
+    arguments and keyword arguments are used in the filter() query.
+    """
     if isinstance(klass, Manager):
         manager = klass
     else:
