Metadata-Version: 1.1
Name: PyLg
Version: 1.3.3
Summary: Python module to facilitate and automate the process of writing runtime logs.
Home-page: https://gitlab.wojciechkozlowski.eu/wojtek/PyLg
Author: Wojciech Kozlowski
Author-email: wk@wojciechkozlowski.eu
License: UNKNOWN
Description: 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_fuction():
               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_fuction():
               pass
        
           @TraceFunction(trace_args = False, exception_tb_stderr = True)
           def some_fuction():
               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.
        
Keywords: development log debug trace
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Debuggers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
