github-actions-logger 0.1.0__py3-none-any.whl

github_actions_logger/__init__.py

@@ -0,0 +1,133 @@
+import logging
+import os
+import sys
+import traceback
+from typing import Self
+
+
+def is_github_actions() -> bool:
+    """Return True when running inside a GitHub Actions workflow."""
+    return os.environ.get("GITHUB_ACTIONS") == "true"
+
+
+def _escape_data(message: str) -> str:
+    """Escape a message as required by workflow commands."""
+    return message.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _escape_property(value: object) -> str:
+    """Escape an annotation property value as required by workflow commands."""
+    return _escape_data(str(value)).replace(":", "%3A").replace(",", "%2C")
+
+
+# `extra` key -> workflow command property name
+_ANNOTATION_PROPERTIES = {
+    "title": "title",
+    "file": "file",
+    "line": "line",
+    "end_line": "endLine",
+    "col": "col",
+    "end_column": "endColumn",
+}
+
+
+def _exc_text(exc_info: object) -> str:
+    """Format an `exc_info` argument the way `logging` accepts it."""
+    if exc_info is True:
+        exc_info = sys.exc_info()
+    elif isinstance(exc_info, BaseException):
+        exc_info = (type(exc_info), exc_info, exc_info.__traceback__)
+    if not isinstance(exc_info, tuple) or exc_info[0] is None:
+        return ""
+    return "".join(traceback.format_exception(*exc_info)).rstrip("\n")
+
+
+class Group:
+    """Context manager that wraps output in a collapsible log group.
+
+    Emits `::group::{title}` on entry and `::endgroup::` on exit. Does nothing
+    when not running in CI.
+    """
+
+    def __init__(self, title: str, in_ci: bool) -> None:
+        self.title = title
+        self._in_ci = in_ci
+
+    def __enter__(self) -> Self:
+        if self._in_ci:
+            sys.stdout.write(f"::group::{_escape_data(self.title)}\n")
+            sys.stdout.flush()
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        if self._in_ci:
+            sys.stdout.write("::endgroup::\n")
+            sys.stdout.flush()
+
+
+class Logger(logging.Logger):
+    """Logger that emits GitHub Actions workflow commands when running in CI.
+
+    `debug` -> `::debug::`, `info` -> `::notice::`, `warning` -> `::warning::`,
+    `error`/`critical`/`exception` -> `::error::`. Outside CI, standard logging is used.
+
+    Annotation properties can be passed via `extra` (ignored for `debug`):
+    `title`, `file`, `line`, `end_line`, `col` and `end_column`.
+    """
+
+    def __init__(self, name: str, in_ci: bool | None = None) -> None:
+        super().__init__(name)
+        self._in_ci = is_github_actions() if in_ci is None else in_ci
+
+    def _command(self, command: str, msg: object, args: tuple, kwargs: dict) -> None:
+        message = str(msg) % args if args else str(msg)
+        if kwargs.get("exc_info"):
+            text = _exc_text(kwargs["exc_info"])
+            if text:
+                message = f"{message}\n{text}"
+        properties = ""
+        extra = kwargs.get("extra")
+        if command != "debug" and isinstance(extra, dict):
+            parts = [
+                f"{name}={_escape_property(extra[key])}"
+                for key, name in _ANNOTATION_PROPERTIES.items()
+                if extra.get(key) is not None
+            ]
+            if parts:
+                properties = " " + ",".join(parts)
+        sys.stdout.write(f"::{command}{properties}::{_escape_data(message)}\n")
+        sys.stdout.flush()
+
+    def group(self, title: str) -> Group:
+        """Return a context manager that wraps output in a collapsible log group."""
+        return Group(title, self._in_ci)
+
+    def debug(self, msg: object, *args: object, **kwargs: object) -> None:
+        if self._in_ci:
+            self._command("debug", msg, args, kwargs)
+        else:
+            super().debug(msg, *args, **kwargs)  # type: ignore[arg-type]
+
+    def info(self, msg: object, *args: object, **kwargs: object) -> None:
+        if self._in_ci:
+            self._command("notice", msg, args, kwargs)
+        else:
+            super().info(msg, *args, **kwargs)  # type: ignore[arg-type]
+
+    def warning(self, msg: object, *args: object, **kwargs: object) -> None:
+        if self._in_ci:
+            self._command("warning", msg, args, kwargs)
+        else:
+            super().warning(msg, *args, **kwargs)  # type: ignore[arg-type]
+
+    def error(self, msg: object, *args: object, **kwargs: object) -> None:
+        if self._in_ci:
+            self._command("error", msg, args, kwargs)
+        else:
+            super().error(msg, *args, **kwargs)  # type: ignore[arg-type]
+
+    def critical(self, msg: object, *args: object, **kwargs: object) -> None:
+        if self._in_ci:
+            self._command("error", msg, args, kwargs)
+        else:
+            super().critical(msg, *args, **kwargs)  # type: ignore[arg-type]

