hio.help.ogling
===============

.. py:module:: hio.help.ogling

.. autoapi-nested-parse::

   hio.help.ogling module

   Provides python stdlib logging module support







Module Contents
---------------

.. py:function:: initOgler(level=logging.CRITICAL, **kwa)

   Initialize the ogler global instance once.

   Usage: assign ogler = hio.help.ogling.initOgler() at module top level.
   Critical is most severe to restrict logging by default.
   force is Boolean True to reinit even if global ogler is not None; level is
   default logging level.
   Call in package .__init__ to ensure that global ogler is defined by default.
   Users may reset level and reopen log file before calling ogler.getLoggers().


.. py:function:: openOgler(cls=None, name='test', temp=True, **kwa)

   Context manager wrapper Ogler instances.
   Defaults to temporary file logs.
   Context 'with' statements call .close on exit of 'with' block

   :param cls is Class instance of subclass instance:
   :param name is str name of ogler instance for filename so can have multiple oglers: at different paths thar each use different log file directories
   :param temp is Boolean: Otherwise open in persistent directory, do not clear on close
   :param True means open in temporary directory: Otherwise open in persistent directory, do not clear on close
   :param clear on close: Otherwise open in persistent directory, do not clear on close

   Usage:

   with openOgler(name="bob") as ogler:
       logger = ogler.getLogger()  ....

   with openOgler(name="eve", cls=SubclassedOgler)



.. py:class:: Ogler(name='main', level=logging.ERROR, temp=False, prefix=None, headDirPath=None, reopen=False, clear=False, consoled=True, syslogged=True, filed=True, when='H', interval=1, count=48)

   Olger instances provide loggers as global logging facility
   Only need one Ogler per application
   Uses python stdlib logging module, logging.getLogger(name).
   Multiple calls to .getLogger() with the same name will always return a
   reference to the same Logger object.

   .. attribute:: name

      usage specific component used in file name

      :type: str

   .. attribute:: level

      logging severity level

      :type: int

   .. attribute:: temp

      True means use /tmp directory

      :type: bool

   .. attribute:: prefix

      application specific path prefix and formating

      :type: str

   .. attribute:: headDirPath

      head of path

      :type: str

   .. attribute:: dirPath

      full directory path

      :type: str

   .. attribute:: path

      full file path

      :type: str

   .. attribute:: opened

      True means file is opened, False not opened

      :type: bool

   .. attribute:: consoled

      True means log to console (stderr), False do not

      :type: bool

   .. attribute:: syslogged

      True means log to syslog, False do not

      :type: bool

   .. attribute:: filed

      True means log to rotating file at .path, False do not

      :type: bool

   .. attribute:: when

      interval type for timed rotating file handler

      :type: str

   .. attribute:: interval

      length of interval of type when

      :type: int

   .. attribute:: count

      backup count number of backups to keep

      :type: int


   .. py:method:: reopen(name=None, temp=None, headDirPath=None, clear=False)

      Create file handler log.
      Use or Create if not preexistent, directory path .dirPath for file .path
      First closes .path if already opened. If clear is True then also clears
      .path before reopening

      :param name is optional name:
                                    if None or unchanged then ignore otherwise recreate path
                                        When recreating path, If not provided use .name
      :param temp is optional boolean:
                                       If None ignore Otherwise
                                           Assign to .temp
                                           If True then open temporary directory,
                                           If False then open persistent directory
      :param headDirPath is optional str head directory pathname of main database:
                                                                                   if None or unchanged then ignore otherwise recreate path
                                                                                      When recreating path, If not provided use default .HeadDirpath
      :param clear is Boolean True means clear .path when closing:



   .. py:method:: close(clear=False)

      Set .opened to False and remove directory at .path
      :param clear is boolean:
      :param True means clear directory:



   .. py:method:: clearDirPath()

      Remove logfile directory at .dirPath



   .. py:method:: resetLevel(name=__name__, level=None, globally=False)

      Resets the level of preexisting loggers to level. If level is None then
      use .level



   .. py:method:: getLogger(name=__name__, level=None)

      Returns Basic Logger
      default is to name logger after module