j2py-converter 0.3.0a1

Java-to-Python source translator with line-level structural correspondence for side-by-side review

j2py

j2py is a Java-to-Python source translator. It converts Java classes to Python that preserves line-level structural correspondence — same method order, same control flow, camelCase→snake_case naming — so reviewers can audit output against the original Java side by side. The goal is reviewable equivalence, not a fully idiomatic rewrite.

How it works

Java source
  → parse (tree-sitter-java)
  → analyze (symbols, dependency graph)
  → translate (deterministic rule layer, then optional LLM completion)
  → validate (syntax, lint, types)
  → Python output

The rule layer handles common language constructs deterministically (~70% of typical code). Where rules stop, Claude (optional) fills gaps using disk-cached prompts. Every file gets a confidence score based on rule-layer coverage and structured diagnostics for anything left unhandled.

Status

Alpha. The library is usable for experimentation, fixture-driven development, and batch translation of real Java projects, but construct coverage is still incomplete and output on large enterprise codebases will contain TODOs and review warnings.

Deterministic support today includes:

• tree-sitter Java parsing and symbol extraction
• class, nested class, local/anonymous class helpers, interface, enum, and record skeletons
• interface abstract methods, default methods, and static methods
• fields, constructors, methods, and overloads: chained constructor delegation, builder-style forwarding merged into default parameters, and type-dispatch overload groups via a vendored @overloaded runtime dispatcher (ADR 0009)
• common expressions: literals, identifiers, field access, arrays, class literals, assignments, updates, ternaries, null checks, collection calls, string concat, and typed get(...) lowering for lists, maps, and common API receivers
• stream pipelines: map, filter, flatMap, distinct, sorted, collectors such as toList, toSet, joining, groupingBy/mapping, toMap, and block lambdas
• control flow: if/else, enhanced and classic for, while, do while, safe switch forms, try/catch/finally, throw, break, and continue
• configured import emission, naming policy, type maps, exception maps, and comment flags
• dependency-ordered directory translation
• structured diagnostics, confidence scoring, validation, post-LLM structural verification, and optional Anthropic completion
• side-by-side Java/Python review via j2py compare

Known gaps include:

• overload groups whose erased Python signatures collide (e.g. int vs long) and static-method overload groups that still fall back to manual-dispatch TODOs
• enum constant class bodies and complex enum static initialization
• annotation semantics beyond syntactic metadata shells
• runtime/framework behavior (dependency injection, persistence mappings, container lifecycle) — j2py translates source structure, not application frameworks

Quick start

Install the alpha from PyPI:

pip install --pre j2py-converter
j2py --help

The PyPI distribution is j2py-converter; the import package and CLI command are j2py. (The bare j2py name on PyPI is owned by an unrelated project.)

Local development:

uv sync --locked
make check

Translate a file without LLM completion:

uv run j2py translate tests/fixtures/java/HelloWorld.java --no-llm --no-validate --dry-run

Translate a directory in dependency order:

uv run j2py translate path/to/java/root --output translated_py --no-llm

Side-by-side review in VS Code:

uv run j2py compare tests/fixtures/java/HelloWorld.java --no-llm

Print compare paths without opening an editor:

uv run j2py compare tests/fixtures/java/HelloWorld.java --no-open --no-llm

LLM completion (requires ANTHROPIC_API_KEY):

ANTHROPIC_API_KEY=... uv run j2py translate SomeClass.java

Quality gates

make check         # ruff + mypy strict + pytest (excludes behavior, live_llm)
make test-behavior # Java/Python stdout/stderr/exit-code equivalence (requires JDK)
make test-targets  # future xfail roadmap targets (empty while all targets graduated)
make release-check # alpha release gate: check + targets + behavior + dist check

Benchmark corpus

Translation quality is measured against an external Spring Framework checkout plus a curated set of small Java construct fixtures under tests/fixtures/corpus/. Spring is used as a realistic, open-source stress test — not as a product scope or target runtime.

make corpus-spring-dense-check  # preferred: density sample + construct fixtures vs baseline
make corpus-spring-dense      # run without baseline comparison
make corpus-spring-broad      # larger spring-context sample + constructs
make corpus-spring            # historical lexical Spring-only baseline

Baseline: tests/fixtures/corpus/spring-dense-baseline.json. See docs/CORPUS_SCOREBOARD.md and docs/TRANSLATION_TARGETS.md.

On-demand live LLM evaluation (excluded from make check):

make test-llm-e2e
# or: ANTHROPIC_API_KEY=... uv run pytest -m live_llm tests/llm/test_e2e_llm.py -v -s

Adding translation rules

1. Add or update a Java/Python fixture pair under tests/fixtures/.
2. Implement the smallest deterministic rule in j2py/translate/.
3. Graduate the behavior into normal tests once it passes.
4. Run make check and make corpus-spring-dense-check.
5. Update the dense corpus baseline only when the comparison shows no regressions.

Material translation policy changes should get an ADR under docs/decisions/.

Alpha release notes

j2py-converter is published as an alpha package. Expect incomplete construct coverage, diagnostics for unsupported regions, and manual review on production-scale codebases. See docs/RELEASING.md for the release checklist.

License

MIT. See LICENSE.