Metadata-Version: 2.1
Name: pcs-log
Version: 0.3.1
Summary: Generic logger
Home-page: https://github.com/rpietsch1953/pcs-pylibs
Author: Rainer Pietsch
Author-email: r.pietsch@pcs-at.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE

Module LogP
===========
Set up a logging-environment for daemons or console-programs

Variables
---------

    
`debug`
:   Debug logging function
    usage: LogP.debug("Msg")

    
`error`
:   Error logging function
    usage: LogP.error("Msg")

    
`info`
:   Info logging function
    usage: LogP.info("Msg")

    
`log`
:   Log logging function
    usage: LogP.log(level,"Msg")

    
`msg`
:   Msg logging function
    usage: LogP.msg("Msg")

    
`status`
:   Status logging function
    usage: LogP.status("Msg")

    
`trace`
:   Trace logging function
    usage: LogP.trace("Msg")

    
`warning`
:   Warning logging function
    usage: LogP.warning("Msg")

Functions
---------

    
`SetupLogging(*, AppName: str, Verbose: int = 0, NoDaemon: bool = True, StdErr: bool = False, LogFile: str = '', LogFileInterval: int = 86400, LogFileCount: int = 14, Quiet: bool = False, ProcInfo: bool = False, ProcInfoModLen: int = 15, ProcInfoFuncLen: int = 15, LevelType: int = 2, MultiProc: bool = False, MultiProcLen: int = 15, MultiThread: bool = False, MultiThreadLen: int = 15, StackOnDebug: str = 'NONE', StackDepth: int = 5, DebugIp: str = '127.0.0.1', DebugPort: int = 0, DebugCacheSize: int = 100, NoReset: bool = False) ‑> PortLogServer.PortLogServer`
:   Creates a defined Log-setting with rich options
    
    Args:
        AppName (str): Name of application
    
        Verbose (int, optional): Detail of logging. Defaults to 0.
                                0 = ERROR and STATUS
                                1 = MSG, WARNING, STATUS, ERROR 
                                2 = INFO, MSG, WARNING, STATUS, ERROR 
                                3 = DEBUG, INFO, MSG, WARNING, STATUS, ERROR 
                                4 = TRACE, DEBUG, INFO, MSG, WARNING, STATUS, ERROR 
    
        NoDaemon (bool, optional): Is this an terminal-task. Defaults to True.
                                If this is false => i am a daemon.
                                On deamons output to StdErr do not make sense, so this is ignored
                                and "syslog" or "logfile" is used.
    
        StdErr (bool, optional): Log to StdErr. Defaults to False.
                                If this is set the log goes to StdErr.
                                Ignored if we are a daemon.
    
        LogFile (str, optional): Log to a Log-file. Defaults to ''.
                                Log to the file which is given as the argument.
                                this file is rotated on a daily base and holded up to 14 files
    
        LogFileInterval (int, optional): Number of seconds a logfile lasts until it is rotated.
                                Defaults to 60*60*24 => one day.
    
        LogFileCount (int, optional): Number of log-file kept. Defaults to 14.
    
        Quiet (bool, optional): Output only errors. Defaults to False.
    
        ProcInfo (bool, optional): Show process and thread. Defaults to False.
    
        LevelType (int, optional): Format of LevelInfo. 0=None, 1=Number, 2=Name, 3=Both. 
                                    Defaults to 2.
    
        MultiProc (bool, optional): Show process-names. Defaults to False.
    
        MultiThread (bool, optional): Show thread-names. Defaults to False.
    
        StackOnDebug (str, optional): Log-level below or equal a call-stack trace is included.
                                    Defaults to "NONE" => Disabled.
                                    The levels are:
                                        "ERROR"
                                        "STATUS"
                                        "WARNING"
                                        "MSG"
                                        "INFO"
                                        "DEBUG"
                                        "TRACE"
                                        "NONE"
                                    All other values are interpretet as "NONE".
                                    Value is not case-sensitive.
    
        StackDepth (int, optional): Maximum number of call-stack entries to display. Defaults to 5.
    
        DebugPort (int, optional): If 0 no debug-server is started. Else the value has to be 
                                    between 1024 and 65535. A log-server is started on 'DebugIp' 
                                    at port 'DebugPort'. 
                                    It is possible to connect to this port (e.g with telnet) to 
                                    receive ALL log-messages from this program. ALL means really
                                    all, no mather which loglevel is set. This output also 
                                    includes all possible information about process, thread, 
                                    module and function. The stacktrace ('StackOnDebug') is also
                                    honored. This output can be really heavy, but can help to debug
                                    already running programs without the need to restart with 
                                    another loglevel.
                                    This server runs as a separated process and you have to 
                                    terminate it by calling the'Stop' and afterward 'Join' or 
                                    'Kill'-function of the returned 'PortLogServer'-object, 
                                    otherwise this process may block the termination of your 
                                    program. This server will restart himselve if it is terminated 
                                    by any means except you call the above mentioned functions.
                                    This port has to be free. Defaults to 0.
                                    
        DebugIp (str, optional): The IP-address to bind to. This address must exist on the host 
                                    this program is running. '0.0.0.0' for 'all IPs' is also 
                                    valid. Only examined if 'DebugPort' > 0. 
                                    Defaults to '127.0.0.1',
                                    
        DebugCacheSize (int, optional): Only used if 'DebugPort' > 0. This is the number of 
                                    log-messages cached for use at a new connection to the 
                                    server. So if someone connects to the server he receives the
                                    last 'DebugCacheSize' log messages and after them all new 
                                    messages.
                                    This is like a history. if set to 0 this function is disabled.
                                    Defaults to 100.
    
        NoReset (bool, optional): Do not reset logger on init. Defaults to False.
                                    Use with care. Could tend to mess up the logging.
    Output format:
        General overview:
            2022-06-22 07:37:42,494 Appname:MainProcess:MainThread LogP:main:461 - 40=   ERROR - Message
                                    ^       ^           ^          ^               ^     ^       ^
                                    |       |           |          |               |     |       |
            Name of application ----+       |           |          |               |     |       |
                only if not StdErr          |           |          |               |     |       |
            Name of procvess ---------------+           |          |               |     |       |
                if MultiProc = true                     |          |               |     |       |
            Name of thread if --------------------------+          |               |     |       |
                MultiThread = true                                 |               |     |       |
            Module, function and linenumber -----------------------+               |     |       |
                only if ProcInfo = true                                            |     |       |
            Level-number of message if LevelType = 1 or 3 -------------------------+     |       |
            Level-name of message if LevelType = 2 or 3 ---------------------------------+       |
            The message given to the log-call ---------------------------------------------------+
    
            The minimal log entry for StdErr is:
                2022-06-22 07:37:42,494 Errormessage
            The maximal log entry is shown above.
    
        The output format to StdErr is like this:
            2022-06-22 07:37:42,494 MainProcess:MainThread LogP:main:461     - 40=   ERROR - Message
                No "Appname" because you know whitch program is running 
    
        The output format to sylog like this:
            Appname:MainProcess:MainThread LogP:main:461 - 40=   ERROR - Errormessage
                No timestamp because syslogg adds his own timestamp.
    
        The output format to a logfile is like this:
            2022-06-22 07:37:42,494 Appname:MainProcess:MainThread LogP:main:461 - 40=   ERROR - Message
    
    
        if a call-stack trace is requested lines like these are appended:
                File "./LogP.py", line 471, in <module>
                main()
                File "./LogP.py", line 448, in main
                abc()
                File "./LogP.py", line 411, in abc
                LogP.debug('Debug')
