Out
===========
Fun take on logging for non-huge projects—out gets "outta" the way!
Background
--------------------------
If you're here it's very likely you already know that the Python standard
logging module is extremely flexible,
and that's great.
Unfortunately, it is overkill for small to medium projects,
and these days many larger ones too.
Additionally,
its various Java-isms grate on the nerves,
accentuating a big enterprisey design.
Meanwhile,
the rise of
`12 Factor App <https://12factor.net/logs>`_
patterns for daemons and services
means that simply logging to stdout/err is expected and desired
for portability:
*A twelve-factor app never concerns itself with routing or storage of its
output stream. It should not attempt to write to or manage logfiles.
Instead, each running process writes its event stream, unbuffered, to
stdout. During local development, the developer will view this stream in
the foreground of their terminal to observe the app’s behavior.*
Therefore,
for many (if not most) applications,
all the complexity and mumbo-jumbo in the logging package documentation about
multiple loggers with different levels, different handlers, formatters,
adapters, filters, rotation,
and complex configuration is flexibility at the *wrong level!*
In fairness,
this may not have always been the case,
and can still be helpful, perhaps on Windows.
Additionally, logging tools have also become standardized over time,
handling cross-language and cross-platform messages.
Imagine a pipeline where log events are routed and multiple tools can be
plugged in or out as needed—\
organization-wide rather than app- or language-wide.
So, unless you have unique requirements,
there's no need to reimplement ``logrotate``, ``syslog``, ``systemd``, and
proprietary metrics tools in every programming language.
Just blast those logs to stdout/stderr and get logging *outta* the way!
Enter the ``out`` project.
It's ready to start logging from the get go.
It uses Python's standard logging infrastructure by default,
so is still quite flexible when need be.
Well, you've heard this before.
However, *out* tries a bit harder create a fun, easy-to-use interface,
as discussed above.
**Naming**
Regarding the name,
well of course would have liked something along the lines of ``log`` but all
variations of that are *long gone* on PyPI.
``out()`` is a name I've often used over the years as a poor-man's logger—\
really a functional wrapper around ``print``,
until I could get around to adding proper logging.
Now, the tradition continues.
The name is short, simple, and conceptually fits,
if a little bland.
Features
------------
First of all,
out is concise as hell,
basically a singleton logger configuration ready on import.
In interactive mode:
.. code-block:: python-console
>>> import out
>>> out('And away we go…') # configurable default level
🅸 main/func:1 And away we go…
>>> out.warn('Danger Will Robinson!')
🆆 main/func:1 Danger Will Robinson!
(Imagine with nice ANSI colors. 😁)
Out has simple themes for message formats, styles, and icons.
Not to worry,
out is more conservative in "production mode,"
which may be turned on automatically by redirecting ``stderr``:
.. code-block:: shell
⏵ python3 script.py |& cat # bash, for fish use: &|
2018-09-10 17:18:19.123 ✗ ERROR main/func:1 Kerblooey!
.. note::
This is a library to simplify logging configuration for *applications.*
Libraries and independent modules should continue on logging *messages* as
they always have:
.. code-block:: python
import logging
log = logging.getLogger(__name__)
# do not configure loggers, just use:
log.debug('foo')
Colors, Highlighting, Unicode Icons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Colors are ready to go in interactive mode,
and turn off automatically when output is redirected.
- Unicode symbols are used throughout as "icons" for increased readability and
conciseness.
- Syntax highlighting of data structures (oft parsed from remote APIs) is
available too, via Pygments.
Useful defaults, and easy to configure!
.. code-block:: python-console
>>> out.configure(
level='note', # level messages passed: str/int
default_level='info', # when called w/o a method: out('…')
datefmt='…', # see strftime
msgfmt='…', # see logging and below
stream=file, # stderr is default
theme=name|dict, # see below
icons=name|dict, # about themes
style=name|dict,
highlight=False, # disable highlighting
lexer='python3', # choose lexer
)
We'll go into more detail below.
Log Message Format
~~~~~~~~~~~~~~~~~~~
By default out supports the curly-brace ``{}`` formatting style for both the
log message format and message template,
as it is a bit easier to read than printf-style.
Field definitions are found in the Python
`logging docs <https://docs.python.org/3/library/logging.html#logrecord-attributes>`_::
{asctime} Textual time when the LogRecord created.
{msecs} Millisecond portion of the creation time
{filename} Filename portion of pathname
{funcName} Function name
{lineno) Source line number where called.
{levelno} Numeric logging level for the message
{levelname} Text logging level for the message
{pathname} Full path of the source file called.
{message} The result of record.getMessage().
{module} Module (name portion of filename)
{name} Name of the logger (logging channel)
Use of the
``out.format.ColorFormatter`` class adds these additional fields::
{on}{icon}{off} Per-level style and icon support.
For example:
.. code-block:: python
out.configure(
msgfmt='{on}{icon}{levelname:<7}{off} {message}',
)
DateTime Format
++++++++++++++++++
These are configuable via the standard
`strftime <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`_
syntax and the
``datefmt`` keyword to ``configure``.
.. code-block:: python
out.configure(
datefmt='%y-%m-%d %H:%M:%S',
)
Message:
++++++++++++++++++
When writing messages, printf ``%`` formatting style is supported as well
due to compatibility requirements with a majority of libraries:
.. code-block:: python
out.warn('foo: %s', bar)
out.warn('foo: {}', bar)
The second form may be used also,
though it will be a tiny bit slower,
since the printf-style must be tried first.
You'll want to use one of these forms,
as (in logging) they skip formatting of the string when the message isn't
sent.
Levels++
~~~~~~~~~~~~~~~~~~~~~~~~~~
While the
`standard levels <https://docs.python.org/3/library/logging.html#levels>`_
continue to exist
(``NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL``).
A few additions and slight modifications have been made.
Commonly requested:
- ``TRACE``, for absurdly voluminous data, perhaps system calls or network
traffic.
- ``NOTE``, for **positive** messages
that should/must be shown by default---\
unlike the standard warning,
which could encourage the viewer to worry. e.g.:
| ``NOTE`` - Token is ABCXYZ, rather than…
| ``WARNING`` - Token is ABCXYZ.
- ``EXCEPT``, to differentiate common from unexpected errors.
Think ``FileNotFound`` vs. ``Exception``.
- ``FATAL``, an alias of ``CRITICAL``,
since that name is long, pushes alignment,
and does not capture intent as well as fatal.
Std-lib already allows this but still labels it critical on output.
Out does not.
Themes
~~~~~~~~~~~~~~~~~~
Icons and Styles
+++++++++++++++++
``out`` can be themed with icon sets and/or styles and are simply dictionaries
with one entry per level.
.. code-block:: python-console
>>> from out.themes import themes, icons, styles
>>> icons['circled'] # Unicode
{'TRACE': '🅣', 'DEBUG': '🅓', 'INFO': '🅘', 'WARNING': '🅦',
'NOTE': '🅝', 'ERROR': '🅔', 'EXCEPT': '🅧', 'CRITICAL': '🅕',
'FATAL': '🅕', 'NOTSET': '🅝'}
>>> styles['blink'] # ANSI escapes
{'TRACE': '\x1b[35m', 'DEBUG': '\x1b[34m', 'INFO': '\x1b[32m',
'WARNING': '\x1b[93m', 'NOTE': '\x1b[96m', 'ERROR': '\x1b[31m',
'EXCEPT': '\x1b[91m', 'CRITICAL': '\x1b[97m',
'FATAL': '\x1b[97;5m', 'NOTSET': '\x1b[0m'}
The
`console <https://mixmastamyk.bitbucket.io/console/>`_
package is a good choice to generate ANSI styles for the levels,
as well as styling other fields:
.. code-block:: python
from console import fg, bg, fx
import out
blue_note = dict(
NOTE=str(fg.lightblue + fx.bold + fx.reverse),
# other levels…
)
out.configure(
style=blue_note, # ← level styles, ↓ field styles
msgfmt=bg.blue('{asctime}') + ' {message}',
)
out.note('John Coltrane')
Creating and Using Themes
++++++++++++++++++++++++++
A full theme is the whole kit together in a mapping—\
styles, icons, ``message`` and/or ``datefmt`` templates:
.. code-block:: python-console
>>> interactive_theme = {
'style': {}, # level:value mapping, see above
'icons': {}, # level:value
'fmt': '{asctime} {icon} {message}', # message format
'datefmt': '%H:%M:%S', # date/time format,
}
In the ``configure`` method of the out logger,
to use a theme from the themes module,
simply specify an existing one by name:
.. code-block:: python-console
>>> out.configure(
theme='production',
)
Or by setting a custom mapping, as created above:
.. code-block:: python-console
>>> out.configure(
theme=interactive_theme, # or perhaps just icons:
icons=dict(DEBUG='• ', INFO='✓ ', WARNING='⚠ ', ) # …
)
A few themes are bundled:
Icons:
ascii,
ascii_symbol,
circled,
circled_lower,
rounded,
symbol
Styles:
- norm
- bold
- mono (monochrome)
- blink (fatal error only)
Full themes:
- interactive
- production
- plain (Uses logging.Formatter for lower overhead.)
- json (Uses formatter.JSONFormatter)
- mono (monochrome)
- linux_interactive, linux_production (vga console)
.. note::
When there are conflicting arguments to the ``configure`` method,
the last specified will win.
This requires a Python version >=3.6, due to ordered keyword args.
Below this version it is not recommended to try since keyword order
will be undefined and therefore the result.
One workaround, call ``configure()`` twice.
Syntax Highlighting w/Pygments
--------------------------------
When Pygments is installed,
syntax highlighting is available for Python data structures and code,
as well as JSON and XML strings—\
potentially anything Pygments can highlight.
This can be helpful when debugging remote APIs for example.
A lexer may be
`selected by name <http://pygments.org/docs/lexers/>`_
via ``configure(lexer=LEXER_NAME)``,
disabled by setting to ``None``.
Some common lexer names are: ``('json', 'python3', 'xml')``.
**Use:**
Message text following a ``{, [, <, or '`` char
is highlighted with the current
lexer+formatter:
.. code-block:: python
out.configure(level='trace')
# default Python3
out.trace('PYON data: %s',
{'data': [None, True, False, 123]})
out.configure(lexer='json')
out.trace('JSON data: '
'{"data": [null, true, false, 123]}')
(Imagine with lovely ANSI flavors. 😁)
Performance
-----------------
out does quite a few things,
but it tries not to do any duplicate work or anything excessively stupid.
It takes about 25 microseconds to log a simple message,
or ~90 for a complex highlighted one on a newer machine.
Had to run a loop several thousand times (only logging) before it added up to
a noticeable delay.
Theming and highlighting are easy to turn off for production mode,
so "out" should hopefully not slow you down at all when not developing.
Tips
---------
- By default the logger prints to ``stderr``.
The reason being that when used in an interactive script normal application
output may be easily segregated from log messages during redirection.
.. code-block:: shell
# bash, fish
⏵ script.py 2> logfile.txt
Configurable via the ``stream`` keyword to ``.configure()``:
.. code-block:: python
import sys, out
out.configure(
stream=sys.stdout,
)
- Upgrading a long script from ``print()`` is easy:
.. code-block:: python
import out
print = out # or other level: out.note
Or perhaps some logging was already added, but you'd like to downsize.
Add this to your main script::
import out as logger
Less code will need to be changed.
.. ~ - Want to keep your complex configuration but use the ``ColorFormatter`` class
.. ~ and themes in your own project?
- The ``ColorFormatter`` and ``JSONFormatter`` classes can be used in your own
project:
.. code-block:: python-console
>>> from out.format import ColorFormatter
>>> cf = ColorFormatter()
>>> handler.setFormatter(cf)
- To print the current logging configuration:
.. code-block:: python-console
>>> out.log_config() # quotes to shut off highlighting:
'''
🅳 Logging config:
🅳 / name: main, id: 139973461370360
🅳 .level: trace (7)
🅳 .default_level: info (20)
🅳 + Handler: 0 <StreamHandler <stderr> (NOTSET)>
🅳 + Formatter: <out.format.ColorFormatter object at 0x7f4e1c65efd0>
🅳 .style: <logging.StrFormatStyle object at 0x7f4e1c65ef28>
🅳 .datefmt: '%H:%M:%S'
🅳 .msgfmt: ' {on}{icon}{off} {message}'
'''
The logger in the main script file is named "main,"
also known as the "root" logger.
Troubleshooting
-----------------
- If you'd like to know what ``out`` is doing,
try running the ``.log_config()`` method to log what's currently up:
.. code-block:: python-console
>>> out.log_config()
.. code-block:: shell
🅳 out logging config, version: '0.70a1'
🅳 .name: main, id: 0x7f88e9ec7198
🅳 .level: debug (10)
🅳 .default_level: info (20)
🅳 + Handler: 0 <StreamHandler <stdout> (NOTSET)>
🅳 + Formatter: <out.format.ColorFormatter object at 0x7f88e9ce1b70>
🅳 .datefmt: '%H:%M:%S'
🅳 .msgfmt: ' {on}{icon:<2}{off} \x1b[38;5;242m{name}/\x1b[38;5;245m{funcName}:\x1b[32m{lineno:<3}\x1b[0m {message}'
🅳 fmt_style: <logging.StrFormatStyle object at 0x7f88e9ca5080>
🅳 theme.styles: {'TRACE': '\x1b[35m', 'DEBUG': '\x1b[34m', 'INFO': '\x1b[32m', 'NOTE': '\x1b[96m', 'WARNING': '\x1b[93m', 'ERROR': '\x1b[31m', 'EXCEPT': '\x1b[91m', 'CRITICAL': '\x1b[97m', 'FATAL': '\x1b[97m', 'NOTSET': ''}
🅳 theme.icons: {'TRACE': '🆃', 'DEBUG': '🅳', 'INFO': '🅸', 'NOTE': '🅽', 'WARNING': '🆆', 'ERROR': '🅴', 'EXCEPT': '🆇', 'CRITICAL': '🅵', 'FATAL': '🅵', 'NOTSET': '🅽'}
🅳 highlighting: 'Python3Lexer', 'Terminal256Formatter'
Import ``out`` in debug mode first and you can see any logging other modules do
as the start up.
- If you're using fbterm, make sure the ``TERM`` environment variable is set
to ``fbterm``.
This makes several adjustments to help it work better under that terminal.
Install
------------
.. code-block:: shell
⏵ pip3 install out # or out[highlight]
Raw data
{
"_id": null,
"home_page": "https://github.com/mixmastamyk/out",
"name": "out",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "log logging events levels color terminal console standard out err",
"author": "Mike Miller",
"author_email": "mixmastamyk@github.com",
"download_url": "https://files.pythonhosted.org/packages/58/6a/d45e171c4ed61ccc52f1241cd0e30c0b886038ac64315f0988bf16c59b50/out-0.80.tar.gz",
"platform": null,
"description": "\nOut\n===========\n\nFun take on logging for non-huge projects\u2014out gets \"outta\" the way!\n\nBackground\n--------------------------\n\nIf you're here it's very likely you already know that the Python standard\nlogging module is extremely flexible,\nand that's great.\nUnfortunately, it is overkill for small to medium projects,\nand these days many larger ones too.\nAdditionally,\nits various Java-isms grate on the nerves,\naccentuating a big enterprisey design.\n\nMeanwhile,\nthe rise of\n`12 Factor App <https://12factor.net/logs>`_\npatterns for daemons and services\nmeans that simply logging to stdout/err is expected and desired\nfor portability:\n\n *A twelve-factor app never concerns itself with routing or storage of its\n output stream. It should not attempt to write to or manage logfiles.\n Instead, each running process writes its event stream, unbuffered, to\n stdout. During local development, the developer will view this stream in\n the foreground of their terminal to observe the app\u2019s behavior.*\n\n\nTherefore,\nfor many (if not most) applications,\nall the complexity and mumbo-jumbo in the logging package documentation about\nmultiple loggers with different levels, different handlers, formatters,\nadapters, filters, rotation,\nand complex configuration is flexibility at the *wrong level!*\n\u00a0In fairness,\nthis may not have always been the case,\nand can still be helpful, perhaps on Windows.\n\nAdditionally, logging tools have also become standardized over time,\nhandling cross-language and cross-platform messages.\nImagine a pipeline where log events are routed and multiple tools can be\nplugged in or out as needed\u2014\\\norganization-wide rather than app- or language-wide.\n\nSo, unless you have unique requirements,\nthere's no need to reimplement ``logrotate``, ``syslog``, ``systemd``, and\nproprietary metrics tools in every programming language.\nJust blast those logs to stdout/stderr and get logging *outta* the way!\n\nEnter the ``out`` project.\nIt's ready to start logging from the get go.\nIt uses Python's standard logging infrastructure by default,\nso is still quite flexible when need be.\n\nWell, you've heard this before.\nHowever, *out* tries a bit harder create a fun, easy-to-use interface,\nas discussed above.\n\n**Naming**\n\nRegarding the name,\nwell of course would have liked something along the lines of ``log`` but all\nvariations of that are *long gone* on PyPI.\n``out()`` is a name I've often used over the years as a poor-man's logger\u2014\\\nreally a functional wrapper around ``print``,\nuntil I could get around to adding proper logging.\nNow, the tradition continues.\nThe name is short, simple, and conceptually fits,\nif a little bland.\n\nFeatures\n------------\n\nFirst of all,\nout is concise as hell,\nbasically a singleton logger configuration ready on import.\nIn interactive mode:\n\n.. code-block:: python-console\n\n >>>\u00a0import out\n\n >>>\u00a0out('And away we go\u2026') # configurable default level\n \ud83c\udd78 main/func:1 And away we go\u2026\n\n >>>\u00a0out.warn('Danger Will Robinson!')\n \ud83c\udd86 main/func:1 Danger Will Robinson!\n\n(Imagine with nice ANSI colors. \ud83d\ude01)\nOut has simple themes for message formats, styles, and icons.\nNot to worry,\nout is more conservative in \"production mode,\"\nwhich may be turned on automatically by redirecting ``stderr``:\n\n.. code-block:: shell\n\n \u23f5 python3 script.py |& cat #\u00a0bash, for fish use: &|\n 2018-09-10 17:18:19.123 \u2717 ERROR main/func:1 Kerblooey!\n\n\n.. note::\n\n This is a library to simplify logging configuration for *applications.*\n\n Libraries and independent modules should continue on logging *messages* as\n they always have:\n\n .. code-block:: python\n\n import logging\n\n log = logging.getLogger(__name__)\n\n # do not configure loggers, just use:\n log.debug('foo')\n\n\nColors, Highlighting, Unicode Icons\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n- Colors are ready to go in interactive mode,\n and turn off automatically when output is redirected.\n\n- Unicode symbols are used throughout as \"icons\" for increased readability and\n conciseness.\n\n- Syntax highlighting of data structures (oft parsed from remote APIs) is\n available too, via Pygments.\n\n\nUseful defaults, and easy to configure!\n\n.. code-block:: python-console\n\n >>>\u00a0out.configure(\n level='note', # level messages passed: str/int\n default_level='info', # when called w/o a method: out('\u2026')\n datefmt='\u2026', # see strftime\n msgfmt='\u2026', # see logging and below\n stream=file, # stderr is default\n\n theme=name|dict, # see below\n icons=name|dict, # about themes\n style=name|dict,\n highlight=False, # disable highlighting\n lexer='python3', # choose lexer\n )\n\nWe'll go into more detail below.\n\n\nLog Message Format\n~~~~~~~~~~~~~~~~~~~\n\nBy default out supports the curly-brace ``{}`` formatting style for both the\nlog message format and message template,\nas it is a bit easier to read than printf-style.\nField definitions are found in the Python\n`logging docs <https://docs.python.org/3/library/logging.html#logrecord-attributes>`_::\n\n {asctime} Textual time when the LogRecord created.\n {msecs} Millisecond portion of the creation time\n {filename} Filename portion of pathname\n {funcName} Function name\n {lineno) Source line number where called.\n {levelno} Numeric logging level for the message\n {levelname} Text logging level for the message\n {pathname} Full path of the source file called.\n {message} The result of record.getMessage().\n {module} Module (name portion of filename)\n {name} Name of the logger (logging channel)\n\nUse of the\n``out.format.ColorFormatter`` class adds these additional fields::\n\n {on}{icon}{off} Per-level style and icon support.\n\nFor example:\n\n.. code-block:: python\n\n out.configure(\n msgfmt='{on}{icon}{levelname:<7}{off} {message}',\n )\n\n\nDateTime Format\n++++++++++++++++++\n\nThese are configuable via the standard\n`strftime <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`_\nsyntax and the\n``datefmt`` keyword to ``configure``.\n\n.. code-block:: python\n\n out.configure(\n datefmt='%y-%m-%d %H:%M:%S',\n )\n\n\nMessage:\n++++++++++++++++++\n\nWhen writing messages, printf ``%`` formatting style is supported as well\ndue to compatibility requirements with a majority of libraries:\n\n.. code-block:: python\n\n out.warn('foo: %s', bar)\n out.warn('foo: {}', bar)\n\nThe second form may be used also,\nthough it will be a tiny bit slower,\nsince the printf-style must be tried first.\n\nYou'll want to use one of these forms,\nas (in logging) they skip formatting of the string when the message isn't\nsent.\n\n\nLevels++\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nWhile the\n`standard levels <https://docs.python.org/3/library/logging.html#levels>`_\ncontinue to exist\n(``NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL``).\nA few additions and slight modifications have been made.\nCommonly requested:\n\n- ``TRACE``, for absurdly voluminous data, perhaps system calls or network\n traffic.\n\n- ``NOTE``, for **positive** messages\n that should/must be shown by default---\\\n unlike the standard warning,\n which could encourage the viewer to worry. e.g.:\n\n | ``NOTE`` - Token is ABCXYZ, rather than\u2026\n | ``WARNING`` - Token is ABCXYZ.\n\n- ``EXCEPT``, to differentiate common from unexpected errors.\n Think ``FileNotFound`` vs. ``Exception``.\n\n- ``FATAL``, an alias of ``CRITICAL``,\n since that name is long, pushes alignment,\n and does not capture intent as well as fatal.\n Std-lib already allows this but still labels it critical on output.\n Out does not.\n\n\nThemes\n~~~~~~~~~~~~~~~~~~\n\n\nIcons and Styles\n+++++++++++++++++\n\n``out`` can be themed with icon sets and/or styles and are simply dictionaries\nwith one entry per level.\n\n\n.. code-block:: python-console\n\n >>> from out.themes import themes, icons, styles\n\n >>> icons['circled'] # Unicode\n {'TRACE': '\ud83c\udd63', 'DEBUG': '\ud83c\udd53', 'INFO': '\ud83c\udd58', 'WARNING': '\ud83c\udd66',\n 'NOTE': '\ud83c\udd5d', 'ERROR': '\ud83c\udd54', 'EXCEPT': '\ud83c\udd67', 'CRITICAL': '\ud83c\udd55',\n 'FATAL': '\ud83c\udd55', 'NOTSET': '\ud83c\udd5d'}\n\n >>> styles['blink'] # ANSI escapes\n {'TRACE': '\\x1b[35m', 'DEBUG': '\\x1b[34m', 'INFO': '\\x1b[32m',\n 'WARNING': '\\x1b[93m', 'NOTE': '\\x1b[96m', 'ERROR': '\\x1b[31m',\n 'EXCEPT': '\\x1b[91m', 'CRITICAL': '\\x1b[97m',\n 'FATAL': '\\x1b[97;5m', 'NOTSET': '\\x1b[0m'}\n\nThe\n`console <https://mixmastamyk.bitbucket.io/console/>`_\npackage is a good choice to generate ANSI styles for the levels,\nas well as styling other fields:\n\n.. code-block:: python\n\n from console import fg, bg, fx\n import out\n\n blue_note = dict(\n NOTE=str(fg.lightblue + fx.bold + fx.reverse),\n # other levels\u2026\n )\n out.configure(\n style=blue_note, # \u2190 level styles, \u2193 field styles\n msgfmt=bg.blue('{asctime}') + ' {message}',\n )\n out.note('John Coltrane')\n\n\nCreating and Using Themes\n++++++++++++++++++++++++++\n\nA full theme is the whole kit together in a mapping\u2014\\\nstyles, icons, ``message`` and/or ``datefmt`` templates:\n\n.. code-block:: python-console\n\n >>> interactive_theme = {\n 'style': {}, # level:value mapping, see above\n 'icons': {}, # level:value\n 'fmt': '{asctime} {icon} {message}', #\u00a0message format\n 'datefmt': '%H:%M:%S', #\u00a0date/time format,\n }\n\n\nIn the ``configure`` method of the out logger,\nto use a theme from the themes module,\nsimply specify an existing one by name:\n\n.. code-block:: python-console\n\n >>>\u00a0out.configure(\n theme='production',\n )\n\nOr by setting a custom mapping, as created above:\n\n.. code-block:: python-console\n\n >>>\u00a0out.configure(\n theme=interactive_theme, # or perhaps just icons:\n icons=dict(DEBUG='\u2022 ', INFO='\u2713 ', WARNING='\u26a0 ', ) #\u00a0\u2026\n )\n\nA few themes are bundled:\n\nIcons:\n ascii,\n ascii_symbol,\n circled,\n circled_lower,\n rounded,\n symbol\n\nStyles:\n - norm\n - bold\n - mono (monochrome)\n - blink (fatal error only)\n\nFull themes:\n - interactive\n - production\n - plain (Uses logging.Formatter for lower overhead.)\n - json (Uses formatter.JSONFormatter)\n - mono (monochrome)\n - linux_interactive, linux_production (vga console)\n\n\n.. note::\n\n When there are conflicting arguments to the ``configure`` method,\n the last specified will win.\n This requires a Python version >=3.6, due to ordered keyword args.\n Below this version it is not recommended to try since keyword order\n will be undefined and therefore the result.\n One workaround, call ``configure()`` twice.\n\n\nSyntax Highlighting w/Pygments\n--------------------------------\n\nWhen Pygments is installed,\nsyntax highlighting is available for Python data structures and code,\nas well as JSON and XML strings\u2014\\\npotentially anything Pygments can highlight.\nThis can be helpful when debugging remote APIs for example.\n\nA lexer may be\n`selected by name <http://pygments.org/docs/lexers/>`_\nvia ``configure(lexer=LEXER_NAME)``,\ndisabled by setting to ``None``.\nSome common lexer names are: ``('json', 'python3', 'xml')``.\n\n**Use:**\n\nMessage text following a ``{, [, <, or '`` char\nis highlighted with the current\nlexer+formatter:\n\n.. code-block:: python\n\n out.configure(level='trace')\n\n # default Python3\n out.trace('PYON data: %s',\n {'data': [None, True, False, 123]})\n\n out.configure(lexer='json')\n out.trace('JSON data: '\n '{\"data\": [null, true, false, 123]}')\n\n(Imagine with lovely ANSI flavors. \ud83d\ude01)\n\n\nPerformance\n-----------------\n\nout does quite a few things,\nbut it tries not to do any duplicate work or anything excessively stupid.\nIt takes about 25 microseconds to log a simple message,\nor ~90 for a complex highlighted one on a newer machine.\nHad to run a loop several thousand times (only logging) before it added up to\na noticeable delay.\n\nTheming and highlighting are easy to turn off for production mode,\nso \"out\" should hopefully not slow you down at all when not developing.\n\n\nTips\n---------\n\n- By default the logger prints to ``stderr``.\n The reason being that when used in an interactive script normal application\n output may be easily segregated from log messages during redirection.\n\n .. code-block:: shell\n\n # bash, fish\n \u23f5 script.py 2> logfile.txt\n\n Configurable via the ``stream`` keyword to ``.configure()``:\n\n .. code-block:: python\n\n import sys, out\n\n out.configure(\n stream=sys.stdout,\n )\n\n- Upgrading a long script from ``print()`` is easy:\n\n .. code-block:: python\n\n import out\n\n print = out # or other level: out.note\n\n Or perhaps some logging was already added, but you'd like to downsize.\n Add this to your main script::\n\n import out as logger\n\n Less code will need to be changed.\n\n.. ~ - Want to keep your complex configuration but use the ``ColorFormatter`` class\n .. ~ and themes in your own project?\n\n- The ``ColorFormatter`` and ``JSONFormatter`` classes can be used in your own\n project:\n\n .. code-block:: python-console\n\n >>> from out.format import ColorFormatter\n\n >>> cf = ColorFormatter()\n >>> handler.setFormatter(cf)\n\n- To print the current logging configuration:\n\n .. code-block:: python-console\n\n >>> out.log_config() # quotes to shut off highlighting:\n '''\n \ud83c\udd73 Logging config:\n \ud83c\udd73 / name: main, id: 139973461370360\n \ud83c\udd73 .level: trace (7)\n \ud83c\udd73 .default_level: info (20)\n \ud83c\udd73 + Handler: 0 <StreamHandler <stderr> (NOTSET)>\n \ud83c\udd73 + Formatter: <out.format.ColorFormatter object at 0x7f4e1c65efd0>\n \ud83c\udd73 .style: <logging.StrFormatStyle object at 0x7f4e1c65ef28>\n \ud83c\udd73 .datefmt: '%H:%M:%S'\n \ud83c\udd73 .msgfmt: ' {on}{icon}{off} {message}'\n '''\n\nThe logger in the main script file is named \"main,\"\nalso known as the \"root\" logger.\n\n\nTroubleshooting\n-----------------\n\n- If you'd like to know what ``out`` is doing,\n try running the ``.log_config()`` method to log what's currently up:\n\n .. code-block:: python-console\n\n >>> out.log_config()\n\n .. code-block:: shell\n\n \ud83c\udd73 out logging config, version: '0.70a1'\n \ud83c\udd73 .name: main, id: 0x7f88e9ec7198\n \ud83c\udd73 .level: debug (10)\n \ud83c\udd73 .default_level: info (20)\n \ud83c\udd73 + Handler: 0 <StreamHandler <stdout> (NOTSET)>\n \ud83c\udd73 + Formatter: <out.format.ColorFormatter object at 0x7f88e9ce1b70>\n \ud83c\udd73 .datefmt: '%H:%M:%S'\n \ud83c\udd73 .msgfmt: ' {on}{icon:<2}{off} \\x1b[38;5;242m{name}/\\x1b[38;5;245m{funcName}:\\x1b[32m{lineno:<3}\\x1b[0m {message}'\n \ud83c\udd73 fmt_style: <logging.StrFormatStyle object at 0x7f88e9ca5080>\n \ud83c\udd73 theme.styles: {'TRACE': '\\x1b[35m', 'DEBUG': '\\x1b[34m', 'INFO': '\\x1b[32m', 'NOTE': '\\x1b[96m', 'WARNING': '\\x1b[93m', 'ERROR': '\\x1b[31m', 'EXCEPT': '\\x1b[91m', 'CRITICAL': '\\x1b[97m', 'FATAL': '\\x1b[97m', 'NOTSET': ''}\n \ud83c\udd73 theme.icons: {'TRACE': '\ud83c\udd83', 'DEBUG': '\ud83c\udd73', 'INFO': '\ud83c\udd78', 'NOTE': '\ud83c\udd7d', 'WARNING': '\ud83c\udd86', 'ERROR': '\ud83c\udd74', 'EXCEPT': '\ud83c\udd87', 'CRITICAL': '\ud83c\udd75', 'FATAL': '\ud83c\udd75', 'NOTSET': '\ud83c\udd7d'}\n \ud83c\udd73 highlighting: 'Python3Lexer', 'Terminal256Formatter'\n\n Import ``out`` in debug mode first and you can see any logging other modules do\n as the start up.\n\n- If you're using fbterm, make sure the ``TERM`` environment variable is set\n to ``fbterm``.\n This makes several adjustments to help it work better under that terminal.\n\n\nInstall\n------------\n\n.. code-block:: shell\n\n \u23f5 pip3 install out #\u00a0or out[highlight]\n",
"bugtrack_url": null,
"license": "LGPL 3",
"summary": "Fun take on logging for non-huge projects. Gets \"outta\" the way.",
"version": "0.80",
"project_urls": {
"Homepage": "https://github.com/mixmastamyk/out"
},
"split_keywords": [
"log",
"logging",
"events",
"levels",
"color",
"terminal",
"console",
"standard",
"out",
"err"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a88563e134901e6f565d6a9106c3e54eb97052095d9caed3799a07624f886ce3",
"md5": "ac65b29f9e4341eac6e88239c721e6c0",
"sha256": "2b4fd18355ef4ca89d3f0ec7a06207ac8f3611e7ae22abd6baddc5d4c539ed4a"
},
"downloads": -1,
"filename": "out-0.80-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ac65b29f9e4341eac6e88239c721e6c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22018,
"upload_time": "2024-11-06T04:19:29",
"upload_time_iso_8601": "2024-11-06T04:19:29.706685Z",
"url": "https://files.pythonhosted.org/packages/a8/85/63e134901e6f565d6a9106c3e54eb97052095d9caed3799a07624f886ce3/out-0.80-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "586ad45e171c4ed61ccc52f1241cd0e30c0b886038ac64315f0988bf16c59b50",
"md5": "2100df34b861332e6a0edbd8def325a2",
"sha256": "b366491476b3aef829044a7733c6f13a12716b7294fb0f222c33205426b6d36e"
},
"downloads": -1,
"filename": "out-0.80.tar.gz",
"has_sig": false,
"md5_digest": "2100df34b861332e6a0edbd8def325a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26599,
"upload_time": "2024-11-06T04:19:31",
"upload_time_iso_8601": "2024-11-06T04:19:31.685930Z",
"url": "https://files.pythonhosted.org/packages/58/6a/d45e171c4ed61ccc52f1241cd0e30c0b886038ac64315f0988bf16c59b50/out-0.80.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 04:19:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mixmastamyk",
"github_project": "out",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "out"
}
JSON
