Skip to content

README.md

Latest commit

 

History

History
107 lines (77 loc) · 2.65 KB

README.md

File metadata and controls

107 lines (77 loc) · 2.65 KB

Monkay

Monkay is a production-focused module lifecycle toolkit for Python packages. It helps you ship lazy imports, settings loading, extension orchestration, and context-isolated state without fragile import-time side effects.

Why Monkay

Monkay is designed for libraries and applications that need to:

  • expose stable public imports while deferring expensive imports,
  • run controlled startup preloads and settings evaluation,
  • apply pluggable extensions with deterministic conflict behavior,
  • isolate mutable state per thread/task for safe tests and request scopes,
  • validate module export consistency during development.

Installation

pip install monkay

Runtime requirement: Python 3.10+.

60-Second Example

# yourpkg/__init__.py
from monkay import Monkay

monkay = Monkay(
    globals(),
    lazy_imports={
        "json_dumps": "json:dumps",
    },
)

__all__ = ["json_dumps", "monkay"]
# yourpkg/main.py
from yourpkg import json_dumps

payload = {"status": "ok"}
print(json_dumps(payload))

json_dumps is resolved lazily on first access and cached by default.

Core Capabilities

  • Monkay: lifecycle coordinator for imports, settings, instances, and extensions
  • load, load_any, absolutify_import: import/path helpers
  • Cage, TransparentCage: context-isolated mutable proxies
  • Lifespan, LifespanHook: ASGI lifespan utilities
  • find_missing, sorted_exports: export inspection and debugging helpers

Public API Stability

Monkay keeps top-level public imports stable via monkay.__all__:

  • Monkay
  • DeprecatedImport
  • PRE_ADD_LAZY_IMPORT_HOOK
  • ExtensionProtocol
  • load, load_any, absolutify_import
  • InGlobalsDict, UnsetError, get_value_from_settings
  • Cage, TransparentCage

Documentation

Full docs: monkay.dymmond.com

Recommended order:

  1. Getting Started
  2. Tutorials
  3. Concepts
  4. How-to Guides
  5. Reference

Development Quickstart

Monkay uses hatch, ruff, ty, pytest, and mkdocs/zensical.

pip install hatch
hatch run lint
hatch run check_types
hatch test
hatch run docs:build

If you use Task, Monkay ships both Taskfile.yml and Taskfile.yaml:

task check
task coverage
task docs
task docs:serve

Contributing

See Contributing for setup, quality gates, docs workflow, and pull request expectations.