Merge branch 'master' into reverse_lookup

.gitignore

@@ -19,3 +19,8 @@ prof/
 .env/
 .venv/
 result.json
+
+# CockroachDB
+cockroach-data/
+heap_profiler/
+goroutine_dump/

CHANGES.rst

@@ -1,6 +1,159 @@
 Changes
 =======
 
+0.109.0
+-------
+
+Joins are now possible without foreign keys using ``join_on``.
+
+For example:
+
+.. code-block:: python
+
+    class Manager(Table):
+        name = Varchar(unique=True)
+        email = Varchar()
+
+    class Band(Table):
+        name = Varchar()
+        manager_name = Varchar()
+
+    >>> await Band.select(
+    ...     Band.name,
+    ...     Band.manager_name.join_on(Manager.name).email
+    ... )
+
+-------------------------------------------------------------------------------
+
+0.108.0
+-------
+
+Added support for savepoints within transactions.
+
+.. code-block:: python
+
+  async with DB.transaction() as transaction:
+      await Manager.objects().create(name="Great manager")
+      savepoint = await transaction.savepoint()
+      await Manager.objects().create(name="Great manager")
+      await savepoint.rollback_to()
+      # Only the first manager will be inserted.
+
+The behaviour of nested context managers has also been changed slightly.
+
+.. code-block:: python
+
+  async with DB.transaction():
+      async with DB.transaction():
+          # This used to raise an exception
+
+We no longer raise an exception if there are nested transaction context
+managers, instead the inner ones do nothing.
+
+If you want the existing behaviour:
+
+.. code-block:: python
+
+  async with DB.transaction():
+      async with DB.transactiona(allow_nested=False):
+          # TransactionError!
+
+-------------------------------------------------------------------------------
+
+0.107.0
+-------
+
+Added the ``log_responses`` option to the database engines. This makes the
+engine print out the raw response from the database for each query, which
+is useful during debugging.
+
+.. code-block:: python
+
+  # piccolo_conf.py
+
+  DB = PostgresEngine(
+    config={'database': 'my_database'},
+    log_queries=True,
+    log_responses=True
+  )
+
+We also updated the Starlite ASGI template - it now uses the new import paths
+(thanks to @sinisaos for this).
+
+-------------------------------------------------------------------------------
+
+0.106.0
+-------
+
+Joins now work within ``update`` queries. For example:
+
+.. code-block:: python
+
+  await Band.update({
+      Band.name: 'Amazing Band'
+  }).where(
+      Band.manager.name == 'Guido'
+  )
+
+Other changes:
+
+* Improved the template used  by ``piccolo app new`` when creating a new
+  Piccolo app (it now uses ``table_finder``).
+
+-------------------------------------------------------------------------------
+
+0.105.0
+-------
+
+Improved the performance of select queries with complex joins. Many thanks to
+@powellnorma and @sinisaos for their help with this.
+
+-------------------------------------------------------------------------------
+
+0.104.0
+-------
+
+Major improvements to Piccolo's typing / auto completion support.
+
+For example:
+
+.. code-block:: python
+
+  >>> bands = await Band.objects()  # List[Band]
+
+  >>> band = await Band.objects().first()  # Optional[Band]
+
+  >>> bands = await Band.select().output(as_json=True)  # str
+
+-------------------------------------------------------------------------------
+
+0.103.0
+-------
+
+``SelectRaw``
+~~~~~~~~~~~~~
+
+This allows you to access features in the database which aren't exposed
+directly by Piccolo. For example, Postgres functions:
+
+.. code-block:: python
+
+    from piccolo.query import SelectRaw
+
+    >>> await Band.select(
+    ...     Band.name,
+    ...     SelectRaw("log(popularity) AS log_popularity")
+    ... )
+    [{'name': 'Pythonistas', 'log_popularity': 3.0}]
+
+Large fixtures
+~~~~~~~~~~~~~~
+
+Piccolo can now load large fixtures using ``piccolo fixtures load``. The
+rows are inserted in batches, so the database adapter doesn't raise any errors.
+
+-------------------------------------------------------------------------------
+
 0.102.0
 -------
 

