Skip to main content

Simple task automation for projects.

Project description


Current version: 0.2.5

Tested with Python 3.8, 3,9, 3.10 and 3.11 on latest Linux, MacOS and Windows. Code is simple. Probably works in other versions and platforms.



Need help organizing your project's tasks?

Don't want to learn a complex tool with an unnecessarily cumbersome syntax or API?

Want to specify your tasks in plain Python still having easy and flexible access to the shell?

Just call PePython!


pip install pepython

Quick start

Define your tasks in a file your root directory. Tasks are just plain Python functions. Note how dependencies are just calls in the body of the tasks themselves, alowing all kinds of dependencies and parameter forwarding (see the parameters in action further down!).

from pepython.task_def import task, s

def clean():
    s("rm -rf build dist *.egg-info")

def build():
    s("pipenv run python sdist bdist_wheel")

def publish():
    s("pipenv run twine upload dist/*", interactive=True)

def build_and_publish():
    build()     # These are
    publish()   #  dependencies!

Then just call PePython!

$ pepython --help
        pepython [--defs-path] task [task params ...]

$ pepython clean
Executed task 'clean' successfuly.

$ pepython build_and_publish
Enter your username: your-name-here
Enter your password: ************
Uploading distributions to
Uploading pepython-0.1.0-py2-none-any.whl
100%|█████████████████████████████████████████████████████| 7.77k/7.77k [00:00<00:00, 42.6kB/s]
Uploading pepython-0.1.0.tar.gz
100%|█████████████████████████████████████████████████████| 5.65k/5.65k [00:01<00:00, 4.74kB/s]

Executed task 'build_and_publish' successfuly.

Note how dependencies are just method calls in the body of the tasks themselves. This allows easy forwarding of params and a more flexible schema than some configured pre/post dependencies, like it's done in other tools.

If you need task arguments, they are defined naturally, again in plain Pyhton:

def task_args(first_arg, second_arg, *rest_of_args):
        f"You've passed {first_arg} and {second_arg} as "
        f"the 2 first parms, then passed:\n{rest_of_args}."
$ pepython task_args a b c d e
You've passed a and b as the 2 first parms, then passed:
('c', 'd', 'e').

Executed task 'task_args' successfuly.

The main idea is to use the Python language for your task automation, with all of it's flexibility but without loosing the shell. This is why there's s() (short for shell).

s() is meant to to be easy to use. Above we saw how using the interactive option, the password prompt was handled interactively by the user, while other non interactive processes can be left to be managed by the task. We'll demonstrate it here, along with the fail_fast option, that when set to false, allows the task to manage the errors:

def process_python_files():
    ls_result = s("ls *py", fail_fast=False)

    if not ls_result.ok:
        exit("No python files here")

    python_files_raw = ls_result.value['out'].split("\n")
    python_files = [f.strip() for f in python_files_raw if f.strip()]

        f"These are the python files in this directory:\n{python_files}"
$ pepython process_python_files
These are the python files in this directory:
['', '']

Executed task 'shell_returned_values' successfuly.

s() can also receive the verbose option so you can see the exit code, stdout and stderr printed as follows:

Executed shell command 'ls *py'
exit code was: 0
stdout was:

stderr was:


Make sure you have the lastest pip and pipenv versions:

pip install --upgrade pip pipenv

To start developing, start the environment by:

pipenv shell
pipenv install -d

The installed pepython within the pipenv environment is the editable (alla pip install -e .) version of the package, so you can manually test right away.

This tool uses both pipenv for development and setuptools for packaging and distribution. To this date there is not a 100% community-accepted best practice so I've taken this approach. In summary:

To add an application dependency, add it in and leave it with a loose version definition. Then, just do pipenv install -e . to install the dependency. Pipenv locking mecanism will work as expected, since pepython itself is in the [packages] section of Pipfile (check Pipfile.lock and you'll find the deps there).

To add a development dependency, add it to Pipfile via pipenv install -d <my-dependency>.

This way there's a single source of truth for package definition. No need to repeat the deps in and Pipfile*.


To test the project run pytest inside the pipenv. Once you have something running, run tox to check it's compatible with all python versions supported.

IMPORTANT: in order to make tox test with different python versions, those have to be installed. pyenv is used for that purpose and should work out of the box. Check the required versions in tox.ini and related files.

Dev tasks automation and publishing to PyPI

This project uses pepython itself for automation. There you'll find tasks to build and publish the package to PyPI.


This project is licensed under the MIT License - see the LICENSE file for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pepython-0.2.5.tar.gz (6.5 kB view hashes)

Uploaded Source

Built Distribution

pepython-0.2.5-py3-none-any.whl (7.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page