PyLg
====

PyLg (read as py-log) is a python module that facilitates the process
of writing runtime logs. The goal of PyLg is to provide an unobtrusive
and flexible interface that automates the process of generating
informative logs.

Demo
----

.. image:: https://gitlab.wojciechkozlowski.eu/wojtek/PyLg/raw/pylg-dev/screenshots/demo.png
  :target: https://gitlab.wojciechkozlowski.eu/wojtek/PyLg/raw/pylg-dev/screenshots/demo.png

Features
--------

- Ease of use - the API consists of only one decorator and one
  function.
- Flexible - the user can set global preferences as well as on a
  per-function basis.
- Informative - PyLg can automatically log input arguments, return
  values and exceptions raised.
- User logs - the user can make additional logs that will be collected
  together with the automatically generated logs.

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

::

   [sudo] pip install pylg --upgrade

Note that PyLg is under active development. Frequent upgrades are
recommended.

Usage
-----

Import the module:

::

   from pylg import TraceFunction, trace

To automatically log function entry and exit use the
``@TraceFunction`` decorator:

::

   @TraceFunction
   def some_function():
       pass

Despite the name, this works for both functions and methods.

``@TraceFunction`` can take up to seven optional arguments:

- ``exception_warning`` - if ``True``, PyLg will print a warning about
  every exception caught to ``stderr``.

- ``exception_tb_file`` - if ``True``, PyLg will write the exception
  tracebacks to the log file.

- ``exception_tb_stderr`` - if ``True``, PyLg will print the exception
  tracebacks to ``stderr``.

- ``exception_exit`` - if ``True``, PyLg will force the program to
  exit (and not just raise SystemExit) whenever an exception
  occurs. This will happen even if the exception would be handled at a
  later point.

- ``trace_args`` - if ``True``, PyLg will log input parameters.

- ``trace_rv`` - if ``True``, PyLg will log return values.

- ``trace_rv_type`` - if ``True``, PyLg will log return value types.

The default values for these arguments are set in a global settings
file.

These arguments have to specified explicitly by name. Some examples:

::

   @TraceFunction(trace_args = False)
   def some_function():
       pass

   @TraceFunction(trace_args = False, exception_tb_stderr = True)
   def some_function():
       pass

The other way to interact with PyLg is to log a user defined message
with the ``trace`` function.

::

   trace("The user can pass any string they desire in here")

User Settings
-------------

The user can adjust several settings to suit their preferences. To do
so, create a file named ``pylg_settings.py`` somewhere in your path
and set any of the following variables to the desired values in order
to override the defaults. The settings.py file in the project
directory contains all the default settings and can be used as a
template.

- ``PYLG_ENABLE`` (default = ``True``) - enable/disable PyLg.

- ``PYLG_FILE`` (default = ``'pylg.log'``) - the log file name.

- ``DEFAULT_EXCEPTION_WARNING`` (default = ``True``) - the default
  setting for ``exception_warning``.

- ``DEFAULT_EXCEPTION_TB_FILE`` (default = ``True``) - the default
  setting for ``exception_tb_file``.

- ``DEFAULT_EXCEPTION_TB_STDERR`` (default = ``False``) - the default
  setting for ``exception_tb_stderr``.

- ``DEFAULT_EXCEPTION_EXIT`` (default = ``False``) - the default
  setting for ``exception_exit``.

- ``TRACE_TIME`` (default = ``TRUE``) - enable/disable time logging.

- ``TIME_FORMAT`` (default = ``"%Y-%m-%d %H:%M:%S.%f"``) - formatting
  for the time trace. For a full list of options, see
  https://docs.python.org/2/library/datetime.html#strftime-strptime-behavior.

- ``TRACE_FILENAME`` (default = ``True``) - enable/disable file name
  logging.

- ``FILENAME_COLUMN_WIDTH`` (default = ``20``) - the column width for
  the file name. If a name is too long, it will be truncated.

- ``TRACE_LINENO`` (default = ``True``) - enable/disable the logging
  of the line number from which the trace call was made. For entry and
  exit messages this logs the line in which the decorator is placed
  (which should be directly above the function itself).

- ``LINENO_WIDTH`` (default = ``4``) - the minimum number of digits to
  use to print the line number. If the number is too long, more digits
  will be used.

- ``TRACE_FUNCTION`` (default = ``True``) - enable/disable the logging
  of the function name from which the trace call was made. Entry/exit
  logs refer to the function they enter into and exit from.

- ``FUNCTION_COLUMN_WIDTH`` (default = ``32``) - the column width for
  the function name. If a name is too long, it will be truncated.

- ``CLASS_NAME_RESOLUTION`` (default = ``False``) - enable/disable
  class name resolution. Function names will be printed with their
  class names. IMPORTANT: If this setting is enabled, the trace
  function should ONLY be called from within functions that have the
  ``@TraceFunction`` decorator OR outside of any function.

- ``TRACE_MESSAGE`` (default = ``True``) - enable/disable message
  logging.

- ``MESSAGE_WIDTH`` (default = ``0``) - the column width for the
  message. A width of zero means unlimited.

- ``MESSAGE_WRAP`` (default = ``True``) - if ``True``, PyLg will wrap
  the message to fit within the column width. Otherwise, the message
  will be truncated.

- ``MESSAGE_MARK_TRUNCATION`` (default = ``True``) - if ``True``,
  truncated message lines should have the last character replaced with
  ``\``. Note that this reduces ``MESSAGE_WIDTH`` by ``1`` for
  truncated lines which may truncate words that would've otherwise
  appeared in the message.

- ``TRACE_SELF`` (default = ``False``) - enable/disable logging of the
  ``self`` function argument.

- ``COLLAPSE_LISTS`` (default = ``False``) - if ``True`` lists will be
  collapsed to ``[ len=x ]`` where ``x`` denotes the number of
  elements in the list.

- ``COLLAPSE_DICTS`` (default = ``False``) - if ``True`` dictionaries
  will be collapsed to ``{ len=x }`` where ``x`` denotes the number of
  elements in the dictionary.

- ``DEFAULT_TRACE_ARGS`` (default = ``True``) - the default setting
  for ``trace_args``.

- ``DEFAULT_TRACE_RV`` (default = ``True``) - the default setting for
  ``trace_rv``.

- ``DEFAULT_TRACE_RV_TYPE`` (default = ``True``) - the default setting
  for ``trace_rv_type``.

Under development
-----------------

Since this module is under development, here are a few things to keep
in mind when using PyLg.

- The behaviour of ``@TraceFunction`` has not been tested when multiple
  decorators are present.
- When PyLg opens a new log file, it overwrites any file present with
  the same name. Therefore, it can erase important files if you are
  not careful.
- Some features of PyLg do not work with old-style classes.

Contributing
------------

Please submit contributions branched from the ``pylg-dev`` branch.