Logduo
======
Logging, console output, and file management for Python scripts and interactive sessions.

Simple by default, configurable for advanced logging workflows.

Platform: Tested on macOS, Windows, and Ubuntu.


Key Capabilities
-----------------
- Manages output directories and log files
- Supports ANSI-styled and Rich console output while preserving readable plain-text logs
- Provides extensive `help()` documentation and actionable error messages
- Validates arguments to all Logduo methods and functions to prevent unexpected behavior
- Safely prunes old run directories containing a Logduo marker file
- Generates optional session artifacts: `config_table.txt`, `config.json`
- Captures JSONL event streams
- Creates dedicated log files via `new_logger()`
- Creates advanced pass-through Loguru sinks via `new_loguru_sink()`
- Creates custom logging labels via `new_level()`
- Supports nested scripts via `log.join()` and `run()`
- Reports files created during the logging session in console and log footers


Quick Start (in script or interactive session)
----------------------------------------------
    from logduo import log

    log("hello world")
    log.warning("warning message")

If a message is logged before `log.configure()` is called, the logging session starts automatically
using Logduo defaults and `pyproject.toml` settings.

Key default settings:
  - `console_verbosity = 3` and `log_verbosity = 3`
    - All messages (including TRACE and DEBUG) are sent to both the console and the main log file.
  - `console_prefix = "level"` and `log_prefix = "timestamp"`
    - Console messages show the logging level without a timestamp.
    - Log-file messages include the timestamp and logging level.
    - Set `console_prefix="timestamp"` to include timestamps in console output, or
      `console_prefix="off"` to omit the prefix entirely.
  - `log_file_mode = "write"`
    - Existing log files are overwritten.
    - Set `log_file_mode="append"` to preserve existing contents.
    - Set `log_file_mode="timestamped"` to add a timestamp to the filename.
  - `log_dir_path = "auto"`
    - The `logs` directory is placed in the project root if identified; otherwise, in the current
      working directory.
  - `log_file_layout = "run"`
    - Logs are created in timestamped run directories.
  - `keep = "off"`
    - Previous run directories are not pruned automatically.
    - If `keep` is set to a positive integer `n`, the newest `n` Logduo-marked run directories are
      kept and older run directories are pruned.
  - `write_config_table = True`
    - `config_table.txt` is written with configuration values, descriptions, and allowed values.


Example Output
--------------
    logging started:  2026-07-20 10:10:28
    running script :  main.py
    pruned run directories: 1 (keep=3)

    | INFO     | hello world
    ───────────────────────────────────────────────────────
    logging ended   :  2026-07-20 10:10:28 (duration 00 sec)
    script path     :  temp_project/main.py
    output directory:  temp_project/logs/main/run_2026_07_20__10_10_28

    files created this logging session in output directory:
        config_table.txt
        main.log

Configure (Optional)
--------------------
Recommendation: Place regularly used configuration settings in pyproject.toml under `[tool.logduo]`

    from pathlib import Path
    from logduo import log

    my_log_dir = Path("/absolute/path/to/my_log_dir")

    log.configure(log_dir_path=my_log_dir, keep=3)
    log("hello world")


Export Logduo Docs
------------------
Export bundled documentation and example scripts to a local `logduo_docs/` directory:

    log.export_logduo_docs()

Exported files include:
- `README.txt`
- `examples/first_script.py`
- `examples/console_rendering.py`
- `examples/data_analysis.py`
- `examples/math_report_notation.py`
- `examples/nested_parent_script.py`
- `examples/nested_child_script.py`


Help
----
- Help is available for all Logduo methods and functions (displays in console only):

      help(log.configure)

- Help includes examples, argument descriptions, and usage notes.


Typical Workflows
-----------------
- Debug session: By default, `log.debug()` includes the calling filename and
  line number at the start of each message.
  - Disable source information with `log.configure(show_debug_source=False)`.
  - Debug messages are displayed when the corresponding verbosity setting is 3.
    Both `console_verbosity` and `log_verbosity` default to 3.

        from logduo import log

        log.debug(f"made it here: var = {var}")

- Create additional log files for dedicated output. Messages logged with `rep` are recorded in
  report.log and optionally mirrored to the console and/or main log file.

       rep = log.new_logger("report", to_console=True, to_main_log=False)
       rep("Question 1 answer:")

- Use the output directory to save plots, CSVs, reports, and other generated files

       myplot_output_path = log.output_dir_path / "myplot.png"

- Close the session explicitly in interactive sessions. Logging sessions in scripts are closed
  automatically at interpreter shutdown, with best-effort cleanup during abnormal shutdown.
  Explicit `log.close()` is still supported.

       log.close()


Logduo Methods and Functions
----------------------------
- Manage session:
  - `log.configure()`
  - `log.close()`
  - `log.join()`

- Log levels:
  - `log()` or `log.info()`
  - `log.trace()`
  - `log.debug()`
  - `log.success()`
  - `log.warning()`
  - `log.error()`
  - `log.critical()`
  - `log.exception()`  # ERROR + Traceback

- Create custom log label:
  - `log.new_level()`  # Maps a custom display label to an existing severity level;
     default severity = "INFO"

- Create additional output:
  - `log.new_logger()`       # Logduo-managed extra log file
  - `log.new_loguru_sink()`  # Advanced Loguru sink
  - `log.export_logduo_docs()`

- Access paths:
  - `log.output_dir_path`
  - `log.main_log_file_path`

