From e05d31eaaf4e275b0f1f3af2bdd36ee74181f105 Mon Sep 17 00:00:00 2001
From: Harry Marr <harry.marr@gmail.com>
Date: Sun, 31 Jan 2010 13:47:27 +0000
Subject: [PATCH] Added get{,_or_create} docs

---
 docs/guide/querying.rst | 35 +++++++++++++++++++++++++++++++++++
 docs/index.rst          |  5 +++++
 mongoengine/queryset.py |  7 ++-----
 3 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst
index 10712047..0742244d 100644
--- a/docs/guide/querying.rst
+++ b/docs/guide/querying.rst
@@ -86,6 +86,41 @@ achieving this is using array-slicing syntax::
     # 5 users, starting from the 10th user found
     users = User.objects[10:15]
 
+You may also index the query to retrieve a single result. If an item at that
+index does not exists, an :class:`IndexError` will be raised. A shortcut for
+retrieving the first result and returning :attr:`None` if no result exists is
+provided (:meth:`~mongoengine.queryset.QuerySet.first`)::
+    
+    >>> # Make sure there are no users
+    >>> User.drop_collection()
+    >>> User.objects[0]
+    IndexError: list index out of range
+    >>> User.objects.first() == None
+    True
+    >>> User(name='Test User').save()
+    >>> User.objects[0] == User.objects.first()
+    True
+
+Retrieving unique results
+-------------------------
+To retrieve a result that should be unique in the collection, use
+:meth:`~mongoengine.queryset.QuerySet.get`. This will raise
+:class:`~mongoengine.queryset.DoesNotExist` if no document matches the query,
+and :class:`~mongoengine.queryset.MultipleObjectsReturned` if more than one
+document matched the query.
+
+A variation of this method exists, 
+:meth:`~mongoengine.queryset.Queryset.get_or_create`, that will create a new
+document with the query arguments if no documents match the query. An 
+additional keyword argument, :attr:`defaults` may be provided, which will be
+used as default values for the new document, in the case that it should need
+to be created::
+
+    >>> a = User.objects.get_or_create(name='User A', defaults={'age': 30})
+    >>> b = User.objects.get_or_create(name='User A', defaults={'age': 40})
+    >>> a.name == b.name and a.age == b.age
+    True
+
 Default Document queries
 ========================
 By default, the objects :attr:`~mongoengine.Document.objects` attribute on a
diff --git a/docs/index.rst b/docs/index.rst
index 1205e4b9..6e0db8b0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,11 @@ MongoDB. To install it, simply run
 
 The source is available on `GitHub <http://github.com/hmarr/mongoengine>`_.
 
+If you are interested in contributing, join the developers' `mailing list 
+<http://groups.google.com/group/mongoengine-dev>`_. Some of us also like to
+hang out at `#mongoengine IRC channel <irc://irc.freenode.net/mongoengine>`_.
+
+
 .. toctree::
    :maxdepth: 2
 
diff --git a/mongoengine/queryset.py b/mongoengine/queryset.py
index 9764c699..f2405b82 100644
--- a/mongoengine/queryset.py
+++ b/mongoengine/queryset.py
@@ -10,6 +10,7 @@ __all__ = ['queryset_manager', 'Q', 'InvalidQueryError',
 # The maximum number of items to display in a QuerySet.__repr__
 REPR_OUTPUT_SIZE = 20
 
+
 class DoesNotExist(Exception):
 	pass
 
@@ -21,14 +22,10 @@ class MultipleObjectsReturned(Exception):
 class InvalidQueryError(Exception):
     pass
 
+
 class OperationError(Exception):
     pass
 
-class MultipleObjectsReturned(Exception):
-    pass
-
-class DoesNotExist(Exception):
-    pass
 
 class Q(object):