dd-logging 0.1.0__tar.gz

dd_logging-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 digital-duck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dd_logging-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: dd-logging
+Version: 0.1.0
+Summary: Shared logging helpers for Digital Duck projects (spl-llm, spl-flow, …)
+Author-email: Wen Gong <wen.gong.research@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/digital-duck/dd-logging
+Project-URL: Repository, https://github.com/digital-duck/dd-logging
+Project-URL: Issues, https://github.com/digital-duck/dd-logging/issues
+Keywords: logging,digital-duck,spl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dd-logging
+
+Shared logging helpers for [Digital Duck](https://github.com/digital-duck) projects.
+
+Provides a consistent, timestamped-file logging pattern for CLI tools and Streamlit apps.
+Used by **spl-llm** and **spl-flow**; designed to be reused by any project in the ecosystem.
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install dd-logging
+
+# local editable install (for development)
+pip install -e /path/to/dd-logging
+```
+
+## Usage
+
+```python
+from dd_logging import setup_logging, get_logger, disable_logging
+
+# 1. Call once per process (CLI entry point or app startup)
+log_path = setup_logging(
+    "run",
+    root_name="my_app",       # top-level logger namespace
+    adapter="openrouter",     # appended to filename (optional)
+    log_level="info",         # debug | info | warning | error
+)
+# → logs/run-openrouter-20260215-143022.log
+
+# 2. In each module
+_log = get_logger("nodes.text2spl", root_name="my_app")
+_log.info("translating query  len=%d", len(query))
+
+# 3. Silence all logging (e.g. --no-log CLI flag)
+disable_logging("my_app")
+```
+
+### Thin wrapper pattern (recommended)
+
+Each project wraps `dd_logging` so call-sites never pass `root_name`:
+
+```python
+# myapp/logging_config.py
+from pathlib import Path
+from dd_logging import setup_logging as _setup, get_logger as _get, disable_logging as _disable
+
+_ROOT   = "my_app"
+LOG_DIR = Path(__file__).resolve().parent.parent / "logs"
+
+def get_logger(name: str):
+    return _get(name, _ROOT)
+
+def setup_logging(run_name: str, **kw):
+    kw.setdefault("log_dir", LOG_DIR)
+    return _setup(run_name, root_name=_ROOT, **kw)
+
+def disable_logging():
+    return _disable(_ROOT)
+```
+
+## Log file naming
+
+```
+<log_dir>/<run_name>[-<adapter>]-<YYYYMMDD-HHMMSS>.log
+
+logs/run-openrouter-20260215-143022.log
+logs/benchmark-claude_cli-20260215-144500.log
+logs/generate-20260215-145001.log
+```
+
+## Logger hierarchy
+
+```
+my_app                     ← root (FileHandler attached here)
+├── my_app.api             ← get_logger("api", "my_app")
+├── my_app.nodes.text2spl  ← get_logger("nodes.text2spl", "my_app")
+└── my_app.flows           ← get_logger("flows", "my_app")
+```
+
+All child loggers inherit the root's handler — no per-module handler setup needed.
+
+## Design notes
+
+- **`propagate=False`** — prevents duplicate output when a root Python logger
+  handler is already configured (e.g. Streamlit, pytest, Jupyter).
+- **Stale-handler removal** — calling `setup_logging()` multiple times in one
+  process (e.g. test suites) is safe; old `FileHandler`s are replaced.
+- **No third-party dependencies** — stdlib `logging` only.
+
+## Projects using dd-logging
+
+| Project | Root name | Log dir |
+|---------|-----------|---------|
+| [spl-llm](https://github.com/digital-duck/SPL) | `spl` | `SPL/logs/` |
+| [spl-flow](https://github.com/digital-duck/SPL-Flow) | `spl_flow` | `SPL-Flow/logs/` |
+
+## License
+
+MIT

dd_logging-0.1.0/README.md

@@ -0,0 +1,101 @@
+# dd-logging
+
+Shared logging helpers for [Digital Duck](https://github.com/digital-duck) projects.
+
+Provides a consistent, timestamped-file logging pattern for CLI tools and Streamlit apps.
+Used by **spl-llm** and **spl-flow**; designed to be reused by any project in the ecosystem.
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install dd-logging
+
+# local editable install (for development)
+pip install -e /path/to/dd-logging
+```
+
+## Usage
+
+```python
+from dd_logging import setup_logging, get_logger, disable_logging
+
+# 1. Call once per process (CLI entry point or app startup)
+log_path = setup_logging(
+    "run",
+    root_name="my_app",       # top-level logger namespace
+    adapter="openrouter",     # appended to filename (optional)
+    log_level="info",         # debug | info | warning | error
+)
+# → logs/run-openrouter-20260215-143022.log
+
+# 2. In each module
+_log = get_logger("nodes.text2spl", root_name="my_app")
+_log.info("translating query  len=%d", len(query))
+
+# 3. Silence all logging (e.g. --no-log CLI flag)
+disable_logging("my_app")
+```
+
+### Thin wrapper pattern (recommended)
+
+Each project wraps `dd_logging` so call-sites never pass `root_name`:
+
+```python
+# myapp/logging_config.py
+from pathlib import Path
+from dd_logging import setup_logging as _setup, get_logger as _get, disable_logging as _disable
+
+_ROOT   = "my_app"
+LOG_DIR = Path(__file__).resolve().parent.parent / "logs"
+
+def get_logger(name: str):
+    return _get(name, _ROOT)
+
+def setup_logging(run_name: str, **kw):
+    kw.setdefault("log_dir", LOG_DIR)
+    return _setup(run_name, root_name=_ROOT, **kw)
+
+def disable_logging():
+    return _disable(_ROOT)
+```
+
+## Log file naming
+
+```
+<log_dir>/<run_name>[-<adapter>]-<YYYYMMDD-HHMMSS>.log
+
+logs/run-openrouter-20260215-143022.log
+logs/benchmark-claude_cli-20260215-144500.log
+logs/generate-20260215-145001.log
+```
+
+## Logger hierarchy
+
+```
+my_app                     ← root (FileHandler attached here)
+├── my_app.api             ← get_logger("api", "my_app")
+├── my_app.nodes.text2spl  ← get_logger("nodes.text2spl", "my_app")
+└── my_app.flows           ← get_logger("flows", "my_app")
+```
+
+All child loggers inherit the root's handler — no per-module handler setup needed.
+
+## Design notes
+
+- **`propagate=False`** — prevents duplicate output when a root Python logger
+  handler is already configured (e.g. Streamlit, pytest, Jupyter).
+- **Stale-handler removal** — calling `setup_logging()` multiple times in one
+  process (e.g. test suites) is safe; old `FileHandler`s are replaced.
+- **No third-party dependencies** — stdlib `logging` only.
+
+## Projects using dd-logging
+
+| Project | Root name | Log dir |
+|---------|-----------|---------|
+| [spl-llm](https://github.com/digital-duck/SPL) | `spl` | `SPL/logs/` |
+| [spl-flow](https://github.com/digital-duck/SPL-Flow) | `spl_flow` | `SPL-Flow/logs/` |
+
+## License
+
+MIT

dd_logging-0.1.0/dd_logging/__init__.py

@@ -0,0 +1,18 @@
+"""dd-logging — shared logging helpers for Digital Duck projects."""
+from dd_logging.core import (
+    FORMATTER,
+    LOG_LEVELS,
+    disable_logging,
+    get_logger,
+    setup_logging,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "setup_logging",
+    "get_logger",
+    "disable_logging",
+    "LOG_LEVELS",
+    "FORMATTER",
+]

dd_logging-0.1.0/dd_logging/core.py

@@ -0,0 +1,118 @@
+"""Core logging helpers shared across Digital Duck projects.
+
+Provides a consistent, timestamped-file logging pattern for CLI tools and
+Streamlit apps.  Each project supplies its own *root_name* (the top-level
+logger namespace) so hierarchies stay isolated:
+
+    spl       → spl / spl.executor   (spl-llm package)
+    spl_flow  → spl_flow / spl_flow.nodes.*  (spl-flow package)
+
+Log file naming convention
+--------------------------
+    <log_dir>/<run_name>[-<adapter>]-<YYYYMMDD-HHMMSS>.log
+    e.g.  logs/run-openrouter-20260215-143022.log
+          logs/benchmark-claude_cli-20260215-144500.log
+          logs/generate-20260215-145001.log
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from pathlib import Path
+
+# ── Constants ──────────────────────────────────────────────────────────────────
+
+LOG_LEVELS: dict[str, int] = {
+    "debug":   logging.DEBUG,
+    "info":    logging.INFO,
+    "warning": logging.WARNING,
+    "error":   logging.ERROR,
+}
+
+FORMATTER = logging.Formatter(
+    "%(asctime)s  %(levelname)-7s  %(name)s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+def setup_logging(
+    run_name: str,
+    *,
+    root_name: str,
+    adapter: str = "",
+    log_level: str = "info",
+    log_dir: Path | str | None = None,
+    console: bool = False,
+) -> Path:
+    """Attach a timestamped FileHandler to *root_name* logger.
+
+    Safe to call multiple times in one process — stale FileHandlers from
+    a previous call are removed before the new one is attached.
+
+    Parameters
+    ----------
+    run_name  : short label for the filename, e.g. ``"run"``, ``"benchmark"``
+    root_name : root logger namespace, e.g. ``"spl"`` or ``"spl_flow"``
+    adapter   : LLM adapter name appended to the filename (omitted if empty)
+    log_level : ``"debug"`` | ``"info"`` | ``"warning"`` | ``"error"``
+    log_dir   : directory for log files; defaults to ``./logs`` relative to CWD
+    console   : also attach a StreamHandler (useful in CLI --verbose mode)
+
+    Returns
+    -------
+    Path  absolute path of the log file created
+    """
+    target_dir = Path(log_dir) if log_dir else Path.cwd() / "logs"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    dt_str = datetime.now().strftime("%Y%m%d-%H%M%S")
+    suffix = f"-{adapter}" if adapter else ""
+    log_path = target_dir / f"{run_name}{suffix}-{dt_str}.log"
+
+    level = LOG_LEVELS.get(log_level.lower(), logging.INFO)
+
+    root = logging.getLogger(root_name)
+    root.setLevel(logging.DEBUG)   # capture everything; handlers filter
+
+    # Remove stale FileHandlers from a previous setup_logging() call
+    root.handlers = [h for h in root.handlers if not isinstance(h, logging.FileHandler)]
+
+    fh = logging.FileHandler(log_path, encoding="utf-8")
+    fh.setLevel(level)
+    fh.setFormatter(FORMATTER)
+    root.addHandler(fh)
+
+    if console:
+        ch = logging.StreamHandler()
+        ch.setLevel(level)
+        ch.setFormatter(FORMATTER)
+        root.addHandler(ch)
+
+    # Prevent propagation to the Python root logger — avoids duplicate output
+    # in environments that configure their own root handler (e.g. Streamlit).
+    root.propagate = False
+
+    return log_path
+
+
+def get_logger(name: str, root_name: str) -> logging.Logger:
+    """Return a child logger under *root_name*.
+
+    Parameters
+    ----------
+    name      : dotted sub-path, e.g. ``"nodes.text2spl"`` or ``"executor"``
+    root_name : root logger namespace, e.g. ``"spl"`` or ``"spl_flow"``
+
+    Returns
+    -------
+    logging.Logger  named  ``<root_name>.<name>``
+    """
+    return logging.getLogger(f"{root_name}.{name}")
+
+
+def disable_logging(root_name: str) -> None:
+    """Remove all handlers from *root_name* logger (no-op log mode)."""
+    root = logging.getLogger(root_name)
+    root.handlers.clear()
+    root.propagate = False

dd_logging-0.1.0/dd_logging.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: dd-logging
+Version: 0.1.0
+Summary: Shared logging helpers for Digital Duck projects (spl-llm, spl-flow, …)
+Author-email: Wen Gong <wen.gong.research@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/digital-duck/dd-logging
+Project-URL: Repository, https://github.com/digital-duck/dd-logging
+Project-URL: Issues, https://github.com/digital-duck/dd-logging/issues
+Keywords: logging,digital-duck,spl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dd-logging
+
+Shared logging helpers for [Digital Duck](https://github.com/digital-duck) projects.
+
+Provides a consistent, timestamped-file logging pattern for CLI tools and Streamlit apps.
+Used by **spl-llm** and **spl-flow**; designed to be reused by any project in the ecosystem.
+
+## Install
+
+```bash
+# from PyPI (once published)
+pip install dd-logging
+
+# local editable install (for development)
+pip install -e /path/to/dd-logging
+```
+
+## Usage
+
+```python
+from dd_logging import setup_logging, get_logger, disable_logging
+
+# 1. Call once per process (CLI entry point or app startup)
+log_path = setup_logging(
+    "run",
+    root_name="my_app",       # top-level logger namespace
+    adapter="openrouter",     # appended to filename (optional)
+    log_level="info",         # debug | info | warning | error
+)
+# → logs/run-openrouter-20260215-143022.log
+
+# 2. In each module
+_log = get_logger("nodes.text2spl", root_name="my_app")
+_log.info("translating query  len=%d", len(query))
+
+# 3. Silence all logging (e.g. --no-log CLI flag)
+disable_logging("my_app")
+```
+
+### Thin wrapper pattern (recommended)
+
+Each project wraps `dd_logging` so call-sites never pass `root_name`:
+
+```python
+# myapp/logging_config.py
+from pathlib import Path
+from dd_logging import setup_logging as _setup, get_logger as _get, disable_logging as _disable
+
+_ROOT   = "my_app"
+LOG_DIR = Path(__file__).resolve().parent.parent / "logs"
+
+def get_logger(name: str):
+    return _get(name, _ROOT)
+
+def setup_logging(run_name: str, **kw):
+    kw.setdefault("log_dir", LOG_DIR)
+    return _setup(run_name, root_name=_ROOT, **kw)
+
+def disable_logging():
+    return _disable(_ROOT)
+```
+
+## Log file naming
+
+```
+<log_dir>/<run_name>[-<adapter>]-<YYYYMMDD-HHMMSS>.log
+
+logs/run-openrouter-20260215-143022.log
+logs/benchmark-claude_cli-20260215-144500.log
+logs/generate-20260215-145001.log
+```
+
+## Logger hierarchy
+
+```
+my_app                     ← root (FileHandler attached here)
+├── my_app.api             ← get_logger("api", "my_app")
+├── my_app.nodes.text2spl  ← get_logger("nodes.text2spl", "my_app")
+└── my_app.flows           ← get_logger("flows", "my_app")
+```
+
+All child loggers inherit the root's handler — no per-module handler setup needed.
+
+## Design notes
+
+- **`propagate=False`** — prevents duplicate output when a root Python logger
+  handler is already configured (e.g. Streamlit, pytest, Jupyter).
+- **Stale-handler removal** — calling `setup_logging()` multiple times in one
+  process (e.g. test suites) is safe; old `FileHandler`s are replaced.
+- **No third-party dependencies** — stdlib `logging` only.
+
+## Projects using dd-logging
+
+| Project | Root name | Log dir |
+|---------|-----------|---------|
+| [spl-llm](https://github.com/digital-duck/SPL) | `spl` | `SPL/logs/` |
+| [spl-flow](https://github.com/digital-duck/SPL-Flow) | `spl_flow` | `SPL-Flow/logs/` |
+
+## License
+
+MIT

dd_logging-0.1.0/dd_logging.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+dd_logging/__init__.py
+dd_logging/core.py
+dd_logging.egg-info/PKG-INFO
+dd_logging.egg-info/SOURCES.txt
+dd_logging.egg-info/dependency_links.txt
+dd_logging.egg-info/top_level.txt

dd_logging-0.1.0/dd_logging.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dd_logging-0.1.0/dd_logging.egg-info/top_level.txt

@@ -0,0 +1 @@
+dd_logging

dd_logging-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dd-logging"
+version = "0.1.0"
+description = "Shared logging helpers for Digital Duck projects (spl-llm, spl-flow, …)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Wen Gong", email = "wen.gong.research@gmail.com"},
+]
+keywords = ["logging", "digital-duck", "spl"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Logging",
+]
+
+[project.urls]
+Homepage    = "https://github.com/digital-duck/dd-logging"
+Repository  = "https://github.com/digital-duck/dd-logging"
+Issues      = "https://github.com/digital-duck/dd-logging/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["dd_logging*"]

dd_logging-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+