From 720840f704743c46d8ca4a21bca4f9b30cd1f14f Mon Sep 17 00:00:00 2001 From: Andrew Pikul Date: Wed, 18 Dec 2024 11:07:39 -0500 Subject: [PATCH] Improve README documentation --- README.md | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 4d01817..93f82c4 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,31 @@ `logistro` is an extremely light addition to `logging`. -It provides two *structured* and *human-readable* formats. +It provides two *structured* and *human-readable* formats with better defaults. Additionally, it also includes `getPipeLogger()` which can be passed to `Popen()` -so that there stdout and stderr is piped to the already thread-safe logging +so that there `stdout` and `stderr` is piped to the already thread-safe `logging` library. -With CLI flags: +Set level by flag: `--logistro-level DEBUG|DEBUG2|INFO|WARNING|ERROR|CRITICAL` -* `--logistro-structured` which outputs JSON +With CLI flags: * `--logistro-human` (default) +* `--logistro-structured` which outputs JSON + Or with functions: `logistro.set_structured()` and `logistro.set_human()`. -Generally, they can be called once before anything else happens in logging. +Generally, they must be called before any other logging call. (See note below about changing mid-program). It also adds `logger.debug2(...)`: more verbose then `logger.debug(...)`. -Calling `logistro.betterConfig(...)` will apply the formatter selected -as the default (it will gnore what you set with `format`). It accepts -all normal arguments as `logging.basicConfig(...)`. +Calling `logistro.betterConfig(...)` will apply the formatter and level selected +as the default (it will ignore what you set with `format`). It accepts +all other normal arguments as `logging.basicConfig(...)`. -Calling `logistro.getLogger(__name__)` will also call `betterConfig()` +Calling `logistro.getLogger(...)` will also call `betterConfig()` if you haven't called it already*. Feel free to use the two formatters it provides manually: `human_formatter` and @@ -37,6 +39,8 @@ logger = logistro.getLogger(__name__) logger.debug2('hey, this still works! its just more informative') logger.debug1('hey, this still works! its just more informative') +# debug1 = debug +logger.debug('hey, this still works! its just more informative') logger.info('hey, this still works! its just more informative') logger.warning('hey, this still works! its just more informative') logger.error('hey, this still works! its just more informative') @@ -50,13 +54,5 @@ logger.exception('hey, this still works! its just more informative') If you don't have any weird setup, and you need to change the logging style mid-execution, try calling an above function like `set_structured()` and then `logistro.coerce_logger(logistro.getLogger())`. See the file -*TECH_NOTE.md* for an intro into the complexities. -Like logging, If using from multiple threads, call `betterConfig()` early. - - -* tests -* argument flag levels -* docs -* get it into choreographer - -and after this, we continue refactor +*TECH_NOTE.md* for an intro into the complexities of Python's `logging`. +Like `logging`, if using from multiple threads, call `betterConfig()` early.