Metadata-Version: 2.4
Name: monkay
Version: 0.5.2
Summary: The ultimate preload, settings, lazy import manager.
Project-URL: Documentation, https://github.com/devkral/monkay#readme
Project-URL: Issues, https://github.com/devkral/monkay/issues
Project-URL: Source, https://github.com/devkral/monkay
Author-email: alex <devkral@web.de>, Tiago Silva <tiago.arasilva@gmail.com>
License-File: LICENSE
Keywords: lazy-imports,monkey-patching,settings
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: docs
Requires-Dist: griffe-typingdoc<1.0,>=0.2.2; extra == 'docs'
Requires-Dist: mkdocs-meta-descriptions-plugin>=2.3.0; extra == 'docs'
Requires-Dist: mkdocstrings-python>=1.16.12; extra == 'docs'
Requires-Dist: mkdocstrings>=0.28.3; extra == 'docs'
Requires-Dist: zensical<0.1.0,>=0.0.23; extra == 'docs'
Provides-Extra: testing
Requires-Dist: anyio; extra == 'testing'
Requires-Dist: pydantic-settings; extra == 'testing'
Requires-Dist: pytest-timeout; extra == 'testing'
Requires-Dist: pytest<10.0.0,>=7.0.0; extra == 'testing'
Requires-Dist: ruff<5.0.0,>=0.3.0; extra == 'testing'
Requires-Dist: ty; extra == 'testing'
Description-Content-Type: text/markdown

# 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

```shell
pip install monkay
```

Runtime requirement: **Python 3.10+**.

## 60-Second Example

```python
# yourpkg/__init__.py
from monkay import Monkay

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

__all__ = ["json_dumps", "monkay"]
```

```python
# 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](https://monkay.dymmond.com)

Recommended order:

1. [Getting Started](https://monkay.dymmond.com/getting-started/)
2. [Tutorials](https://monkay.dymmond.com/tutorials/)
3. [Concepts](https://monkay.dymmond.com/concepts/)
4. [How-to Guides](https://monkay.dymmond.com/guides/)
5. [Reference](https://monkay.dymmond.com/reference/)

## Development Quickstart

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

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

If you use [Task](https://taskfile.dev), Monkay ships both `Taskfile.yml` and `Taskfile.yaml`:

```shell
task check
task coverage
task docs
task docs:serve
```

## Contributing

See [Contributing](https://monkay.dymmond.com/project/contributing/) for setup,
quality gates, docs workflow, and pull request expectations.
