clog._logger.Logger Class Reference

Public Member Functions
Logger	__new__ (cls, *Union[str, None] out_f=None)
Logger	new (cls, *Union[str, None] out_f=None)
Type[Logger]	debug (cls, *object value, Union[str, None] sep=None, Union[str, None] end=None, bool wrapping=True, bool strace=True)
Type[Logger]	warn (cls, *object value, Union[str, None] sep=None, Union[str, None] end=None, bool wrapping=True, bool strace=True)
Type[Logger]	error (cls, *object value, Union[str, None] sep=None, Union[str, None] end=None, bool wrapping=True, bool strace=True)

Static Public Member Functions
None	withConsole ()
None	printLog2File (*object value, Union[common.LogLevel, int] level=common.LogLevel.DEBUG, str mode='a', Union[TextIOWrapper, str, None] file=None, Union[str, None] sep=None, Union[str, None] end=None, bool wrapping=True, bool strace=True, bool header=True)
None	printLog (*object value, Union[int, common.LogLevel] level=common.LogLevel.NORMAL, Union[str, None] sep=None, Union[str, None] end=None, file=None, bool flush=True)
None	__printLog__ (bool isatty, Union[common.LogLevel, int] lv, object msg, Union[str, None] s=None, Union[str, None] e=None, bool flsh=True)

Static Public Attributes
	bool
	set the PIPE to STDOUT by default More...
	str
	the default log out file More...
	log = __default_out_file
	create instance attribute as read-only for log location More...

Private Attributes
	__loginfo

Static Private Attributes
	__LOG_INFO_TUPLE
	log info namedtuple for storing class states More...
	__instance__ = None
	create instance attribute for class singleton More...
	__default_out_file = __DEFAULT_OUT_FILE
	create default file instance which can change on construct More...

Detailed Description

A simple logging class to write messages directly to the console
or to a log file.

Class contains a variety of methods to perform logging, all of which
invoke a private wrapper method over the built-in `print()` function,
with enhanced features built into the class methods.

Make use of pseudolog methods (`Logger` pseudonyms) to quickly, and
effectively write a message to a log file. These pseudolog methods
modify the class state to remember the last message logged out to a
file, in addition to its formatting, which can then be written to
the console using the `Logger.withConsole()` method.

Example of using pseudolog methods:
```py
    >>> import clog
    >>> logger = clog.Logger()
    >>>
    >>> logger.debug("A debug message with stacktrace!")
    >>> logger.error("Whoops! This should not be here.").withConsole()
    \033[91mWhoops! This should not be here.\033[0m
    >>>
    >>> msg = "Checking if 1 + 1 = 2..."
    >>> logger.debug(msg, end="\r").withConsole()
    >>> if 1 + 1 != 2:
    ...     logger.error(msg + "failed.").withConsole()
    ... else:
    ...     logger.debug(msg + "ok.").withConsole()
```

Logger can output text to a console with colour, depending on its
associated log level given. Different standard `PIPE`s can also
be written to depending on the level of the log, or if a file
redirect descriptor has been given. Note, colour is omitted when
not writing to console on STDOUT or STDERR.

Member Function Documentation

__new__()

Logger clog._logger.Logger.__new__	(		cls,
		*Union[str, None]	out_f = None
	)

Construct a new instance of the class and initialise it.

Constructor method is used to establish the class as a
Singleton+Factory pattern. A new instance is returned from
the constructor, or if an existing instance is present,
return the object of that instance.

__printLog__()

None clog._logger.Logger.__printLog__ ( bool  isatty, Union[common.LogLevel, int]  lv, object  msg, Union[str, None]   s = None, Union[str, None]   e = None, bool   flsh = True  )

static

Private helper method responsible for invoking the built-in
`print` function with appropriate keyword arugments. Method
identifies the PIPE used and provide text highlighting accordingly.

debug()

Type[Logger] clog._logger.Logger.debug	(		cls,
		*object	value,
		Union[str, None]	sep = None,
		Union[str, None]	end = None,
		bool	wrapping = True,
		bool	strace = True
	)

Pseudolog for writing to log file with level `LogLevel.DEBUG`.

Method is invoked on a `Logger` instance and will directly write
out to a log file using the built-in `printLog2File` helper method.
The returned object is a modified instance of the `Logger` class
which stores information regarding what was written to the log
file, and what formatting was applied. The `Logger.withConsole()`
method can be invoked directly afterwards (or later) to write
the same message to the console.

error()

Type[Logger] clog._logger.Logger.error	(		cls,
		*object	value,
		Union[str, None]	sep = None,
		Union[str, None]	end = None,
		bool	wrapping = True,
		bool	strace = True
	)

Pseudolog for writing to log file with level `LogLevel.ERROR`.

Method is invoked on a `Logger` instance and will directly write
out to a log file using the built-in `printLog2File` helper method.
The returned object is a modified instance of the `Logger` class
which stores information regarding what was written to the log
file, and what formatting was applied. The `Logger.withConsole()`
method can be invoked directly afterwards (or later) to write
the same message to the console.

new()

Logger clog._logger.Logger.new	(		cls,
		*Union[str, None]	out_f = None
	)

printLog()

None clog._logger.Logger.printLog ( *object  value, Union[int, common.LogLevel]   level = common.LogLevel.NORMAL, Union[str, None]   sep = None, Union[str, None]   end = None,   file = None, bool   flush = True  )

static

Wrapper method over the built-in `print()` function defined
using 3.x syntax. All Familiar functionality can be passed to
the method as found when calling `print()`, but comes with added
features.

