Basic Runtime examples

These examples show the direct Python-to-Deno path. Start with an inline or file-based script, then add dependencies, a workspace, or an installed command when the project needs them.

File-based scripts

The simple example keeps the TypeScript module next to the Python package and runs it from a folder-backed runtime. The complete entrypoint is included from the shipped example:

from pathlib import Path
from typing import Final

from belgie import Runtime, Script

PACKAGE_DIR: Final[Path] = Path(__file__).resolve().parent
PROJECT_ROOT: Final[Path] = Path(__file__).resolve().parents[2]


async def greet(name: str) -> str:
    script = Script.from_file(PACKAGE_DIR / "greet.ts")
    async with Runtime.from_folder(PROJECT_ROOT) as runtime:
        result = await runtime(script)(name=name)
    return str(result["greeting"])


async def main() -> None:
    print(await greet("belgie"))  # noqa: T201


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

See examples/basic/simple for the complete project.

Inline dependencies

Inline modules can import npm, JSR, and URL modules directly:

import camelcase from "npm:camelcase@8.0.0";
import { join } from "https://deno.land/std@0.224.0/path/mod.ts";

export default function run(value: string) {
  return {
    camelcase: camelcase(value),
    join: join.name,
  };
}

Use this path for a small script whose dependencies do not need to be shared. For project-wide dependency versions, use an Environment.

Named environment dependencies

The jsr-deps example declares an alias and imports it by name. Its complete entrypoint is:

from typing import Final

from belgie import Environment, Runtime, Script

SOURCE: Final[str] = """
import { join } from "std_path";

export default function run() {
  return join.name;
}
"""


def resolve_join_export() -> str:
    with Environment({"std_path": "jsr:@std/path@^1"}) as env:
        env.install()
        with Runtime(env=env) as runtime:
            return str(runtime(Script(SOURCE))())


def main() -> None:
    print(resolve_join_export())  # noqa: T201


if __name__ == "__main__":
    main()

This makes dependency declarations and lockfile updates independent from script source.

Commands

The commands example installs Vite and invokes its binary. Its complete entrypoint is:

from asyncio import run as asyncio_run
from typing import Final

from belgie import Command, Environment, Runtime

VITE_VERSION: Final[str] = "6"
ROLLUP_VERSION: Final[str] = "4.62.2"


async def run_version_command() -> None:
    async with Environment(
        {
            "rollup": ROLLUP_VERSION,
            "vite": VITE_VERSION,
        },
    ) as env:
        await env.install()
        async with Runtime(env=env) as runtime:
            await runtime(Command("vite"))("--version")


def main() -> None:
    asyncio_run(run_version_command())


if __name__ == "__main__":
    main()

See Command for working directories, environment variables, and module mode.

Run the examples

cd examples/basic/simple
uv run main

cd ../inline-deps
uv run main

cd ../commands
uv run main