Add plugin pipeline and plugins

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,5 +15,5 @@
 
 ## Scope
 
-<!-- One phase/concern per PR where possible. Call out here if this
+<!-- One concern per PR where possible. Call out here if this
  intentionally spans more than one. -->

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Plugin pipeline: `Plugin` base (`before_log`/`after_log`/`on_error`,
+ all optional to override), `ContextPlugin` (merges fixed context into
+ `meta`), `RedactPlugin` (replaces sensitive `meta` values by key, case-
+ insensitive), and `SamplingPlugin` (probabilistically drops records).
+ `Logger` now accepts `plugins=[...]` and gained `.use(plugin)` to register
+ one and chain. A plugin hook that raises is caught, routed to that same
+ plugin's `on_error`, and the pipeline continues — a broken plugin can't
+ crash logging, verified by test.
 - Added `.github/dependabot.yml`: weekly version updates for `pip`
  dependencies and GitHub Actions.
 - Added GitHub issue templates: `.github/ISSUE_TEMPLATE/bug_report.yml`,
@@ -12,23 +20,23 @@ All notable changes to this project are documented in this file.
 - Added `.github/SECURITY.md`: supported-versions policy and instructions
  to report vulnerabilities via GitHub's private vulnerability reporting
  instead of public issues. Linked from the README.
-- Phase 2 transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
+- Transports: `Transport` base (`format`/`write`/`close`), `ConsoleTransport`
  (colorized, ERROR/FATAL to stderr), `FileTransport` (size-based rotation), and
  `HTTPTransport` (batched, newline-delimited JSON over stdlib `urllib`, with an
  injectable `sender` for tests or alternate backends). `Logger` now accepts
  `transports=[...]` and dispatches each record to them synchronously, and gained
  `.close()` to close all attached transports. Dispatch is still synchronous —
-the non-blocking queue/async path is Phase 4. Also added `CollectingTransport`,
- an in-memory transport for tests.
+a non-blocking queue/async path isn't implemented yet. Also added
+`CollectingTransport`, an in-memory transport for tests.
 - Added `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1), `.github/CODEOWNERS`,
  `.github/PULL_REQUEST_TEMPLATE.md`, and `CONTRIBUTING.md` documenting the
  PR workflow (branch naming, scoping, review/CI requirements, squash-merge).
-- Phase 1 core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
+- Core API: `Level` (TRACE/DEBUG/INFO/WARN/ERROR/FATAL, matching
  logquill-js's numeric weights), `parse_level()`, the `LogRecord` shape,
  `Logger` with `.trace()/.debug()/.info()/.warn()/.error()/.fatal()` and
  `.set_level()`, and a `Formatter` protocol with a `JSONFormatter`
  implementation. Log calls return the record dict (or `None` when filtered
- by level) — no transports or dispatch yet, that's Phase 2.
+ by level) — no transports or dispatch yet.
 - Repo scaffold: `pyproject.toml`, package skeleton, dev tooling (ruff, mypy --strict, pytest), pre-commit hooks, and CI workflow.
 - Packaging metadata: expanded classifiers (OS, Topic) and keywords, added an `Issues` project URL, and fixed the `Homepage`/`Repository`/`Changelog` URLs to point at the actual `nikhilvdev/logquill-python` GitHub repo instead of a stale placeholder org.
 - Added a pepy.tech download-count badge to the README for tracking installs.

CONTRIBUTING.md

@@ -21,9 +21,8 @@ pytest
 
 - **Branch from `main`**, name branches by intent: `feat/…`, `fix/…`,
  `docs/…`, `chore/…` (e.g. `feat/rotating-file-transport`).
-- **Keep PRs scoped to one phase or concern** where possible. A PR that
- mixes an unrelated refactor with a feature is harder to review and harder
- to revert.
+- **Keep PRs scoped to one concern** where possible. A PR that mixes an
+ unrelated refactor with a feature is harder to review and harder to revert.
 - **Every PR must satisfy this definition of done** before it's ready for
  review:
  1. Type hints throughout, `mypy --strict` clean on the public API

README.md

@@ -14,18 +14,20 @@ Sibling to [`logquill` on npm](https://www.npmjs.com/package/logquill)
 across a Python + Node stack.
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, and transports are implemented; plugins and non-blocking async
-dispatch are not yet — see `CHANGELOG.md` for what's landed so far.
+filtering, transports, and the plugin pipeline are implemented;
+non-blocking async dispatch is not yet — see `CHANGELOG.md` for what's
+landed so far.
 
 ## Features
 
 - **Structured by default** — every call carries a `meta` dict, not just a message string
 - **Cross-language record shape** — identical JSON shape and level names/weights as [`logquill` on npm](https://www.npmjs.com/package/logquill)
 - **Pluggable transports** — `ConsoleTransport` (colorized, stderr for errors), `FileTransport` (rotation), `HTTPTransport` (batched); write your own by subclassing `Transport`
 - **Pluggable formatters** — `JSONFormatter` out of the box; implement `format(record) -> str` for your own
+- **Plugin pipeline** — `ContextPlugin`, `RedactPlugin`, `SamplingPlugin` out of the box; a broken plugin can't crash logging
 - **Zero required runtime dependencies** — stdlib only; `aiohttp` is opt-in, for async HTTP
 - **Typed throughout** — `mypy --strict` clean on the public API
-- *(planned)* plugin pipeline (redaction, sampling, rate limiting), non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
+- *(planned)* non-blocking async dispatch, `contextvars`-based context propagation — see `CHANGELOG.md`
 
 ## Install
 
@@ -66,7 +68,7 @@ print(JSONFormatter().format(record))
 
 Attach transports to a `Logger` to actually write records somewhere. Each
 record is dispatched to every attached transport synchronously (non-blocking
-dispatch lands in a later phase):
+dispatch isn't implemented yet):
 
 ```python
 from logquill import ConsoleTransport, FileTransport, HTTPTransport, Logger
