#########################
API Reference
#########################

*************************
Global Objects
*************************
.. module:: twiggy

.. data:: log

    the magic log object

.. data:: internal_log

    `.InternalLogger` for reporting errors within Twiggy itself

.. data:: devel_log

    `.InternalLogger` for use by developers writing extensions to Twiggy

.. data:: emitters

    the global :class:`emitters <.Emitter>` dictionary, tied to the :data:`.log`

.. autofunction:: addEmitters

.. autofunction:: quickSetup

*************************
Features
*************************

.. automodule:: twiggy.features
    :members:

procinfo
===========
.. automodule:: twiggy.features.procinfo
    :members:

socket
========
.. automodule:: twiggy.features.socket
    :members:

*************************
Filters
*************************
.. module:: twiggy.filters

.. function:: filter(msg : Message) -> bool

    A *filter* is any function that takes a :class:`.Message` and returns True if it should be :class:`emitted <Emitter>`.

.. function:: msgFilter(x) -> filter

    create a `.filter` intelligently

    You may pass:

        :None, True: the filter will always return True
        :False: the filter will always return False
        :string: compiled into a regex
        :regex: ``match()`` against the message text
        :callable: returned as is
        :list: apply `msgFilter` to each element, and ``all()`` the results

    :rtype: `.filter` function

.. function:: names(*names) -> filter

    create a `.filter`, which gives True if the messsage's name equals any of those provided

    ``names`` will be stored as an attribute on the filter.

    :arg strings names: names to match
    :rtype: `.filter` function

.. function:: glob_names(*names) -> filter

    create a `.filter`, which gives True if the messsage's name globs those provided.

    ``names`` will be stored as an attribute on the filter.

    This is probably quite a bit slower than :func:`names`.

    :arg strings names: glob patterns.
    :rtype: `.filter` function

.. class:: Emitter

    Hold and manage an :class:`.Output` and associated :func:`.filter`

    .. attribute:: min_level

        only emit if greater than this `.LogLevel`

    .. attribute:: filter

        arbitrary :func:`.filter` on message contents. Assigning to this attribute is :func:`intelligent <.msgFilter>`.

    .. attribute:: _output

        `.Output` to emit messages to. Do not modify.

*************************
Formats
*************************

.. module:: twiggy.formats

.. _format-function:

*Formats* are single-argument callables that take a `.Message` and return an object appropriate for the `.Output` they are assigned to.

.. class:: LineFormat(separator=':', traceback_prefix='\\nTRACE', conversion=line_conversion)


    .. attribute:: separator

        string to separate line parts. Defaults to ``:``.

    .. attribute:: traceback_prefix

        string to prepend to traceback lines. Defaults to ``\nTRACE``.

        .. _folding-exceptions:

        Set to ``'\\n'`` (double backslash n) to roll up tracebacks to a single line.

    .. attribute:: conversion

        :class:`.ConversionTable` used to format :attr:`.fields`. Defaults to :data:`line_conversion`

    .. automethod:: format_text

    .. automethod:: format_fields

    .. automethod:: format_traceback


.. data:: line_conversion

    a default line-oriented :class:`.ConversionTable`. Produces a nice-looking string from :attr:`.fields`.

    Fields are separated by a colon (``:``). Resultant string includes:

        :time: in iso8601 format (required)
        :level: message level (required)
        :name: logger name

    Remaining fields are sorted alphabetically and formatted as ``key=value``

.. data:: line_format

    a default :class:`.LineFormat` for output to a file. :ref:`Sample output <sample-file-output>`.

    Fields are formatted using :data:`.line_conversion` and separated from the message :attr:`.text` by a colon (``:``). Traceback lines are prefixed by ``TRACE``.

.. data:: shell_conversion

    a default line-oriented :class:`.ConversionTable` for use in the shell.  Returns the same string as :data:`.line_conversion` but drops the ``time`` field.

.. data:: shell_format

    a default :class:`.LineFormat` for use in the shell.  Same as :data:`.line_format` but uses :data:`.shell_conversion` for :attr:`.fields`.

*************************
Levels
*************************
.. automodule:: twiggy.levels
    :members:

*************************
Library
*************************
.. automodule:: twiggy.lib
    :members:

Converter
===============
.. module:: twiggy.lib.converter

.. autoclass:: Converter

.. class:: ConversionTable(seq)

    Convert data dictionaries using `Converters <.Converter>`

    For each item in the dictionary to be converted:

    #. Find one or more corresponding converters ``c`` by matching key.
    #. Build a list of converted items by calling ``c.convertItem(item_key, c.convertValue(item_value))``. The list will have items in the same order as converters were supplied.
    #. Dict items for which no converter was found are sorted by key and passed to `.genericValue` / `.genericItem`. These items are appended to the list from step 2.
    #. If any required items are missing, :exc:`ValueError` is raised.
    #. The resulting list of converted items is passed to `.aggregate`. The value it returns is the result of the conversion.


    Users may override `.genericValue`/`.genericItem`/`.aggregate` by subclassing or assigning a new function on a ConversionTable instance.

    Really, it's :ref:`pretty intuitive <conversion-table-example>`.

    .. automethod:: __init__

    .. automethod:: convert

    .. method:: genericValue(value)

        convert values for which no specific `.Converter` is supplied

    .. method:: genericItem(key, value)

        convert items for which no specific `.Converter` is supplied

    .. method:: aggregate(converteds)

        aggregate list of converted items.  The return value of `.convert`

    .. automethod:: copy

    .. automethod:: get

    .. automethod:: getAll

    .. automethod:: add

    .. automethod:: delete


