stdlogkit 0.1.0__tar.gz → 0.2.0__tar.gz

{stdlogkit-0.1.0 → stdlogkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stdlogkit
-Version: 0.1.0
+Version: 0.2.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
@@ -27,16 +27,17 @@ Requires-Dist: twine>=5; extra == "dev"
 
 # stdlogkit
 
-`stdlogkit` is a tiny, vLLM-independent wrapper around Python's standard
-`logging` package.
+`stdlogkit` is a vLLM-style, vLLM-independent wrapper around Python's
+standard `logging` package.
 
-Importing it configures standard logging immediately:
+Importing it configures logging immediately. Like vLLM, the default
+configuration installs a handler on a named root logger, `stdlogkit`, and child
+loggers propagate to it.
 
 ```python
-import logging
-import stdlogkit  # noqa: F401
+import stdlogkit
 
-logger = logging.getLogger(__name__)
+logger = stdlogkit.init_logger("stdlogkit.app")
 logger.info("hello")
 logger.warning_once("this warning appears once")
 ```
@@ -48,33 +49,48 @@ INFO 06-24 12:00:01 [example.py:5] hello
 WARNING 06-24 12:00:01 [example.py:6] this warning appears once
 ```
 
-## Features
+The default format intentionally does not include process name or PID, matching
+vLLM. Single-process and multiprocessing logs therefore use the same fields.
 
-- 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.
+## vLLM Compatibility
+
+This package mirrors vLLM's logging behavior while remaining fully decoupled:
+
+- Uses `logging.config.dictConfig`.
+- Configures one named logger by default, `stdlogkit`, with `propagate=false`.
+- Child loggers such as `stdlogkit.app` have no handler and propagate upward.
+- `init_logger(name)` patches `debug_once`, `info_once`, and `warning_once`
+  onto that returned logger instance.
+- `*_once` uses `functools.lru_cache`, so arguments must be hashable, as in
+  vLLM.
+- Multiline logs are aligned with the same prefix strategy as vLLM.
+- Color constants match vLLM exactly.
+
+## Colors
+
+The ANSI color values are identical to vLLM:
+
+| Level/field | ANSI code |
+| --- | --- |
+| `DEBUG` | `\033[37m` |
+| `INFO` | `\033[32m` |
+| `WARNING` | `\033[33m` |
+| `ERROR` | `\033[31m` |
+| `CRITICAL` | `\033[35m` |
+| timestamp and file info | `\033[90m` |
+| reset | `\033[0m` |
 
 ## 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_LEVEL` | `INFO` | Named logger and handler 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`. |
+| `STDLOGKIT_LOGGER_NAME` | `stdlogkit` | Named logger to configure. |
 | `NO_COLOR` | `0` | Standard flag to disable ANSI colors. |
 
 ## Custom JSON Config
@@ -98,9 +114,12 @@ WARNING 06-24 12:00:01 [example.py:6] this warning appears once
       "stream": "ext://sys.stdout"
     }
   },
-  "root": {
-    "handlers": ["console"],
-    "level": "INFO"
+  "loggers": {
+    "stdlogkit": {
+      "handlers": ["console"],
+      "level": "INFO",
+      "propagate": false
+    }
   }
 }
 ```
@@ -111,32 +130,13 @@ Run with:
 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
+PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
 uv build
 ```
 

{stdlogkit-0.1.0 → stdlogkit-0.2.0}/README.md

@@ -1,15 +1,16 @@
 # stdlogkit
 
-`stdlogkit` is a tiny, vLLM-independent wrapper around Python's standard
-`logging` package.
+`stdlogkit` is a vLLM-style, vLLM-independent wrapper around Python's
+standard `logging` package.
 
-Importing it configures standard logging immediately:
+Importing it configures logging immediately. Like vLLM, the default
+configuration installs a handler on a named root logger, `stdlogkit`, and child
+loggers propagate to it.
 
 ```python
-import logging
-import stdlogkit  # noqa: F401
+import stdlogkit
 
-logger = logging.getLogger(__name__)
+logger = stdlogkit.init_logger("stdlogkit.app")
 logger.info("hello")
 logger.warning_once("this warning appears once")
 ```
@@ -21,33 +22,48 @@ INFO 06-24 12:00:01 [example.py:5] hello
 WARNING 06-24 12:00:01 [example.py:6] this warning appears once
 ```
 
-## Features
+The default format intentionally does not include process name or PID, matching
+vLLM. Single-process and multiprocessing logs therefore use the same fields.
 
-- 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.
+## vLLM Compatibility
+
+This package mirrors vLLM's logging behavior while remaining fully decoupled:
+
+- Uses `logging.config.dictConfig`.
+- Configures one named logger by default, `stdlogkit`, with `propagate=false`.
+- Child loggers such as `stdlogkit.app` have no handler and propagate upward.
+- `init_logger(name)` patches `debug_once`, `info_once`, and `warning_once`
+  onto that returned logger instance.
+- `*_once` uses `functools.lru_cache`, so arguments must be hashable, as in
+  vLLM.
+- Multiline logs are aligned with the same prefix strategy as vLLM.
+- Color constants match vLLM exactly.
+
+## Colors
+
+The ANSI color values are identical to vLLM:
+
+| Level/field | ANSI code |
+| --- | --- |
+| `DEBUG` | `\033[37m` |
+| `INFO` | `\033[32m` |
+| `WARNING` | `\033[33m` |
+| `ERROR` | `\033[31m` |
+| `CRITICAL` | `\033[35m` |
+| timestamp and file info | `\033[90m` |
+| reset | `\033[0m` |
 
 ## 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_LEVEL` | `INFO` | Named logger and handler 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`. |
+| `STDLOGKIT_LOGGER_NAME` | `stdlogkit` | Named logger to configure. |
 | `NO_COLOR` | `0` | Standard flag to disable ANSI colors. |
 
 ## Custom JSON Config
@@ -71,9 +87,12 @@ WARNING 06-24 12:00:01 [example.py:6] this warning appears once
       "stream": "ext://sys.stdout"
     }
   },
-  "root": {
-    "handlers": ["console"],
-    "level": "INFO"
+  "loggers": {
+    "stdlogkit": {
+      "handlers": ["console"],
+      "level": "INFO",
+      "propagate": false
+    }
   }
 }
 ```
@@ -84,32 +103,13 @@ Run with:
 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
+PYTHONPATH=src .venv/bin/python -m unittest discover -s tests -v
 uv build
 ```
 

{stdlogkit-0.1.0 → stdlogkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stdlogkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "A small stdlib logging auto-configuration kit with colored multiline logs and log-once helpers."
 readme = "README.md"
 requires-python = ">=3.9"

{stdlogkit-0.1.0 → stdlogkit-0.2.0}/src/stdlogkit/__init__.py

@@ -22,7 +22,7 @@ from stdlogkit.logger import (
 )
 from stdlogkit.timing import logtime
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 configure_logging()
 

{stdlogkit-0.1.0 → stdlogkit-0.2.0}/src/stdlogkit/env.py

@@ -23,9 +23,7 @@ class Settings:
     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"
+    logger_name: str = "stdlogkit"
     no_color: bool = False
 
     @classmethod
@@ -38,9 +36,7 @@ class Settings:
             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(),
+            logging_color=os.getenv("STDLOGKIT_LOGGING_COLOR", "auto"),
+            logger_name=os.getenv("STDLOGKIT_LOGGER_NAME", "stdlogkit"),
             no_color=_bool_from_env("NO_COLOR", False),
         )

stdlogkit-0.2.0/src/stdlogkit/formatter.py

@@ -0,0 +1,90 @@
+"""Formatters used by stdlogkit."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from stdlogkit.env import Settings
+
+
+class NewLineFormatter(logging.Formatter):
+    """Adds logging prefix to newlines to align multi-line messages."""
+
+    def __init__(self, fmt, datefmt=None, style="%"):
+        super().__init__(fmt, datefmt, style)
+
+        self.use_relpath = Settings.from_env().logging_level == "DEBUG"
+        if self.use_relpath:
+            self.root_dir = Path(__file__).resolve().parent.parent.parent
+
+    def format(self, record):
+        def shrink_path(relpath: Path) -> str:
+            parts = list(relpath.parts)
+            new_parts = []
+            if parts and parts[0] == "stdlogkit":
+                parts = parts[1:]
+            if parts and parts[0] == "v1":
+                new_parts += parts[:2]
+                parts = parts[2:]
+            elif parts:
+                new_parts += parts[:1]
+                parts = parts[1:]
+            if len(parts) > 2:
+                new_parts += ["..."] + parts[-2:]
+            else:
+                new_parts += parts
+            return "/".join(new_parts)
+
+        if self.use_relpath:
+            abs_path = getattr(record, "pathname", None)
+            if abs_path:
+                try:
+                    relpath = Path(abs_path).resolve().relative_to(self.root_dir)
+                except Exception:
+                    relpath = Path(record.filename)
+            else:
+                relpath = Path(record.filename)
+            record.fileinfo = shrink_path(relpath)
+        else:
+            record.fileinfo = record.filename
+
+        msg = super().format(record)
+        if record.message != "":
+            parts = msg.split(record.message)
+            msg = msg.replace("\n", "\r\n" + parts[0])
+        return msg
+
+
+class ColoredFormatter(NewLineFormatter):
+    """Adds ANSI color codes to log levels for terminal output."""
+
+    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, datefmt=None, style="%"):
+        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):
+        orig_levelname = record.levelname
+        if (color_code := self.COLORS.get(record.levelname)) is not None:
+            record.levelname = f"{color_code}{record.levelname}{self.RESET}"
+
+        msg = super().format(record)
+
+        record.levelname = orig_levelname
+
+        return msg