PolyglotPiranha
PolyglotPiranha is a lightweight code transformation toolset for automating large scale changes. At Uber, it is mostly used to clean up stale feature flags.
We only support languages that are used at Uber. We likely won't be able to add new languages in this repo. There are a number of forks (see https://github.com/uber/piranha/forks for a full list) that may provide additional features.
Installation
To install Polyglot Piranha, you can use it as a Python library or as a command-line tool.
Python API
To install the Python API, run the following command:
pip install polyglot-piranha
Command-line Interface
To install the command-line interface, follow these steps:
- Install Rust
- Clone the repository:
git clone https://github.com/uber/piranha.git - Navigate to the cloned directory:
cd piranha - Build the project:
cargo build --release(orcargo build --release --no-default-featuresfor macOS) - The binary will be generated under
target/release
Example Usage
from polyglot_piranha import execute_piranha, PiranhaArguments, Rule, RuleGraph, OutgoingEdges
# Original code snippet
code = """
if (obj.isLocEnabled() || x > 0) {
// do something
} else {
// do something else!
}
"""
# Define the rule to replace the method call
r1 = Rule(
name="replace_method",
query="cs :[x].isLocEnabled()", # cs indicates we are using concrete syntax
replace_node="*",
replace="true",
is_seed_rule=True
)
# Define the edges for the rule graph.
# In this case, boolean_literal_cleanup is already defined for java [see src/cleanup_rules]
edge = OutgoingEdges("replace_method", to=["boolean_literal_cleanup"], scope="parent")
# Create Piranha arguments
piranha_arguments = PiranhaArguments(
code_snippet=code,
language="java",
rule_graph=RuleGraph(rules=[r1], edges=[edge])
)
# Execute Piranha and print the transformed code
piranha_summary = execute_piranha(piranha_arguments)
print(piranha_summary[0].content)
Documentation
For more examples and explanations of the toolset, please check our demos and extended POLYGLOT_README.md file.
Feature Flags
Feature flags are commonly used to enable gradual rollout or experiment with new features. In a few cases, even after the purpose of the flag is accomplished, the code pertaining to the feature flag is not removed. We refer to such flags as stale flags. The presence of code pertaining to stale flags can have the following drawbacks:
- Unnecessary code clutter increases the overall complexity w.r.t maintenance resulting in reduced developer productivity
- The flags can interfere with other experimental flags (e.g., due to nesting under a flag that is always false)
- Presence of unused code in the source as well as the binary
- Stale flags can also cause bugs
PolyglotPiranha is a tool that can automatically refactor code related to stale flags. At a higher level, the input to the tool is the name of the flag and the expected behavior, after specifying a list of APIs related to flags in a properties file. Piranha will use these inputs to automatically refactor the code according to the expected behavior.
PolyglotPiranha (as of May 2022) is a common refactoring tool to support multiple languages and feature flag APIs. For legacy language-specific implementations please check following tag.
A few additional links on Piranha:
- Research paper published at PLDI 2024 on PolyglotPiranha.
- A technical report detailing our experiences with using Piranha at Uber.
- A blogpost presenting more information on Piranha.
- 6 minute video overview of Piranha.
Support
If you have any questions on how to use Piranha or find any bugs, please open a GitHub issue.
Piranha Development
Piranha uses several grammar repositories with custom patches to support the transformations. While these patches are being upstreamed, there may be discrepancies between the grammars in this repository and the upstream grammars. Therefore, we have built a custom tree-sitter playground that can be used to test the grammars and queries for easier development:
https://uber.github.io/piranha/tree-sitter-playground/
License
Piranha is licensed under the Apache 2.0 license. See the LICENSE file for more information.
Note
This is not an official Uber product, and provided as is.
4 maintainers
Release files for polyglot-piranha 0.4.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| polyglot_piranha-0.4.8.tar.gz | 135.1 kB | Details |
Built distributions (wheels)
Total release size: 63.2 MB
Release files / polyglot_piranha-0.4.8.tar.gz
| Download URL | polyglot_piranha-0.4.8.tar.gz |
|---|---|
| Size | 135.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e233441774651ba7ad601e37c961f2bdd9b1b4a078500e6a5765c966a46dbf68
|
|
BLAKE2b-256 checksum How to use checksums |
5c067d2e2ed46e9e110bad463cc6275f85e35774ebfa86d17b656fa8f724e5c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | polyglot_piranha-0.4.8-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
9208ebca840a515b045c82794aa089f721c8bcfa19270c1e64611afa998b4fd1
|
|
BLAKE2b-256 checksum How to use checksums |
113772e9a77c3e8c738ec4dc4ffde221112e9bcd1c37f423ef8db7429cef22c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp312-cp312-manylinux_2_28_aarch64.whl
| Download URL | polyglot_piranha-0.4.8-cp312-cp312-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
304c0f39712d0f7af67a2a42c693364a0fdf4fda4bffe039183aba3291cd15a1
|
|
BLAKE2b-256 checksum How to use checksums |
af500d4d761bfe4ae252cfbf0f75eb54103609fcbca9b0f61bcc43e6b030cd0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp312-cp312-macosx_10_13_universal2.whl
| Download URL | polyglot_piranha-0.4.8-cp312-cp312-macosx_10_13_universal2.whl |
|---|---|
| Size | 7.7 MB |
| Tags | CPython 3.12 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
8783540389c42935fec3660b95e461d88cb8be3c79f2ab5d0bb00ebc208ad334
|
|
BLAKE2b-256 checksum How to use checksums |
657734990f53680a2df2e894eb9fadf909c678e9e0f7a7c9023c1b0ce6aa3db9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | polyglot_piranha-0.4.8-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
73fc96ba4439db51aa5940f858448bb62900c04a9422be45bf8213eb66824522
|
|
BLAKE2b-256 checksum How to use checksums |
3d238f48a1e65610ee693e6c479f05d6597f1af180926b1b3a15d6a8cdbbd70f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp311-cp311-manylinux_2_28_aarch64.whl
| Download URL | polyglot_piranha-0.4.8-cp311-cp311-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
4b73ad85e50ae7dd38507e5a9c7da41202db1ede1faaefd4a99356498f435837
|
|
BLAKE2b-256 checksum How to use checksums |
8c4f3d21f4e0e770760a143c399054c669e41de361c44e6f791e3e64419c13f2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp311-cp311-macosx_10_13_universal2.whl
| Download URL | polyglot_piranha-0.4.8-cp311-cp311-macosx_10_13_universal2.whl |
|---|---|
| Size | 7.7 MB |
| Tags | CPython 3.11 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
2f91cd5fedd422c8e07d49ed420cdd014464b8280c697a2cead3a0d75eddd537
|
|
BLAKE2b-256 checksum How to use checksums |
029c7ade4c7bf2ad1e3ab81df4592377b8c1a6b93b0b8622a9e2d2c2fa3b808a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | polyglot_piranha-0.4.8-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
7e566c0ffdcccae68b7c76f94e0c72027a1c822babc350d1f38ba6b7690394e2
|
|
BLAKE2b-256 checksum How to use checksums |
57bbdeff64a339d82d5fc3ed75da8bd9490fc091bb8d8b8c1963fceb844b6aab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp310-cp310-manylinux_2_28_aarch64.whl
| Download URL | polyglot_piranha-0.4.8-cp310-cp310-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
5b561d0717536f615a8713446c3d3a88b2496bf0e68f8493a7c9da92064c07b9
|
|
BLAKE2b-256 checksum How to use checksums |
9c630bdac04373cf018b0d66acceb62b96ceebb7c4c5a2c92525fab374f72b73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp310-cp310-macosx_10_13_universal2.whl
| Download URL | polyglot_piranha-0.4.8-cp310-cp310-macosx_10_13_universal2.whl |
|---|---|
| Size | 7.7 MB |
| Tags | CPython 3.10 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
f4a0f637eb3772a49db097bf37c7bb49166016eb752f8998e51c411017b2bfb8
|
|
BLAKE2b-256 checksum How to use checksums |
30de5ab34effd4e9ff0b01331e5185a0c2dca496b4186584ed559990477bea44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp39-cp39-manylinux_2_28_x86_64.whl
| Download URL | polyglot_piranha-0.4.8-cp39-cp39-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f147141ecff8c5422496c28b27667e92ba7b5645dc4c14555ee10780ef8ef27e
|
|
BLAKE2b-256 checksum How to use checksums |
c62b108c8d7a62a253d76f406d7dda7184e875c00636c32bbab0710d1daa24ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp39-cp39-manylinux_2_28_aarch64.whl
| Download URL | polyglot_piranha-0.4.8-cp39-cp39-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 4.0 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
ed62e36a262afd17d8193b4b4d33f427f9af4565f1a4cc4a140ebf37db95abdc
|
|
BLAKE2b-256 checksum How to use checksums |
0459f529f713894460e20b4a60dc25063455afaf786afc2263f0512a395888b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / polyglot_piranha-0.4.8-cp39-cp39-macosx_10_13_universal2.whl
| Download URL | polyglot_piranha-0.4.8-cp39-cp39-macosx_10_13_universal2.whl |
|---|---|
| Size | 7.7 MB |
| Tags | CPython 3.9 macOS 10.13+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
cd8ff6ed73da6524232f2153345f94be905d193cb36a59ffeaf6158743c1e5cb
|
|
BLAKE2b-256 checksum How to use checksums |
48be268f27c095d948dea4fb806562f125a3dc8b5b9588b768fbf593795b0410
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
