Python API

jgo provides a Python API at two levels: a simple high-level API for common tasks, and a layered API for fine-grained control.

High-level API

The jgo module exports three main functions:

`jgo.run()`

Run a Java application from a Maven endpoint.

import jgo

result = jgo.run(
    "org.python:jython-standalone:2.7.3",
    app_args=["script.py"],
    jvm_args=["-Xmx2G"],
)
print(result.returncode)

Parameters:

Parameter	Type	Description
`endpoint`	`str`	Maven endpoint (e.g., `"org.python:jython-standalone:2.7.3"`)
`app_args`	`list[str]`	Arguments passed to the Java application
`jvm_args`	`list[str]`	JVM arguments (e.g., `["-Xmx2G"]`)
`main_class`	`str`	Main class to run (auto-detected if omitted)
`update`	`bool`	Force update of cached environment
`verbose`	`bool`	Enable verbose output
`cache_dir`	`Path`	Override cache directory
`repositories`	`dict[str, str]`	Additional Maven repositories (`name` -> `URL`)
`java_version`	`int`	Force specific Java version
`java_vendor`	`str`	Prefer specific Java vendor
`java_source`	`str`	`"auto"` (download if needed) or `"system"` (use installed Java)

Returns: subprocess.CompletedProcess

`jgo.build()`

Build an environment without running it. Useful for getting the classpath or inspecting resolved dependencies.

import jgo

env = jgo.build("org.python:jython-standalone:2.7.3")
print(env.classpath)    # List of Path objects
print(env.main_class)   # Detected main class
print(env.path)         # Environment directory

Parameters:

Parameter	Type	Description
`endpoint`	`str`	Maven endpoint
`update`	`bool`	Force update of cached environment
`cache_dir`	`Path`	Override cache directory
`repositories`	`dict[str, str]`	Additional Maven repositories

Returns: Environment

`jgo.resolve()`

Resolve dependencies to a list of Maven components without materializing JARs.

import jgo

components = jgo.resolve("org.python:jython-standalone:2.7.3")
for comp in components:
    print(f"{comp.groupId}:{comp.artifactId}:{comp.version}")

Parameters:

Parameter	Type	Description
`endpoint`	`str`	Maven endpoint
`repositories`	`dict[str, str]`	Additional Maven repositories

Returns: list[Artifact]

Layered API

For fine-grained control, use the three-layer architecture directly. Each layer is independently useful.

Layer 1: Maven resolution (`jgo.maven`)

Resolve Maven dependencies using pure Python – no Maven installation required.

from jgo.maven import MavenContext, PythonResolver

# Configure Maven access
maven = MavenContext(
    resolver=PythonResolver(),
    remote_repos={
        "central": "https://repo.maven.apache.org/maven2",
        "scijava": "https://maven.scijava.org/content/groups/public",
    },
)

# Access a project
project = maven.project("org.python", "jython-standalone")
component = project.at_version("2.7.3")

# Get the dependency model
model = component.model()
deps, root = model.dependencies()

for dep in deps:
    print(f"{dep.groupId}:{dep.artifactId}:{dep.version} ({dep.scope})")

Key classes:

MavenContext: Maven configuration: repository locations, resolver strategy, remote repositories.
PythonResolver: Pure Python resolver. Parses POM files directly, handles transitive dependencies, property interpolation, dependency management (BOMs), exclusions, and scopes.
MvnResolver: Shells out to the system mvn command. Use as a fallback for edge cases.
Project: A Maven project identified by groupId:artifactId.
Component: A project at a specific version (groupId:artifactId:version).
Dependency: An artifact with scope, optional flag, and exclusions.

Layer 2: Environment materialization (`jgo.env`)

Materialize Maven dependencies into a directory of JARs.

from jgo.maven import MavenContext
from jgo.env import EnvironmentBuilder, LinkStrategy

maven = MavenContext()
builder = EnvironmentBuilder(
    context=maven,
    link_strategy=LinkStrategy.HARD,
)

