Super-lint + add docs

.pre-commit-config.yaml

@@ -2,6 +2,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 %YAML 1.2
 ---
+exclude: 'site/.*'
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v3.2.0
@@ -18,12 +19,6 @@ repos:
     rev: v3.1.0
     hooks:
       - id: add-trailing-comma
-  #  alternative: isort
-  # optional comments: # noreorder
-  - repo: https://github.com/asottile/reorder-python-imports
-    rev: v3.14.0
-    hooks:
-      - id: reorder-python-imports
   - repo: https://github.com/astral-sh/ruff-pre-commit
     #  Ruff version.
     rev: v0.8.2

.python-version

@@ -0,0 +1 @@
+3.10

README.md

@@ -1,58 +1,64 @@
 # **logistro (low-hee-stro)**
 
-`logistro` is an extremely light addition to `logging`.
+`logistro` is an extremely light addition to `logging`, providing sensible defaults.
 
-It provides two *structured* and *human-readable* formats with better defaults.
+It also includes `getPipeLogger()` which can be passed to `Popen()` so that its
+`stderr` is piped to the already thread-safe `logging` library.
 
-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`
-library.
+## CLI Flags
 
-Set level by flag: `--logistro-level DEBUG|DEBUG2|INFO|WARNING|ERROR|CRITICAL`
+* `--logistro-level DEBUG|DEBUG2|INFO|WARNING|ERROR|CRITICAL`
+* `--logistro-human` (default)
+* `--logistro-structured` which outputs JSON
 
-With CLI flags:
+### Programmatic Alternatives
 
-* `--logistro-human` (default)
+* `logistro.set_structured()`
+* `logistro.set_human()`
 
-* `--logistro-structured` which outputs JSON
+*Generally, they must be called before any other logging call (See note below).*
+
+## Additionally
 
-Or with functions: `logistro.set_structured()` and `logistro.set_human()`.
-Generally, they must be called before any other logging call.
-(See note below about changing mid-program).
+`logger.debug2(...)` is more verbose than `logger.debug(...)`.
 
-It also adds `logger.debug2(...)`: more verbose then `logger.debug(...)`.
+`logistro.betterConfig(...)` will apply the formatter  and level selected
+as the default (it will ignore what you set with `format`). It accepts the same
+arguments as `logging.basicConfig(...)`. **It is better to call this early in a
+multithread program.**
 
-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(...)`.
+`logistro.getLogger(...)` will call `betterConfig()`.
 
-Calling `logistro.getLogger(...)` will also call `betterConfig()`
-if you haven't called it already*.
+It provides two formatters
 
-Feel free to use the two formatters it provides manually: `human_formatter` and
-`structured_formatter`.
+* `human_formatter`
+* `structured_formatter`
+
+### Example
 
 ```python
 import logistro
 
 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')
-logger.critical('hey, this still works! its just more informative')
-# following should be called in except: clause
-logger.exception('hey, this still works! its just more informative')
+logger.debug2(...)
+logger.debug(...) # or debug1()
+logger.info(...)
+logger.warning(...)
+logger.error(...)
+logger.critical(...)
+logger.exception(...) # always inside except:
+
+# For subprocesses:
+
+pipe, logger = logistro.getPipeLogger(__name__+"-subprocess")
+subprocess.Popen(cli_command, stderr=pipe)
+os.close(pipe)
 ```
 
 ## Changing Logger Formatter Mid-Execution
 
-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 of Python's `logging`.
-Like `logging`, if using from multiple threads, call `betterConfig()` early.
+With a typical setup, calling `set_structured()` or `set_human()`
+and then `logistro.coerce_logger(logistro.getLogger())` will change the format.
+
+See [the tech note](TECH_NOTE.md) for an intro into the complexities of `logging`.

docs/README.md

@@ -0,0 +1,64 @@
+# **logistro (low-hee-stro)**
+
+`logistro` is an extremely light addition to `logging`, providing sensible defaults.
+
+It also includes `getPipeLogger()` which can be passed to `Popen()` so that its
+`stderr` is piped to the already thread-safe `logging` library.
+
+## CLI Flags
+
+* `--logistro-level DEBUG|DEBUG2|INFO|WARNING|ERROR|CRITICAL`
+* `--logistro-human` (default)
+* `--logistro-structured` which outputs JSON
+
+### Programmatic Alternatives
+
+* `logistro.set_structured()`
+* `logistro.set_human()`
+
+*Generally, they must be called before any other logging call (See note below).*
+
+## Additionally
+
+`logger.debug2(...)` is more verbose than `logger.debug(...)`.
+
+`logistro.betterConfig(...)` will apply the formatter  and level selected
+as the default (it will ignore what you set with `format`). It accepts the same
+arguments as `logging.basicConfig(...)`. **It is better to call this early in a
+multithread program.**
+
+`logistro.getLogger(...)` will call `betterConfig()`.
+
+It provides two formatters
+
+* `human_formatter`
+* `structured_formatter`
+
+### Example
+
+```python
+import logistro
+
+logger = logistro.getLogger(__name__)
+
+logger.debug2(...)
+logger.debug(...) # or debug1()
+logger.info(...)
+logger.warning(...)
+logger.error(...)
+logger.critical(...)
+logger.exception(...) # always inside except:
+
+# For subprocesses:
+
+pipe, logger = logistro.getPipeLogger(__name__+"-subprocess")
+subprocess.Popen(cli_command, stderr=pipe)
+os.close(pipe)
+```
+
+## Changing Logger Formatter Mid-Execution
+
+With a typical setup, calling `set_structured()` or `set_human()`
+and then `logistro.coerce_logger(logistro.getLogger())` will change the format.
+
+See [the tech note](TECH_NOTE.md) for an intro into the complexities of `logging`.

docs/style.css

@@ -0,0 +1,6 @@
+.qmkapi-item-list li p {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  width: 90%;
+}

logistro/__init__.py

@@ -1,21 +1,41 @@
-from .custom_logging import betterConfig
-from .custom_logging import coerce_logger
-from .custom_logging import DEBUG2
-from .custom_logging import getLogger
-from .custom_logging import getPipeLogger
-from .custom_logging import human_formatter
-from .custom_logging import set_human
-from .custom_logging import set_structured
-from .custom_logging import structured_formatter
+"""
+Logistro wraps `logging` for added defaults and subprocess logging.
 
-__all__ = [
+Typical usage:
+
+    import logistro
+    logger = logistro.getLogger(__name__)
+    logger.debug2("This will be printed more informatively")
+
+    # Advanced
+    pipe, logger = logistro.getPipeLogger(__name__)
+    # Pipe all stderr to our logger
+    subprocess.Popen(process_name, stderr=pipe)
+
+    subprocess.wait()
+    os.close(pipe)
+"""
+
+from ._api import (
     DEBUG2,
     betterConfig,
+    coerce_logger,
     getLogger,
     getPipeLogger,
+    human_formatter,
     set_human,
     set_structured,
-    human_formatter,
     structured_formatter,
-    coerce_logger,
+)
+
+__all__ = [
+    "DEBUG2",
+    "betterConfig",
+    "coerce_logger",
+    "getLogger",
+    "getPipeLogger",
+    "human_formatter",
+    "set_human",
+    "set_structured",
+    "structured_formatter",
 ]