*************************
Logger
*************************
Loggers should not be created directly by users; use the global :data:`.log` instead.

.. module:: twiggy.logger

.. class:: BaseLogger(fields=None, options=None, min_level=None)

    Base class for loggers

    .. attribute:: _fields

        dictionary of bound fields for :term:`structured logging`.
        By default, contains a single field ``time`` with value ``time.gmtime()``.  This function will be called for each message emitted, populating the field with the current ``time.struct_time``.

    .. attribute:: _options

        dictionary of bound :ref:`options <message-options>`.

    .. attribute:: min_level

        minimum :class:`.LogLevel` for which to emit. For optimization purposes only.

    .. method:: fields(**kwargs) -> bound Logger

        bind fields for :term:`structured logging`. ``kwargs`` are interpreted as names/values of fields.

    .. method:: fieldsDict(d) -> bound Logger

        bind fields for structured logging. Use this instead of `.fields` if you have keys which are not valid Python identifiers.

        :arg dict d: dictionary of fields. Keys should be strings.

    .. method:: options(**kwargs) -> bound Logger

        bind :ref:`options <message-options>` for message creation.

    .. method:: trace(trace='error') -> bound Logger

        convenience method to enable :ref:`traceback logging <message-options>`

    .. method:: name(name) -> bound Logger

        convenvience method to bind ``name`` field

    .. method:: struct(**kwargs) -> bound Logger

        convenience method for :term:`structured logging`. Calls :meth:`.fields` and emits at `.info`

    .. method:: structDict(d) -> bound Logger

        convenience method for :term:`structured logging`. Use instead of `.struct` if you have keys which are not valid Python identifiers.

        :arg dict d: dictionary of fields. Keys should be strings.



    The following methods cause messages to be emitted.  ``format_spec`` is a template string into which ``args`` and ``kwargs`` will be substitued.

    .. automethod:: debug
    .. automethod:: info
    .. automethod:: warning
    .. automethod:: error
    .. automethod:: critical


.. class:: Logger(fields=None, options=None, min_level=None)

    Logger for end-users. The type of the magic :data:`.log`

    .. attribute:: filter

        Filter on ``format_spec``. For optimization purposes only. Should have the following signature:

        .. function:: func(format_spec : string) -> bool
            :noindex:

            Should the message be emitted.

    .. automethod:: addFeature

    .. automethod:: disableFeature

    .. automethod:: delFeature

.. autoclass:: InternalLogger

.. autofunction:: emit

*************************
Message
*************************
.. module:: twiggy.message

.. class:: Message(level, format_spec, fields, options, args, kwargs)

    A logging message.  Users never create these directly.

    .. versionchanged:: 0.4.1
        Pass args/kwargs as list/dict instead of via ``*``/``**`` expansion.

    .. _message-options:

    The constructor takes a dict of ``options`` to control message creation.  In addition to :attr:`.suppress_newlines`, the following options are recognized:

        :trace: control traceback inclusion.  Either a traceback tuple, or one of the strings ``always``, ``error``, in which case a traceback will be extracted from the current stack frame.
        :style: the style of template used for ``format_spec``. One of ``braces``, ``percent``, ``dollar``.

    Any callables passed in ``fields``, ``args`` or ``kwargs`` will be called and the returned value used instead. See :ref:`dynamic messages <dynamic-messages>`.

    All attributes are read-only.

    .. attribute:: fields

        dictionary of :term:`structured logging` fields.  Keys are string, values are arbitrary. A ``level`` item is required.

    .. attribute:: suppress_newlines

        should newlines be escaped in output. Boolean.

    .. attribute:: traceback

        a stringified traceback, or None.

    .. attribute:: text

        the human-readable message. Constructed by substituting ``args``/``kwargs`` into ``format_spec``. String.

    .. automethod:: __init__


*************************
Outputs
*************************
.. module:: twiggy.outputs

.. class:: Output(format=None, close_atexit=True)

    .. attribute:: _format

        a :ref:`callable <format-function>` taking a `.Message` and formatting it for output. None means return the message unchanged.

    .. attribute:: use_locks

        Class variable, indicating that locks should be used when running in a synchronous, multithreaded environment. Threadsafe subclasses may disable locking for higher throughput. Defaults to True.

    .. automethod:: __init__
    
    .. versionadded:: 0.4.1
        Add the `close_atexit` parameter.     
    
    .. method:: close
        
        Finalize the output.

    The following methods should be implemented by subclasses.

    .. automethod:: twiggy.outputs.Output._open

    .. automethod:: twiggy.outputs.Output._close

    .. automethod:: twiggy.outputs.Output._write

.. class:: AsyncOutput(msg_buffer=0)

    An `.Output` with support for :term:`asynchronous logging`.

    Inheriting from this class transparently adds support for asynchronous logging using the multiprocessing module. This is off by default, as it can cause log messages to be dropped.

    :arg int msg_buffer: number of messages to buffer in memory when using asynchronous logging. ``0`` turns asynchronous output off, a negative integer means an unlimited buffer, a positive integer is the size of the buffer.

.. autoclass:: FileOutput

.. class:: StreamOutput(format, stream=sys.stderr)

    Output to an externally-managed stream.

    The stream will be written to, but otherwise left alone (i.e., it will *not* be closed).

.. autoclass:: NullOutput

.. autoclass:: ListOutput
    
.. versionchanged:: 0.4.1
    Replace `DequeOutput` with more useful `ListOutput`.