stdlogkit 0.1.0__tar.gz

stdlogkit-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: stdlogkit
+Version: 0.1.0
+Summary: A small stdlib logging auto-configuration kit with colored multiline logs and log-once helpers.
+Author-email: Your Name <you@example.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/your-org/stdlogkit
+Project-URL: Repository, https://github.com/your-org/stdlogkit
+Project-URL: Issues, https://github.com/your-org/stdlogkit/issues
+Keywords: logging,stdlib,colored-logs,python-logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# stdlogkit
+
+`stdlogkit` is a tiny, vLLM-independent wrapper around Python's standard
+`logging` package.
+
+Importing it configures standard logging immediately:
+
+```python
+import logging
+import stdlogkit  # noqa: F401
+
+logger = logging.getLogger(__name__)
+logger.info("hello")
+logger.warning_once("this warning appears once")
+```
+
+Default output:
+
+```text
+INFO 06-24 12:00:01 [example.py:5] hello
+WARNING 06-24 12:00:01 [example.py:6] this warning appears once
+```
+
+## Features
+
+- Uses only Python's standard `logging` machinery.
+- Auto-configures logging on `import stdlogkit`.
+- Configures the root logger by default, so normal `logging.getLogger(...)`
+  calls work immediately.
+- Adds `debug_once`, `info_once`, and `warning_once` to standard logger
+  instances.
+- Supports multiline log alignment.
+- Supports ANSI colors with `auto`, forced-on, and forced-off modes.
+- Supports custom JSON config through `logging.config.dictConfig`.
+- Includes optional uvicorn access-log filtering helpers.
+- Has no runtime dependency on vLLM or any other third-party package.
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `STDLOGKIT_CONFIGURE_LOGGING` | `1` | Set `0` to disable auto configuration. |
+| `STDLOGKIT_LOGGING_LEVEL` | `INFO` | Root or named logger level. |
+| `STDLOGKIT_LOGGING_STREAM` | `ext://sys.stdout` | Handler stream. |
+| `STDLOGKIT_LOGGING_PREFIX` | empty | Prefix prepended to every log line. |
+| `STDLOGKIT_LOGGING_COLOR` | `auto` | `auto`, `1`, or `0`. |
+| `STDLOGKIT_LOGGING_CONFIG_PATH` | unset | Path to a JSON `dictConfig` file. |
+| `STDLOGKIT_LOGGER_NAME` | empty | Configure a named logger instead of root. |
+| `STDLOGKIT_ROOT_DIR` | current working directory | Base path for relative file display. |
+| `STDLOGKIT_SHOW_REL_PATH` | `debug` | `debug`, `always`, or `never`. |
+| `NO_COLOR` | `0` | Standard flag to disable ANSI colors. |
+
+## Custom JSON Config
+
+```json
+{
+  "version": 1,
+  "disable_existing_loggers": false,
+  "formatters": {
+    "plain": {
+      "class": "stdlogkit.formatter.NewLineFormatter",
+      "format": "%(levelname)s %(asctime)s [%(fileinfo)s:%(lineno)d] %(message)s",
+      "datefmt": "%m-%d %H:%M:%S"
+    }
+  },
+  "handlers": {
+    "console": {
+      "class": "logging.StreamHandler",
+      "formatter": "plain",
+      "level": "INFO",
+      "stream": "ext://sys.stdout"
+    }
+  },
+  "root": {
+    "handlers": ["console"],
+    "level": "INFO"
+  }
+}
+```
+
+Run with:
+
+```bash
+STDLOGKIT_LOGGING_CONFIG_PATH=/path/to/logging.json python app.py
+```
+
+## Named Logger Mode
+
+By default, stdlogkit configures the root logger. If you want behavior closer
+to a framework-specific logger, configure only a named logger:
+
+```bash
+STDLOGKIT_LOGGER_NAME=my_app python app.py
+```
+
+Then loggers under `my_app.*` propagate to that logger:
+
+```python
+import logging
+import stdlogkit  # noqa: F401
+
+logger = logging.getLogger("my_app.service")
+logger.info("hello")
+```
+
+## Development
+
+```bash
+cd standalone_logging_pkg
+uv venv --python 3.12
+uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+uv build
+```
+
+## Publish to PyPI
+
+Before publishing, make sure the project name in `pyproject.toml` is available
+on PyPI and replace the placeholder author/repository metadata.
+
+```bash
+cd standalone_logging_pkg
+uv build
+uv publish --token "$PYPI_TOKEN"
+```
+
+For TestPyPI:
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ --token "$TEST_PYPI_TOKEN"
+```

stdlogkit-0.1.0/README.md

@@ -0,0 +1,131 @@
+# stdlogkit
+
+`stdlogkit` is a tiny, vLLM-independent wrapper around Python's standard
+`logging` package.
+
+Importing it configures standard logging immediately:
+
+```python
+import logging
+import stdlogkit  # noqa: F401
+
+logger = logging.getLogger(__name__)
+logger.info("hello")
+logger.warning_once("this warning appears once")
+```
+
+Default output:
+
+```text
+INFO 06-24 12:00:01 [example.py:5] hello
+WARNING 06-24 12:00:01 [example.py:6] this warning appears once
+```
+
+## Features
+
+- Uses only Python's standard `logging` machinery.
+- Auto-configures logging on `import stdlogkit`.
+- Configures the root logger by default, so normal `logging.getLogger(...)`
+  calls work immediately.
+- Adds `debug_once`, `info_once`, and `warning_once` to standard logger
+  instances.
+- Supports multiline log alignment.
+- Supports ANSI colors with `auto`, forced-on, and forced-off modes.
+- Supports custom JSON config through `logging.config.dictConfig`.
+- Includes optional uvicorn access-log filtering helpers.
+- Has no runtime dependency on vLLM or any other third-party package.
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `STDLOGKIT_CONFIGURE_LOGGING` | `1` | Set `0` to disable auto configuration. |
+| `STDLOGKIT_LOGGING_LEVEL` | `INFO` | Root or named logger level. |
+| `STDLOGKIT_LOGGING_STREAM` | `ext://sys.stdout` | Handler stream. |
+| `STDLOGKIT_LOGGING_PREFIX` | empty | Prefix prepended to every log line. |
+| `STDLOGKIT_LOGGING_COLOR` | `auto` | `auto`, `1`, or `0`. |
+| `STDLOGKIT_LOGGING_CONFIG_PATH` | unset | Path to a JSON `dictConfig` file. |
+| `STDLOGKIT_LOGGER_NAME` | empty | Configure a named logger instead of root. |
+| `STDLOGKIT_ROOT_DIR` | current working directory | Base path for relative file display. |
+| `STDLOGKIT_SHOW_REL_PATH` | `debug` | `debug`, `always`, or `never`. |
+| `NO_COLOR` | `0` | Standard flag to disable ANSI colors. |
+
+## Custom JSON Config
+
+```json
+{
+  "version": 1,
+  "disable_existing_loggers": false,
+  "formatters": {
+    "plain": {
+      "class": "stdlogkit.formatter.NewLineFormatter",
+      "format": "%(levelname)s %(asctime)s [%(fileinfo)s:%(lineno)d] %(message)s",
+      "datefmt": "%m-%d %H:%M:%S"
+    }
+  },
+  "handlers": {
+    "console": {
+      "class": "logging.StreamHandler",
+      "formatter": "plain",
+      "level": "INFO",
+      "stream": "ext://sys.stdout"
+    }
+  },
+  "root": {
+    "handlers": ["console"],
+    "level": "INFO"
+  }
+}
+```
+
+Run with:
+
+```bash
+STDLOGKIT_LOGGING_CONFIG_PATH=/path/to/logging.json python app.py
+```
+
+## Named Logger Mode
+
+By default, stdlogkit configures the root logger. If you want behavior closer
+to a framework-specific logger, configure only a named logger:
+
+```bash
+STDLOGKIT_LOGGER_NAME=my_app python app.py
+```
+
+Then loggers under `my_app.*` propagate to that logger:
+
+```python
+import logging
+import stdlogkit  # noqa: F401
+
+logger = logging.getLogger("my_app.service")
+logger.info("hello")
+```
+
+## Development
+
+```bash
+cd standalone_logging_pkg
+uv venv --python 3.12
+uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+uv build
+```
+
+## Publish to PyPI
+
+Before publishing, make sure the project name in `pyproject.toml` is available
+on PyPI and replace the placeholder author/repository metadata.
+
+```bash
+cd standalone_logging_pkg
+uv build
+uv publish --token "$PYPI_TOKEN"
+```
+
+For TestPyPI:
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ --token "$TEST_PYPI_TOKEN"
+```

stdlogkit-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stdlogkit"
+version = "0.1.0"
+description = "A small stdlib logging auto-configuration kit with colored multiline logs and log-once helpers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [
+  { name = "Your Name", email = "you@example.com" },
+]
+keywords = ["logging", "stdlib", "colored-logs", "python-logging"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Logging",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8",
+  "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/stdlogkit"
+Repository = "https://github.com/your-org/stdlogkit"
+Issues = "https://github.com/your-org/stdlogkit/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+stdlogkit = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

stdlogkit-0.1.0/setup.cfg

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

stdlogkit-0.1.0/src/stdlogkit/__init__.py

@@ -0,0 +1,44 @@
+"""Auto-configuring helpers for Python's standard :mod:`logging` package.
+
+Importing :mod:`stdlogkit` configures standard-library logging immediately
+unless ``STDLOGKIT_CONFIGURE_LOGGING=0`` is set.
+"""
+
+from stdlogkit.access_log_filter import (
+    UvicornAccessLogFilter,
+    create_uvicorn_log_config,
+)
+from stdlogkit.formatter import ColoredFormatter, NewLineFormatter
+from stdlogkit.lazy import lazy
+from stdlogkit.logger import (
+    LogScope,
+    configure_logging,
+    current_formatter_type,
+    get_logger,
+    init_logger,
+    install_logger_methods,
+    reset_once_cache,
+    suppress_logging,
+)
+from stdlogkit.timing import logtime
+
+__version__ = "0.1.0"
+
+configure_logging()
+
+__all__ = [
+    "ColoredFormatter",
+    "LogScope",
+    "NewLineFormatter",
+    "UvicornAccessLogFilter",
+    "configure_logging",
+    "create_uvicorn_log_config",
+    "current_formatter_type",
+    "get_logger",
+    "init_logger",
+    "install_logger_methods",
+    "lazy",
+    "logtime",
+    "reset_once_cache",
+    "suppress_logging",
+]

stdlogkit-0.1.0/src/stdlogkit/access_log_filter.py

@@ -0,0 +1,89 @@
+"""Optional uvicorn access-log filtering helpers."""
+
+from __future__ import annotations
+
+import logging
+from urllib.parse import urlparse
+
+
+class UvicornAccessLogFilter(logging.Filter):
+    """Filter uvicorn access logs for exact endpoint paths."""
+
+    def __init__(self, excluded_paths: list[str] | None = None):
+        super().__init__()
+        self.excluded_paths = set(excluded_paths or [])
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if not self.excluded_paths or record.name != "uvicorn.access":
+            return True
+
+        log_args = record.args
+        if isinstance(log_args, tuple) and len(log_args) >= 3:
+            path_with_query = log_args[2]
+            if isinstance(path_with_query, str):
+                path = urlparse(path_with_query).path
+                return path not in self.excluded_paths
+
+        return True
+
+
+def create_uvicorn_log_config(
+    excluded_paths: list[str] | None = None,
+    log_level: str = "info",
+) -> dict:
+    """Create a uvicorn ``log_config`` dictionary with access-log filtering."""
+
+    return {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "filters": {
+            "access_log_filter": {
+                "()": UvicornAccessLogFilter,
+                "excluded_paths": excluded_paths or [],
+            },
+        },
+        "formatters": {
+            "default": {
+                "()": "uvicorn.logging.DefaultFormatter",
+                "fmt": "%(levelprefix)s %(message)s",
+                "use_colors": None,
+            },
+            "access": {
+                "()": "uvicorn.logging.AccessFormatter",
+                "fmt": (
+                    '%(levelprefix)s %(client_addr)s - '
+                    '"%(request_line)s" %(status_code)s'
+                ),
+            },
+        },
+        "handlers": {
+            "default": {
+                "formatter": "default",
+                "class": "logging.StreamHandler",
+                "stream": "ext://sys.stderr",
+            },
+            "access": {
+                "formatter": "access",
+                "class": "logging.StreamHandler",
+                "stream": "ext://sys.stdout",
+                "filters": ["access_log_filter"],
+            },
+        },
+        "loggers": {
+            "uvicorn": {
+                "handlers": ["default"],
+                "level": log_level.upper(),
+                "propagate": False,
+            },
+            "uvicorn.error": {
+                "handlers": ["default"],
+                "level": log_level.upper(),
+                "propagate": False,
+            },
+            "uvicorn.access": {
+                "handlers": ["access"],
+                "level": log_level.upper(),
+                "propagate": False,
+            },
+        },
+    }

stdlogkit-0.1.0/src/stdlogkit/env.py

@@ -0,0 +1,46 @@
+"""Environment-backed settings for stdlogkit."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _bool_from_env(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() not in {"0", "false", "no", "off", ""}
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Logging settings loaded from environment variables."""
+
+    configure_logging: bool = True
+    logging_level: str = "INFO"
+    logging_prefix: str = ""
+    logging_stream: str = "ext://sys.stdout"
+    logging_config_path: str | None = None
+    logging_color: str = "auto"
+    logger_name: str = ""
+    root_dir: str | None = None
+    show_rel_path: str = "debug"
+    no_color: bool = False
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        """Build settings from ``STDLOGKIT_*`` environment variables."""
+
+        return cls(
+            configure_logging=_bool_from_env("STDLOGKIT_CONFIGURE_LOGGING", True),
+            logging_level=os.getenv("STDLOGKIT_LOGGING_LEVEL", "INFO").upper(),
+            logging_prefix=os.getenv("STDLOGKIT_LOGGING_PREFIX", ""),
+            logging_stream=os.getenv("STDLOGKIT_LOGGING_STREAM", "ext://sys.stdout"),
+            logging_config_path=os.getenv("STDLOGKIT_LOGGING_CONFIG_PATH"),
+            logging_color=os.getenv("STDLOGKIT_LOGGING_COLOR", "auto").lower(),
+            logger_name=os.getenv("STDLOGKIT_LOGGER_NAME", ""),
+            root_dir=os.getenv("STDLOGKIT_ROOT_DIR"),
+            show_rel_path=os.getenv("STDLOGKIT_SHOW_REL_PATH", "debug").lower(),
+            no_color=_bool_from_env("NO_COLOR", False),
+        )

stdlogkit-0.1.0/src/stdlogkit/formatter.py

@@ -0,0 +1,89 @@
+"""Formatters used by stdlogkit."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+from stdlogkit.env import Settings
+
+
+def _shrink_path(relpath: Path) -> str:
+    parts = list(relpath.parts)
+    if len(parts) <= 4:
+        return "/".join(parts)
+    return "/".join(parts[:1] + ["..."] + parts[-2:])
+
+
+class NewLineFormatter(logging.Formatter):
+    """Formatter that aligns every line in a multiline log message."""
+
+    def __init__(self, fmt: str, datefmt: str | None = None, style: str = "%"):
+        super().__init__(fmt, datefmt, style)
+        settings = Settings.from_env()
+        self.show_rel_path = settings.show_rel_path
+        self.root_dir = Path(settings.root_dir or os.getcwd()).resolve()
+
+    def _use_relpath(self, record: logging.LogRecord) -> bool:
+        if self.show_rel_path == "always":
+            return True
+        if self.show_rel_path == "never":
+            return False
+        return record.levelno <= logging.DEBUG
+
+    def _fileinfo(self, record: logging.LogRecord) -> str:
+        if not self._use_relpath(record):
+            return record.filename
+
+        pathname = getattr(record, "pathname", None)
+        if not pathname:
+            return record.filename
+
+        try:
+            relpath = Path(pathname).resolve().relative_to(self.root_dir)
+        except Exception:
+            relpath = Path(record.filename)
+        return _shrink_path(relpath)
+
+    def format(self, record: logging.LogRecord) -> str:
+        record.fileinfo = self._fileinfo(record)
+        msg = super().format(record)
+        message = record.getMessage()
+        if message:
+            prefix = msg.partition(message)[0]
+            msg = msg.replace("\n", "\r\n" + prefix)
+        return msg
+
+
+class ColoredFormatter(NewLineFormatter):
+    """Formatter that colors level names and static metadata with ANSI codes."""
+
+    COLORS = {
+        "DEBUG": "\033[37m",
+        "INFO": "\033[32m",
+        "WARNING": "\033[33m",
+        "ERROR": "\033[31m",
+        "CRITICAL": "\033[35m",
+    }
+    GREY = "\033[90m"
+    RESET = "\033[0m"
+
+    def __init__(self, fmt: str, datefmt: str | None = None, style: str = "%"):
+        if fmt:
+            fmt = fmt.replace("%(asctime)s", f"{self.GREY}%(asctime)s{self.RESET}")
+            fmt = fmt.replace(
+                "[%(fileinfo)s:%(lineno)d]",
+                f"{self.GREY}[%(fileinfo)s:%(lineno)d]{self.RESET}",
+            )
+        super().__init__(fmt, datefmt, style)
+
+    def format(self, record: logging.LogRecord) -> str:
+        original_levelname = record.levelname
+        color = self.COLORS.get(original_levelname)
+        if color is not None:
+            record.levelname = f"{color}{original_levelname}{self.RESET}"
+        try:
+            return super().format(record)
+        finally:
+            record.levelname = original_levelname

stdlogkit-0.1.0/src/stdlogkit/lazy.py

@@ -0,0 +1,21 @@
+"""Lazy log message arguments."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class lazy:
+    """Wrap a zero-argument callable evaluated only during log formatting."""
+
+    __slots__ = ("_factory",)
+
+    def __init__(self, factory: Callable[[], Any]) -> None:
+        self._factory = factory
+
+    def __str__(self) -> str:
+        return str(self._factory())
+
+    def __repr__(self) -> str:
+        return str(self)

stdlogkit-0.1.0/src/stdlogkit/logger.py

@@ -0,0 +1,298 @@
+"""Configuration and extensions for Python's standard logging package."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import threading
+from collections.abc import Generator
+from contextlib import contextmanager
+from logging import Logger
+from logging.config import dictConfig
+from pathlib import Path
+from typing import Any, Literal, TypeVar, cast
+
+from stdlogkit.env import Settings
+from stdlogkit.formatter import ColoredFormatter, NewLineFormatter
+
+_FORMAT_TEMPLATE = (
+    "{prefix}%(levelname)s %(asctime)s "
+    "[%(fileinfo)s:%(lineno)d] %(message)s"
+)
+_DATE_FORMAT = "%m-%d %H:%M:%S"
+
+LogScope = Literal["process", "global", "local"]
+_LoggerT = TypeVar("_LoggerT", bound=Logger)
+_CONFIGURED = False
+_ONCE_LOCK = threading.RLock()
+_ONCE_KEYS: set[tuple[str, int, str, tuple[str, ...], str]] = set()
+
+
+def _env_rank(names: tuple[str, ...]) -> int:
+    for name in names:
+        raw = os.getenv(name)
+        if raw is None:
+            continue
+        try:
+            return int(raw)
+        except ValueError:
+            return 0
+    return 0
+
+
+def _should_log_with_scope(scope: LogScope) -> bool:
+    if scope == "process":
+        return True
+    if scope == "global":
+        return _env_rank(("RANK", "WORLD_RANK", "SLURM_PROCID")) == 0
+    if scope == "local":
+        return (
+            _env_rank(
+                ("LOCAL_RANK", "MPI_LOCALRANKID", "OMPI_COMM_WORLD_LOCAL_RANK")
+            )
+            == 0
+        )
+    return True
+
+
+def _safe_key(value: Any) -> str:
+    try:
+        return repr(value)
+    except Exception:
+        return f"<unrepresentable {type(value).__name__}>"
+
+
+def _log_once(
+    logger: Logger,
+    level: int,
+    msg: str,
+    args: tuple[Any, ...],
+    scope: LogScope,
+    kwargs: dict[str, Any],
+) -> None:
+    if not _should_log_with_scope(scope):
+        return
+
+    key = (logger.name, level, msg, tuple(_safe_key(arg) for arg in args), scope)
+    with _ONCE_LOCK:
+        if key in _ONCE_KEYS:
+            return
+        _ONCE_KEYS.add(key)
+
+    kwargs.setdefault("stacklevel", 3)
+    logger.log(level, msg, *args, **kwargs)
+
+
+class StdLogKitLogger(Logger):
+    """Logger type used for static typing of stdlogkit helper methods."""
+
+    def debug_once(
+        self,
+        msg: str,
+        *args: Any,
+        scope: LogScope = "local",
+        **kwargs: Any,
+    ) -> None:
+        """Log a DEBUG message once per logger/message/argument tuple."""
+
+        _log_once(self, logging.DEBUG, msg, args, scope, kwargs)
+
+    def info_once(
+        self,
+        msg: str,
+        *args: Any,
+        scope: LogScope = "local",
+        **kwargs: Any,
+    ) -> None:
+        """Log an INFO message once per logger/message/argument tuple."""
+
+        _log_once(self, logging.INFO, msg, args, scope, kwargs)
+
+    def warning_once(
+        self,
+        msg: str,
+        *args: Any,
+        scope: LogScope = "local",
+        **kwargs: Any,
+    ) -> None:
+        """Log a WARNING message once per logger/message/argument tuple."""
+
+        _log_once(self, logging.WARNING, msg, args, scope, kwargs)
+
+
+_METHODS_TO_PATCH = {
+    "debug_once": StdLogKitLogger.debug_once,
+    "info_once": StdLogKitLogger.info_once,
+    "warning_once": StdLogKitLogger.warning_once,
+}
+
+
+def install_logger_methods(*, overwrite: bool = False) -> None:
+    """Install ``*_once`` methods onto standard-library logger classes."""
+
+    for target in (logging.Logger, logging.RootLogger):
+        for name, method in _METHODS_TO_PATCH.items():
+            if overwrite or not hasattr(target, name):
+                setattr(target, name, method)
+
+
+def _use_color(settings: Settings) -> bool:
+    if settings.no_color or settings.logging_color == "0":
+        return False
+    if settings.logging_color == "1":
+        return True
+    if settings.logging_color != "auto":
+        return False
+
+    if settings.logging_stream == "ext://sys.stdout":
+        return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+    if settings.logging_stream == "ext://sys.stderr":
+        return hasattr(sys.stderr, "isatty") and sys.stderr.isatty()
+    return False
+
+
+def _default_logging_config(settings: Settings) -> dict[str, Any]:
+    formatter_name = "stdlogkit_color" if _use_color(settings) else "stdlogkit"
+    config: dict[str, Any] = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "stdlogkit": {
+                "class": "stdlogkit.formatter.NewLineFormatter",
+                "datefmt": _DATE_FORMAT,
+                "format": _FORMAT_TEMPLATE.format(prefix=settings.logging_prefix),
+            },
+            "stdlogkit_color": {
+                "class": "stdlogkit.formatter.ColoredFormatter",
+                "datefmt": _DATE_FORMAT,
+                "format": _FORMAT_TEMPLATE.format(prefix=settings.logging_prefix),
+            },
+        },
+        "handlers": {
+            "stdlogkit": {
+                "class": "logging.StreamHandler",
+                "formatter": formatter_name,
+                "level": settings.logging_level,
+                "stream": settings.logging_stream,
+            },
+        },
+    }
+
+    if settings.logger_name:
+        config["loggers"] = {
+            settings.logger_name: {
+                "handlers": ["stdlogkit"],
+                "level": settings.logging_level,
+                "propagate": False,
+            },
+        }
+    else:
+        config["root"] = {
+            "handlers": ["stdlogkit"],
+            "level": settings.logging_level,
+        }
+
+    return config
+
+
+def _load_custom_config(path: str) -> dict[str, Any]:
+    config_path = Path(path)
+    if not config_path.exists():
+        raise RuntimeError(
+            "Could not load logging config. File does not exist: "
+            f"{path}"
+        )
+
+    with config_path.open(encoding="utf-8") as file:
+        custom_config = json.loads(file.read())
+
+    if not isinstance(custom_config, dict):
+        raise ValueError(
+            "Invalid logging config. Expected dict, got "
+            f"{type(custom_config).__name__}."
+        )
+    return custom_config
+
+
+def configure_logging(*, force: bool = False, settings: Settings | None = None) -> None:
+    """Configure standard-library logging from environment-backed settings.
+
+    Importing :mod:`stdlogkit` calls this once automatically. Call it manually
+    with ``force=True`` after changing environment variables in tests or tools.
+    """
+
+    global _CONFIGURED
+
+    install_logger_methods()
+    if _CONFIGURED and not force:
+        return
+
+    settings = settings or Settings.from_env()
+    if not settings.configure_logging and settings.logging_config_path:
+        raise RuntimeError(
+            "STDLOGKIT_CONFIGURE_LOGGING evaluated to false, but "
+            "STDLOGKIT_LOGGING_CONFIG_PATH was given. Enable "
+            "STDLOGKIT_CONFIGURE_LOGGING or unset STDLOGKIT_LOGGING_CONFIG_PATH."
+        )
+
+    if not settings.configure_logging:
+        _CONFIGURED = True
+        return
+
+    logging_config = (
+        _load_custom_config(settings.logging_config_path)
+        if settings.logging_config_path
+        else _default_logging_config(settings)
+    )
+    dictConfig(logging_config)
+    _CONFIGURED = True
+
+
+def init_logger(name: str) -> StdLogKitLogger:
+    """Return a logger with stdlogkit's ``*_once`` helper methods available."""
+
+    install_logger_methods()
+    return cast(StdLogKitLogger, logging.getLogger(name))
+
+
+def get_logger(name: str) -> StdLogKitLogger:
+    """Alias for :func:`init_logger`."""
+
+    return init_logger(name)
+
+
+def reset_once_cache() -> None:
+    """Clear the de-duplication cache used by ``*_once`` methods."""
+
+    with _ONCE_LOCK:
+        _ONCE_KEYS.clear()
+
+
+@contextmanager
+def suppress_logging(level: int = logging.INFO) -> Generator[None, Any, None]:
+    """Temporarily suppress logging up to ``level``."""
+
+    current_level = logging.root.manager.disable
+    logging.disable(level)
+    try:
+        yield
+    finally:
+        logging.disable(current_level)
+
+
+def current_formatter_type(logger: Logger) -> Literal["color", "newline", None]:
+    """Return the stdlogkit formatter type found on ``logger`` or its parents."""
+
+    current: Logger | None = logger
+    while current is not None:
+        for handler in current.handlers:
+            if handler.name == "stdlogkit":
+                formatter = handler.formatter
+                if isinstance(formatter, ColoredFormatter):
+                    return "color"
+                if isinstance(formatter, NewLineFormatter):
+                    return "newline"
+        current = current.parent
+    return None

stdlogkit-0.1.0/src/stdlogkit/py.typed

@@ -0,0 +1 @@
+

stdlogkit-0.1.0/src/stdlogkit/timing.py

@@ -0,0 +1,34 @@
+"""Timing helpers for logging."""
+
+from __future__ import annotations
+
+import functools
+import time
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def logtime(logger, msg: str | None = None):
+    """Log the execution time of the decorated function at DEBUG level."""
+
+    def _inner(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start = time.perf_counter()
+            result = func(*args, **kwargs)
+            elapsed = time.perf_counter() - start
+
+            prefix = (
+                f"Function '{func.__module__}.{func.__qualname__}'"
+                if msg is None
+                else msg
+            )
+            logger.debug("%s: Elapsed time %.7f secs", prefix, elapsed)
+            return result
+
+        return _wrapper
+
+    return _inner

stdlogkit-0.1.0/src/stdlogkit.egg-info/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: stdlogkit
+Version: 0.1.0
+Summary: A small stdlib logging auto-configuration kit with colored multiline logs and log-once helpers.
+Author-email: Your Name <you@example.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/your-org/stdlogkit
+Project-URL: Repository, https://github.com/your-org/stdlogkit
+Project-URL: Issues, https://github.com/your-org/stdlogkit/issues
+Keywords: logging,stdlib,colored-logs,python-logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+
+# stdlogkit
+
+`stdlogkit` is a tiny, vLLM-independent wrapper around Python's standard
+`logging` package.
+
+Importing it configures standard logging immediately:
+
+```python
+import logging
+import stdlogkit  # noqa: F401
+
+logger = logging.getLogger(__name__)
+logger.info("hello")
+logger.warning_once("this warning appears once")
+```
+
+Default output:
+
+```text
+INFO 06-24 12:00:01 [example.py:5] hello
+WARNING 06-24 12:00:01 [example.py:6] this warning appears once
+```
+
+## Features
+
+- Uses only Python's standard `logging` machinery.
+- Auto-configures logging on `import stdlogkit`.
+- Configures the root logger by default, so normal `logging.getLogger(...)`
+  calls work immediately.
+- Adds `debug_once`, `info_once`, and `warning_once` to standard logger
+  instances.
+- Supports multiline log alignment.
+- Supports ANSI colors with `auto`, forced-on, and forced-off modes.
+- Supports custom JSON config through `logging.config.dictConfig`.
+- Includes optional uvicorn access-log filtering helpers.
+- Has no runtime dependency on vLLM or any other third-party package.
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `STDLOGKIT_CONFIGURE_LOGGING` | `1` | Set `0` to disable auto configuration. |
+| `STDLOGKIT_LOGGING_LEVEL` | `INFO` | Root or named logger level. |
+| `STDLOGKIT_LOGGING_STREAM` | `ext://sys.stdout` | Handler stream. |
+| `STDLOGKIT_LOGGING_PREFIX` | empty | Prefix prepended to every log line. |
+| `STDLOGKIT_LOGGING_COLOR` | `auto` | `auto`, `1`, or `0`. |
+| `STDLOGKIT_LOGGING_CONFIG_PATH` | unset | Path to a JSON `dictConfig` file. |
+| `STDLOGKIT_LOGGER_NAME` | empty | Configure a named logger instead of root. |
+| `STDLOGKIT_ROOT_DIR` | current working directory | Base path for relative file display. |
+| `STDLOGKIT_SHOW_REL_PATH` | `debug` | `debug`, `always`, or `never`. |
+| `NO_COLOR` | `0` | Standard flag to disable ANSI colors. |
+
+## Custom JSON Config
+
+```json
+{
+  "version": 1,
+  "disable_existing_loggers": false,
+  "formatters": {
+    "plain": {
+      "class": "stdlogkit.formatter.NewLineFormatter",
+      "format": "%(levelname)s %(asctime)s [%(fileinfo)s:%(lineno)d] %(message)s",
+      "datefmt": "%m-%d %H:%M:%S"
+    }
+  },
+  "handlers": {
+    "console": {
+      "class": "logging.StreamHandler",
+      "formatter": "plain",
+      "level": "INFO",
+      "stream": "ext://sys.stdout"
+    }
+  },
+  "root": {
+    "handlers": ["console"],
+    "level": "INFO"
+  }
+}
+```
+
+Run with:
+
+```bash
+STDLOGKIT_LOGGING_CONFIG_PATH=/path/to/logging.json python app.py
+```
+
+## Named Logger Mode
+
+By default, stdlogkit configures the root logger. If you want behavior closer
+to a framework-specific logger, configure only a named logger:
+
+```bash
+STDLOGKIT_LOGGER_NAME=my_app python app.py
+```
+
+Then loggers under `my_app.*` propagate to that logger:
+
+```python
+import logging
+import stdlogkit  # noqa: F401
+
+logger = logging.getLogger("my_app.service")
+logger.info("hello")
+```
+
+## Development
+
+```bash
+cd standalone_logging_pkg
+uv venv --python 3.12
+uv pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+uv build
+```
+
+## Publish to PyPI
+
+Before publishing, make sure the project name in `pyproject.toml` is available
+on PyPI and replace the placeholder author/repository metadata.
+
+```bash
+cd standalone_logging_pkg
+uv build
+uv publish --token "$PYPI_TOKEN"
+```
+
+For TestPyPI:
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ --token "$TEST_PYPI_TOKEN"
+```

stdlogkit-0.1.0/src/stdlogkit.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/stdlogkit/__init__.py
+src/stdlogkit/access_log_filter.py
+src/stdlogkit/env.py
+src/stdlogkit/formatter.py
+src/stdlogkit/lazy.py
+src/stdlogkit/logger.py
+src/stdlogkit/py.typed
+src/stdlogkit/timing.py
+src/stdlogkit.egg-info/PKG-INFO
+src/stdlogkit.egg-info/SOURCES.txt
+src/stdlogkit.egg-info/dependency_links.txt
+src/stdlogkit.egg-info/requires.txt
+src/stdlogkit.egg-info/top_level.txt
+tests/test_stdlogkit.py

stdlogkit-0.1.0/src/stdlogkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stdlogkit-0.1.0/src/stdlogkit.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+build>=1.2
+pytest>=8
+twine>=5

stdlogkit-0.1.0/src/stdlogkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+stdlogkit

stdlogkit-0.1.0/tests/test_stdlogkit.py

@@ -0,0 +1,177 @@
+import importlib
+import json
+import logging
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+import stdlogkit
+from stdlogkit.env import Settings
+from stdlogkit.formatter import ColoredFormatter, NewLineFormatter
+from stdlogkit.logger import configure_logging, current_formatter_type, reset_once_cache
+
+
+class EnvTestCase(unittest.TestCase):
+    def setUp(self):
+        self._old_env = dict(os.environ)
+        for key in list(os.environ):
+            if key.startswith("STDLOGKIT_") or key == "NO_COLOR":
+                os.environ.pop(key, None)
+        reset_once_cache()
+
+    def tearDown(self):
+        os.environ.clear()
+        os.environ.update(self._old_env)
+        reset_once_cache()
+
+
+class StdLogKitTests(EnvTestCase):
+    def test_import_configures_root_logger(self):
+        os.environ["STDLOGKIT_LOGGING_COLOR"] = "0"
+        configure_logging(force=True)
+
+        root = logging.getLogger()
+        self.assertEqual(root.level, logging.INFO)
+        self.assertEqual(len(root.handlers), 1)
+
+        handler = root.handlers[0]
+        self.assertEqual(handler.name, "stdlogkit")
+        self.assertIs(handler.stream, sys.stdout)
+        self.assertIsInstance(handler.formatter, NewLineFormatter)
+
+    def test_standard_loggers_have_once_methods(self):
+        logger = logging.getLogger("example")
+
+        self.assertTrue(hasattr(logger, "debug_once"))
+        self.assertTrue(hasattr(logger, "info_once"))
+        self.assertTrue(hasattr(logger, "warning_once"))
+
+    def test_once_methods_deduplicate_unhashable_args(self):
+        records = []
+
+        class CollectHandler(logging.Handler):
+            def emit(self, record):
+                records.append(record)
+
+        handler = CollectHandler()
+        root = logging.getLogger()
+        root.handlers = [handler]
+        root.setLevel(logging.DEBUG)
+
+        logger = logging.getLogger("example.once")
+        logger.warning_once("payload=%s", {"items": [1, 2]})
+        logger.warning_once("payload=%s", {"items": [1, 2]})
+
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0].getMessage(), "payload={'items': [1, 2]}")
+
+    def test_custom_json_config_is_used(self):
+        config = {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "handlers": {
+                "null": {
+                    "class": "logging.NullHandler",
+                },
+            },
+            "root": {
+                "handlers": ["null"],
+                "level": "ERROR",
+            },
+        }
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            config_path = Path(tmpdir) / "logging.json"
+            config_path.write_text(json.dumps(config), encoding="utf-8")
+            os.environ["STDLOGKIT_LOGGING_CONFIG_PATH"] = str(config_path)
+
+            configure_logging(force=True)
+
+        root = logging.getLogger()
+        self.assertEqual(root.level, logging.ERROR)
+        self.assertIsInstance(root.handlers[0], logging.NullHandler)
+
+    def test_config_path_requires_configuration_enabled(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            config_path = Path(tmpdir) / "logging.json"
+            config_path.write_text("{}", encoding="utf-8")
+
+            os.environ["STDLOGKIT_CONFIGURE_LOGGING"] = "0"
+            os.environ["STDLOGKIT_LOGGING_CONFIG_PATH"] = str(config_path)
+
+            with self.assertRaisesRegex(RuntimeError, "STDLOGKIT_CONFIGURE_LOGGING"):
+                configure_logging(force=True)
+
+    def test_formatter_aligns_multiline_messages(self):
+        os.environ["STDLOGKIT_LOGGING_COLOR"] = "0"
+        formatter = NewLineFormatter(
+            "%(levelname)s %(asctime)s [%(fileinfo)s:%(lineno)d] %(message)s",
+            "%m-%d %H:%M:%S",
+        )
+        record = logging.LogRecord(
+            name="example",
+            level=logging.INFO,
+            pathname=__file__,
+            lineno=123,
+            msg="hello\nworld",
+            args=(),
+            exc_info=None,
+        )
+
+        formatted = formatter.format(record)
+
+        self.assertIn("hello", formatted)
+        self.assertIn("\r\nINFO ", formatted)
+        self.assertIn("world", formatted)
+
+    def test_color_formatter_restores_levelname(self):
+        formatter = ColoredFormatter("%(levelname)s %(message)s")
+        record = logging.LogRecord(
+            name="example",
+            level=logging.WARNING,
+            pathname=__file__,
+            lineno=1,
+            msg="hello",
+            args=(),
+            exc_info=None,
+        )
+
+        formatted = formatter.format(record)
+
+        self.assertIn("\033[33mWARNING\033[0m", formatted)
+        self.assertEqual(record.levelname, "WARNING")
+
+    def test_named_logger_mode(self):
+        os.environ["STDLOGKIT_LOGGER_NAME"] = "my_app"
+        os.environ["STDLOGKIT_LOGGING_COLOR"] = "0"
+        configure_logging(force=True)
+
+        app_logger = logging.getLogger("my_app")
+        child_logger = logging.getLogger("my_app.service")
+
+        self.assertTrue(app_logger.handlers)
+        self.assertFalse(child_logger.handlers)
+        self.assertTrue(child_logger.propagate)
+        self.assertEqual(current_formatter_type(child_logger), "newline")
+
+    def test_settings_are_read_at_configure_time(self):
+        os.environ["STDLOGKIT_LOGGING_LEVEL"] = "DEBUG"
+        settings = Settings.from_env()
+
+        self.assertEqual(settings.logging_level, "DEBUG")
+
+    def test_module_can_be_reloaded_without_double_configuring(self):
+        os.environ["STDLOGKIT_LOGGING_COLOR"] = "0"
+        configure_logging(force=True)
+        root = logging.getLogger()
+        before = list(root.handlers)
+
+        importlib.reload(stdlogkit)
+
+        self.assertEqual(logging.getLogger().handlers, before)
+
+
+if __name__ == "__main__":
+    unittest.main()