arafura 0.1.0

A transpiler that converts Python syntax with C semantics into C code

Arafura - C as Python Transpiler

A transpiler that converts Python syntax with C semantics into C code.

Overview

Arafura allows you to write C programs using Python syntax. The code is syntactically valid Python (passes ast.parse) but has C semantics. The transpiler reads the Python AST and emits C code.

Features

• Valid Python syntax: All source files are valid Python that can be parsed
• C semantics: Primitive types, manual memory management, pointers, etc.
• Local AST translation: No type inference, purely syntactic transformation
• Full C feature support: Structs, unions, enums, macros, preprocessor directives, goto/labels

Installation

# Install in development mode
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

Usage

# Print C code to stdout
arafura input.py

# Write to output file
arafura input.py -o output.c

# Check syntax without generating output
arafura input.py --check

Example

Input (example.py):

from stdio import *

class Node:
    data: int
    next: -Node

def create_node(value: int) -> -Node:
    node: -Node = malloc(sizeof(Node))
    if node == None:
        return None
    node._.data = value
    node._.next = None
    return node

def main() -> int:
    head: -Node = create_node(42)
    printf("%d\n", head._.data)
    return 0

Output:

#include <stdio.h>

struct Node {
    int data;
    struct Node *next;
};

struct Node *create_node(int value) {
    struct Node *node = malloc(sizeof(struct Node));
    if (node == NULL) {
        return NULL;
    }
    node->data = value;
    node->next = NULL;
    return node;
}

int main(void) {
    struct Node *head = create_node(42);
    printf("%d\n", head->data);
    return 0;
}

Language Reference

Types

• Basic types: int, char, float, double, long, short, void
• Pointers: -int for int*, --int for int**
• Arrays: int[10] for int[10]
• Pointer-to-array: +int[10] for int (*)[10]
• Qualifiers: const[int], volatile[int], unsigned[int]
• Storage class: static[int], extern[int]

Special _ Forms

The underscore is reserved for special operations:

• Address-of: _.x → &x
• Dereference: ptr._ → *ptr
• Pointer member: ptr._.field → ptr->field
• Increment: i ** _ → i++, _ ** i → ++i
• Decrement: i // _ → i--, _ // i → --i
• Compound literals: _(x=1, y=2) → designated initializer

Composite Types

# Struct
class Point:
    x: int
    y: int

# Union
class Data(Union):
    i: int
    f: float

# Enum
class Color(Enum):
    RED = 0
    GREEN = 1
    BLUE = 2

Control Flow

# Regular if/elif/else
if x > 0:
    pass
elif x < 0:
    pass
else:
    pass

# While loop
while x < 10:
    x += 1

# C-style for loop
for i in int(i := 0)(i < 10)(i ** _):
    printf("%d\n", i)

# Do-while loop
while ():
    x ** _
    if x < 10:
        continue

# Goto and labels
LOOP: label
raise LOOP  # goto LOOP

Functions and Macros

# Function (all params and return annotated)
def add(a: int, b: int) -> int:
    return a + b

# Macro (no annotations)
def MAX(a, b):
    a if a > b else b

# Constant macro
PI: macro = 3.14159

Preprocessor

# Includes
import stdio              # #include "stdio.h"
from stdio import *       # #include <stdio.h>

# Conditional compilation
if [DEBUG]:               # #ifdef DEBUG
    printf("debug\n")

Other Features

• Casts: [int](3.14) → (int)3.14
• sizeof: sizeof(int) → sizeof(int)
• NULL: None → NULL
• Ternary: a if x > 0 else b → (x > 0 ? a : b)
• Walrus operator: (x := 5) → (x = 5)

Implementation

The transpiler is implemented in Python using the ast module. It:

1. Parses the input Python code into an AST
2. Performs a first pass to collect type names (structs, unions, enums)
3. Walks the AST and emits C code based on local patterns

No type inference is performed - all types must be explicitly annotated.

Project Structure

arafura/
├── src/
│   └── arafura/
│       ├── __init__.py       # Package exports
│       ├── transpiler.py     # Main transpiler implementation
│       └── cli.py            # Command-line interface
├── tests/
│   ├── fixtures/             # Test input files (.py)
│   ├── golden_outputs/       # Expected output files (.c)
│   ├── conftest.py          # Pytest configuration
│   ├── test_golden_master.py # Golden master tests
│   └── test_transpiler.py   # Unit tests
├── pyproject.toml           # Project metadata and dependencies
└── README.md

Testing

Run all tests:

# Install dev dependencies first
pip install -e ".[dev]"

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run only golden master tests
pytest tests/test_golden_master.py

# Run only unit tests
pytest tests/test_transpiler.py

Golden Master Tests

The project uses golden master testing to ensure transpiler output stability. Golden outputs are stored in tests/golden_outputs/ and are compared against current transpiler output.

To regenerate golden outputs after intentional changes:

python src/arafura/transpiler.py tests/fixtures/example.py > tests/golden_outputs/example.c
python src/arafura/transpiler.py tests/fixtures/features.py > tests/golden_outputs/features.c
python src/arafura/transpiler.py tests/fixtures/typedef.py > tests/golden_outputs/typedef.c

Design Philosophy

• Python syntax, C semantics: Write code that looks like Python but behaves like C
• No magic: Every construct has a clear, predictable mapping to C
• Local transformation: No global analysis or type inference needed
• Explicit over implicit: All types, casts, and operations must be explicit

Limitations

• No Python runtime features (no garbage collection, no dynamic typing, etc.)
• Requires explicit type annotations
• Some C features may require verbose syntax
• Error messages reference Python AST, not C concepts

License

See DESIGN.md for the complete language specification.