- Utility function:
  - `run()`  Execute child script or importable module in a parent script or an interactive session.
  - Import with: `from logduo import run`


Behavior
========

Prefixes
--------
- One prefix per log event.
- Console and log files have independent prefix settings: `console_prefix`, `log_prefix`
  - `off` → No prefix. Wrapped lines align flush left.
  - `level` → Prefix shows level. Wrapped lines align under message.
  - `timestamp` → Prefix shows timestamp and level. Wrapped lines align under message.
  - `source` → Prefix shows timestamp, level, and source. Wrapped lines align under source.
- Example console output:
   with settings: `console_prefix="source"`, `show_pid_in_console=True`, `console_wrap_width=80`


        16:30:40.371 | WARNING  | example_2.py:382 -  (15408:i1) Logduo is designed for
                                  data scientists, researchers, students, and Python
                                  developers who want readable console output, organized
                                  log files, and minimal logging setup.


Message Rendering
-----------------
- Strings without `\n`: Displayed inline with the prefix.
    - Console: Wrapped (displayed line width = `console_wrap_width`).
    - Log files: Wrapped only if `log_wrap_width` is set to a positive integer. Default is `"off"`.
- Strings containing `\n`: Displayed as block flush left below prefix. Line breaks are honored.
    - This preserves the full available line width for tables, panels, JSON, tracebacks, and other
      structured content.
    - Use manual indenting or Rich `Padding` if indent behavior is desired:

           indent = " " * 13
           log(
              f"{indent}Step 1: Load data\n"
              f"{indent}Step 2: Clean data\n"
           )
- ANSI-styled strings and Rich `Text` objects are rendered on the console and written as plain text
  in log files.
- Other Rich objects, such as `Panel`, are rendered on the console but displayed as placeholders in
  log files.
    - For more examples, use `log.export_logduo_docs()` and see `console_rendering.py`.


Log File Name and Location
--------------------------
- Log file name:
  - Custom `log_file_name`: `log.configure(log_file_name="my_name.ext")`
  - Default `log_file_name`: calling script stem + `.log`
    - If the calling script is my_file.py: default `log_file_name` → `my_file.log`
    - If no calling script is found, as expected in interactive sessions:
      default `log_file_name` → `session.log`
- Location of log directory:
  - Custom `log_dir_path`: `log.configure(log_dir_path=my_log_dir)`
  - Default `log_dir_path`:
    - If pyproject.toml is not detected: `log_dir_path` = current working directory / "logs"
    - If pyproject.toml is detected: `log_dir_path` = parent directory of pyproject.toml / "logs"
- Location of log file: set by `log_file_layout`: `"flat"`, `"script"`, or `"run"` (default)
  - flat:   `log_dir_path/log_file_name`
  - script: `log_dir_path/script_stem/log_file_name`
  - run:    `log_dir_path/script_stem/run_yyyy_mm_dd__hh_mm_ss/log_file_name`

Note:
  - If no calling script is found, `script_stem` is set to `"session"` when
    `log_file_layout` = `"script"` or `"run"`
  - If `log_file_path` is provided, it specifies the complete log file path
    - `log_file_path` overrides `log_file_layout`, `log_dir_path`, and `log_file_name`
    - `log_file_path` does not override `log_file_mode` (`"write"`, `"append"`, or `"timestamped"`)
    - `log.output_dir_path` is set to the parent of `log_file_path`


Loguru Integration
------------------
- Logduo uses Loguru as its underlying file-sink engine.

- The following Loguru sink options can be passed through `log.configure()`:
  - `rotation`: start a new log file when a size/time rule is met.
      Example: `rotation="10 MB"` or `rotation="1 week"`.
      Use `rotation="off"` for no rotation (default = `"off"`).
  - `retention`: remove older rotated log files when a retention rule is met.
      Example: `retention="14 days"` or `retention=5`.
      This applies to rotated files, not to Logduo run-directory pruning (default = `"off"`).
  - `compression`: compress rotated log files.
      Example: `compression="zip"`.
      This applies to rotated files, not the active log file (default = `"off"`).
  - `enqueue`: write logs through a background queue.
      Useful for thread/process safety (default = `True`).
  - `catch`: catch logging errors instead of letting them crash the program (default = `True`).
  - `backtrace`: show extended traceback context for exceptions (default = `False`).
  - `diagnose`: include extra context information in exception tracebacks (default = `False`).

- Logduo performs message formatting, wrapping, routing, session management,
  and Rich integration before messages reach Loguru.

- Use `log.new_logger()` when you want a normal Logduo-managed extra log file.

- Use `log.new_loguru_sink()` when you want direct Loguru control, such as:
  - using custom Loguru filters
  - adding extra Loguru sinks
  - sending selected events to separate destinations
  - passing options directly to `logger.add()`

- Sinks added with `log.new_loguru_sink()` are advanced pass-through sinks.
  Logduo manages their creation and session lifecycle, but messages sent directly
  through Loguru bypass normal Logduo formatting, wrapping, routing, headers, and footers.


Console compatibility
---------------------
- Logduo supports modern Unicode-capable terminals on Windows, macOS, and Linux.
- Some older or restricted terminals may not display every Rich character correctly.
- Log files are always written as UTF-8.


Quality Assurance
-----------------
Logduo is validated using:
- pytest, with over 90% coverage on over 600 individual tests
- Ruff
- mypy
- Vulture
