Skip to main content
LTHN Documentation
Back to website
Components

Core Py

The Python binding for Core primitives — the fourth corner of the polyglot stack, on a pure-Go interpreter with a CPython escape hatch.

doc/components/py.md

Core Py is the Python binding for Core primitives, and the fourth corner of the polyglot stack alongside Go, TypeScript, and PHP. Python code imports core the way Go code imports core/go: the same primitive names and import paths, a different syntax surface. It runs on a pure-Go Python interpreter by default, with a managed CPython subprocess for code that needs C extensions. Status: bootstrap.

Quick start

The Go host module is dappco.re/go/py; the Python package is core. Run a script through the CorePy runtime, or open a stateful session for quick experiments.

corepy run app.py
corepy run app.py --tier2-fallback
corepy repl

In a script, import core and reach for the primitive you need:

import core

data = core.json.parse(core.fs.read("config.json"))
mean = core.math.mean([1, 2, 3, 4])

The two tiers

Core Py runs Python on two interpreters, with an explicit boundary between them.

  • Tier 1 — gpython. A pure-Go Python interpreter embedded in the host, with no dependency on a host CPython install. This is the default, and it backs the Core-native primitive bindings.
  • Tier 2 — CPython via uv. A managed CPython subprocess for C extensions and newer language features. It runs with a timeout, streams stdout and stderr, and returns structured exit results.

corepy run --tier2-fallback retries a script in Tier 2 when Tier 1 reports an unsupported import, so the two-tier boundary stays explicit rather than silent.

The module surface

The core.* modules mirror the Core primitives. The bindings cover, among others:

  • core.fs, core.path, core.process — files, paths, and process control
  • core.json, core.data, core.strings, core.array — data handling
  • core.options, core.config, core.registry, core.info — configuration and metadata
  • core.action, core.task, core.service, core.entitlement — the action and service contract
  • core.log, core.err, core.i18n, core.echo, core.medium — runtime support
  • core.math — the first maths surface, with core.math.kdtree, core.math.knn, and core.math.signal

Tier 1 also registers stdlib-shaped shadows for common imports — json, os, os.path, subprocess, logging, hashlib, base64, and socket — so scripts can use familiar import names while still calling Core-backed primitives. Initial coverage also exists for core.cache, core.crypto, core.dns, and core.scm, with importable stubs for core.api, core.ws, core.store, core.container, core.agent, and core.mcp.

Maths without NumPy

The core.math surface wraps Poindexter rather than NumPy. It provides mean, median, variance, stdev, sorting, scaling, and signal helpers, plus the k-d tree, k-nearest-neighbour, and signal import paths. Nothing in the maths binding pulls in a third-party numerical stack.