Directories and bootstrap caching

Use the path registry so that services do not depend on the process working directory. Directory provides named methods for that same registry. Compilation stores bootstrap metadata: it does not compile Python or replace deployment management. compile(...) returns None; call it in a separate statement before create().

Examples

Use the application’s configured directories

This handler fragment receives the existing application through dependency injection. It returns the configured views directory rather than constructing a second application or relying on the working directory.

from pathlib import Path
from orionis.foundation.contracts.application import IApplication
from orionis.foundation.directory import Directory

async def views_directory(app: IApplication) -> Path:
    directory = Directory(app)
    return directory.resourcesViews()

The default result is <project>/resources/views. You can also use app.path("resources_views") directly. All named paths are absolute after application creation; unknown keys return None.

Path key	Default directory	Application code
app_http_controllers	app/http/controllers	Request handlers.
app_models	app/models	ORM models.
app_providers	app/providers	Service registrations.
resources_views	resources/views	Jinja templates.
database_migrations	database/migrations	Schema changes.
storage_logs	storage/logs	Log files.
tests	tests	Application tests.

Configure compiled bootstrap state

import base64
from pathlib import Path
from tempfile import TemporaryDirectory
from orionis import Application
from orionis.environment import Env


class CachedApplication(Application):
    pass


key = "base64:" + base64.b64encode(b"c" * 32).decode()
Env.set("APP_KEY", key, only_os=True)
try:
    with TemporaryDirectory() as directory:
        root = Path(directory)
        (root / "config").mkdir()
        (root / ".env").touch()
        app = CachedApplication(root)
        app.compile("bootstrap/cache", ["config", ".env"])
        app.withConfigApp(key=key)
        app.create()
        assert app.compiled
        assert app.compiledPath == (root / "bootstrap/cache").resolve()
        assert (root / "config").resolve() in app.compiledInvalidationPathsDirs
        assert (root / ".env").resolve() in app.compiledInvalidationPathsFiles
        print("compiled cache configured")
finally:
    Env.unset("APP_KEY", only_os=True)

Refresh bootstrap caches after a change

The skeleton configures app.compile(...) in bootstrap/app.py before create(). Its monitored files and directories determine automatic invalidation. When changing bootstrap registrations or a path not included in that list, clear the previous artifacts from the project root, then restart running processes:

uv run python -B reactor optimize:clear

optimize:clear removes compiled configuration, command and route cache files, Python bytecode, and project build/dist artifacts. Review those effects when the application stores deployment assets there. It is distinct from deleting cached business values. The next process reconstructs bootstrap metadata as needed.

reactor optimize validates Python source syntax in memory; it does not prewarm the bootstrap cache or execute your application tests. A valid compiled-cache hit reuses earlier registrations, so edits to with... calls do not take effect until invalidation.

Reference and next steps

directory.py · core_paths.py · application.py

Return to the module index.