Build Your First Module¶

This walkthrough builds a minimal package that exports a lazy API surface.

Step 1: Create package entrypoint¶

import os

from monkay import Monkay

monkay = Monkay(
    # Required for auto-hooking
    globals(),
    with_extensions=True,
    with_instance=True,
    settings_path=lambda: os.environ.get("SETTINGS_MODULE_IMPORT", "settings_path:Settings") or "",
    preloads=["tests.targets.module_full_preloaded1:load"],
    # Warning: settings names have a catch
    settings_preloads_name="preloads",
    settings_extensions_name="extensions",
    uncached_imports=["settings"],
    lazy_imports={
        "bar": "tests.targets.fn_module:bar",
        "settings": lambda: monkay.settings,
    },
    deprecated_lazy_imports={
        "deprecated": {
            "path": "tests.targets.fn_module:deprecated",
            "reason": "old.",
            "new_attribute": "super_new",
        }
    },
)

Step 2: Use your package from runtime code¶

yourpkg/main.py

from foo import monkay as foo_monkay


def get_application():
    # sys.path updates
    important_preloads = [...]
    foo_monkay.evaluate_preloads(important_preloads, ignore_import_errors=False)
    extra_preloads = [...]
    foo_monkay.evaluate_preloads(extra_preloads)
    foo_monkay.evaluate_settings()
    return ...


app = get_application()

Step 3: Validate behavior¶

Access a lazy export and confirm it resolves on first use.
Call evaluate_settings() during startup.
Ensure repeated calls are safe (onetime=True by default).

Step 4: Run checks¶

task check
task docs

Next¶

Continue with Wire settings and extensions.