05_python_emitter

Python Emitter

Writing Python code

Purpose

The Python Emitter is a backend component used for tasks that involve data science, machine learning, or simple visualization. It turns your ARES scripts into clean, readable Python code. This backend is often chosen automatically by the system for tasks that are not computationally difficult or when you need to create graphs and charts.

Why it exists

Python is the best language for analyzing data and creating visual results. It has a massive collection of libraries that simplify complex tasks like neural networks or plotting data. The Python Emitter exists to give you access to this powerful ecosystem using the simple ARES logic. It allows you to build a complex data pipeline or a machine learning model without needing to worry about the specific details of Python's syntax or library management.

How it works

The system follows the specific rules of the Python language to build your final program.

  1. Import management. The system scans your code to see which external tools you need. It then adds the correct import statements at the top of the file, such as import numpy or import matplotlib.pyplot.
  2. Tracking indentation. Unlike C++, Python uses spaces to organize blocks of code. The system carefully tracks the "nesting level" of your logic and adds exactly 4 spaces for every level to ensure the code is valid.
  3. Translating symbols. Common programming symbols are changed into Python's word-based alternatives. For example, && is changed to and, and ! is changed to not.
  4. Simplified input. Reading a whole list of numbers is turned into a single, efficient Python line that reads the entire console input at once.
  5. Visualization hooks. If you use a "plot" command, the system identifies the target data and writes all the necessary code to display a chart using standard libraries.

Intuition

Think of the Python Emitter like a careful translator. You have a story written in ARES, and the translator turns it into Python. They don't just swap the words; they make sure the final story follows all the cultural rules of Python, like proper spacing and using phrases that Python speakers like. The result is a story that feels natural to a Python programmer but still tells exactly the logic you intended.

Implementation details

The logic for writing Python is located in src/codegen/py_emitter.ts.

  • Logic Blocks: Every "if" or "while" block is ended with a colon : to follow Python rules.
  • Empty Blocks: If you have a block of code with nothing in it, the system adds the pass keyword to prevent the Python interpreter from complaining.

Trace example

This is what happens when the system processes a function fn add(a, b) { return a + b }:

  1. Header: The system writes def add(a, b):.
  2. Indentation: It moves to the next line and adds 4 spaces.
  3. Body: It writes the return command and the math.
  4. Cleanup: It resets the space counter for the next section of your code.

Related entities

  • 04_cpp_emitter.md: The high-performance alternative to Python.
  • src/codegen/py_emitter.ts: The actual code that generates the Python representation.
ARES