out 0.79__py3-none-any.whl

out/__init__.py

@@ -0,0 +1,253 @@
+'''
+    out - Simple logging with a few fun features.
+    © 2018-25, Mike Miller - Released under the LGPL, version 3+.
+'''
+import os
+import sys
+import logging
+import traceback
+
+from .detection import _find_palettes, is_fbterm
+
+
+# detect environment before loading formatters and themes
+_out_file = sys.stderr
+fg, bg, fx, _level, _is_a_tty  = _find_palettes(_out_file)
+
+
+# now we're ready to import these:
+from .format import (ColorFormatter as _ColorFormatter,
+                     JSONFormatter as _JSONFormatter)
+from .themes import (render_themes as _render_themes,
+                     render_styles as _render_styles,
+                     icons as _icons)
+
+__version__ = '0.79'
+
+# Allow string as well as constant access.  Levels will be added below:
+level_map = {
+    'debug': logging.DEBUG,
+    'info': logging.INFO,
+    'warn': logging.WARN,
+    'warning': logging.WARN,
+    'err': logging.ERROR,
+    'error': logging.ERROR,
+    'critical': logging.FATAL,
+    'fatal': logging.FATAL,
+}
+
+
+class Logger(logging.Logger):
+    '''
+        A singleton logger with centralized configuration.
+    '''
+    default_level = logging.INFO
+    __path__ = __path__         # allows python3 -m out.demos to work
+    __version__ = __version__
+    __name__ = __name__
+    __spec__ = None  # needed to make -m happy in recent pythons :-/
+
+    def configure(self, **kwargs):
+        ''' Convenience function to set a number of parameters on this logger
+            and associated handlers and formatters.
+        '''
+        for kwarg in kwargs:
+            value = kwargs[kwarg]
+
+            if kwarg == 'level':
+                self.set_level(value)
+
+            elif kwarg == 'default_level':
+                self.default_level = level_map.get(value, value)
+
+            elif kwarg == 'datefmt':
+                self.handlers[0].formatter.datefmt = value
+
+            elif kwarg == 'msgfmt':
+                self.handlers[0].formatter._style._fmt = value
+
+            elif kwarg == 'stream':
+                self.handlers[0].stream = value
+                _, _, _, tlevel, is_a_tty = _find_palettes(value)
+                # probably shouldn't auto configure theme, but it does,
+                # skipping currently
+                _add_handler(value, is_a_tty, tlevel, theme=None)
+
+            elif kwarg == 'theme':
+                if type(value) is str:
+                    # this section should be reconciled with _add_handler
+                    theme = _render_themes(self.handlers[0].stream)[value]
+                    if value == 'plain':
+                        fmtr = logging.Formatter(style='{', **theme)
+                    elif value == 'json':
+                        tlvl = self.handlers[0]._term_level
+                        if is_fbterm:   hl = False          # doesn't work well
+                        else:           hl = bool(tlvl)     # highlighting
+                        fmtr = _JSONFormatter(term_level=tlvl, hl=hl, **theme)
+                    else:
+                        fmtr =  _ColorFormatter(**theme)
+                elif type(value) is dict:
+                    if 'style' in value or 'icons' in value:
+                        fmtr =  _ColorFormatter(**theme)
+                    else:
+                        fmtr =  logging.Formatter(style='{', **theme)
+                self.handlers[0].setFormatter(fmtr)
+
+            elif kwarg == 'highlight':
+                value = bool(value)
+                if value is False:  # True value is a highlighter
+                    self.handlers[0].formatter._highlight = value
+
+            elif kwarg == 'icons':
+                if type(value) is str:
+                    value = _icons[value]
+                self.handlers[0].formatter._theme_icons = value
+
+            elif kwarg == 'style':
+                if type(value) is str:
+                    value = _render_styles(self.handlers[0].stream)[value]
+                self.handlers[0].formatter._theme_style = value
+
+            elif kwarg == 'lexer':
+                try:
+                    self.handlers[0].formatter.set_lexer(value)
+                except AttributeError:
+                    self.error('lexer: ColorFormatter not available.')
+            else:
+                raise NameError('unknown keyword argument: %s' % kwarg)
+
+    def log_config(self):
+        ''' Log the current logging configuration. '''
+        level = self.level
+        debug = self.debug
+        debug('out logging config, version: %r', __version__)
+        debug('  .name: {}, id: {}', self.name, hex(id(self)))
+        debug('  .level: %s (%s)', level_map_int[level], level)
+        debug('  .propagate: %s', self.propagate)
+        debug('  .default_level: %s (%s)',
+                   level_map_int[self.default_level], self.default_level)
+
+        for i, handler in enumerate(self.handlers):
+            fmtr = handler.formatter
+            debug('  + Handler: %s %r', i, handler)
+            debug('    + Formatter: %r', fmtr)
+            debug('      .datefmt: %r', fmtr.datefmt)
+            debug('      .msgfmt: %r', fmtr._fmt)
+            debug('      fmt_style: %s', fmtr._style)
+            debug('      theme.styles: %r', fmtr._theme_style)
+            debug('      theme.icons: %r', fmtr._theme_icons)
+            try:
+                debug('      highlighting: %r, %r',
+                    fmtr._lexer.__class__.__name__,
+                    fmtr._hl_fmtr.__class__.__name__)
+            except AttributeError:
+                pass
+
+    def setLevel(self, level):
+        if type(level) is int:
+            super().setLevel(level)
+        else:
+            super().setLevel(level_map.get(level.lower(), level))
+    set_level = setLevel
+
+    def __call__(self, message, *args):
+        ''' Call logger directly, without function. '''
+        if self.isEnabledFor(self.default_level):
+            self._log(self.default_level, message, args)
+
+
+def add_logging_level(name, value, method_name=None):
+    ''' Comprehensively adds a new logging level to the ``logging`` module and
+        the currently configured logging class.
+
+        Derived from: https://stackoverflow.com/a/35804945/450917
+    '''
+    if not method_name:
+        method_name = name.lower()
+
+    # set levels
+    logging.addLevelName(value, name)
+    setattr(logging, name, value)
+    level_map[name.lower()] = value
+
+    if value == getattr(logging, 'EXCEPT', None):  # needs traceback added
+        def log_for_level(self, message='', *args, **kwargs):
+            show = kwargs.pop('show', True)
+            if self.isEnabledFor(value):
+                if show:
+                    message = message.lstrip() + ' ▾\n'
+                    message += traceback.format_exc()
+                else:
+                    message = message.lstrip()
+                self._log(value, message, args, stacklevel=2, **kwargs)
+    else:
+        def log_for_level(self, message, *args, **kwargs):
+            if self.isEnabledFor(value):
+                self._log(value, message, args, stacklevel=2, **kwargs)
+
+    #~ def logToRoot(message, *args, **kwargs):  # may not need
+        #~ logging.log(value, message, *args, **kwargs)
+
+    # set functions
+    setattr(logging.getLoggerClass(), method_name, log_for_level)
+    #~ setattr(logging, method_name, logToRoot)
+
+
+def _add_handler(out_file, is_a_tty, level, theme='auto'):
+    ''' Repeatable handler config. '''
+    if is_fbterm:
+        hl = False          # doesn't work well
+    else:
+        hl = level > 1    # highlighting > ANSI_MONOCHROME
+    _handler = logging.StreamHandler(stream=out_file)
+
+    if theme == 'auto':
+        _theme_name = 'interactive' if is_a_tty else 'production'
+        if os.environ.get('TERM') in ('linux', 'fbterm'):
+            _theme_name = 'linux_' + _theme_name
+        if os.name == 'nt':
+            _theme_name = 'windows_' + _theme_name
+        theme = _render_themes(out_file, fg=fg, bg=bg, fx=fx)[_theme_name]
+    elif theme is None:
+        try:
+            fmtr = out.handlers[0].formatter
+            theme = dict(
+                icons=fmtr._theme_icons, style=fmtr._theme_style,
+                fmt=fmtr._style._fmt, datefmt=fmtr.datefmt,
+            )
+        except AttributeError:
+            theme = {}
+
+    out.handlers = []  # clear any old
+    _handler._term_level = level
+    _formatter = _ColorFormatter(hl=hl, term_level=level, **theme)
+    _handler.setFormatter(_formatter)
+    out.addHandler(_handler)
+
+
+# re-configure root logger
+out = logging.getLogger()   # root
+out.name = 'main'
+out.__class__ = Logger      # one way to add call()
+
+# odd level numbers chosen to avoid commonly configured variations
+add_logging_level('TRACE', 7)
+add_logging_level('NOTE', 27)
+add_logging_level('EXCEPT', logging.ERROR + 3, 'exception')
+add_logging_level('EXCEPT', logging.ERROR + 3, 'exc')
+add_logging_level('FATAL', logging.FATAL)
+level_map_int = {
+    val: key
+    for key, val in level_map.items()
+}
+out.warn = out.warning  # fix warn
+out.set_level('note')
+
+_add_handler(_out_file, _is_a_tty, _level)
+
+
+# save original module for later, in case it's needed.
+out._module = sys.modules[__name__]
+
+# Wrap module with instance for direct access
+sys.modules[__name__] = out

