Skip to main content

rn-forge-commons

Documentation · Changelog · Source · All pykit packages

Shared, framework-agnostic utilities for Python programming.

Install

Require the package by version range:

[project]
dependencies = ["rn-forge-commons>=0.8,<0.9"]

Optional extras:

Extra Adds
json JSON-formatted log output (python-json-logger)
pydantic Strict pydantic models for configuration documents, with every failure named by dotted path
otel OpenTelemetry logging instrumentation
testing assertpy + pytest integration helpers
resilience Async circuit breakers and HTTP retries (purgatory, stamina, httpx)
structlog Structured logging over the existing stdlib handlers
templates The Jinja template engine, rn_forge.commons.text.templates (jinja2)
markdown Markdown structure, rn_forge.commons.text.markdown (markdown, markdown-it-py)
all Everything above

Console log output is Rich-formatted by default (a hard dependency) when stdout is a TTY.

What's inside

Modules are grouped by kind of mechanism. Public class names do not encode the grouping and are all re-exported from the package facade, so from rn_forge.commons import PathUtils works regardless of which submodule holds it.

Top level

  • config — Config: loads JSON/YAML config from a file or directory, deep-merges multiple sources, and resolves internal references.
  • exceptions — AppException: structured exception base class for the rn-forge-* family.
  • findings — Finding, Severity: the structured result shape every checker and doctor reports in, serialisable for --json.
  • testing — output_path fixture and assertpy integration, for use from conftest.py.

lang/ — Python objects themselves; no filesystem, no outside world.

  • collections — DictUtils, ListUtils: dot-path get/set, typed dot-path reads that treat a wrong-shaped value as absent (get_mapping, get_list, get_strings, get_str, get_bool), layered merge with provenance, flatten, structural comparison, sorting, filtering, grouping.
  • dataclasses — DataclassMixin: adds as_dict(), to_json(), to_yaml(), from_dict() to any @dataclass, reconstructing nested dataclasses and enum members on the way back. from_dict() is strict: a value whose type does not match its field is rejected as an AppException naming the offending field. LenientDataclassMixin: the same surface with type checking off — for a record whose input is known-ragged, and for the two annotations dacite cannot see through (a PEP 695 type alias, an unbound type variable), which the module docstring spells out. StrictDataclassMixin: type checking plus rejection of unknown keys at every nesting level, named by dotted path (repository.archtype) — for configuration documents.
  • models (pydantic extra) — StrictModel, parse_model, ModelValidationError: pydantic models that are strict, frozen and reject unknown keys, raising one AppException that names every failing key by its dotted path. Not on the facade, so import rn_forge.commons never loads pydantic.
  • reflection — ReflectUtils: fully-qualified name resolution, error-message formatting, and stack-frame variable inspection.
  • types — the recursive JsonValue alias.
  • utils — AppUtils, Base64: bool parsing, emptiness checks, dynamic imports, null-safe attribute access, string joining, unified diffs, and base64 encode/decode.

fs/ — everything that reads or writes a real file.

  • paths — PathUtils: atomic writes and replacements, no-clobber moves, empty-directory pruning, backups, temp dirs, repository-root discovery and the assert_within path-escape guard.
  • hashing — ContentHash: content and file digests, for detecting drift.
  • locks — DirectoryLock, atomic_symlink: cross-process serialization and atomic publication.
  • state — StateStore: a locked, atomically-written JSON key-to-entry store.
  • blocks — ManagedBlock: render, extract and remove a generator-owned fenced block inside a file somebody else owns (.gitignore, CLAUDE.md, mkdocs.yml), preserving every byte outside the markers.
  • documents — JsonUtils, YamlUtils, DocumentUtils, ConfigFormat: JSON/YAML/TOML (de)serialization and file I/O, plus comment-preserving round-trip editing of config documents.

generation/ — plan, diff and atomic apply of owned files (Artifact, plan, apply). Imported directly, never through the facade.

text/ — text formats, each module behind its own extra and imported directly (never through the facade).

  • markdown (markdown extra) — MarkdownUtils, MarkdownHeading, MarkdownTable: headings and MkDocs-compatible anchors, link and image targets, pipe tables with line positions, and text without fenced code.
  • templates (templates extra) — TemplateEngine, RenderError: strict Jinja rendering from a directory or a package, with autoescape, a process-wide TemplateEngine.cached constructor, and to_toml/to_yaml filters.