@@ -99,6 +101,28 @@ logger.info("hello")
 assert sink.records[0]["message"] == "hello"
 ```
 
+## Plugins
+
+Plugins hook into the pipeline around each log call: `before_log(record)` can
+transform a record or return `None` to drop it, `after_log(record)` runs once
+it's been dispatched to every transport, and `on_error(exc, record)` catches
+anything a plugin's own hooks raise — a broken plugin can't take down logging.
+
+```python
+from logquill import ContextPlugin, Logger, RedactPlugin, SamplingPlugin
+
+logger = Logger("app")
+logger.use(ContextPlugin(service="api", env="prod")) # merged into every record's meta
+logger.use(RedactPlugin(keys=["password", "token"])) # replaces matching meta values
+logger.use(SamplingPlugin(0.1)) # keep ~10% of records that reach this point
+
+logger.info("login attempt", user_id=42, password="hunter2")
+# meta: {'service': 'api', 'env': 'prod', 'user_id': 42, 'password': '***'}
+# (unless this call was one of the ~90% sampling dropped, in which case it's None)
+```
+
+Write your own by subclassing `Plugin`; override only the hooks you need.
+
 ## Development
 
 ```bash

logquill/__init__.py

@@ -1,24 +1,32 @@
 from logquill.console_transport import ConsoleTransport
+from logquill.context_plugin import ContextPlugin
 from logquill.file_transport import FileTransport
 from logquill.formatter import Formatter, JSONFormatter
 from logquill.http_transport import HTTPTransport
 from logquill.levels import Level, parse_level
 from logquill.logger import Logger
+from logquill.plugin import Plugin
 from logquill.records import LogRecord
+from logquill.redact_plugin import RedactPlugin
+from logquill.sampling_plugin import SamplingPlugin
 from logquill.transport import CollectingTransport, Transport
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
  "CollectingTransport",
  "ConsoleTransport",
+ "ContextPlugin",
  "FileTransport",
  "Formatter",
  "HTTPTransport",
  "JSONFormatter",
  "Level",
  "LogRecord",
  "Logger",
+ "Plugin",
+ "RedactPlugin",
+ "SamplingPlugin",
  "Transport",
  "parse_level",
  "__version__",

logquill/context_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class ContextPlugin(Plugin):
+ """Injects fixed key/value pairs into every record's `meta`.
+
+ A value already present in a record's own `meta` wins over the fixed context.
+ """
+
+ def __init__(self, **context: Any) -> None:
+ self.context = context
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ record["meta"] = {**self.context, **record["meta"]}
+ return record

logquill/http_transport.py

