Your faithful companion
Project description
Zrb (WIP)
Your faithful companion.
How to install
pip install zrb
How to use
To run a task, you can invoke the following command:
zrb <task> [arguments]
How to define tasks
Zrb will automatically load:
zrb_init.py
in your current directory (or parent directories).- or any Python file defined in
ZRB_INIT_SCRIPTS
environment.
You can use a colon separator (:
) to define multiple scripts in ZRB_INIT_SCRIPTS
. For example:
ZRB_SCRIPTS=~/personal/zrb_init.py:~/work/zrb_init.py
Your Zrb script (e.g: ./zrb_init.py
) should contain your task definitions. For example:
from typing import Any
from zrb import (
runner,
Env, StrInput,
Group, Task, CmdTask, HTTPChecker,
builtin_group
)
def _concat(*args: str, **kwargs: Any) -> str:
separator = kwargs.get('separator', ' ')
return separator.join(args)
'''
Simple Python task to concatenate words
'''
concat = Task(
name='concat',
inputs=[StrInput(name='separator', description='Separator', default=' ')],
runner=_concat
)
runner.register(concat)
'''
Simple CLI task, read input and show output
'''
hello = CmdTask(
name='hello',
group=builtin_group.show,
inputs=[StrInput(name='name', description='Name', default='world')],
cmd='echo Hello {{input.name}}'
)
runner.register(hello)
'''
A new group: make
'''
make = Group(name='make', description='Make things')
'''
Simple CLI task, part of 'make' group
'''
make_coffee = CmdTask(
name='coffee',
group=make,
upstreams=[hello],
cmd='echo Coffee for you โ'
)
runner.register(make_coffee)
'''
Simple CLI task, part of 'make' group
'''
make_beer = CmdTask(
name='beer',
group=make,
upstreams=[hello],
cmd='echo Cheers ๐บ'
)
runner.register(make_beer)
'''
Sub group of 'make'
'''
make_gitignore = Group(
name='gitignore', description='Make gitignore', parent=make
)
'''
Simple CLI task, part of 'make_gitignore' group.
Having multiline cmd
'''
make_gitignore_python = CmdTask(
name='node',
group=make_gitignore,
cmd=[
'echo "node_modules/" >> .gitignore'
'echo ".npm" >> .gitignore'
'echo "npm-debug.log" >> .gitignore'
]
)
runner.register(make_gitignore_python)
'''
Simple CLI task, part of 'make_gitignore' group.
Having multiline cmd
'''
make_gitignore_nodejs = CmdTask(
name='node',
group=make_gitignore,
cmd=[
'echo "__pycache__/" >> .gitignore'
'echo "venv" >> .gitignore'
]
)
runner.register(make_gitignore_nodejs)
'''
Long running CLI task.
Run a server and waiting for the port to be ready.
'''
start_server = CmdTask(
name='server',
group=builtin_group.start,
upstreams=[make_coffee, make_beer],
inputs=[StrInput(name='dir', description='Directory', default='.')],
envs=[Env(name='PORT', os_name='WEB_PORT', default='3000')],
cmd='python -m http.server $PORT --directory {{input.dir}}',
checkers=[HTTPChecker(port='{{env.PORT}}')]
)
runner.register(start_server)
Once registered, your task will be accessible from the terminal.
For example, you can run a server by performing:
export WEB_PORT=8080
zrb start server
The output will be similar to this:
Name [world]: Go Frendi
Dir [.]:
๐ค โ 2023-02-04T11:08:11.921472 โ 12264 โค 1 of 3 โข ๐ show hello โข Hello Go Frendi
๐ค โ 2023-02-04T11:08:12.039529 โ 12266 โค 1 of 3 โข ๐น make coffee โข Coffee for you โ
๐ค โ 2023-02-04T11:08:12.040651 โ 12268 โค 1 of 3 โข ๐ถ make beer โข Cheers ๐บ
๐ค โ 2023-02-04T11:08:12.160402 โ 12270 โค 1 of 3 โข ๐ start server โข Serving HTTP on 0.0.0.0 port 8080 (http://0.0.0.0:8080/) ...
๐ค โ 2023-02-04T11:08:12.224660 โ 12263 โค 1 of 1 โข ๐ http_check โข HEAD http://localhost:8080/ 200 (OK)
๐ค ๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐
๐ค ๐ start server completed in
๐ค ๐ 0.311281681060791 seconds
๐ค ๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐๐
๐ค โ 2023-02-04T11:08:12.228542 โ 12270 โค 1 of 3 โข ๐ start server โข 127.0.0.1 - - [04/Feb/2023 11:08:12] "HEAD / HTTP/1.1" 200 -
How to run tasks programmatically
To run a task programmatically, you need to create a main loop
.
For example:
from zrb import CmdTask
cmd_task = CmdTask(
name='sample',
cmd='echo hello'
)
main_loop = cmd_task.create_main_loop(env_prefix='')
result = main_loop() # This run the task
print(result.output) # Should be "hello"
Configuration
The following configurations are available:
ZRB_LOGGING_LEVEL
: Logging verbosity.- Default:
WARNING
- Possible values:
CRITICAL
ERROR
WARNING
WARN
(The same asWARNING
)INFO
DEBUG
NOTSET
- Default:
ZRB_INIT_SCRIPTS
: List of task registration script that should be loaded by default.- Default: Empty
- Possible values: List of script paths, separated by colons(
:
). - Example:
~/personal/zrb_init.py:~/work/zrb_init.py
ZRB_ENV
: Environment prefix that will be used when loading Operating System's environment.- Default: Empty
- Possible values: Any combination of alpha-numeric and underscore
- Example:
DEV
ZRB_SHOULD_LOAD_BUILTIN
: Whether load builtin tasks or not- Default:
1
- Possible values:
1
0
- Default:
ZRB_SHELL
: Default shell for running cmdTask- Default: empty, indicating the system's default (usually
/usr/bin/bash
or/usr/bin/sh
) - Possible value:
/usr/bin/bash
/usr/bin/sh
node
python
- Default: empty, indicating the system's default (usually
Quirks
- No one is sure how to pronounce Zrb. Let's keep it that way.
- If not set,
PYTHONUNBUFFERED
will be set to1
. - Once
zrb_init.py
is loaded, Zrb will automatically:- Set
ZRB_PROJECT_DIR
tozrb_init.py
's parent directory. - Adding
ZRB_PROJECT_DIR
toPYTHONPATH
.
- Set
- Zrb passes several keyword arguments that will be accessible from the task's run method:
_args
: Shell argument when the task is invoked._task
: Reference to the current task.
- You can access the built-in command groups by importing
zrb.builtin_group
.
For contributors
There is a toolkit you can use to test whether Zrb is working as intended.
To use the toolkit, you can invoke the following command:
source ./project.sh
Once you load the toolkit, you can start playing around.
# Run test and serve coverage.
zrb test
# Test zrb in playground
zrb prepare-playground
For maintainers
To publish Zrb, you need a Pypi
account:
- Log in or register to https://pypi.org/
- Create an API token
You can also create a TestPypi
account:
- Log in or register to https://test.pypi.org/
- Create an API token
Once you have your API token, you need to create a ~/.pypirc
file:
[distutils]
index-servers =
pypi
testpypi
[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-xxx-xxx
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-xxx-xxx
To publish Zrb, you can do the following:
source ./project.sh
# Publish Zrb to TestPypi
zrb publish-test
# Publish Zrb to Pypi
zrb publish
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.