Piccolo

------

There was a bug when doing joins with a ``JSONB`` column with ``as_alias``.

.. code-block:: python

class User(Table, tablename="my_user"):
name = Varchar(length=120)
config = JSONB(default={})


class Subscriber(Table, tablename="subscriber"):
name = Varchar(length=120)
user = ForeignKey(references=User)


async def main():
This was failing:
await Subscriber.select(
Subscriber.name,
Subscriber.user.config.as_alias("config")
)

Thanks to Anton-Karpenko for reporting this issue.

Even though this is a bug fix, the minor version number has been bumped because
the fix resulted in some refactoring of Piccolo's internals, so is a fairly big
change.

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

------

Added a custom ``__repr__`` method to ``Table``'s metaclass. It's needed to
improve the appearance of our Sphinx docs. See
`issue 549 <https://github.com/piccolo-orm/piccolo/issues/549>`_ for more
details.

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

------

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.

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