Skip to main content

Gandora

Gandora is the project for gan, a compiler for an Elixir-flavored language that produces readable Python. You write Elixir-style modules, pattern matching, pipelines, and hygienic defmacro macros; deployment is ordinary Python managed by uv with the standard .venv layout. Where Elixir reaches its host platform through :erlang calls, Gandora reaches Python through the $ sigil: $math.sqrt(2.0) compiles to import math plus math.sqrt(2.0) with no wrapper code.

defmodule App.Mathy do
  @moduledoc "Math helpers showing patterns and interop."

  def fact(0), do: 1
  def fact(n) when n > 0, do: n * fact(n - 1)

  def norm(xs) do
    xs
    |> sum_squares()
    |> then_sqrt()
  end

  defp sum_squares(xs) do
    $functools.reduce(fn acc, x -> acc + x * x end, xs, 0)
  end

  defp then_sqrt(x), do: $math.sqrt(x)
end

compiles to plain Python with multi-clause dispatch as a match statement, private functions as _-prefixed functions, and the interop as direct imports — no Gandora runtime is needed to execute the output.

The practical guide is the language manual (中文版). Design decisions are recorded as Gandora Enhancement Proposals in geps/:

  • GEP-0000 — the proposal process and translation policy (中文)
  • GEP-0001 — language identity, surface syntax, module naming, configuration, and the gan CLI (中文)
  • GEP-0002 — the hygienic macro system (中文)
  • GEP-0003 — Python interop (中文)
  • GEP-0004 — structs (frozen dataclasses) and module attributes (中文)
  • GEP-0005 — sigils (~w, ~s, ~r, and the raw embedded-Python ~python) (中文)
  • GEP-0006 — publishing packages as ordinary PyPI wheels, with macros shipped as source and zero runtime (中文)
  • GEP-0007 — Markdown @doc with locale variants, doctests compiled to native Python doctests, gan doc / gan test (中文)
  • GEP-0008 — definition-generating macros, use/__using__, and the defattr/@on_definition attribute system (中文)
  • GEP-0009 — the ~<lang> embedded-language family (~sql, ~markdown, ...) with EEx-style <%= %> splices (中文)
  • GEP-0010 — the standard library (std/): Enum, String, Map, List, Keyword as an ordinary PyPI package (中文)
  • GEP-0011 — multi-arity name groups and \\ default parameters (中文)
  • GEP-0012 — gandora-core: the compiler as a Python extension, quoted terms as native data — tooling is written in Gandora itself (中文)
  • GEP-0013 — the gan task runner (mix/cargo role), a Gandora program in tools/gan; the Rust binary is the stage-0 compiler ganc (中文)
  • GEP-0014 — try/rescue/after, tail-call-optimized recursion with explicit recur, for comprehensions, and the in operator (中文)
  • GEP-0015 — gan-lsp, the language server written in Gandora (tools/lsp), plus the VS Code client (editors/vscode) (中文)

English GEPs are normative; the synchronized Chinese translations are generated with scripts/translate-gep.py (a DeepSeek-backed translator configured by .env) and human-reviewed per GEP-0000-R030.

Requirements

  • Rust 1.85 or newer (to build the compiler)
  • Python 3.11 or newer
  • uv for Python development (optional but recommended)

Quick start

uv tool install gandora-tool     # gan — the task runner (brings ganc along)

gan init my-app                  # adds gandora-std to dependencies
cd my-app
gan run src/main.gan

(Or build from source: cargo build --release.)

gan init creates a uv-compatible project: pyproject.toml owns Python metadata and dependencies, gandora.jsonc owns the compiler configuration, and sources live under src/. It also wires the MCP surface for the agents that read a project-level file — .mcp.json (Claude Code), .codex/config.toml (Codex), opencode.json (opencode) — each declaring the same pathless command, uv run gan mcp, so the checked-in config works for everyone who clones (GEP-0028). gan run compiles into .gandora/cache/ and executes with .venv/bin/python, uv run python, or python3 — whichever is available first.

gan build              # the verdict + compile: diagnostics, advice,
                       # artifact verification; errors stop artifacts
gan expand src/x.gan   # show a module after macro expansion
gan compile src/x.gan --out build/

The v0 surface

