[![GitHub release; latest by date](https://img.shields.io/github/v/release/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/releases)
[![GitHub Release Date](https://img.shields.io/github/release-date/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/releases)
[![Test Status](https://img.shields.io/github/actions/workflow/status/SETI/rms-pdslogger/run-tests.yml?branch=main)](https://github.com/SETI/rms-pdslogger/actions)
[![Documentation Status](https://readthedocs.org/projects/rms-pdslogger/badge/?version=latest)](https://rms-pdslogger.readthedocs.io/en/latest/?badge=latest)
[![Code coverage](https://img.shields.io/codecov/c/github/SETI/rms-pdslogger/main?logo=codecov)](https://codecov.io/gh/SETI/rms-pdslogger)
<br />
[![PyPI - Version](https://img.shields.io/pypi/v/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)
[![PyPI - Format](https://img.shields.io/pypi/format/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)
<br />
[![GitHub commits since latest release](https://img.shields.io/github/commits-since/SETI/rms-pdslogger/latest)](https://github.com/SETI/rms-pdslogger/commits/main/)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/commits/main/)
[![GitHub last commit](https://img.shields.io/github/last-commit/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/commits/main/)
<br />
[![Number of GitHub open issues](https://img.shields.io/github/issues-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/issues)
[![Number of GitHub closed issues](https://img.shields.io/github/issues-closed-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/issues)
[![Number of GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/pulls)
[![Number of GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/pulls)
<br />
![GitHub License](https://img.shields.io/github/license/SETI/rms-pdslogger)
[![Number of GitHub stars](https://img.shields.io/github/stars/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/stargazers)
![GitHub forks](https://img.shields.io/github/forks/SETI/rms-pdslogger)
# Introduction
`pdslogger` provides a new class and associated functions that augment the functionality
of the standard Python `logging` module.
`pdslogger` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).
# Installation
The `pdslogger` module is available via the
[`rms-pdslogger`](https://pypi.org/project/rms-pdslogger) package on PyPI and can be
installed with:
```sh
pip install rms-pdslogger
```
# Getting Started
The
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
class provides a variety of enhancements to Python's
`logging.Logger` class. Use the
[`PdsLogger()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
constructor or method
[`get_logger()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.get_logger)
to create a new logger or access an existing one by name. To
add the capabilities of this class to an existing ``logging.Logger``, use
[`PdsLogger.as_pdslogger()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.as_pdslogger).
In this case, the behavior of the new
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
will be identical to that of the given ``Logger``, including all formatting, but the
additional capabilities of this class will also become available.
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
supports hierarchical logs, in which the log generated by a running task can be cleanly
separated into individual sub-tasks. When a sub-task is completed, the log contains a
summary of the number of logged messages by category and, optionally, the elapsed time.
You create a new level in the hierarchy with
[`open()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.open)
and close it with
[`close()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.close).
Alternatively, you can write:
```python
with logger.open(...):
# Write log messages here
```
to close the newly-opened section of the log automatically. A specific handler can be
assigned to the
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
as part of the
[`open()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.open)
call and it
will be removed upon closing. Use this feature, for example, to obtain separate log files
for individual tasks or when processing a sequence of individual files.
The constructor allows the user to create additional error categories beyond the standard
ones named "debug", "info", "warn", etc. Each category can be assigned its own
numeric level, where DEBUG=10, INFO=20, WARNING=30, ERROR=40, and FATAL=50. A level of
None or HIDDEN means that messages with this alias are always suppressed.
The following additional message categories are used widely by the RMS Node and are
defined by default:
* "normal" (default level 20=INFO) is used for any normal outcome.
* "header" (default level 20=INFO) is used for message headers following
[`open()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.open)
and summary messages following
[`close()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.close).
* "exception" (default level 50=FATAL) is used when an exception is encountered.
* "ds_store" (default level 10=DEBUG) is used when a task encounters a ".DS_Store" file
as managed by the MacOS Finder.
* "dot_" (default level 40=ERROR) is used when a file beginning with "._" is
encountered. These files are sometimes created by "tar" commands in MacOS.
* "invisible" (default level 30=WARN) is used if any other invisible file is
encountered.
Of course, any of these default levels can be modified on a logger-by-logger basis.
Use
[`set_limit()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.set_limit)
to specify a limit on the number of messages that can be
associated with an alias. For example, if the limit on "info" messages is 100, then log
messages after the hundredth will be suppressed, although the number of suppressed
messages will still be tracked. At the end of the log, a tally of the messages associated
with each alias is printed, including the number suppressed if the limit was exceeded.
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
supports a rich set of formatting options for the log records, which
can be specified in the constructor or by using
[`set_format()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.set_format).
By
default, each log record automatically includes a time tag, log name, level, text message,
and optional file path. You can also use
[`add_root()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.add_root)
and related methods to
exercise more control over how file paths appear.
Use
[`log()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.log)
to log a message, or level-specific methods such as
[`debug()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.debug),
[`info()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.info),
[`warning()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.warning),
etc. Each
of these methods receives a message string and arguments identical to the methods of the
same name in `logging.Logger`. However, they also take an optional file path, which is
automatically formatted to appear after the message text in the log.
Method
[`exception()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.exception)
can be used inside a Python **except** clause to write an
exception message into the log, including the stacktrace. If you desire greater control
over how an exception is recorded in the log, you can use the
[`LoggerException`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.LoggerException)
class or define your own subclass.
Simple tools are also provided to create handlers to assign to a
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
using
[`add_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.add_handler)
and related methods:
* [`file_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.file_handler)
is a function that provides a rich set of options for constructing
`logging.FileHandler` objects, which allow logs to be written to a file. The options
include version numbering, appending a date or time to the file name, and daily
rotations.
[`file_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.file_handler)
also supports the RMS Node's
[`rms-filecache`](https://pypi.org/project/rms-filecache)
module, which
allows log files to be seamlessly saved into cloud storage; simply pass in a URI or
[`FCPath`](https://rms-filecache.readthedocs.io/en/latest/module.html#filecache.file_cache_path.FCPath)
object instead of a local file path.
* [`info_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.info_handler),
[`warning_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.warning_handler),
and
[`error_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.error_handler)
are
simpler versions of the above, in which the level of message logging is implied.
* [`stream_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.stream_handler)
is a function that creates handlers to write to an I/O
stream such as **sys.stdout** or **sys.stderr**.
* ``STDOUT_HANDLER`` is a pre-defined handler that prints all output to the terminal.
* ``NULL_HANDLER`` is a pre-defined handler that suppresses all output.
Note that a [`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
will print message to the terminal if no handler has been assigned
to it. As a result, if you really wish to not see any messages, you must assign it the
`NULL_HANDLER`.
In the Macintosh Finder, log files are color-coded by the most severe message encountered
within the file: green for info, yellow for warnings, red for errors, and violet for
fatal or critical errors.
For extremely simple logging needs, four subclasses of
[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)
are provided.
* [`EasyLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.EasyLogger)
prints all messages above a specified level of severity to the
terminal.
* [`ErrorLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.ErrorLogger)
only prints error messages.
* [`CriticalLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.CriticalLogger)
only prints exceptions and other "fatal" messages.
* [`NullLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.NullLogger)
suppresses all messages, including logged exceptions.
These four subclasses have the common trait that they cannot be assigned handlers.
Details of each function and class are available in the [module
documentation](https://rms-pdslogger.readthedocs.io/en/latest/module.html).
This simple example:
```
import pdslogger
logger = pdslogger.PdsLogger('sample', parent='test')
logger.warning('Warning message')
with logger.open('Sub-log'):
logger.debug('Debug message level 2')
logger.close()
```
will yield:
```
2024-12-04 13:47:37.004203 | test.sample || WARNING | Warning message
2024-12-04 13:47:37.004224 | test.sample || HEADER | Sub-log
2024-12-04 13:47:37.004240 | test.sample |-| DEBUG | Debug message level 2
2024-12-04 13:47:37.004270 | test.sample || SUMMARY | Completed: Sub-log
2024-12-04 13:47:37.004276 | test.sample || SUMMARY | Elapsed time = 0:00:00.000016
2024-12-04 13:47:37.004280 | test.sample || SUMMARY | 1 DEBUG message
2024-12-04 13:47:37.004295 | test.sample || SUMMARY | Completed: test.sample
2024-12-04 13:47:37.004299 | test.sample || SUMMARY | Elapsed time = 0:00:00.000094
2024-12-04 13:47:37.004302 | test.sample || SUMMARY | 1 WARNING message
2024-12-04 13:47:37.004305 | test.sample || SUMMARY | 1 DEBUG message
```
# Contributing
Information on contributing to this package can be found in the
[Contributing Guide](https://github.com/SETI/rms-pdslogger/blob/main/CONTRIBUTING.md).
# Links
- [Documentation](https://rms-pdslogger.readthedocs.io)
- [Repository](https://github.com/SETI/rms-pdslogger)
- [Issue tracker](https://github.com/SETI/rms-pdslogger/issues)
- [PyPi](https://pypi.org/project/rms-pdslogger)
# Licensing
This code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-pdslogger/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "rms-pdslogger",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "\"Robert S. French\" <rfrench@seti.org>",
"keywords": "pdslogger",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d1/2f/0a7797605d6d47b1ca5cbdb24039500abe770e6feff6d0c031a0a0f036bb/rms_pdslogger-3.0.0.tar.gz",
"platform": null,
"description": "[![GitHub release; latest by date](https://img.shields.io/github/v/release/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/releases)\n[![GitHub Release Date](https://img.shields.io/github/release-date/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/releases)\n[![Test Status](https://img.shields.io/github/actions/workflow/status/SETI/rms-pdslogger/run-tests.yml?branch=main)](https://github.com/SETI/rms-pdslogger/actions)\n[![Documentation Status](https://readthedocs.org/projects/rms-pdslogger/badge/?version=latest)](https://rms-pdslogger.readthedocs.io/en/latest/?badge=latest)\n[![Code coverage](https://img.shields.io/codecov/c/github/SETI/rms-pdslogger/main?logo=codecov)](https://codecov.io/gh/SETI/rms-pdslogger)\n<br />\n[![PyPI - Version](https://img.shields.io/pypi/v/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)\n[![PyPI - Format](https://img.shields.io/pypi/format/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rms-pdslogger)](https://pypi.org/project/rms-pdslogger)\n<br />\n[![GitHub commits since latest release](https://img.shields.io/github/commits-since/SETI/rms-pdslogger/latest)](https://github.com/SETI/rms-pdslogger/commits/main/)\n[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/commits/main/)\n[![GitHub last commit](https://img.shields.io/github/last-commit/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/commits/main/)\n<br />\n[![Number of GitHub open issues](https://img.shields.io/github/issues-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/issues)\n[![Number of GitHub closed issues](https://img.shields.io/github/issues-closed-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/issues)\n[![Number of GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/pulls)\n[![Number of GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed-raw/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/pulls)\n<br />\n![GitHub License](https://img.shields.io/github/license/SETI/rms-pdslogger)\n[![Number of GitHub stars](https://img.shields.io/github/stars/SETI/rms-pdslogger)](https://github.com/SETI/rms-pdslogger/stargazers)\n![GitHub forks](https://img.shields.io/github/forks/SETI/rms-pdslogger)\n\n# Introduction\n\n`pdslogger` provides a new class and associated functions that augment the functionality\nof the standard Python `logging` module.\n\n`pdslogger` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).\n\n# Installation\n\nThe `pdslogger` module is available via the\n[`rms-pdslogger`](https://pypi.org/project/rms-pdslogger) package on PyPI and can be\ninstalled with:\n\n```sh\npip install rms-pdslogger\n```\n\n# Getting Started\n\nThe\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nclass provides a variety of enhancements to Python's\n`logging.Logger` class. Use the\n[`PdsLogger()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nconstructor or method\n[`get_logger()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.get_logger)\nto create a new logger or access an existing one by name. To\nadd the capabilities of this class to an existing ``logging.Logger``, use\n[`PdsLogger.as_pdslogger()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.as_pdslogger).\nIn this case, the behavior of the new\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nwill be identical to that of the given ``Logger``, including all formatting, but the\nadditional capabilities of this class will also become available.\n\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nsupports hierarchical logs, in which the log generated by a running task can be cleanly\nseparated into individual sub-tasks. When a sub-task is completed, the log contains a\nsummary of the number of logged messages by category and, optionally, the elapsed time.\nYou create a new level in the hierarchy with\n[`open()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.open)\nand close it with\n[`close()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.close).\nAlternatively, you can write:\n\n```python\nwith logger.open(...):\n # Write log messages here\n```\n\nto close the newly-opened section of the log automatically. A specific handler can be\nassigned to the\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nas part of the\n[`open()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.open)\ncall and it\nwill be removed upon closing. Use this feature, for example, to obtain separate log files\nfor individual tasks or when processing a sequence of individual files.\n\nThe constructor allows the user to create additional error categories beyond the standard\nones named \"debug\", \"info\", \"warn\", etc. Each category can be assigned its own\nnumeric level, where DEBUG=10, INFO=20, WARNING=30, ERROR=40, and FATAL=50. A level of\nNone or HIDDEN means that messages with this alias are always suppressed.\n\nThe following additional message categories are used widely by the RMS Node and are\ndefined by default:\n\n* \"normal\" (default level 20=INFO) is used for any normal outcome.\n* \"header\" (default level 20=INFO) is used for message headers following\n [`open()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.open)\nand summary messages following\n [`close()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.close).\n* \"exception\" (default level 50=FATAL) is used when an exception is encountered.\n* \"ds_store\" (default level 10=DEBUG) is used when a task encounters a \".DS_Store\" file\n as managed by the MacOS Finder.\n* \"dot_\" (default level 40=ERROR) is used when a file beginning with \"._\" is\n encountered. These files are sometimes created by \"tar\" commands in MacOS.\n* \"invisible\" (default level 30=WARN) is used if any other invisible file is\n encountered.\n\nOf course, any of these default levels can be modified on a logger-by-logger basis.\n\nUse\n[`set_limit()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.set_limit)\nto specify a limit on the number of messages that can be\nassociated with an alias. For example, if the limit on \"info\" messages is 100, then log\nmessages after the hundredth will be suppressed, although the number of suppressed\nmessages will still be tracked. At the end of the log, a tally of the messages associated\nwith each alias is printed, including the number suppressed if the limit was exceeded.\n\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nsupports a rich set of formatting options for the log records, which\ncan be specified in the constructor or by using\n[`set_format()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.set_format).\nBy\ndefault, each log record automatically includes a time tag, log name, level, text message,\nand optional file path. You can also use\n[`add_root()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.add_root)\nand related methods to\nexercise more control over how file paths appear.\n\nUse\n[`log()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.log)\nto log a message, or level-specific methods such as\n[`debug()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.debug),\n[`info()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.info),\n[`warning()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.warning),\netc. Each\nof these methods receives a message string and arguments identical to the methods of the\nsame name in `logging.Logger`. However, they also take an optional file path, which is\nautomatically formatted to appear after the message text in the log.\n\nMethod\n[`exception()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.exception)\ncan be used inside a Python **except** clause to write an\nexception message into the log, including the stacktrace. If you desire greater control\nover how an exception is recorded in the log, you can use the\n[`LoggerException`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.LoggerException)\nclass or define your own subclass.\n\nSimple tools are also provided to create handlers to assign to a\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nusing\n[`add_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger.add_handler)\nand related methods:\n\n* [`file_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.file_handler)\n is a function that provides a rich set of options for constructing\n `logging.FileHandler` objects, which allow logs to be written to a file. The options\n include version numbering, appending a date or time to the file name, and daily\n rotations.\n [`file_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.file_handler)\n also supports the RMS Node's\n [`rms-filecache`](https://pypi.org/project/rms-filecache)\n module, which\n allows log files to be seamlessly saved into cloud storage; simply pass in a URI or\n [`FCPath`](https://rms-filecache.readthedocs.io/en/latest/module.html#filecache.file_cache_path.FCPath)\n object instead of a local file path.\n* [`info_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.info_handler),\n [`warning_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.warning_handler),\n and\n [`error_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.error_handler)\n are\n simpler versions of the above, in which the level of message logging is implied.\n* [`stream_handler()`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.stream_handler)\n is a function that creates handlers to write to an I/O\n stream such as **sys.stdout** or **sys.stderr**.\n* ``STDOUT_HANDLER`` is a pre-defined handler that prints all output to the terminal.\n* ``NULL_HANDLER`` is a pre-defined handler that suppresses all output.\n\nNote that a [`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nwill print message to the terminal if no handler has been assigned\nto it. As a result, if you really wish to not see any messages, you must assign it the\n`NULL_HANDLER`.\n\nIn the Macintosh Finder, log files are color-coded by the most severe message encountered\nwithin the file: green for info, yellow for warnings, red for errors, and violet for\nfatal or critical errors.\n\nFor extremely simple logging needs, four subclasses of\n[`PdsLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.PdsLogger)\nare provided.\n\n* [`EasyLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.EasyLogger)\n prints all messages above a specified level of severity to the\n terminal.\n* [`ErrorLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.ErrorLogger)\n only prints error messages.\n* [`CriticalLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.CriticalLogger)\n only prints exceptions and other \"fatal\" messages.\n* [`NullLogger`](https://rms-pdslogger.readthedocs.io/en/latest/module.html#pdslogger.NullLogger)\n suppresses all messages, including logged exceptions.\n\nThese four subclasses have the common trait that they cannot be assigned handlers.\n\nDetails of each function and class are available in the [module\ndocumentation](https://rms-pdslogger.readthedocs.io/en/latest/module.html).\n\nThis simple example:\n\n```\nimport pdslogger\nlogger = pdslogger.PdsLogger('sample', parent='test')\nlogger.warning('Warning message')\nwith logger.open('Sub-log'):\n logger.debug('Debug message level 2')\nlogger.close()\n```\n\nwill yield:\n\n```\n2024-12-04 13:47:37.004203 | test.sample || WARNING | Warning message\n2024-12-04 13:47:37.004224 | test.sample || HEADER | Sub-log\n2024-12-04 13:47:37.004240 | test.sample |-| DEBUG | Debug message level 2\n2024-12-04 13:47:37.004270 | test.sample || SUMMARY | Completed: Sub-log\n2024-12-04 13:47:37.004276 | test.sample || SUMMARY | Elapsed time = 0:00:00.000016\n2024-12-04 13:47:37.004280 | test.sample || SUMMARY | 1 DEBUG message\n\n2024-12-04 13:47:37.004295 | test.sample || SUMMARY | Completed: test.sample\n2024-12-04 13:47:37.004299 | test.sample || SUMMARY | Elapsed time = 0:00:00.000094\n2024-12-04 13:47:37.004302 | test.sample || SUMMARY | 1 WARNING message\n2024-12-04 13:47:37.004305 | test.sample || SUMMARY | 1 DEBUG message\n\n```\n\n# Contributing\n\nInformation on contributing to this package can be found in the\n[Contributing Guide](https://github.com/SETI/rms-pdslogger/blob/main/CONTRIBUTING.md).\n\n# Links\n\n- [Documentation](https://rms-pdslogger.readthedocs.io)\n- [Repository](https://github.com/SETI/rms-pdslogger)\n- [Issue tracker](https://github.com/SETI/rms-pdslogger/issues)\n- [PyPi](https://pypi.org/project/rms-pdslogger)\n\n# Licensing\n\nThis code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-pdslogger/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Extension to the Python logging module",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/SETI/rms-pdslogger",
"Issues": "https://github.com/SETI/rms-pdslogger/issues",
"Repository": "https://github.com/SETI/rms-pdslogger",
"Source": "https://github.com/SETI/rms-pdslogger"
},
"split_keywords": [
"pdslogger"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1a51779810f224e338ec79657f6887f87ecc3e74a7793d0c2b0cf4a25e825e3",
"md5": "dc259c1ac29c15307886292f519c69b5",
"sha256": "001fa8d55c9d420ab87da295d8d821e2372a62d00cdecaf24a36998687c514e0"
},
"downloads": -1,
"filename": "rms_pdslogger-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dc259c1ac29c15307886292f519c69b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 30729,
"upload_time": "2025-01-08T19:01:10",
"upload_time_iso_8601": "2025-01-08T19:01:10.967567Z",
"url": "https://files.pythonhosted.org/packages/e1/a5/1779810f224e338ec79657f6887f87ecc3e74a7793d0c2b0cf4a25e825e3/rms_pdslogger-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d12f0a7797605d6d47b1ca5cbdb24039500abe770e6feff6d0c031a0a0f036bb",
"md5": "c5109e2176079467ddcafb913c9ce4d4",
"sha256": "595643929e3b2d35eb9c86d37baa0bec3371ef68537999e295493db2f991f7fe"
},
"downloads": -1,
"filename": "rms_pdslogger-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c5109e2176079467ddcafb913c9ce4d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 51401,
"upload_time": "2025-01-08T19:01:12",
"upload_time_iso_8601": "2025-01-08T19:01:12.523817Z",
"url": "https://files.pythonhosted.org/packages/d1/2f/0a7797605d6d47b1ca5cbdb24039500abe770e6feff6d0c031a0a0f036bb/rms_pdslogger-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 19:01:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SETI",
"github_project": "rms-pdslogger",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "coverage",
"specs": []
},
{
"name": "flake8",
"specs": []
},
{
"name": "myst-parser",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "rms-filecache",
"specs": [
[
">=",
"2.3.0"
]
]
},
{
"name": "sphinx",
"specs": []
},
{
"name": "sphinxcontrib-napoleon",
"specs": []
},
{
"name": "sphinx-rtd-theme",
"specs": []
}
],
"lcname": "rms-pdslogger"
}