| Name | groovy JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A small Python library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks. |
| upload_time | 2025-02-26 23:02:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<a href="https://pypi.org/project/groovy/"><img alt="PyPI" src="https://img.shields.io/pypi/v/groovy"></a>
<img alt="Python version" src="https://img.shields.io/badge/python-3.10+-success">
<a href="https://github.com/abidlabs/groovy/actions/workflows/format.yml"><img alt="Format" src="https://github.com/abidlabs/groovy/actions/workflows/format.yml/badge.svg"></a>
<a href="https://github.com/abidlabs/groovy/actions/workflows/test.yml"><img alt="Test" src="https://github.com/abidlabs/groovy/actions/workflows/test.yml/badge.svg"></a>
</p>
<p align="center">
<img src="https://github.com/user-attachments/assets/49d40a48-3c73-4911-8033-250cfa7aafd4" width=400>
</p>
Groovy is a Python-to-JavaScript transpiler, meaning that it converts Python functions to their JavaScript equivalents. It is used in the [Gradio](https://gradio.app) 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:
```bash
pip install groovy
```
### 🔧 Usage
```python
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)
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.
```python
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:
```python
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:
```python
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 || y)` |
| `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](https://github.com/abidlabs/groovy/blob/main/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.
Raw data
{
"_id": null,
"home_page": null,
"name": "groovy",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Abubakar Abid <abubakar@hf.co>",
"download_url": "https://files.pythonhosted.org/packages/c7/0e/536ed8386c8c4749ee1e7481a96e96e66a05d1ed0dec67e690d30080108d/groovy-0.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://pypi.org/project/groovy/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/groovy\"></a>\n <img alt=\"Python version\" src=\"https://img.shields.io/badge/python-3.10+-success\">\n <a href=\"https://github.com/abidlabs/groovy/actions/workflows/format.yml\"><img alt=\"Format\" src=\"https://github.com/abidlabs/groovy/actions/workflows/format.yml/badge.svg\"></a>\n <a href=\"https://github.com/abidlabs/groovy/actions/workflows/test.yml\"><img alt=\"Test\" src=\"https://github.com/abidlabs/groovy/actions/workflows/test.yml/badge.svg\"></a>\n</p>\n\n\n<p align=\"center\">\n<img src=\"https://github.com/user-attachments/assets/49d40a48-3c73-4911-8033-250cfa7aafd4\" width=400>\n</p>\n\nGroovy is a Python-to-JavaScript transpiler, meaning that it converts Python functions to their JavaScript equivalents. It is used in the [Gradio](https://gradio.app) library, so that developers can write functions in Python and have them run as fast as client-side JavaScript \u26a1. 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.\n\n### \ud83d\ude80 Features\n- Converts simple Python functions into JavaScript equivalents.\n- Supports a subset of the Python standard library along with some Gradio-specific classes.\n- Provides **complete error reporting** when a function can't be transpiled (either due to no equivalent in JavaScript or ambiguity).\n\n### \ud83d\udce6 Installation\nInstall groovy via pip:\n```bash\npip install groovy\n```\n\n### \ud83d\udd27 Usage\n```python\nfrom groovy import transpile\n\ndef sum_range(n: int):\n total = 0\n for i in range(n):\n total = total + i\n return total\n\njs_code = transpile(sum)\nprint(js_code)\n```\nproduces:\n\n```\nfunction sum_range(n) {\n let total = 0;\n for (let i of Array.from({length: n}, (_, i) => i)) {\n total = (total + i);\n }\n return total;\n```\n\nNote 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.\n\nIf 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.\n\n\n```python\ndef example_function(x, y):\n z = x + y\n if z > 10:\n print(z)\n else:\n print(0)\n\ntranspile(example_function)\n```\n\nraises:\n\n```\nTranspilerError: 2 issues found:\n\n* Line 4: Unsupported function \"print()\"\n>> print(z)\n* Line 6: Unsupported function \"print()\"\n>> print(0)\n```\n\n### \ud83e\udd14 Ambiguity\ngroovy 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:\n\n```python\ndef sum(a, b):\n return a + b\n\ntranspile(sum) # Raises TranspilationError: Cannot determine types for parameters 'a' and 'b'\n```\n\nThis 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:\n\n```python\ndef sum(a: int, b: int):\n return a + b\n\ntranspile(sum) # Works! Produces: function sum(a, b) { return (a + b); }\n```\n\n### \ud83d\udd25 Supported Syntax\n\ngroovy supports the following Python syntax and built-in functions. Other functions will not be transpiled.\n\n**General**\n\n| Python Syntax | JavaScript Equivalent |\n|--------------|----------------------|\n| `def function(x: int)` | `function function(x)` |\n| `x + y`, `x - y`, `x * y`, `x / y` | `(x + y)`, `(x - y)`, `(x * y)`, `(x / y)` |\n| `x > y`, `x < y`, `x >= y`, `x <= y` | `(x > y)`, `(x < y)`, `(x >= y)`, `(x <= y)` |\n| `x == y`, `x != y` | `(x === y)`, `(x !== y)` |\n| `x in list`, `x not in list` | `list.includes(x)`, `!list.includes(x)` |\n| `x = value` | `let x = value` |\n| `if condition: ... elif: ... else: ...` | `if (condition) { ... } else if { ... } else { ... }` |\n| `for x in range(n)` | `for (let x of Array.from({length: n}, (_, i) => i))` |\n| `for x in list` | `for (let x of list)` |\n| `while condition` | `while (condition)` |\n| `[x for x in list if condition]` | `list.filter(x => condition).map(x => x)` |\n| `len(list)` | `list.length` |\n| `len(dict)` | `Object.keys(dict).length` |\n| `[1, 2, 3]` | `[1, 2, 3]` |\n| `(1, 2, 3)` | `[1, 2, 3]` |\n| `{\"key\": \"value\"}` | `{\"key\": \"value\"}` |\n| `x and y`, `x or y` | `(x && y)`, `(x || y)` |\n| `None` | `null` |\n\n\n**Gradio-specific syntax**\n\n| Python Syntax | JavaScript Equivalent |\n|--------------|----------------------|\n| `gr.Component(param=value)` | `{\"param\": \"value\", \"__type__\": \"update\"}` |\n\n\n### \ud83d\udcdc License\ngroovy is open-source under the [MIT License](https://github.com/abidlabs/groovy/blob/main/LICENSE).\n\n---\nContributions 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.\n",
"bugtrack_url": null,
"license": null,
"summary": "A small Python library created to help developers protect their applications from Server Side Request Forgery (SSRF) attacks.",
"version": "0.1.1",
"project_urls": {
"homepage": "https://github.com/gradio-app/groovy",
"repository": "https://github.com/gradio-app/groovy"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "12600b7e0904e52621b0d0a1a052aaf35526f66572a6377fb26ff51339c2fbd9",
"md5": "6c3b0ad59383ef687c8a8efa553cc428",
"sha256": "372787bddf166c7e93c9429226504c8753864ec57dfccec48f6b0c2317e99b74"
},
"downloads": -1,
"filename": "groovy-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c3b0ad59383ef687c8a8efa553cc428",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.9",
"size": 13848,
"upload_time": "2025-02-26T23:02:18",
"upload_time_iso_8601": "2025-02-26T23:02:18.674939Z",
"url": "https://files.pythonhosted.org/packages/12/60/0b7e0904e52621b0d0a1a052aaf35526f66572a6377fb26ff51339c2fbd9/groovy-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c70e536ed8386c8c4749ee1e7481a96e96e66a05d1ed0dec67e690d30080108d",
"md5": "4f68cd52d91d7224a40b576799857d3d",
"sha256": "1f537d4125f89b97b8657d787a410bcdf22ed3ab7c5c32dc4e25c3e88fe60956"
},
"downloads": -1,
"filename": "groovy-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4f68cd52d91d7224a40b576799857d3d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.9",
"size": 16884,
"upload_time": "2025-02-26T23:02:20",
"upload_time_iso_8601": "2025-02-26T23:02:20.469529Z",
"url": "https://files.pythonhosted.org/packages/c7/0e/536ed8386c8c4749ee1e7481a96e96e66a05d1ed0dec67e690d30080108d/groovy-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-26 23:02:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gradio-app",
"github_project": "groovy",
"github_not_found": true,
"lcname": "groovy"
}
