Usage
=====

Installation
------------

Default installation option is to use pip+git

.. code-block:: console

    (.venv) $ pip install git+https://gitea.parrrate.ru/PTV/ptvp35.git

Basic functionality
-------------------

.. autoclass:: ptvp35.DbFactory

    :code:`DbFactory` class provides context management for database connections (:code:`DbConnection`) via :code:`async with` statement.
    The connection isn't just a "connection", it's also the MMDB itself, so **using two connections to one database is an undefined behaviour**.
    Also, that means that each connection start/shutdown is quite time expensive.
    These two facts together tell that, if you intend on using the connection, you should probably wrap the main program in an :code:`async with` block.

.. code-block:: python3

    import pathlib
    from ptvp35 import DbFactory, KVJson
    
    async def main():
        async with DbFactory(pathlib.Path('example.db', kvfactory=KVJson())) as connection:
            await _main(connection)

.. autoclass:: ptvp35.DbConnection

    .. automethod:: get

        this method is instant.

    .. automethod:: set

        this method may take time to run.
        ordering may not be guaranteed (depends on event loop implementation).

    .. automethod:: set_nowait

        this method is instant.
        ordering is guaranteed.

    .. automethod:: commit

        this method may take time to run.
        respects the ordering of previously called :code:`set_nowait` methods.
        will, under most circumstances, also execute later changes.

    .. automethod:: transaction