# Parslet: Your Pocket-Sized Workflow Assistant
**A tool for running automated to-do lists (workflows) on your Python projects. It's built to work anywhere, especially on your android phone.**
### What is Parslet?
Parslet is a tiny workflow engine built in Python. That means it's a tool that helps you automate tasks in a specific order, especially on phones and devices that can’t run heavy-duty software. Think of it like a smart to-do list for your computer or phone, but instead of reminding you to do things, **it actually does them for you in the right order, automatically.**
Imagine this real-world example:
You run a small juice business with your best friend. Every morning you:
1. Wash the fruits
2. Peel them
3. Blend them
4. Pour into bottles
5. Label and store
Now imagine you could automate this entire process using a small robot. You just tell it the steps once, and it does them every morning, in order. You get to spend quality time with your best friend.
**That’s what Parslet does, but for software tasks.**
---
### What Kinds of Tasks Can It Handle?
In a real-world tech setting, you could use Parslet to:
1. Run a script to **collect data** from a website.
2. Then, **clean up** that messy data.
3. Then, **save** the clean data to a file.
4. Then, **back up** that file to a server.
5. Finally, **send you an email** confirming the job is done.
All of this, in the right order, without you needing to supervise it.
---
### Why is Parslet Special?
Most tools like this are built for powerful servers in a data center. Parslet is different. It’s designed from the ground up to:
- **Be Super Lightweight:** It works on a Raspberry Pi or even an Android phone.
- **Run in Termux:** It’s built and tested to work perfectly inside [Termux](https://termux.dev/en/), the command-line tool for Android.
- **Work Offline:** No internet? No problem. Your workflows will still run.
- **Empower Everyone:** It’s for students, creators, and developers who might not have a laptop but have a brilliant idea.
- **Battery-smart scheduling:** Adapts on Android, Raspberry Pi, and Linux laptops to stretch runtime.
---
### How Does It Work?
It uses something called a **DAG** (Directed Acyclic Graph), which is just a technical way of saying:
> “Step B only runs after Step A is done.”
You define these steps (we call them **Tasks**) in a simple Python file. Parslet reads your file, understands the order, and handles the rest. It manages failures and runs everything as efficiently as possible.
---
## Get Started
Ready to try it? You can be up and running in less than a minute.
1. **Install It:**
The easiest way to install Parslet is directly from PyPI.
```bash
pip install parslet
```
2. **For Developers (or to get the latest changes):**
If you want to contribute or get the very latest code, you can install it from the source.
```bash
git clone https://github.com/Kanegraffiti/Parslet.git
cd Parslet
pip install -e .
```
3. **Create Your First Workflow**
Create a new file called `my_first_workflow.py` and paste this in. This is your recipe, telling Parslet what to do.
```python
from parslet import parslet_task, ParsletFuture
from typing import List
# This is a "task." It's just a normal Python function
# with a special @parslet_task note for Parslet.
@parslet_task
def say_hello(name: str) -> str:
print(f"Task 1: Saying hello to {name}")
return f"Hello, {name}!"
# Here's a second task.
@parslet_task
def make_it_loud(text: str) -> str:
print("Task 2: Making the text loud!")
return f"{text.upper()}!"
# This is the main "recipe" function.
# Parslet looks for this to know how your tasks connect.
def main() -> List[ParsletFuture]:
# First, we tell Parslet to run the say_hello task.
# It doesn't run yet! It just gives us an "IOU" for the result.
greeting_iou = say_hello("Parslet")
# Next, we give the "IOU" from the first task to the second task.
# This tells Parslet: "Wait for task 1 to finish before starting task 2."
loud_greeting_iou = make_it_loud(greeting_iou)
# We return the very last IOU. This tells Parslet, "We're done when this is done."
return [loud_greeting_iou]
```
4. **Run It**
Now for the fun part. Tell Parslet to run your new workflow.
```bash
parslet run my_first_workflow.py
```
You'll see the `print` statements from your tasks as they run, in the correct order 🎉
You can also reference a workflow by module path and tweak execution:
```bash
parslet run my_package.workflow:main --max-workers 4 --json-logs --export-stats stats.json
```
---
## What Else Can It Do?
Parslet is small, but it's packed with neat features for real-world use.
- **Works Offline:** Your automated workflows run even without an internet connection. See the [examples](docs/examples.md).
- **Saves Battery:** Use the special `--battery-mode` to tell Parslet to take it easy and conserve power. Read about [battery mode](docs/source/battery_mode.rst).
- **Smart About Resources:** It automatically checks your device's CPU and memory to run smoothly without crashing. The [AdaptivePolicy](docs/policy.md) adjusts workers on the fly.
- **DEFCON:** A multi-layered defense system in Parslet that proactively blocks zero-day exploits and malicious DAG behavior using offline rules. Learn more in the [security notes](docs/technical-overview.md).
- **Plays Well with Others:** If you ever move to a big server, Parslet has tools to convert your recipes to run on powerful systems like Parsl or Dask. See [compatibility](docs/compatibility.md).
- **Made for Termux:** We use it and test it on Android phones, so you know it'll work. Check the [install guide](docs/install.md).
- **Concierge Mode & Context Scenes:** `parslet run --concierge` gives you a luxury pre-flight briefing, live context audit, and a polished post-run ledger. Combine it with `@parslet_task(contexts=[...])` to ensure tasks only run when the right battery, network, or time-of-day scene is active.
Want to see more? Check out the `use_cases/` and `examples/` folders for more advanced recipes!
---
## Visualizing Your Workflows
Parslet can generate a picture of your workflow (a "DAG") to help you see how your tasks are connected. This is great for debugging and documentation.
To use this feature, you need to have **Graphviz** installed on your system.
---
## Concierge Mode & Context Scenes
Parslet 0.6.1 introduces **Concierge Mode**, a premium orchestration experience that makes your workflow feel like it shipped with its own operations team.
- **Concierge Briefing:** Run `parslet run my_flow.py --concierge` to get a handcrafted pre-flight report. It shows which context detectors are live (battery, network, VPN, time-of-day) and which tasks are gated by those contexts.
- **Context Scenes:** Declare contextual requirements directly on tasks:
```python
@parslet_task(contexts=["network.online", "battery>=60"], name="sync_to_vault")
def sync_to_vault(payload: dict) -> None:
upload(payload)
```
Parslet will defer the task with a `DEFERRED` status if the context isn't satisfied, protecting your workflow just like the best Tasker rule sets—only with readable Python and offline detectors.
- **Manual Overrides:** Activate ad-hoc scenes with `parslet run my_flow.py --context evening --context wifi`. You can also set a `PARSLET_CONTEXTS="evening,wifi"` environment variable or programmatically enable custom detectors using `ContextOracle`.
- **Concierge Runbook:** Need a paper trail? Add `--concierge-runbook runbook.json` and Parslet will record the complete itinerary, task metadata, and execution timings in a JSON dossier.
This combination gives Parslet the runway to outclass traditional mobile automation apps—every run feels bespoke, intentional, and enterprise ready.
- **On Linux (Debian/Ubuntu):** `sudo apt install graphviz`
- **On Linux (Fedora):** `sudo dnf install graphviz`
- **On Android (Termux):** `pkg install graphviz`
- **On Windows:** Download and run the installer from the [official Graphviz website](https://graphviz.org/download/) and make sure to add it to your system's PATH.
You will also need the `pydot` Python package, which is included in `requirements.txt`.
Once Graphviz is installed, you can use the `--export-png` flag with the `run` command:
```bash
parslet run my_first_workflow.py --export-png my_workflow.png
```
This will create an image file named `my_workflow.png` showing your workflow.
---
## Want to Learn More? (Documentation)
We've written down everything you need to know in a simple, friendly way.
- [**See All Features (Full Documentation)**](https://parslet.readthedocs.io/en/latest/)
- [**How It Really Works (Architecture)**](https://parslet.readthedocs.io/en/latest/architecture.html)
- [**The Remote Control (CLI Commands)**](https://parslet.readthedocs.io/en/latest/usage.html)
---
## Contributing
We'd love your help making Parslet even better. It's easy to get started. Check out our [Contributing Guide](./CONTRIBUTING.md).
## Development
Install dependencies and run the checks:
```
pip install -e .[dev]
pip install -r requirements-dev.txt
ruff parslet/core/__init__.py tests/test_imports.py
black --check parslet/core/__init__.py tests/test_imports.py
mypy
pytest -q
```
### Interoperability
Parslet ships with experimental bridges for [Parsl](https://parsl-project.org).
Use ``parsl_python`` to call a Parsl ``python_app`` as a Parslet task:
```python
from parslet.core.parsl_bridge import parsl_python
@parsl_python
def add(x, y):
return x + y
```
The returned ``add`` function behaves like a regular ``@parslet_task`` and can
participate in a Parslet DAG while executing the body via Parsl.
---
## License
This project is licensed under the MIT License. See [LICENSE](./LICENSE) for the full text.
## Acknowledgements
Inspired by the powerful [Parsl](https://github.com/Parsl/parsl) project.
A big thank you to the Outreachy community and the Parsl maintainers.
Raw data
{
"_id": null,
"home_page": null,
"name": "parslet",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "workflow, dag, automation",
"author": null,
"author_email": "Kelechi Nwankwo <kelechiann.nwankwo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5d/45/e3716c1b5230e0be04caa0ffcd9c5a50d831362542aa92e793ba7035f5d4/parslet-0.6.2.tar.gz",
"platform": null,
"description": "# Parslet: Your Pocket-Sized Workflow Assistant\n**A tool for running automated to-do lists (workflows) on your Python projects. It's built to work anywhere, especially on your android phone.**\n\n\n\n\n\n\n### What is Parslet?\n\nParslet is a tiny workflow engine built in Python. That means it's a tool that helps you automate tasks in a specific order, especially on phones and devices that can\u2019t run heavy-duty software. Think of it like a smart to-do list for your computer or phone, but instead of reminding you to do things, **it actually does them for you in the right order, automatically.**\n\nImagine this real-world example:\n\nYou run a small juice business with your best friend. Every morning you:\n\n1. Wash the fruits\n2. Peel them\n3. Blend them\n4. Pour into bottles\n5. Label and store\n\nNow imagine you could automate this entire process using a small robot. You just tell it the steps once, and it does them every morning, in order. You get to spend quality time with your best friend.\n\n**That\u2019s what Parslet does, but for software tasks.**\n\n---\n\n### What Kinds of Tasks Can It Handle?\n\nIn a real-world tech setting, you could use Parslet to:\n\n1. Run a script to **collect data** from a website.\n2. Then, **clean up** that messy data.\n3. Then, **save** the clean data to a file.\n4. Then, **back up** that file to a server.\n5. Finally, **send you an email** confirming the job is done.\n\nAll of this, in the right order, without you needing to supervise it.\n\n---\n\n### Why is Parslet Special?\n\nMost tools like this are built for powerful servers in a data center. Parslet is different. It\u2019s designed from the ground up to:\n\n- **Be Super Lightweight:** It works on a Raspberry Pi or even an Android phone.\n- **Run in Termux:** It\u2019s built and tested to work perfectly inside [Termux](https://termux.dev/en/), the command-line tool for Android.\n- **Work Offline:** No internet? No problem. Your workflows will still run.\n- **Empower Everyone:** It\u2019s for students, creators, and developers who might not have a laptop but have a brilliant idea.\n- **Battery-smart scheduling:** Adapts on Android, Raspberry Pi, and Linux laptops to stretch runtime.\n\n---\n\n### How Does It Work?\n\nIt uses something called a **DAG** (Directed Acyclic Graph), which is just a technical way of saying:\n\n> \u201cStep B only runs after Step A is done.\u201d\n\nYou define these steps (we call them **Tasks**) in a simple Python file. Parslet reads your file, understands the order, and handles the rest. It manages failures and runs everything as efficiently as possible.\n\n---\n\n## Get Started\n\nReady to try it? You can be up and running in less than a minute.\n\n1. **Install It:**\n\n The easiest way to install Parslet is directly from PyPI.\n\n ```bash\n pip install parslet\n ```\n\n2. **For Developers (or to get the latest changes):**\n\n If you want to contribute or get the very latest code, you can install it from the source.\n\n ```bash\n git clone https://github.com/Kanegraffiti/Parslet.git\n cd Parslet\n pip install -e .\n ```\n\n3. **Create Your First Workflow**\n\n Create a new file called `my_first_workflow.py` and paste this in. This is your recipe, telling Parslet what to do.\n\n ```python\n from parslet import parslet_task, ParsletFuture\n from typing import List\n\n # This is a \"task.\" It's just a normal Python function\n # with a special @parslet_task note for Parslet.\n @parslet_task\n def say_hello(name: str) -> str:\n print(f\"Task 1: Saying hello to {name}\")\n return f\"Hello, {name}!\"\n\n # Here's a second task.\n @parslet_task\n def make_it_loud(text: str) -> str:\n print(\"Task 2: Making the text loud!\")\n return f\"{text.upper()}!\"\n\n # This is the main \"recipe\" function.\n # Parslet looks for this to know how your tasks connect.\n def main() -> List[ParsletFuture]:\n # First, we tell Parslet to run the say_hello task.\n # It doesn't run yet! It just gives us an \"IOU\" for the result.\n greeting_iou = say_hello(\"Parslet\")\n \n # Next, we give the \"IOU\" from the first task to the second task.\n # This tells Parslet: \"Wait for task 1 to finish before starting task 2.\"\n loud_greeting_iou = make_it_loud(greeting_iou)\n\n # We return the very last IOU. This tells Parslet, \"We're done when this is done.\"\n return [loud_greeting_iou]\n ```\n\n4. **Run It**\n\n Now for the fun part. Tell Parslet to run your new workflow.\n\n ```bash\n parslet run my_first_workflow.py\n ```\n\nYou'll see the `print` statements from your tasks as they run, in the correct order \ud83c\udf89\n\nYou can also reference a workflow by module path and tweak execution:\n\n```bash\nparslet run my_package.workflow:main --max-workers 4 --json-logs --export-stats stats.json\n```\n\n---\n\n## What Else Can It Do?\n\nParslet is small, but it's packed with neat features for real-world use.\n\n- **Works Offline:** Your automated workflows run even without an internet connection. See the [examples](docs/examples.md).\n- **Saves Battery:** Use the special `--battery-mode` to tell Parslet to take it easy and conserve power. Read about [battery mode](docs/source/battery_mode.rst).\n- **Smart About Resources:** It automatically checks your device's CPU and memory to run smoothly without crashing. The [AdaptivePolicy](docs/policy.md) adjusts workers on the fly.\n- **DEFCON:** A multi-layered defense system in Parslet that proactively blocks zero-day exploits and malicious DAG behavior using offline rules. Learn more in the [security notes](docs/technical-overview.md).\n- **Plays Well with Others:** If you ever move to a big server, Parslet has tools to convert your recipes to run on powerful systems like Parsl or Dask. See [compatibility](docs/compatibility.md).\n- **Made for Termux:** We use it and test it on Android phones, so you know it'll work. Check the [install guide](docs/install.md).\n- **Concierge Mode & Context Scenes:** `parslet run --concierge` gives you a luxury pre-flight briefing, live context audit, and a polished post-run ledger. Combine it with `@parslet_task(contexts=[...])` to ensure tasks only run when the right battery, network, or time-of-day scene is active.\n\nWant to see more? Check out the `use_cases/` and `examples/` folders for more advanced recipes!\n\n---\n\n## Visualizing Your Workflows\n\nParslet can generate a picture of your workflow (a \"DAG\") to help you see how your tasks are connected. This is great for debugging and documentation.\n\nTo use this feature, you need to have **Graphviz** installed on your system.\n\n---\n\n## Concierge Mode & Context Scenes\n\nParslet 0.6.1 introduces **Concierge Mode**, a premium orchestration experience that makes your workflow feel like it shipped with its own operations team.\n\n- **Concierge Briefing:** Run `parslet run my_flow.py --concierge` to get a handcrafted pre-flight report. It shows which context detectors are live (battery, network, VPN, time-of-day) and which tasks are gated by those contexts.\n- **Context Scenes:** Declare contextual requirements directly on tasks:\n\n ```python\n @parslet_task(contexts=[\"network.online\", \"battery>=60\"], name=\"sync_to_vault\")\n def sync_to_vault(payload: dict) -> None:\n upload(payload)\n ```\n\n Parslet will defer the task with a `DEFERRED` status if the context isn't satisfied, protecting your workflow just like the best Tasker rule sets\u2014only with readable Python and offline detectors.\n\n- **Manual Overrides:** Activate ad-hoc scenes with `parslet run my_flow.py --context evening --context wifi`. You can also set a `PARSLET_CONTEXTS=\"evening,wifi\"` environment variable or programmatically enable custom detectors using `ContextOracle`.\n- **Concierge Runbook:** Need a paper trail? Add `--concierge-runbook runbook.json` and Parslet will record the complete itinerary, task metadata, and execution timings in a JSON dossier.\n\nThis combination gives Parslet the runway to outclass traditional mobile automation apps\u2014every run feels bespoke, intentional, and enterprise ready.\n\n- **On Linux (Debian/Ubuntu):** `sudo apt install graphviz`\n- **On Linux (Fedora):** `sudo dnf install graphviz`\n- **On Android (Termux):** `pkg install graphviz`\n- **On Windows:** Download and run the installer from the [official Graphviz website](https://graphviz.org/download/) and make sure to add it to your system's PATH.\n\nYou will also need the `pydot` Python package, which is included in `requirements.txt`.\n\nOnce Graphviz is installed, you can use the `--export-png` flag with the `run` command:\n\n```bash\nparslet run my_first_workflow.py --export-png my_workflow.png\n```\n\nThis will create an image file named `my_workflow.png` showing your workflow.\n\n---\n\n## Want to Learn More? (Documentation)\n\nWe've written down everything you need to know in a simple, friendly way.\n\n- [**See All Features (Full Documentation)**](https://parslet.readthedocs.io/en/latest/)\n- [**How It Really Works (Architecture)**](https://parslet.readthedocs.io/en/latest/architecture.html)\n- [**The Remote Control (CLI Commands)**](https://parslet.readthedocs.io/en/latest/usage.html)\n\n---\n\n## Contributing\n\nWe'd love your help making Parslet even better. It's easy to get started. Check out our [Contributing Guide](./CONTRIBUTING.md).\n\n## Development\n\nInstall dependencies and run the checks:\n\n```\npip install -e .[dev]\npip install -r requirements-dev.txt\nruff parslet/core/__init__.py tests/test_imports.py\nblack --check parslet/core/__init__.py tests/test_imports.py\nmypy\npytest -q\n```\n\n### Interoperability\n\nParslet ships with experimental bridges for [Parsl](https://parsl-project.org).\nUse ``parsl_python`` to call a Parsl ``python_app`` as a Parslet task:\n\n```python\nfrom parslet.core.parsl_bridge import parsl_python\n\n@parsl_python\ndef add(x, y):\n return x + y\n```\n\nThe returned ``add`` function behaves like a regular ``@parslet_task`` and can\nparticipate in a Parslet DAG while executing the body via Parsl.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](./LICENSE) for the full text.\n\n## Acknowledgements\n\nInspired by the powerful [Parsl](https://github.com/Parsl/parsl) project. \nA big thank you to the Outreachy community and the Parsl maintainers.\n",
"bugtrack_url": null,
"license": null,
"summary": "Simplify Python workflows with a minimal DAG engine.",
"version": "0.6.2",
"project_urls": {
"Documentation": "https://parslet.readthedocs.io/en/latest/",
"Homepage": "https://github.com/Kanegraffiti/Parslet",
"Source": "https://github.com/Kanegraffiti/Parslet"
},
"split_keywords": [
"workflow",
" dag",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3697734609c7f836df59cf9d40f8e192f6672395bc71c2f5642fc1d95a67237f",
"md5": "7adde956c41dc10288a0cf124c13bd95",
"sha256": "d6063f455e27faed7896c571b9c26183cf94940b80d67fc07f613903b4fd4171"
},
"downloads": -1,
"filename": "parslet-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7adde956c41dc10288a0cf124c13bd95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 169575,
"upload_time": "2025-10-17T18:02:32",
"upload_time_iso_8601": "2025-10-17T18:02:32.071839Z",
"url": "https://files.pythonhosted.org/packages/36/97/734609c7f836df59cf9d40f8e192f6672395bc71c2f5642fc1d95a67237f/parslet-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5d45e3716c1b5230e0be04caa0ffcd9c5a50d831362542aa92e793ba7035f5d4",
"md5": "0806675005d1edea3469e69015a864a7",
"sha256": "b60aa3376357efe6053852aa4d8badf0ce4533444be9649a499ef24a6664311d"
},
"downloads": -1,
"filename": "parslet-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "0806675005d1edea3469e69015a864a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 205563,
"upload_time": "2025-10-17T18:02:34",
"upload_time_iso_8601": "2025-10-17T18:02:34.321068Z",
"url": "https://files.pythonhosted.org/packages/5d/45/e3716c1b5230e0be04caa0ffcd9c5a50d831362542aa92e793ba7035f5d4/parslet-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 18:02:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kanegraffiti",
"github_project": "Parslet",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "networkx",
"specs": []
},
{
"name": "pillow",
"specs": []
},
{
"name": "psutil",
"specs": []
},
{
"name": "pydot",
"specs": []
},
{
"name": "rich",
"specs": []
},
{
"name": "flake8",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "black",
"specs": []
},
{
"name": "transformers",
"specs": []
}
],
"lcname": "parslet"
}
JSON
