=================
 Module contents 
=================

.. moduleauthor:: Nobuo Okazaki <nobrin@biokids.org>
.. currentmodule:: macaron

The :mod:`macaron` module is the main module of *Macaron*. It has some module functions needed to use *Macaron*.


Usage
=====

*Macaron* works with a global :class:`Macaron` object. The object is generated by :mod:`macaron` module. Typical usage starts with :func:`macaronage` and finishes with :func:`cleanup`. If you change the database contents, you will need to call :func:`bake` (as commit) or :func:`rollback`.

Using database models are described in :doc:`class/model`.

Example
-------

::

    import macaron
    
    # Initializing with autocommit and SQL execution logging
    macaron.macaronage("mybook.db", autocommit=True, history=10)
    
    ... uses Models ...
    
    # printing out the last five history
    for idx in range(0, 5):
        print macaron.history[idx]
    
    # finishing macaron
    macaron.bake()
    macaron.cleanup()


Module attributes
=================

.. attribute:: macaron.history

   :exception: RuntimeError -- SQL history is not enabled.
   :exception: IndexError -- index is lager than history count.
   :rtype: string or list

   Returns history of SQL execution. You can get history like a list (index:0 is latest). It may be useful for debugging your applications.

   ::

      last_sql = macaron.history[0]
      second_last_sql = macaron.history[1]
      
      sqls = macaron.history[0:5]

Module methods
==============

.. autofunction:: macaron.bake

.. autofunction:: macaron.cleanup

.. autofunction:: macaron.execute

.. autofunction:: macaron.macaronage

.. autofunction:: macaron.rollback


Logging
=======

SQL logging
-----------

*Macaron*'s logging architecture uses :mod:`logging` which is Python standard module. Simply, you can use SQL history, calling :func:`macaron.macaronage` with ``history`` parameter. It set a logger for recording executions of SQL and you can obtain the SQL and stringfied its parameters through :attr:`macaron.history`.

Using custom logger
-------------------

If you want to use custom logger(s), you call :func:`macaron.macaronage` with ``logger`` parameter. It set the logger for recording history, too. The class of logger object must be a subclass of :class`logging.Logger`.

If you set both ``logger`` and ``history`` parameters, *Macaron* will add handler to your logger object.