out/demos.py

@@ -0,0 +1,76 @@
+'''
+    out - Simple logging with a few fun features.
+    © 2018-25, Mike Miller - Released under the LGPL, version 3+.
+'''
+import sys
+import out
+
+
+def test_levels(full=True):
+
+    out('no explicit level, should be info.')
+    out.trace('trace msg: %s', 'Absurdly voluminous details…')
+    out.debug('debug message')
+    out.info('info message - Normal feedback')
+    out.note('note message - Important positive feedback to remember.')
+    out.warn('warn message - Something to worry about.')
+
+    if full:
+        out.critical('critical message - *flatline*')
+        out.fatal('fatal message - *flatline*')
+        try:
+            1/0
+        except Exception:
+            out.error('error message - Pow!')
+            #~ out.exception('exception message - Kerblooey!')
+            out.exc('exc message - Kerblooey!')
+
+
+out.warn('begin...')
+print('⏵⏵ print std config:')
+out.configure(
+    level='trace',   # needs to go before to allow console log to be viewed!
+)
+out.log_config()
+print('---------------------------------')
+
+
+print('⏵⏵ change to stdout:')
+out.configure(
+    #~ theme='interactive',
+    stream=sys.stdout,  # runs console.detection again
+)
+out.log_config()
+print('---------------------------------')
+
+
+print('⏵⏵ log messages from module:')
+from out import test_mod; test_mod  # pyflakes
+print()
+
+print('⏵⏵ test levels:')
+test_levels()
+print('---------------------------------')
+
+
+print('⏵⏵ test different highlighting, lexers:')
+out.configure(lexer='json')
+out.debug('debug message: JSON: %s', '{"data": [null, true, false, "hi", 123]}')
+
+out.configure(lexer='xml')
+out.trace('trace message: XML: %s', '<xml><tag attr="woot">text</tag></xml><!-- hi -->')
+
+out.configure(lexer='python3')
+out.note('debug message: PyON: %s # hi',
+         {'data': [None, True, False, 'hi', 123]})
+out.note('import foo; [ x for x in y ]')
+print('---------------------------------')
+
+
+print('⏵⏵ test json formatter:')
+out.configure(
+    level='info',
+    theme='json',
+)
+out('no explicit level')
+out.warn('warn: Heavens to Mergatroyd!')