env = builder.from_endpoint("org.python:jython-standalone:2.7.3")
print(env.path)         # Environment directory
print(env.classpath)    # List of JAR paths
print(env.main_class)   # Detected main class

Key classes:

EnvironmentBuilder

Builds environments from endpoint strings or jgo.toml specs.

from_endpoint(endpoint, update=False, main_class=None) – build from a Maven coordinate string.
from_spec(spec) – build from an EnvironmentSpec (parsed jgo.toml).

Environment

A materialized directory of JARs, analogous to a Python virtualenv.

EnvironmentSpec

Parsed jgo.toml file.

EnvironmentSpec.load("jgo.toml") – load from file.

LinkStrategy

How JARs are placed in the environment directory.

HARD – hard links (zero disk overhead, default on Unix).
SOFT – symbolic links.
COPY – file copies.
AUTO – try hard, then soft, then copy.

Layer 3: Execution (`jgo.exec`)

Launch Java programs with configured JVM settings.

from jgo.exec import JavaRunner, JVMConfig, JavaSource

jvm_config = JVMConfig(
    max_heap="4G",
    gc_options=["-XX:+UseG1GC"],
    system_properties={"foo": "bar"},
)

runner = JavaRunner(
    jvm_config=jvm_config,
    java_source=JavaSource.AUTO,  # Download Java if needed
    java_version=17,
)

result = runner.run(
    environment=env,
    main_class="org.example.Main",
    app_args=["--help"],
)

Key classes:

JavaRunner

Executes Java programs from an Environment.

JVMConfig

JVM settings: heap sizes, GC options, system properties.

JavaSource

How to find Java.

AUTO – detect version from bytecode, download if needed.
SYSTEM – use Java from PATH or JAVA_HOME.

Combining layers

A complete example using all three layers:

from pathlib import Path
from jgo.maven import MavenContext, PythonResolver
from jgo.env import EnvironmentBuilder, EnvironmentSpec, LinkStrategy
from jgo.exec import JavaRunner, JVMConfig, JavaSource

# Layer 1: Configure Maven
maven = MavenContext(
    resolver=PythonResolver(),
    remote_repos={
        "central": "https://repo.maven.apache.org/maven2",
        "scijava": "https://maven.scijava.org/content/groups/public",
    },
)

# Layer 2: Build environment from jgo.toml
spec = EnvironmentSpec.load("jgo.toml")
builder = EnvironmentBuilder(
    context=maven,
    link_strategy=LinkStrategy.HARD,
    cache_dir=Path(".jgo"),
)
environment = builder.from_spec(spec)

# Layer 3: Run with custom JVM settings
runner = JavaRunner(
    jvm_config=JVMConfig(max_heap="8G"),
    java_source=JavaSource.AUTO,
    java_version=17,
)
result = runner.run(
    environment=environment,
    main_class=spec.get_main_class("default"),
    app_args=["--config", "prod.yml"],
)

Backward compatibility

jgo 1.x APIs still work but emit deprecation warnings:

Old API	New API
`jgo.main(argv)`	`jgo.run(endpoint, ...)`
`jgo.main_from_endpoint(ep, ...)`	`jgo.run(endpoint, ...)`
`jgo.resolve_dependencies(ep, ...)`	`jgo.resolve(endpoint, ...)`

These deprecated functions will be removed in jgo 3.0. See Migrating from jgo 1.x for details.

Python API

High-level API

jgo.run()

jgo.build()

jgo.resolve()

Layered API

Layer 1: Maven resolution (jgo.maven)

Layer 2: Environment materialization (jgo.env)

Layer 3: Execution (jgo.exec)

Combining layers

Backward compatibility

`jgo.run()`

`jgo.build()`

`jgo.resolve()`

Layer 1: Maven resolution (`jgo.maven`)

Layer 2: Environment materialization (`jgo.env`)

Layer 3: Execution (`jgo.exec`)