logging/

  • logging — AppLogger, LoggingConfig: idempotent logging setup via dictConfig, built on verboselogs with a custom TRACE level. Console records go to stderr, so a command's stdout carries only its result.
  • redaction — redact, RedactionPolicy, RedactFilter: secret redaction by key and by value, applied to every handler by default.
  • structlog (structlog extra) — StructLogger, redact_processor: structured logging over the same handlers.

runtime/ — the process and its surroundings.

  • environment — Environment: typed env-var access, plus the require/forbid fail-fast guards a process calls at startup.
  • console — AppConsole, OutputMode, console: a Rich output facade with RICH/PLAIN/ QUIET/JSON modes, semantic helpers, a one-call table builder and confirm/prompt/status interaction. Imports no Typer or Click, so a script, a worker or a Django management command uses it directly; rn-forge-cli drives its mode from --quiet/--json.
  • subprocess — Process: immutable dataclass that runs a subprocess and captures return code, stdout, and stderr.
  • tasks — Task, TaskPool: parallel task execution via a managed thread pool; TaskPool.map_settled maps a function over items and returns a Succeeded or Failed for each.
  • actor — ThreadActor: owns one resource on a dedicated thread and runs every call against it there, as a Future or an awaitable.
  • plugins — EntryPointLoader: failure-isolated entry-point plugin discovery.

integration/ — protocols for the systems an application talks to.

  • messaging, objects, secrets — MessageBus, ObjectStore, SecretStore and their in-memory implementations.
  • resilience (resilience extra) — async circuit breakers and a retrying HTTP client.

Import from the top-level package for the curated public API:

from rn_forge.commons import AppLogger, Config, DictUtils, JsonUtils

logger = AppLogger.initialize(root_logger_name="my-service")
cfg = Config("config")
logger.info("database.host={}", cfg.get("database.host"))

The developer-tooling packages

The command-line layer lives in rn-forge-cli and the file-owning tooling in rn-forge-tooling. Both depend on this package; neither is depended on by it, and there are deliberately no compatibility re-exports in either direction — that would reverse the dependency. uv run lint-imports proves it.

Concern Package
AppConsole, Typer app factory, standard options, exit codes, the [cli] surface rn-forge-cli
extract_archive, the install lifecycle, docs checkers rn-forge-tooling

Docs

Full API reference and guides are built with mkdocs:

uv run --group docs mkdocs serve   # or `mkdocs build`

Source lives in docs/, configured via mkdocs.yml.

Development

From the repo root or this directory:

uv run pytest packages/rn-forge-commons
uv run ruff check packages/rn-forge-commons
uv run pyright

Metadata

Release files for rn-forge-commons 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rn-forge-commons 0.9.0
File Size Uploaded Provenance Actions
rn_forge_commons-0.9.0.tar.gz 99.6 kB With provenance Details for rn_forge_commons-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rn-forge-commons 0.9.0
File Interpreter ABI Platform Actions
rn_forge_commons-0.9.0-py3-none-any.whl Python 3 none any Details for rn_forge_commons-0.9.0-py3-none-any.whl

Total release size: 218.4 kB

Release files / rn_forge_commons-0.9.0.tar.gz

Download URL rn_forge_commons-0.9.0.tar.gz
Size 99.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f867f7f607ea760ec1c80b4ebd59b42f0c69d1ce5611b87c10bd22d5dd9a32e9
BLAKE2b-256 checksum
How to use checksums
4782849a95eb72824bcc5319df491d8e29b9a2705301f906cdcc5c64be9dc4db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / rn_forge_commons-0.9.0-py3-none-any.whl

Download URL rn_forge_commons-0.9.0-py3-none-any.whl
Size 118.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31f69c9d57f2d860d497ca013c204d173b7364f4d2887489f25cc5d0ad433dbb
BLAKE2b-256 checksum
How to use checksums
ab031e29a36a2e11b6406968a0bc2524ec529fd3811ae8934df5eb2d92451fe6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for rn-forge-commons 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rn_forge_commons-0.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page