improved docs - added comparable Django queries

- Added a new page showing the equivalent of common Django queries in Piccolo.
- Renamed `Create` query page to `Create Table`.
- General tidy up.

Author: dantownsend

docs/src/piccolo/getting_started/example_schema.rst

@@ -8,7 +8,7 @@ This is the schema used by the example queries throughout the docs.
 .. code-block:: python
 
     from piccolo.table import Table
-    from piccolo.columns import ForeignKey, Varchar
+    from piccolo.columns import ForeignKey, Integer, Varchar
 
 
     class Manager(Table):
@@ -18,5 +18,6 @@ This is the schema used by the example queries throughout the docs.
     class Band(Table):
         name = Varchar(length=100)
         manager = Varchar(length=100)
+        popularity = Integer()
 
 To understand more about defining your own schemas, see :ref:`DefiningSchema`.

docs/src/piccolo/query_types/create.rst …src/piccolo/query_types/create_table.rstdocs/src/piccolo/query_types/create.rst renamed to docs/src/piccolo/query_types/create_table.rst docs/src/piccolo/query_types/create.rst renamed to docs/src/piccolo/query_types/create_table.rst

@@ -1,7 +1,7 @@
 .. _Create:
 
-Create
-======
+Create Table
+============
 
 This creates the table and columns in the database.
 

docs/src/piccolo/query_types/django_comparison.rst

@@ -0,0 +1,117 @@
+.. _DjangoComparison:
+
+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
+-------
+
+create
+~~~~~~
+
+.. code-block:: python
+
+    # Django
+    >>> band = Band(name="Pythonistas")
+    >>> band.save()
+    >>> band
+    <Band: 1>
+
+    # Piccolo
+    >>> band = Band(name="Pythonistas")
+    >>> band.save().run_sync()
+    >>> band
+    <Band: 1>
+
+update
+~~~~~~
+
+.. code-block:: python
+
+    # Django
+    >>> band = Band.objects.get(name="Pythonistas")
+    >>> band
+    <Band: 1>
+    >>> band.name = "Amazing Band"
+    >>> band.save()
+
+    # Piccolo
+    >>> band = Band.objects().where(Band.name == 'Pythonistas').first().run_sync()
+    >>> band
+    <Band: 1>
+    >>> band.name = "Amazing Band"
+    >>> band.save().run_sync()
+
+delete
+~~~~~~
+
+Individual rows:
+
+.. code-block:: python
+
+    # Django
+    >>> band = Band.objects.get(name="Pythonistas")
+    >>> band.delete()
+
+    # Piccolo
+    >>> band = Band.objects().where(Band.name == 'Pythonistas').first().run_sync()
+    >>> band.remove().run_sync()
+
+In bulk:
+
+.. code-block:: python
+
+    # Django
+    >>> Band.objects.filter(popularity__lt=1000).delete()
+
+    # Piccolo
+    >>> Band.delete().where(Band.popularity < 1000).delete().run_sync()
+
+filter
+~~~~~~
+
+.. code-block:: python
+
+    # Django
+    >>> Band.objects.filter(name="Pythonistas")
+    [<Band: 1>]
+
+    # Piccolo
+    >>> Band.objects().where(Band.name == "Pythonistas").run_sync()
+    [<Band: 1>]
+
+values_list
+~~~~~~~~~~~
+
+.. code-block:: python
+
+    # Django
+    >>> Band.objects.values_list('name')
+    [{'name': 'Pythonistas'}, {'name': 'Rustaceans'}]
+
+    # Piccolo
+    >>> Band.select(Band.name).run_sync()
+    [{'name': 'Pythonistas'}, {'name': 'Rustaceans'}]
+
+With ``flat=True``:
+
+.. code-block:: python
+
+    # Django
+    >>> Band.objects.values_list('name', flat=True)
+    ['Pythonistas', 'Rustaceans']
+
+    # Piccolo
+    >>> Band.select(Band.name).output(as_list=True).run_sync()
+    ['Pythonistas', 'Rustaceans']
+
+-------------------------------------------------------------------------------
+
+Database Settings
+-----------------
+
+In Django you configure your database in ``settings.py``. With Piccolo, you
+definte an ``Engine`` in ``piccolo_conf.py``. See :ref:`Engines`.

docs/src/piccolo/query_types/index.rst

@@ -1,20 +1,34 @@
 Query Types
 ===========
 
-There are many different queries you can perform using Piccolo. For starters,
-focus on `select`, `insert` and `update`.
+There are many different queries you can perform using Piccolo.
+
+The main ways to query data are with :ref:`Select`, which returns data as
+dictionaries, and :ref:`Objects` , which returns data as class instances, like a
+typical ORM.
 
 .. toctree::
-    :maxdepth: 0
+    :maxdepth: 1
 
     ./select
+    ./objects
     ./alter
     ./count
-    ./create
+    ./create_table
     ./delete
     ./exists
     ./insert
-    ./objects
     ./raw
     ./update
     ./transactions
+
+Comparisons
+-----------
+
+If you're familiar with other ORMs, here are some guides which show the Piccolo
+equivalents of common queries.
+
+.. toctree::
+    :maxdepth: 1
+
+    ./django_comparison

docs/src/piccolo/query_types/objects.rst

@@ -4,36 +4,55 @@ Objects
 =======
 
 When doing :ref:`Select`  queries, you get data back in the form of a list of
-dictionaries (where each dictionary represents a row).
+dictionaries (where each dictionary represents a row). This is useful in a lot
+of situations, but it's sometimes preferable to get objects back instead, as we
+can manipulate them, and save the changes back to the database.
 
-This is useful in a lot of situations, but it's also useful to get objects
-back instead.
+In Piccolo, an instance of a ``Table`` class represents a row. Let's do some
+examples.
 
-In Piccolo, an instance of a Table represents a row. Let's do an
-example.
+Fetching objects
+----------------
+
+To get all objects:
 
 .. code-block:: python
 
-    # To get all objects:
-    Band.objects().run_sync()
+    >>> Band.objects().run_sync()
+    [<Band: 1>, <Band: 2>]
+
+To get certain rows:
+
+.. code-block:: python
+
+    >>> Band.objects().where(Band.name == 'Pythonistas').run_sync()
+    [<Band: 1>]
+
+To get the first row:
 
-    # To get certain rows:
-    Band.objects().where(Band.name == 'Pythonistas').run_sync()
+.. code-block:: python
 
-    # Get the first row
-    Band.objects().first().run_sync()
+    >>> Band.objects().first().run_sync()
+    <Band: 1>
 
-You'll notice that the API is similar to `select` - except it returns all
+You'll notice that the API is similar to :ref:`Select` - except it returns all
 columns.
 
-Saving objects
---------------
+Creating objects
+----------------
+
+.. code-block:: python
+
+    >>> band = Band(name="C-Sharps", popularity=100)
+    >>> band.save().run_sync()
+
+Updating objects
+----------------
 
-Objects have a `save` method, which is convenient for updating values:
+Objects have a ``save`` method, which is convenient for updating values:
 
 .. code-block:: python
 
-    # To get certain rows:
     pythonistas = Band.objects().where(
         Band.name == 'Pythonistas'
     ).first().run_sync()
@@ -44,11 +63,10 @@ Objects have a `save` method, which is convenient for updating values:
 Deleting objects
 ----------------
 
-Similarly, we can delete objects, using the `remove` method.
+Similarly, we can delete objects, using the ``remove`` method.
 
 .. code-block:: python
 
-    # To get certain rows:
     pythonistas = Band.objects().where(
         Band.name == 'Pythonistas'
     ).first().run_sync()