docs/src/piccolo/api_reference/index.rst

@@ -11,6 +11,16 @@ Table
 
 -------------------------------------------------------------------------------
 
+Column
+------
+
+.. currentmodule:: piccolo.columns.base
+
+.. autoclass:: Column
+    :members:
+
+-------------------------------------------------------------------------------
+
 Refresh
 -------
 

docs/src/piccolo/getting_started/installing_piccolo.rst

@@ -13,7 +13,7 @@ Pip
 
 Now install Piccolo, ideally inside a `virtualenv <https://docs.python-guide.org/dev/virtualenvs/>`_:
 
-.. code-block:: python
+.. code-block:: bash
 
     # Optional - creating a virtualenv on Unix:
     python3 -m venv my_project
@@ -40,3 +40,7 @@ Now install Piccolo, ideally inside a `virtualenv <https://docs.python-guide.org
     # If you just want Piccolo with all of it's functionality, you might prefer
     # to use this:
     pip install 'piccolo[all]'
+
+.. hint::
+    On Windows, you may need to use double quotes instead. For example
+    ``pip install "piccolo[all]"``.

docs/src/piccolo/query_types/index.rst

@@ -19,7 +19,17 @@ typical ORM.
     ./insert
     ./raw
     ./update
+
+-------------------------------------------------------------------------------
+
+Features
+--------
+
+.. toctree::
+    :maxdepth: 1
+
     ./transactions
+    ./joins
 
 -------------------------------------------------------------------------------
 

docs/src/piccolo/query_types/joins.rst

@@ -0,0 +1,37 @@
+Joins
+=====
+
+Joins are handled automatically by Piccolo. They work everywhere you'd expect
+(select queries, where clauses, etc.).
+
+A `fluent interface <https://en.wikipedia.org/wiki/Fluent_interface>`_  is used,
+which lets you traverse foreign keys.
+
+Here's an example of a select query which uses joins (using the
+:ref:`example schema <ExampleSchema>`):
+
+.. code-block:: python
+
+    # This gets the band's name, and the manager's name by joining to the
+    # manager table:
+    >>> await Band.select(Band.name, Band.manager.name)
+
+And a ``where`` clause which uses joins:
+
+.. code-block:: python
+
+    # This automatically joins with the manager table to perform the where
+    # clause. It only returns the columns from the band table though by default.
+    >>> await Band.select().where(Band.manager.name == 'Guido')
+
+Left joins are used.
+
+join_on
+-------
+
+Joins are usually performed using ``ForeignKey`` columns, though there may be
+situations where you want to join using a column which isn't a ``ForeignKey``.
+
+You can do this using :meth:`join_on <piccolo.columns.base.Column.join_on>`.
+
+It's generally best to join on unique columns.

docs/src/piccolo/query_types/objects.rst

@@ -78,7 +78,8 @@ We also have this shortcut which combines the above into a single line:
 Updating objects
 ----------------
 
-Objects have a ``save`` method, which is convenient for updating values:
+Objects have a :meth:`save <piccolo.table.Table.save>` method, which is
+convenient for updating values:
 
 .. code-block:: python
 
@@ -278,6 +279,9 @@ has the latest data from the database, you can use the
     # And it has gotten stale, we can refresh it:
     await band.refresh()
 
+    # Or just refresh certain columns:
+    await band.refresh([Band.name])
+
 -------------------------------------------------------------------------------
 
 Query clauses

docs/src/piccolo/query_types/select.rst

@@ -26,8 +26,7 @@ Or use an alias to make it shorter:
 
     >>> b = Band
     >>> await b.select(b.name)
-    [{'id': 1, 'name': 'Pythonistas', 'manager': 1, 'popularity': 1000},
-     {'id': 2, 'name': 'Rustaceans', 'manager': 2, 'popularity': 500}]
+    [{'name': 'Rustaceans'}, {'name': 'Pythonistas'}]
 
 .. hint::
    All of these examples also work synchronously using ``run_sync`` -