.. _transactions:

Authorization and transactions
##############################


Authorization
=============

:class:`crandas.base.Session`



Transactions
============

Transaction context manager (see https://docs.python.org/3/reference/datamodel.html#context-managers)

Commands executed in this context are accumulated and executed as a
single unit when the context is exited.

Within the Transaction, VDL operations (e.g., crandas.merge) return a
DeferredObject instance. After the Transaction, the result of the operation
can be accessed via the `.result` field of the DeferredObject.

See:

:class:`.Transaction`
:class:`.Deferred`
:class:`.DeferredObject`


.. code:: python

    import crandas as cd
    from crandas.errors import ServerError
    from crandas.transactions import Transaction, DirectlyAccessingDeferredObjectError

    import pytest

    """Test that operations can be executed inside a Transaction, i.e., their
    expected value is correctly computed."""
    with Transaction():
        tab1 = cd.demo_table(3, 3)
        cd.get2()
        (tab1["col1"] + 1).as_table()
        tab1[["col1", "col3"]]
        tab1.assign(col44=lambda x: x.col1 + 10).assign(col55=lambda x: x.col44 - 1)

    # after transaction, should not use object itself...
    with pytest.raises(DirectlyAccessingDeferredObjectError):
        tab1.open()

    # ... but use its result instead
    tab1.result.open()


    """Test recursive transactions, use of inner result in outer transaction"""
    tab1 = cd.demo_table(3, 3)

    with Transaction():
        tab2 = tab1[["col1", "col2"]]

        with Transaction():
            tab3 = tab2["col2"].as_table()

        tab3r = tab3.result
        tab4 = tab3r.assign(col3=tab3r[tab3r.columns[0]] - 1)

    tab4r = tab4.result
    tab4r[tab4r["col3"] == 1]


Dry-run mode
============

explain how to run queries in dry-run mode to get JSON without connecting to the server


.. code:: python

    import crandas as cd
    import pandas as pd


    """Tests dry running of closed/opened queries"""

    # test that dry run is used by verifying that the number of closed rows is None
    # and the number of opened rows is 0

    assert cd.demo_table(dry_run=True).shape[0] is None
    assert len(cd.demo_table(dry_run=True, mode="defer").open(dry_run=True)) == 0
    assert len(cd.demo_table(dry_run=True).open(dry_run=True)) == 0
    assert len(cd.demo_table().open(dry_run=True)) == 0


    """Tests dtypes of opened dry run DataFrame"""

    df = cd.get_table(
        "",
        schema=cd.CIndex(
            [
                cd.Col("column1", "s", 1),
                cd.Col("column2", "i", 1),
                cd.Col("column3", "i", 32),
                cd.Col("column4", "b", 1),
            ]
        ),
        dry_run=True,
    ).open(dry_run=True)

    assert df["column1"].dtype == "O"  # string column becomes object
    assert df["column2"].dtype == "int64"  # int column becomes int64
    assert df["column3"].dtype == "O"  # int array column becomes object
    assert df["column4"].dtype == "O"  # bytes column becomes object


    """Test performing a transaction in dry run mode"""

    with cd.Transaction(dry_run=True):
        a = cd.demo_table()
        b = a.open()

    assert len(a.result.open(dry_run=True)) == 0
    assert len(b.result) == 0