out/detection.py

@@ -0,0 +1,20 @@
+'''
+    out - Simple logging with a few fun features.
+    © 2018-25, Mike Miller - Released under the LGPL, version 3+.
+'''
+from console.constants import TermLevel
+from console.detection import init, is_a_tty, is_fbterm, os_name
+from console.style import ForegroundPalette, BackgroundPalette, EffectsPalette
+
+
+def _find_palettes(stream):
+    ''' Need to configure palettes manually, since we are checking stderr. '''
+    level = init(_stream=stream)
+    fg = ForegroundPalette(level=level)
+    bg = BackgroundPalette(level=level)
+    fx = EffectsPalette(level=level)
+
+    return fg, bg, fx, level, is_a_tty(stream)
+
+
+TermLevel, is_fbterm, os_name  # quiet pyflakes

out/format.py

@@ -0,0 +1,249 @@
+'''
+    out - Simple logging with a few fun features.
+    © 2018-25, Mike Miller - Released under the LGPL, version 3+.
+
+    Message template variables:
+
+        {name}              Name of the logger (logging channel)
+        {levelno}           Numeric logging level for the message (DEBUG, INFO,
+                                WARNING, ERROR, CRITICAL)
+        {levelname}         Text logging level for the message ("DEBUG", "INFO",
+                                "WARNING", "ERROR", "CRITICAL")
+        {pathname}          Full pathname of the source file where the logging
+                                call was issued (if available)
+        {filename}          Filename portion of pathname
+        {module}            Module (name portion of filename)
+        {lineno)d           Source line number where the logging call was issued
+                                (if available)
+        {funcName}          Function name
+        {created}           Time when the LogRecord was created (time.time()
+                                return value)
+        {asctime}           Textual time when the LogRecord was created
+        {msecs}             Millisecond portion of the creation time
+        {relativeCreated}   Time in milliseconds when the LogRecord was created,
+                            relative to the time the logging module was loaded
+                            (typically at application startup time)
+        {thread}            Thread ID (if available)
+        {threadName}        Thread name (if available)
+        {process}           Process ID (if available)
+        {message}           The result of record.getMessage(), computed just as
+                                the record is emitted
+
+        # added:
+        {on}…{off}          Toggles level-specific style (colors, etc) support.
+        {icon}              Level-specific icon.
+'''
+import logging
+import re
+from pprint import pformat
+
+from . import themes
+from . import fx
+from . import highlight
+from .detection import is_fbterm
+
+DATA_SEARCH_LIMIT = 80
+_end = str(fx.end)
+if is_fbterm:  # fbterm esc seqs conflict with brace formatting :-/
+    _end = _end.replace('}', '}}')
+
+# compile searches for data message highlighting
+json_data_search = re.compile(r'\{|\[|"').search
+xml_data_search = re.compile('<').search
+pyt_data_search = re.compile(r'''
+    \{              # literal
+        |           #   or
+    \[              # left bracket
+        |           #   or...
+    \(
+        |
+    :
+''', re.VERBOSE).search
+
+
+class ColorFormatter(logging.Formatter):
+    ''' Colors the level-name of a log message according to the level.
+
+        Arguments:
+
+            datefmt         - strftime datetime template
+            fmt             - log template
+            icons           - dict of level:value for icons
+            style           - dict of level:value for terminal style
+            template_style  - log template syntax: %, {, $
+
+            # highlighting
+            hl              - bool, highlight the message.
+            lexer           - None, or Pygment's lexer: python3', 'json', etc.
+            hl_formatter    - None, or pass a configured Pygments formatter.
+            code_indent     - If highlighting data with newlines, indent N sp.
+    '''
+    default_msec_format = '%s.%03d'  # use period decimal point
+
+    def __init__(self,
+            code_indent=12,
+            datefmt=None,
+            fmt=None,
+            hl=True,
+            hl_formatter=None,
+            term_level=None,
+            icons=None,
+            lexer='python3',
+            style=None,
+            template_style='{',
+        ):
+        self._theme_style = (
+            style if style else themes.render_styles(term_level)['norm']
+        )
+        self._theme_icons = icons if icons else themes.icons['rounded']
+        self._code_indent = code_indent
+        self._highlight = self._lexer = None
+        if hl:
+            if lexer:
+                self._highlight = highlight.highlight
+                self.set_lexer(lexer)
+            self._hl_fmtr = hl_formatter or highlight.get_term_formatter(term_level)
+
+        super().__init__(fmt=fmt, datefmt=datefmt, style=template_style)
+
+    def set_lexer(self, name):
+        if highlight.get_lexer_by_name:
+            self._lexer = highlight.get_lexer_by_name(name)
+            self._lexer.ensurenl = False
+        if name == 'xml':
+            self.data_search = xml_data_search
+        elif name == 'json':
+            self.data_search = json_data_search
+        else:
+            self.data_search = pyt_data_search
+
+    def format(self, record):
+        ''' Log color formatting. '''
+        levelname = record.levelname    # len7 limit
+        if levelname == 'CRITICAL':
+            levelname = record.levelname = 'FATAL'
+        if self.usesTime():
+            record.asctime = self.formatTime(record, self.datefmt)
+        if record.funcName == '<module>':
+            record.funcName = ''
+
+        # render the message part with arguments
+        try:  # Allow {} style - need a faster way to determine this:
+            message = record.getMessage()
+        except TypeError:
+            message = record.msg.format(*record.args)
+
+        # decide to highlight w/ pygments
+        # TODO: Highlight args directly and drop text scan? - didn't work well.
+        if self._highlight:
+            if message.find('\x1b', 0, DATA_SEARCH_LIMIT) > -1:
+                pass  # found escape, avoid ANSI
+            else:
+                match = self.data_search(message, 0, DATA_SEARCH_LIMIT)
+                if match:
+                    pos = match.start()
+                    front, back = message[:pos], message[pos:]  # Spliten-Sie
+                    if front.endswith('\n'):                    # indent data?
+                        back = pformat(record.args)
+                        back = left_indent(back, self._code_indent)
+                    back = self._highlight(back, self._lexer, self._hl_fmtr)
+                    message = f'{front}{back}'
+
+        # style the level, icon
+        record.message = message
+        record.on = self._theme_style.get(levelname, '')
+        record.icon = self._theme_icons.get(levelname, '')
+        record.off = _end
+        s = self.formatMessage(record)
+
+        # this needs to be here, Formatter class not very granular.
+        if record.exc_info:
+            # Cache the traceback text to avoid converting it multiple times
+            # (it's constant anyway)
+            if not record.exc_text:
+                record.exc_text = self.formatException(record.exc_info)
+        if record.exc_text:
+            if s[-1:] != "\n":
+                s = s + "\n"
+            s = s + record.exc_text
+        if record.stack_info:
+            if s[-1:] != "\n":
+                s = s + "\n"
+            s = s + self.formatStack(record.stack_info)
+        return s
+
+
+class JSONFormatter(logging.Formatter):
+    '''
+        Formats a log message into line-oriented JSON.
+
+        The message template format is different.
+        It uses simple CSV (no spaces allowed) to define field order, e.g.:
+
+            fmt='asctime,msecs,levelname,name,funcName,lineno,message'
+
+        (Currently field order requires Python 3.6, but could be backported.)
+    '''
+    def __init__(self, datefmt=None, fmt=None, term_level=None, hl=True,
+                 hl_formatter=None):
+        self._fields = fmt.split(',')
+        from json import dumps
+        self.dumps = dumps
+        self._highlight = None
+        if hl:
+            self._highlight = highlight.highlight
+            if self._highlight:
+                self._lexer = highlight.get_lexer_by_name('JSON')
+                self._hl_formatter = (
+                    hl_formatter or highlight.get_term_formatter(term_level)
+                )
+        try:
+            super().__init__(fmt=fmt, datefmt=datefmt)
+        except ValueError:  # py 3.8 :-/
+            super().__init__(fmt=fmt, datefmt=datefmt, validate=False)
+
+    def format(self, record):
+        ''' Log color formatting. '''
+        levelname = record.levelname
+        if levelname == 'CRITICAL':
+            levelname = record.levelname = 'FATAL'
+        record.asctime = self.formatTime(record, self.datefmt)
+
+        # render the message part with arguments
+        try:  # Allow {} style - need a faster way to determine this:
+            message = record.getMessage()
+        except TypeError:
+            message = record.msg.format(*record.args)
+        record.message = message
+
+        fields = self._fields
+        data = { name: getattr(record, name) for name in fields }
+        if 'asctime' in fields and 'msecs' in fields:  # needs option for this
+            data['asctime'] += '.{:03.0f}'.format(data.pop('msecs'))
+        s = self.dumps(data)
+        if self._highlight:
+            s = self._highlight(s, self._lexer, self._hl_formatter).rstrip()
+
+        # this needs to be here, Formatter class isn't very extensible.
+        if record.exc_info:
+            # Cache the traceback text to avoid converting it multiple times
+            # (it's constant anyway)
+            if not record.exc_text:
+                record.exc_text = self.formatException(record.exc_info)
+        if record.exc_text:
+            if s[-1:] != "\n":
+                s = s + "\n"
+            s = s + record.exc_text
+        if record.stack_info:
+            if s[-1:] != "\n":
+                s = s + "\n"
+            s = s + self.formatStack(record.stack_info)
+        return s
+
+
+def left_indent(text, indent=12, end='\n'):
+    ''' A bit of the ol' ultraviolence  :-/ '''
+    indent = ' ' * indent
+    lines = [indent + line for line in text.splitlines(True)]
+    lines.append(end)
+    return ''.join(lines)