github_actions_logger-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.3
+Name: github-actions-logger
+Version: 0.1.0
+Summary: 
+Author: Cyb3r-Jak3
+Author-email: Cyb3r-Jak3 <git@cyberjake.xyz>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# github-actions-logger
+
+A `logging.Logger` subclass that emits [GitHub Actions workflow commands](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands) when running in CI, and behaves like a normal logger everywhere else.
+
+## Installation
+
+```bash
+pip install github-actions-logger
+```
+
+Or with uv:
+
+```bash
+uv add github-actions-logger
+```
+
+Requires Python 3.12 or newer.
+
+## Usage
+
+```python
+from github_actions_logger import Logger
+
+log = Logger("my-app")
+
+log.debug("Cache key: %s", key)
+log.info("Deployed")
+log.warning("Deprecated option used")
+log.error("Build failed")
+```
+
+In GitHub Actions (detected via `GITHUB_ACTIONS=true`) these print:
+
+```text
+::debug::Cache key: abc123
+::notice::Deployed
+::warning::Deprecated option used
+::error::Build failed
+```
+
+Anywhere else, the calls go through standard `logging`, so handlers, levels and formatters work as usual.
+
+### Level mapping
+
+| Method | Workflow command |
+| --- | --- |
+| `debug` | `::debug::` |
+| `info` | `::notice::` |
+| `warning` | `::warning::` |
+| `error`, `critical`, `exception` | `::error::` |
+
+`exception()` (or any call with `exc_info`) appends the traceback to the message.
+
+### Annotations
+
+`notice`, `warning` and `error` messages can be attached to a file and line by passing the standard `extra` argument:
+
+```python
+log.warning(
+    "Unused import",
+    extra={"title": "Lint", "file": "src/app.py", "line": 12, "end_line": 12, "col": 1, "end_column": 20},
+)
+```
+
+```text
+::warning title=Lint,file=src/app.py,line=12,endLine=12,col=1,endColumn=20::Unused import
+```
+
+| `extra` key | Workflow property |
+| --- | --- |
+| `title` | `title` |
+| `file` | `file` |
+| `line` | `line` |
+| `end_line` | `endLine` |
+| `col` | `col` |
+| `end_column` | `endColumn` |
+
+Missing or `None` keys and unrelated keys are ignored, and `debug` ignores them entirely since `::debug::` takes no properties. Outside CI, `extra` becomes attributes on the `LogRecord`, so a formatter can use it (for example `%(file)s:%(line)s`).
+
+### Grouping log lines
+
+`group()` returns a context manager that wraps output in a collapsible [log group](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#grouping-log-lines):
+
+```python
+with log.group("Install dependencies"):
+    log.info("Resolving...")
+```
+
+```text
+::group::Install dependencies
+::notice::Resolving...
+::endgroup::
+```
+
+`::endgroup::` is emitted even if the block raises. Outside CI, `group()` does nothing.
+
+### Overriding detection
+
+CI detection happens once, when the logger is created. To force it on or off, pass `in_ci`:
+
+```python
+Logger("my-app", in_ci=True)   # always emit workflow commands
+Logger("my-app", in_ci=False)  # always use standard logging
+```
+
+### Notes
+
+- In CI, messages are written straight to stdout and bypass the logger's level and handlers. GitHub only displays `::debug::` lines when step debug logging is enabled (`ACTIONS_STEP_DEBUG`).
+- Create the logger with `Logger(...)` directly. `logging.setLoggerClass(Logger)` plus `logging.getLogger(name)` works, but only passes `name`, so `in_ci` can't be set that way.
+
+## Development
+
+```bash
+uv run pytest
+```
+
+Runs the tests with a coverage report.

github_actions_logger-0.1.0.dist-info/RECORD

@@ -0,0 +1,4 @@
+github_actions_logger/__init__.py,sha256=Y4TQrxt5O74WiefEECZnF2gAOutaNk5PYoJeXEluDw4,4711
+github_actions_logger-0.1.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+github_actions_logger-0.1.0.dist-info/METADATA,sha256=GBEs9htkvlRRrwFs0Pglnb8Qg7yTQ4vih6uSFslugG8,3988
+github_actions_logger-0.1.0.dist-info/RECORD,,

github_actions_logger-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.1
+Root-Is-Purelib: true
+Tag: py3-none-any