add select_related, get, and get_or_create comparisons (piccolo-orm#223)

Author: dantownsend

docs/src/piccolo/query_types/django_comparison.rst

@@ -6,9 +6,51 @@ Django Comparison
 Here are some common queries, showing how they're done in Django vs Piccolo.
 All of the Piccolo examples can also be run :ref:`asynchronously<SyncAndAsync>`.
 
+-------------------------------------------------------------------------------
+
 Queries
 -------
 
+get
+~~~
+
+They are very similar, except Django raises an ``ObjectDoesNotExist`` exception
+if no match is found, whilst Piccolo returns ``None``.
+
+.. code-block:: python
+
+    # Django
+    >>> Band.objects.get(name="Pythonistas")
+    <Band: 1>
+    >>> Band.objects.get(name="DOESN'T EXIST")  # ObjectDoesNotExist!
+
+    # Piccolo
+    >>> Band.objects().get(Band.name == 'Pythonistas').run_sync()
+    <Band: 1>
+    >>> Band.objects().get(Band.name == "DOESN'T EXIST").run_sync()
+    None
+
+
+get_or_create
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    # Django
+    band, created = Band.objects.get_or_create(name="Pythonistas")
+    >>> band
+    <Band: 1>
+    >>> created
+    True
+
+    # Piccolo
+    >>> band = Band.objects().get_or_create(Band.name == 'Pythonistas').run_sync()
+    >>> band
+    <Band: 1>
+    >>> band._was_created
+    True
+
+
 create
 ~~~~~~
 
@@ -39,7 +81,7 @@ update
     >>> band.save()
 
     # Piccolo
-    >>> band = Band.objects().where(Band.name == 'Pythonistas').first().run_sync()
+    >>> band = Band.objects().get(Band.name == 'Pythonistas').run_sync()
     >>> band
     <Band: 1>
     >>> band.name = "Amazing Band"
@@ -57,7 +99,7 @@ Individual rows:
     >>> band.delete()
 
     # Piccolo
-    >>> band = Band.objects().where(Band.name == 'Pythonistas').first().run_sync()
+    >>> band = Band.objects().get(Band.name == 'Pythonistas').run_sync()
     >>> band.remove().run_sync()
 
 In bulk:
@@ -68,7 +110,7 @@ In bulk:
     >>> Band.objects.filter(popularity__lt=1000).delete()
 
     # Piccolo
-    >>> Band.delete().where(Band.popularity < 1000).delete().run_sync()
+    >>> Band.delete().where(Band.popularity < 1000).run_sync()
 
 filter
 ~~~~~~
@@ -108,6 +150,34 @@ With ``flat=True``:
     >>> Band.select(Band.name).output(as_list=True).run_sync()
     ['Pythonistas', 'Rustaceans']
 
+select_related
+~~~~~~~~~~~~~~
+
+Django has an optimisation called ``select_related`` which reduces the number
+of SQL queries required when accessing related objects.
+
+.. code-block:: python
+
+    # Django
+    band = Band.objects.get(name='Pythonistas')
+    >>> band.manager  # This triggers another db query
+    <Manager: 1>
+
+    # Django, with select_related
+    band = Band.objects.select_related('manager').get(name='Pythonistas')
+    >>> band.manager  # Manager is pre-cached, so there's no extra db query
+    <Manager: 1>
+
+Piccolo has something similar:
+
+.. code-block:: python
+
+    # Piccolo
+    band = Band.objects(Band.manager).get(name='Pythonistas')
+    >>> band.manager
+    <Manager: 1>
+
+
 -------------------------------------------------------------------------------
 
 Database Settings