out/highlight.py

@@ -0,0 +1,92 @@
+'''
+    out - Simple logging with a few fun features.
+    © 2018-25, Mike Miller - Released under the LGPL, version 3+.
+
+    Highlighting with Pygments!
+'''
+try:
+    from pygments import highlight
+    from pygments.lexers import get_lexer_by_name
+    from pygments.token import (Keyword, Name, Comment, String, Error,
+                                Number, Operator, Punctuation,
+                                Token, Generic, Whitespace)
+except ImportError:
+    highlight = get_lexer_by_name = None
+
+from .detection import TermLevel
+
+
+def get_term_formatter(level):
+    ''' Build formatter according to environment. '''
+
+    term_formatter = None
+    if level and highlight:
+
+        if level >= TermLevel.ANSI_EXTENDED:
+
+            from pygments.formatters import Terminal256Formatter
+            from pygments.style import Style
+
+            class OutStyle(Style):
+                styles = {
+                    Comment:                'italic ansibrightblack',
+                    Keyword:                'bold #4ac',  # light blue
+                    Keyword.Constant:       'nobold #3aa',  # ansicyan
+                    Number:                 'ansigreen',
+
+                    Name.Tag:               '#4ac',  # light blue, xml, json
+                    Name.Attribute:         '#4ac',  # light blue
+
+                    Operator:               'nobold #b94',
+                    Operator.Word:          'bold #4ac',
+                    Punctuation:            'nobold #b94',
+
+                    # not sure about string, hard to find a good warm color
+                    Generic.String:         'ansired',
+                    String:                 'ansibrightmagenta',
+                    #~ String:                 '#b00',  # brick red
+                    #~ String:                 '#f80',  # bright amber
+                    #~ String:                 '#d80',  # med amber
+                }
+            term_formatter = Terminal256Formatter(style=OutStyle)
+
+        elif level >= TermLevel.ANSI_BASIC:
+
+            from pygments.formatters import TerminalFormatter
+
+            _default = ('', '')
+            color_scheme = {
+                Comment.Preproc:    _default,
+                Name:               _default,
+                Token:              _default,
+                Whitespace:         _default,
+                Generic.Heading:    ('**',                  '**'),
+
+                Comment:            ('brightblack',         'brightblack'),
+                Keyword:            ('*brightblue*',        '*brightblue*'),
+                Keyword.Constant:   ('cyan',                'cyan'),
+                Keyword.Type:       ('cyan',                'cyan'),
+                Operator:           ('yellow',              'yellow'),
+                Operator.Word:      ('*brightblue*',        '*brightblue*'),
+
+                Name.Builtin:       ('cyan',                'cyan'),
+                Name.Decorator:     ('magenta',             'magenta'),
+                Name.Tag:           ('brightblue',          'brightblue'),
+                Name.Attribute:     ('brightblue',          'brightblue'),
+
+                String:             ('brightmagenta',       'brightmagenta'),
+                Number:             ('green',               'green'),
+
+                Generic.Deleted:    ('red',                 'brightred'),
+                Generic.Inserted:   ('green',               'brightgreen'),
+                Generic.Error:      ('brightred',           'brightred'),
+
+                Error:              ('_brightred_',         '_brightred_'),
+            }
+
+            term_formatter = TerminalFormatter(
+                bg='dark',
+                colorscheme=color_scheme,
+            )
+
+    return term_formatter