| Name | zapusk JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2024-07-15 18:36:16 |
| maintainer | None |
| docs_url | None |
| author | Anton Shuvalov |
| requires_python | <4.0,>=3.12 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Zapusk
Zapusk is a versatile job runner designed for desktop environments. It simplifies the process of managing background tasks by providing robust features such as pre-configured job execution, background shell command execution, cron-like scheduling, log tailing, and notifications. Zapusk's detailed JSON output also enables powerful data manipulation and analysis when paired with tools like jq.
## Table of Contents
- [Key Features](#key-features)
- [Installation](#installation)
- [Usage](#usage)
- [Basic Commands](#basic-commands)
- [Advanced Usage](#advanced-usage)
- [Configuration](#configuration)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)
## Key Features
- **Preconfigured Jobs:** Run jobs defined in your configuration files.
- **Background Command Execution:** Run shell commands in the background with optional log tailing.
- **Cron-like Scheduling:** Schedule tasks using flexible cron syntax.
- **Log Tailing:** View logs in real-time.
- **Job Management:** Cancel running jobs and check their statuses.
- **Job Groups:** Share settings like callbacks and parallelism between jobs.
- **Colored JSON Output:** Easily readable JSON output.
- **Waybar Integration:** Display job statuses and notifications on Waybar.
- **Custom Working Directory:** Run scripts and callbacks in a specified working directory.
## Installation
Install Zapusk using `pip`:
```sh
pip install zapusk
```
## Usage
Zapusk requires `zapusk-server` to be started. Zapusk offers a command-line interface for managing and executing jobs. Here's a quick reference:
### Basic Commands
```sh
Usage:
zapusk -h | --help
zapusk --version
zapusk run <job_config_id> [--colors|--no-colors] [--tail]
zapusk exec <command> [--name=<name>] [--group=<group>] [--tail] [--schedule=<cron_expression>] [--colors|--no-colors]
zapusk cancel <job_id> [--scheduled] [--colors|--no-colors]
zapusk tail <job_id>
zapusk list [--filter=<state>|--scheduled] [--colors|--no-colors]
zapusk config_jobs [--colors|--no-colors]
zapusk config_groups [--colors|--no-colors]
zapusk waybar
Options:
-h --help Show this screen.
--version Show version.
--colors Enable colors.
--no-colors Disable colors.
--filter=<state> Filter jobs by status.
-n --name=<name> Name for a command.
-g --group=<group> Job group to run the command in.
-t --tail Tail logfile immediately.
```
### Examples
```sh
# Run npm install in the background
zapusk exec "npm i"
# Run pytest and tail its log
zapusk exec "pytest -v" -t
# Schedule a command to run every minute
zapusk exec "ping -c4 google.com" --schedule "*/1 * * * *"
# Run a job defined in ~/.config/zapusk/config.yaml
zapusk run youtube_dl
# Cancel a job by its ID
zapusk cancel 42
# See logs for a job by its ID
zapusk tail 42
```
## Configuration
Here is an example configuration file for Zapusk. It defines job groups and individual jobs, specifying commands, schedules, notifications, and working directories.
```yaml
# The port the server starts on and the client connects to
port: 9876
# Enable colored JSON output
colors: True
job_groups:
- id: unsplash
parallel: 1
- id: sleep
parallel: 2
- id: cmd
parallel: 10
on_finish: notify-send -a "zapusk" "Command Finished" "{job.name} has finished" --icon kitty
on_fail: notify-send -a "zapusk" "Command Failed" "{job.name} has failed" --icon kitty
- id: cronie
parallel: 1
on_finish: notify-send -a "zapusk" "Scheduled Job Finished" "{job.name} has finished" --icon kitty
on_fail: notify-send -a "zapusk" "Scheduled Job Failed" "{job.name} has failed" --icon kitty
jobs:
- name: Unsplash Download
id: unsplash
args_command: "zenity --entry --text 'Collection ID'"
command: ~/.bin/jobs/unsplash_dl.sh
cwd: /path/to/working/directory
- name: Sleep
id: sleep
group: sleep
args_command: "zenity --entry --text 'Sleep Time'"
command: sleep
on_finish: notify-send -a "zapusk" "Job Finished" "{job.name} has finished" --icon kitty
on_fail: notify-send -a "zapusk" "Job Failed" "{job.name} has failed" --icon kitty
- name: Cronie
id: cronie
group: cronie
schedule: "*/10 * * * *"
command: sleep 2
```
## Advanced Usage
### Running Preconfigured Jobs
Run jobs defined in your configuration file using their `id`.
```yaml
# Job configuration in ~/.config/zapusk/config.yaml
jobs:
- name: Unsplash Download
id: unsplash
args_command: "zenity --entry --text 'Collection ID'"
command: ~/.bin/jobs/unsplash_wallpaper_collection_download.sh
cwd: /path/to/working/directory
on_finish: notify-send -a "Zapusk" "Wallpapers downloaded" --icon kitty
on_fail: notify-send -a "Zapusk" "Wallpaper download failed" --icon kitty
```
```sh
# Run the `unsplash` job:
zapusk run unsplash
```
### Background Command Execution
Run commands in the background with optional log tailing:
```sh
zapusk exec "npm i" -t
```
### Scheduling Commands
Schedule commands to run at specific intervals using cron syntax:
```sh
zapusk exec "ping -c4 google.com" --schedule "*/1 * * * *"
```
Pre-configured jobs can also be scheduled:
```yaml
jobs:
- name: Cronie
id: cronie
group: cronie
schedule: "*/10 * * * *"
command: sleep 2
```
### Managing Jobs
Cancel a running or scheduled job by its ID:
```sh
zapusk cancel 42
```
Tail the logs of a running job by its ID:
```sh
zapusk tail 42
```
List all pending, running, and finished jobs:
```sh
zapusk list
```
### Callbacks
Use `on_finish` and `on_fail` callbacks for notifications.
For job group callbacks:
```yaml
job_groups:
- id: my_group
parallel: 10
on_finish: notify-send -a "zapusk" "Command Finished" "{job.name} has finished" --icon kitty
on_fail: notify-send -a "zapusk" "Command Failed" "{job.name} has failed" --icon kitty
```
For individual job callbacks:
```yaml
jobs:
- name: Sleep
id: sleep
group: sleep
command: ~/.bin/jobs/sleep
cwd: /path/to/working/directory
on_finish: notify-send -a "zapusk" "Job Finished" "{job.name} has finished" --icon kitty
on_fail: notify-send -a "zapusk" "Job Failed" "{job.name} has failed" --icon kitty
```
## Waybar Integration
Zapusk integrates with Waybar to display job statuses and notifications directly on your desktop.
```json
// Example integration with wofi and jq
"custom/zapusk": {
"exec": "zapusk waybar",
"on-click": "zapusk config_jobs --no-colors | jq -r \".[].id\" | wofi --dmenu | xargs -I{} zapusk run {}",
"tooltip": true,
"return-type": "json",
"format": "{}",
"interval": 1
}
```
## License
Zapusk is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "zapusk",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Anton Shuvalov",
"author_email": "anton@shuvalov.info",
"download_url": "https://files.pythonhosted.org/packages/49/87/7474a678c11ef19debebca480f013e9bffa0c259c97d397520feb119a366/zapusk-0.1.1.tar.gz",
"platform": null,
"description": "# Zapusk\n\n\n\nZapusk is a versatile job runner designed for desktop environments. It simplifies the process of managing background tasks by providing robust features such as pre-configured job execution, background shell command execution, cron-like scheduling, log tailing, and notifications. Zapusk's detailed JSON output also enables powerful data manipulation and analysis when paired with tools like jq.\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Basic Commands](#basic-commands)\n - [Advanced Usage](#advanced-usage)\n- [Configuration](#configuration)\n- [Examples](#examples)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Key Features\n\n- **Preconfigured Jobs:** Run jobs defined in your configuration files.\n- **Background Command Execution:** Run shell commands in the background with optional log tailing.\n- **Cron-like Scheduling:** Schedule tasks using flexible cron syntax.\n- **Log Tailing:** View logs in real-time.\n- **Job Management:** Cancel running jobs and check their statuses.\n- **Job Groups:** Share settings like callbacks and parallelism between jobs.\n- **Colored JSON Output:** Easily readable JSON output.\n- **Waybar Integration:** Display job statuses and notifications on Waybar.\n- **Custom Working Directory:** Run scripts and callbacks in a specified working directory.\n\n## Installation\n\nInstall Zapusk using `pip`:\n\n```sh\npip install zapusk\n```\n\n## Usage\n\nZapusk requires `zapusk-server` to be started. Zapusk offers a command-line interface for managing and executing jobs. Here's a quick reference:\n\n### Basic Commands\n\n```sh\nUsage:\n zapusk -h | --help\n zapusk --version\n zapusk run <job_config_id> [--colors|--no-colors] [--tail]\n zapusk exec <command> [--name=<name>] [--group=<group>] [--tail] [--schedule=<cron_expression>] [--colors|--no-colors]\n zapusk cancel <job_id> [--scheduled] [--colors|--no-colors]\n zapusk tail <job_id>\n zapusk list [--filter=<state>|--scheduled] [--colors|--no-colors]\n zapusk config_jobs [--colors|--no-colors]\n zapusk config_groups [--colors|--no-colors]\n zapusk waybar\n\nOptions:\n -h --help Show this screen.\n --version Show version.\n --colors Enable colors.\n --no-colors Disable colors.\n --filter=<state> Filter jobs by status.\n -n --name=<name> Name for a command.\n -g --group=<group> Job group to run the command in.\n -t --tail Tail logfile immediately.\n```\n\n### Examples\n\n```sh\n# Run npm install in the background\nzapusk exec \"npm i\"\n\n# Run pytest and tail its log\nzapusk exec \"pytest -v\" -t\n\n# Schedule a command to run every minute\nzapusk exec \"ping -c4 google.com\" --schedule \"*/1 * * * *\"\n\n# Run a job defined in ~/.config/zapusk/config.yaml\nzapusk run youtube_dl\n\n# Cancel a job by its ID\nzapusk cancel 42\n\n# See logs for a job by its ID\nzapusk tail 42\n```\n\n## Configuration\n\nHere is an example configuration file for Zapusk. It defines job groups and individual jobs, specifying commands, schedules, notifications, and working directories.\n\n```yaml\n# The port the server starts on and the client connects to\nport: 9876\n\n# Enable colored JSON output\ncolors: True\n\njob_groups:\n - id: unsplash\n parallel: 1\n - id: sleep\n parallel: 2\n - id: cmd\n parallel: 10\n on_finish: notify-send -a \"zapusk\" \"Command Finished\" \"{job.name} has finished\" --icon kitty\n on_fail: notify-send -a \"zapusk\" \"Command Failed\" \"{job.name} has failed\" --icon kitty\n - id: cronie\n parallel: 1\n on_finish: notify-send -a \"zapusk\" \"Scheduled Job Finished\" \"{job.name} has finished\" --icon kitty\n on_fail: notify-send -a \"zapusk\" \"Scheduled Job Failed\" \"{job.name} has failed\" --icon kitty\n\njobs:\n - name: Unsplash Download\n id: unsplash\n args_command: \"zenity --entry --text 'Collection ID'\"\n command: ~/.bin/jobs/unsplash_dl.sh\n cwd: /path/to/working/directory\n\n - name: Sleep\n id: sleep\n group: sleep\n args_command: \"zenity --entry --text 'Sleep Time'\"\n command: sleep\n on_finish: notify-send -a \"zapusk\" \"Job Finished\" \"{job.name} has finished\" --icon kitty\n on_fail: notify-send -a \"zapusk\" \"Job Failed\" \"{job.name} has failed\" --icon kitty\n\n - name: Cronie\n id: cronie\n group: cronie\n schedule: \"*/10 * * * *\"\n command: sleep 2\n```\n\n## Advanced Usage\n\n### Running Preconfigured Jobs\n\nRun jobs defined in your configuration file using their `id`.\n\n```yaml\n# Job configuration in ~/.config/zapusk/config.yaml\njobs:\n - name: Unsplash Download\n id: unsplash\n args_command: \"zenity --entry --text 'Collection ID'\"\n command: ~/.bin/jobs/unsplash_wallpaper_collection_download.sh\n cwd: /path/to/working/directory\n on_finish: notify-send -a \"Zapusk\" \"Wallpapers downloaded\" --icon kitty\n on_fail: notify-send -a \"Zapusk\" \"Wallpaper download failed\" --icon kitty\n```\n\n```sh\n# Run the `unsplash` job:\nzapusk run unsplash\n```\n\n### Background Command Execution\n\nRun commands in the background with optional log tailing:\n\n```sh\nzapusk exec \"npm i\" -t\n```\n\n### Scheduling Commands\n\nSchedule commands to run at specific intervals using cron syntax:\n\n```sh\nzapusk exec \"ping -c4 google.com\" --schedule \"*/1 * * * *\"\n```\n\nPre-configured jobs can also be scheduled:\n\n```yaml\njobs:\n - name: Cronie\n id: cronie\n group: cronie\n schedule: \"*/10 * * * *\"\n command: sleep 2\n```\n\n### Managing Jobs\n\nCancel a running or scheduled job by its ID:\n\n```sh\nzapusk cancel 42\n```\n\nTail the logs of a running job by its ID:\n\n```sh\nzapusk tail 42\n```\n\nList all pending, running, and finished jobs:\n\n```sh\nzapusk list\n```\n\n### Callbacks\n\nUse `on_finish` and `on_fail` callbacks for notifications.\n\nFor job group callbacks:\n\n```yaml\njob_groups:\n - id: my_group\n parallel: 10\n on_finish: notify-send -a \"zapusk\" \"Command Finished\" \"{job.name} has finished\" --icon kitty\n on_fail: notify-send -a \"zapusk\" \"Command Failed\" \"{job.name} has failed\" --icon kitty\n```\n\nFor individual job callbacks:\n\n```yaml\njobs:\n - name: Sleep\n id: sleep\n group: sleep\n command: ~/.bin/jobs/sleep\n cwd: /path/to/working/directory\n on_finish: notify-send -a \"zapusk\" \"Job Finished\" \"{job.name} has finished\" --icon kitty\n on_fail: notify-send -a \"zapusk\" \"Job Failed\" \"{job.name} has failed\" --icon kitty\n```\n\n## Waybar Integration\n\nZapusk integrates with Waybar to display job statuses and notifications directly on your desktop.\n\n```json\n// Example integration with wofi and jq\n\"custom/zapusk\": {\n \"exec\": \"zapusk waybar\",\n \"on-click\": \"zapusk config_jobs --no-colors | jq -r \\\".[].id\\\" | wofi --dmenu | xargs -I{} zapusk run {}\",\n \"tooltip\": true,\n \"return-type\": \"json\",\n \"format\": \"{}\",\n \"interval\": 1\n}\n```\n\n\n## License\n\nZapusk is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for more information.\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.1.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a817574486fb0ef39b59ad02a80fffadb73d22a5a04f4950aa4fc5d0c86ef6bc",
"md5": "b4f2af686da679af64ae5bec8a46b21e",
"sha256": "c4ca53aeaa4beba351dc2bf2fba63d6fd5148a37bc0fdaeefcda1baf63dbdb05"
},
"downloads": -1,
"filename": "zapusk-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4f2af686da679af64ae5bec8a46b21e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 60695,
"upload_time": "2024-07-15T18:36:14",
"upload_time_iso_8601": "2024-07-15T18:36:14.781713Z",
"url": "https://files.pythonhosted.org/packages/a8/17/574486fb0ef39b59ad02a80fffadb73d22a5a04f4950aa4fc5d0c86ef6bc/zapusk-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49877474a678c11ef19debebca480f013e9bffa0c259c97d397520feb119a366",
"md5": "fccef1a3e4922e1159ea64e18dffa4ae",
"sha256": "5408168854c7c97e2d65ec831d92af492121a58e8cab10ad2b78ee6b36e45e48"
},
"downloads": -1,
"filename": "zapusk-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "fccef1a3e4922e1159ea64e18dffa4ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 33817,
"upload_time": "2024-07-15T18:36:16",
"upload_time_iso_8601": "2024-07-15T18:36:16.432283Z",
"url": "https://files.pythonhosted.org/packages/49/87/7474a678c11ef19debebca480f013e9bffa0c259c97d397520feb119a366/zapusk-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-15 18:36:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "zapusk"
}