`Logger.printLog` is designed for purpose of logging information to
the console window or to a file, either via an explicit write by
passing a compatible `SupportsWrite[str]` value to `file=`, or
by redirecting the standard PIPE streams to an external file.
In addition, different levels of logging will result in output
to standard PIPE streams to have appropriate highlighting to the
message displayed. If standard PIPE streams are to be redirected
to an external file via a PIPE redirect, the highlighting syntax
is dropped do prevent ANSI escape code sequences from being
written to file.

The standard log level is `NORMAL`, referring to standard
formatted text to the standard stream. Log level can be
elevated by either passing an integer to represent the log level,
or pass an enum variable from `class LogLevel` from the
`utils/common.py` module.

Examples of logging:
```
    >>> import clog
    >>> clog.Logger.printLog("Hello, World!")
    Hello, World!
    >>> clog.Logger.printLog("Hello,", "World" + "!", level=LogLevel.DEBUG)
    \033[94mHello, World!\033[0m
    >>> clog.Logger.printLog("Hello,", end=" ") ; clog.Logger.printLog("World!", level=1)
    Hello, \033[92mWorld!\033[0m
    >>> with open("dump.log", 'a') as log_file:
    ...     clog.Logger.printLog("Hello, Log File!", file=log_file)
    ...
    >>>
```

printLog2File()

None clog._logger.Logger.printLog2File ( *object  value, Union[common.LogLevel, int]   level = common.LogLevel.DEBUG, str   mode = 'a', Union[TextIOWrapper, str, None]   file = None, Union[str, None]   sep = None, Union[str, None]   end = None, bool   wrapping = True, bool   strace = True, bool   header = True  )

static

Wrapper method over the built-in `print()` function defined
using 3.x syntax. All Familiar functionality can be passed to
the method as found when calling `print()`, but comes with added
features.

Method not to be confused with `Logger.printLog()`,
`printLog2File` provides enhanced and guaranteed handling of
file streams using the built-in `with` statement. `printLog()`
can however write out to a file stream, but requires a
`TextIOWrapper` object to be given, or omitted with `None` for
output to the `STDOUT` stream. `printLog2File` can take a string
pathspec as the location to a file and open the file stream to
write into.

This method is designed strictly to write messages to a log file
with ehanced features, such as line-wrapping and stacktrace. By
default, this method will generate a log entry header with
`strace` and `wrapping` enabled. Optionally, these can be disabled
when calling the method. If the `header` is disabled, it means the
given `value` is written directly to the log file. This allows for
process controlled messages to be written, i.e., a log might be
written employing a process is about to be performed, and append
the values 'ok' or 'failed', depending on the finishing state of
the process.

Examples of logging to file:
```py
    >>> import clog
    >>>
    >>> log_file = ".dump.log"
    >>> clog.Logger.printLog2File("Hello from log file!", file=log_file)
    >>> # note, we can still pass a TextIOWrapper object
    >>> with open(log_file, 'a') as f:
    ...     clog.Logger.printLog2File("Using own wapper.", file=f)
    ...
    >>> # process controlled logging
    >>> clog.Logger.printLog2File("Establishing OS...", end="")
    >>> import os
    >>> clog.Logger.printLog2File(os.name, header=False)
```

NOTE: if `file` is omitted when invoking method, the default
pathspec is used to write to file (defined as `__DEFAULT_OUT_FILE`).
If a new `Logger` instance was established, when `file` is obmitted,
the default pathspec used is defined by the `Logger` instance.

warn()

Type[Logger] clog._logger.Logger.warn	(		cls,
		*object	value,
		Union[str, None]	sep = None,
		Union[str, None]	end = None,
		bool	wrapping = True,
		bool	strace = True
	)

Pseudolog for writing to log file with level `LogLevel.WARN`.

Method is invoked on a `Logger` instance and will directly write
out to a log file using the built-in `printLog2File` helper method.
The returned object is a modified instance of the `Logger` class
which stores information regarding what was written to the log
file, and what formatting was applied. The `Logger.withConsole()`
method can be invoked directly afterwards (or later) to write
the same message to the console.

withConsole()

None clog._logger.Logger.withConsole ( )

static

Write the last message logged to a file to the console as
well. That is, any message written using a pseudolog method.
The last message is determined by a pseudolog, which modifies
the state of the class to remember information regarding what
was recently written out to a log file.

This method will write to the console according to the standard
PIPE of each type of logging level. Colouring will be enabled
for outputs in association to the log level. If PIPE is
redirected to external file, colouring is disabled. Any other
information regarding the formatting of the message is directly
associated to the formatting used when writing to a log file.

Member Data Documentation

__default_out_file

clog._logger.Logger.__default_out_file = __DEFAULT_OUT_FILE

staticprivate

create default file instance which can change on construct

__instance__

clog._logger.Logger.__instance__ = None

staticprivate

create instance attribute for class singleton

__LOG_INFO_TUPLE

clog._logger.Logger.__LOG_INFO_TUPLE

staticprivate

Initial value:

=  namedtuple('__LOG_INFO_TUPLE',
        ['isatty', 'lv', 'msg', 'sep', 'end'])

log info namedtuple for storing class states

__loginfo

clog._logger.Logger.__loginfo

private

bool

clog._logger.Logger.bool

static

set the PIPE to STDOUT by default

detect if there's a redirect

log

clog._logger.Logger.log = __default_out_file

static

create instance attribute as read-only for log location

handle if a custom file pathspec was given

verify path and convert to real pathspec.

redefine the default log out attribute and create public attribute for the currect log location

str

clog._logger.Logger.str

static

the default log out file

---

The documentation for this class was generated from the following file:

• clog/_logger.py