@@ -27,7 +27,7 @@ class HTTPTransport(Transport):
 
  Uses `urllib` (stdlib) by default so the core package stays dependency-free.
  Pass `sender` to swap in a fake for tests, or a different backend (e.g. an
- aiohttp-based one, once the async dispatch path from Phase 4 exists).
+ aiohttp-based one, once a non-blocking async dispatch path exists).
  """
 
  def __init__(

logquill/logger.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import contextlib
 from typing import Any
 
 from logquill.levels import Level, parse_level
+from logquill.plugin import Plugin
 from logquill.records import LogRecord, create_record
 from logquill.transport import Transport
 
@@ -13,10 +15,12 @@ def __init__(
  name: str,
  level: int | str | Level = Level.INFO,
  transports: list[Transport] | None = None,
+ plugins: list[Plugin] | None = None,
  ) -> None:
  self.name = name
  self._level = parse_level(level)
  self.transports: list[Transport] = list(transports) if transports else []
+ self.plugins: list[Plugin] = list(plugins) if plugins else []
 
  @property
  def level(self) -> Level:
@@ -25,17 +29,45 @@ def level(self) -> Level:
  def set_level(self, level: int | str | Level) -> None:
  self._level = parse_level(level)
 
+ def use(self, plugin: Plugin) -> Logger:
+ """Register a plugin. Returns `self` so calls can be chained."""
+ self.plugins.append(plugin)
+ return self
+
  def close(self) -> None:
  """Close every attached transport. Call on shutdown to flush buffered writes."""
  for transport in self.transports:
  transport.close()
 
+ def _notify_error(self, plugin: Plugin, exc: Exception, record: LogRecord) -> None:
+ # a broken error handler must not crash logging either
+ with contextlib.suppress(Exception):
+ plugin.on_error(exc, record)
+
  def _log(self, level: Level, message: str, meta: dict[str, Any]) -> LogRecord | None:
  if level < self._level:
  return None
  record = create_record(level=level, logger=self.name, message=message, meta=meta)
+
+ for plugin in self.plugins:
+ try:
+ result = plugin.before_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+ continue
+ if result is None:
+ return None
+ record = result
+
  for transport in self.transports:
  transport.write(transport.format(record), record)
+
+ for plugin in self.plugins:
+ try:
+ plugin.after_log(record)
+ except Exception as exc:
+ self._notify_error(plugin, exc, record)
+
  return record
 
  def trace(self, message: str, **meta: Any) -> LogRecord | None:

logquill/plugin.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from logquill.records import LogRecord
+
+
+class Plugin:
+ """Base class for the plugin pipeline: `before_log`, `after_log`, `on_error`.
+
+ Override only the hooks you need — the rest default to no-ops. A plugin
+ hook that raises cannot crash logging: the pipeline catches it, routes it
+ to `on_error`, and moves on.
+ """
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ """Return a (possibly modified) record, or `None` to drop it."""
+ return record
+
+ def after_log(self, record: LogRecord) -> None:
+ """Called after the record has been dispatched to every transport."""
+
+ def on_error(self, exc: Exception, record: LogRecord) -> None:
+ """Called when one of this plugin's own hooks raises."""

logquill/redact_plugin.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+DEFAULT_REDACTED_KEYS = frozenset({"password", "token", "secret", "api_key", "authorization"})
+
+
+class RedactPlugin(Plugin):
+ """Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder."""
+
+ def __init__(
+ self,
+ keys: Iterable[str] = DEFAULT_REDACTED_KEYS,
+ replacement: str = "***",
+ ) -> None:
+ self.keys = {key.lower() for key in keys}
+ self.replacement = replacement
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ meta = record["meta"]
+ record["meta"] = {
+ key: self.replacement if key.lower() in self.keys else value
+ for key, value in meta.items()
+ }
+ return record

logquill/sampling_plugin.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import random
+from typing import Callable
+
+from logquill.plugin import Plugin
+from logquill.records import LogRecord
+
+
+class SamplingPlugin(Plugin):
+ """Keeps roughly `rate` of records (0.0-1.0), dropping the rest."""
+
+ def __init__(self, rate: float, rng: Callable[[], float] | None = None) -> None:
+ if not 0.0 <= rate <= 1.0:
+ raise ValueError(f"rate must be between 0 and 1, got {rate!r}")
+ self.rate = rate
+ self._rng = rng or random.random
+
+ def before_log(self, record: LogRecord) -> LogRecord | None:
+ return record if self._rng() < self.rate else None

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "logquill"
-version = "0.1.2"
+version = "0.1.3"
 description = "A structured, leveled logging framework with pluggable transports and a plugin pipeline."
 readme = "README.md"
 license = "MIT"

tests/test_context_plugin.py

@@ -0,0 +1,20 @@
+from logquill.context_plugin import ContextPlugin
+from logquill.logger import Logger
+
+
+def test_injects_fixed_context_into_meta() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(service="api", env="prod")])
+
+ record = logger.info("hello", user_id=42)
+
+ assert record is not None
+ assert record["meta"] == {"service": "api", "env": "prod", "user_id": 42}
+
+
+def test_call_site_meta_overrides_fixed_context() -> None:
+ logger = Logger("app.test", plugins=[ContextPlugin(env="prod")])
+
+ record = logger.info("hello", env="staging")
+
+ assert record is not None
+ assert record["meta"]["env"] == "staging"