Module PortLogServer
====================

Classes
-------

`DummyPortLogServer(*args, **kwargs)`
:   The dummy-version of the 'PortLogServer'-class
    This class is used to return it to a user if no real Log-server is requested.
    So the programmer can call the functions without the need to question if
    a real server is running. All functions are No-Ops.

    ### Instance variables

    `IsAlive: bool`
    :

    `Name: str`
    :

    `Port: int`
    :

    `RunFlag: bool`
    :

    ### Methods

    `Join(self, *args, **kwargs) ‑> NoneType`
    :

    `Kill(self) ‑> NoneType`
    :

    `PollRestart(self) ‑> NoneType`
    :

    `Run(self, *args, **kwargs) ‑> NoneType`
    :

    `Stop(self, *args, **kwargs) ‑> NoneType`
    :

`PortLogQueueHandler(ProcClass: PortLogServer.PortLogServer, *args, **kwargs)`
:   A queue-handler that allowes the automatic restart of the Log-server
    
    Args:
        ProcClass (PortLogServer): An instance of the listening PortLogServer.
                                    Needet to automatically restart if the
                                    server is terminated. All other parametrs
                                    look at the documentation of 
                                    'logging.handlers.QueueHandler'

    ### Ancestors (in MRO)

    * logging.handlers.QueueHandler
    * logging.Handler
    * logging.Filterer

    ### Methods

    `enqueue(self, record)`
    :   Overwritten enqueue function of the 'logging.handlers.QueueHandler' class.

`PortLogServer(*, host: str = '127.0.0.1', port: int = 0, name: str = '', queue: <bound method BaseContext.Queue of <multiprocessing.context.DefaultContext object at 0x7fcea21d78b0>> = None, logsize: int = 0, format: str = '')`
:   Send the messages from the input-Queue to a tcp-client
    on the defined address and port.
    
    Args:
        port (int, optional): The port to use (1024 to 65535). Defaults to 0.
        name (str, optional): The process-name of this class. Defaults to ''.
        queue (multiprocessing.Queue, optional): The input queue. Defaults to None.
        logsize (int, optional): if >0 logsize messages are buffered and send to the client on connection. Defaults to 0.
    
    Raises:
        ValueError: if invalid arguments are given.

    ### Instance variables

    `IsAlive: bool`
    :   Returnm True if the process is alive

    `Name: str`
    :   Return the process-name of this instance

    `Port: int`
    :   Return the port-number of this instance

    `RunFlag: bool`
    :   Return True if the process is running

    ### Methods

    `Join(self, Timeout: float) ‑> NoneType`
    :   Join this process

    `Kill(self) ‑> NoneType`
    :   Kill this process

    `PollRestart(self) ‑> NoneType`
    :   Restart the process if it is not alive

    `Run(self, *, name: str = '', queue: <bound method BaseContext.Queue of <multiprocessing.context.DefaultContext object at 0x7fcea21d78b0>> = None) ‑> NoneType`
    :   Starts the reader-process
        
        Args:
            name (str, optional): Can overwrite the process-name of this instance. Defaults to ''.
            queue (multiprocessing.Queue, optional): can overwrite the input queue of this instance. 
                        If not given the name from the creation is used Defaults to None.
        
        Raises:
            ValueError: if invalid arguments are given.

    `Stop(self) ‑> NoneType`
    :   Stop the reader-process


