Piccolo

------

Added the ``callback`` clause to ``select`` and ``objects`` queries (courtesy
backwardspy). For example:

.. code-block:: python

>>> await Band.select().callback(my_callback)

The callback can be a normal function or async function, which is called when
the query is successful. The callback can be used to modify the query's output.

It allows for some interesting and powerful code. Here's a very simple example
where we modify the query's output:

.. code-block:: python

>>> def get_uppercase_names() -> Select:
... def make_uppercase(response):
... return [{'name': i['name'].upper()} for i in response]
...
... return Band.select(Band.name).callback(make_uppercase)

>>> await get_uppercase_names().where(Band.manager.name == 'Guido')
[{'name': 'PYTHONISTAS'}]

Here's another example, where we perform validation on the query's output:

.. code-block:: python

>>> def get_concerts() -> Select:
... def check_length(response):
... if len(response) == 0:
... raise ValueError('No concerts!')
... return response
...
... return Concert.select().callback(check_length)

>>> await get_concerts().where(Concert.band_1.name == 'Terrible Band')
ValueError: No concerts!

At the moment, callbacks are just triggered when a query is successful, but in
the future other callbacks will be added, to hook into more of Piccolo's
internals.

-------------------------------------------------------------------------------

------

Added the ``refresh`` method. If you have an object which has gotten stale, and
want to refresh it, so it has the latest data from the database, you can now do
this:

.. code-block:: python

If we have an instance:
band = await Band.objects().first()

And it has gotten stale, we can refresh it:
await band.refresh()

Thanks to trondhindenes for suggesting this feature.

-------------------------------------------------------------------------------

------

Fixed a bug with ``atomic`` when run async with a connection pool.

For example:

.. code-block:: python

atomic = Band._meta.db.atomic()
atomic.add(query_1, query_1)
This was failing:
await atomic.run()

Thanks to Anton-Karpenko for reporting this issue.

-------------------------------------------------------------------------------

------

create_db_tables / drop_db_tables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Added ``create_db_tables`` and ``create_db_tables_sync`` to replace
``create_tables``. The problem was ``create_tables`` was sync only, and was
inconsistent with the rest of Piccolo's API, which is async first.
``create_tables`` will continue to work for now, but is deprecated, and will be
removed in version 1.0.

Likewise, ``drop_db_tables`` and ``drop_db_tables_sync`` have replaced
``drop_tables``.

When calling ``create_tables`` / ``drop_tables`` within other async libraries
(such as `ward <https://github.com/darrenburns/ward>`_) it was sometimes
unreliable - the best solution was just to make async versions of these
functions. Thanks to backwardspy for reporting this issue.

``BaseUser`` password validation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We centralised the password validation logic in ``BaseUser`` into a method
called ``_validate_password``. This is needed by Piccolo API, but also makes it
easier for users to override this logic if subclassing ``BaseUser``.

More ``run_sync`` refinements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``run_sync``, which is the main utility function which Piccolo uses to run
async code, has been further simplified for Python > v3.10 compatibility.

-------------------------------------------------------------------------------

------

Changed how ``piccolo.utils.sync.run_sync`` works, to prevent a warning on
Python 3.10. Thanks to Drapersniper for reporting this issue.

Lots of documentation improvements - particularly around testing, and Docker
deployment.

-------------------------------------------------------------------------------

------

``piccolo schema generate`` now outputs a warning when it can't detect the
``ON DELETE`` and ``ON UPDATE`` for a ``ForeignKey``, rather than raising an
exception. Thanks to theelderbeever for reporting this issue.

``run_sync`` doesn't use the connection pool by default anymore. It was causing
issues when an app contained sync and async code. Thanks to WintonLi for
reporting this issue.

Added a tutorial to the docs for using Piccolo with an existing project and
database. Thanks to virajkanwade for reporting this issue.

-------------------------------------------------------------------------------