Modules (defmodule, one per file, path-derived names), def/defp with multi-clause pattern dispatch and when guards, defmacro with quote/unquote/unquote_splicing and default hygiene (var! escapes), atoms, strings with #{} interpolation, lists, tuples, maps, keyword lists, ranges, the |> pipe, if/unless/case/cond/with, anonymous functions and captures (&Mod.fun/1, &(&1 + 1)), destructuring =, alias/import/require, the interop forms of GEP-0003 (:module calls, pyimport, postfix expr.name(...), @decorate), and the GEP-0004 data declarations: defstruct (a frozen @dataclass with %Mod{...} literals, patterns, and %Mod{s | f: v} updates) plus module attributes (@app $flask.Flask("__main__") compiles to a module-level binding, so @decorate @app.route("/") works like hand-written Python). GEP-0005 adds sigils: ~w(a b c) word lists, ~s(...) strings, ~r/\d+/ compiled Python regexes, and ~p(...) raw prompt prose; $python(sum(i*i for i in range(n))) splices one verbatim Python expression into the output (GEP-0009).

Anything outside the surface produces a diagnostic naming the construct (GEP-0001-R007) rather than a silent mistranslation. See examples/tour for a working multi-module program.

Publishing a package

A Gandora package is an ordinary PyPI wheel (GEP-0006):

gan init --package acme-text
cd acme-text            # write modules under src/acme_text/
gan build               # compiles into pkg/, emits marker + .gan sources
uv build && uv publish  # standard hatchling wheel, standard PyPI

A live example is gandora-text, installable straight from GitHub with uv add git+https://github.com/mjason/gandora-text. Consumers then use it from Gandora:

require AcmeText.Core     # macros: expanded at compile time from the
alias AcmeText.Core       #         .gan sources shipped in the wheel
Core.hello("world")       # functions: a plain `import acme_text.core`

The wheel introduces no runtime: its .py modules are self-contained, Python-only consumers can use them without knowing Gandora exists, and macro expansion leaves nothing behind at runtime. The compiler discovers installed packages by reading their gandora.toml markers from .venv — it never imports or executes package code.

Data mapping

Gandora Python
:atom "atom" (interned string)
nil / true / false None / True / False
list / tuple / map list / tuple / dict
keyword list [a: 1] [("a", 1)]
a..b range(a, b + 1)

Only false and nil are falsy (Elixir semantics); the generated code inserts explicit truthiness checks where needed.

Repository layout

  • crates/core — the compiler library; crates/gan — the stage-0 CLI ganc; crates/core-py — the gandora_core Python extension
  • tools/gan — the task runner; tools/lsp — the language server (both written in Gandora); editors/vscode — the VS Code client
  • docs/ — the language manual (+ docs/local/zh/ translations)
  • geps/ — Gandora Enhancement Proposals (+ geps/local/zh/ translations)
  • examples/tour — a runnable multi-module example
  • tests/e2e.rs — end-to-end tests driving the real binary
  • scripts/translate-gep.py — the GEP translation tool
cargo test             # unit + end-to-end tests

Status

v0.1.0: GEP-0001..0011 are implemented and tested — the language and CLI, hygienic macros with the full metaprogramming surface (definition-generating macros, use/__using__, defattr/ @on_definition), structs, sigils and embedded languages with <%= %> splices, wheel-based package publication, bilingual docs with native doctests, multi-arity functions with \\ defaults, and the standard library (std/, uv add gandora-std). Deferred: protocols, comprehensions, try/rescue, binaries, a formatter, an LSP.

Metadata

Release files for gandora-lang 0.20.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for gandora-lang 0.20.1
File Interpreter ABI Platform Actions
gandora_lang-0.20.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for gandora_lang-0.20.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Release files / gandora_lang-0.20.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL gandora_lang-0.20.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 755.7 kB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
e4f22ebf498cb05fccbdb34c52f3c768982212af73add64dbad643f177f2072a
BLAKE2b-256 checksum
How to use checksums
79e807cea6593b8311226a649c5836ee13bef29b42f6343466d0c68d232878c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 8, 2026.

Transparency log

Security for gandora-lang 0.20.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for gandora_lang-0.20.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.20.1 This release

1 release file Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page