Groovy is a Python-to-JavaScript transpiler, meaning that it converts Python functions to their JavaScript equivalents. It is used in the Gradio library, so that developers can write functions in Python and have them run as fast as client-side JavaScript ⚡. Instead of aiming for full coverage of Python features, groovy prioritizes clear error reporting for unsupported Python code, making it easier for developers to modify their functions accordingly.

🚀 Features

• Converts simple Python functions into JavaScript equivalents.
• Supports a subset of the Python standard library along with some Gradio-specific classes.
• Provides complete error reporting when a function can't be transpiled (either due to no equivalent in JavaScript or ambiguity).

📦 Installation

Install groovy via pip:

pip install groovy

🔧 Usage

from groovy import transpile

def sum_range(n: int):
    total = 0
    for i in range(n):
        total = total + i
    return total

js_code = transpile(sum_range)
print(js_code)

produces:

function sum_range(n) {
    let total = 0;
    for (let i of Array.from({length: n}, (_, i) => i)) {
        total = (total + i);
    }
    return total;

Note that the JavaScript function is not necessarily minimized or optimized (yet) but it should return exactly the same value when called with the same arguments. While the internal implementation of the transpiled JavaScript function may differ slightly from the Python version (e.g. Python tuples may get converted to JS arrays), groovy tries to guarantee that the return values will be identical for the same inputs.

If groovy encounters unsupported syntax, it will complain clearly (throw a TranspilationError with all of the issues along with line numbers and the code that caused the issue, making it easy for developers to fix their code.

def example_function(x, y):
    z = x + y
    if z > 10:
        print(z)
    else:
        print(0)

transpile(example_function)

raises:

TranspilerError: 2 issues found:

* Line 4: Unsupported function "print()"
>> print(z)
* Line 6: Unsupported function "print()"
>> print(0)

🤔 Ambiguity

groovy takes a conservative approach when encountering ambiguous types. Instead of making assumptions about types, it will raise a TranspilationError. For example, a simple sum function without type hints will fail:

def sum(a, b):
    return a + b

transpile(sum)  # Raises TranspilationError: Cannot determine types for parameters 'a' and 'b'

This is because + could mean different things in JavaScript depending on the types (string concatenation vs numeric addition vs. custom behavior for a custom class). Adding type hints (which is strongly recommended for all usage) resolves the ambiguity:

def sum(a: int, b: int):
    return a + b

transpile(sum)  # Works! Produces: function sum(a, b) { return (a + b); }

🔥 Supported Syntax

groovy supports the following Python syntax and built-in functions. Other functions will not be transpiled.

General

Python Syntax	JavaScript Equivalent
def function(x: int)	function function(x)
x + y, x - y, x * y, x / y	(x + y), (x - y), (x * y), (x / y)
x > y, x < y, x >= y, x <= y	(x > y), (x < y), (x >= y), (x <= y)
x == y, x != y	(x === y), (x !== y)
x in list, x not in list	list.includes(x), !list.includes(x)
x = value	let x = value
if condition: ... elif: ... else: ...	if (condition) { ... } else if { ... } else { ... }
for x in range(n)	for (let x of Array.from({length: n}, (_, i) => i))
for x in list	for (let x of list)
while condition	while (condition)
[x for x in list if condition]	list.filter(x => condition).map(x => x)
len(list)	list.length
len(dict)	Object.keys(dict).length
[1, 2, 3]	[1, 2, 3]
(1, 2, 3)	[1, 2, 3]
{"key": "value"}	{"key": "value"}
x and y, x or y	(x && y), `(x
None	null

Gradio-specific syntax

Python Syntax	JavaScript Equivalent
gr.Component(param=value)	{"param": "value", "__type__": "update"}

📜 License

groovy is open-source under the MIT License.

---

Contributions to increase coverage of the Python library that groovy can transpile are welcome! We welcome AI-generated PRs if the rationale is clear to follow, PRs are not too large in scope, and tests are included.