aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2026-03-19 20:58:46 -0400
committerEugene Triguba <hello@eugenetriguba.com>2026-03-19 21:49:08 -0400
commit867c9c02acafe7a0118b6ed7095055efe42fb359 (patch)
treee1bee57034d1589a2cb0452d7f7f5017ae95f87f /README.md
parentRelease version 1.14.1 (#92) (diff)
downloadtaskipy2-867c9c02acafe7a0118b6ed7095055efe42fb359.zip
Setup taskipy2 fork from taskipy v1.14.1
Diffstat (limited to 'README.md')
-rw-r--r--README.md137
1 files changed, 86 insertions, 51 deletions
diff --git a/README.md b/README.md
index ad6b9ec..0d651d0 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-<p align="center">
- <img src="https://github.com/illBeRoy/taskipy/raw/master/logo.svg" width="150" />
-</p>
+# taskipy2
-- [General](#general)
+**The complementary task runner for python.**
+
+- [Overview](#overview)
- [Requirements](#requirements)
- [Usage](#usage)
- [Installation](#installation)
@@ -24,16 +24,17 @@
- [Advanced Use Cases](#advanced-use-cases)
- [Contribution](#contribution)
-## General
+## Overview
-[![pypi](https://img.shields.io/pypi/v/taskipy?style=flat-square)](https://pypi.org/project/taskipy/)
-[![pypi-downloads](https://img.shields.io/pypi/dm/taskipy?style=flat-square)](https://pypi.org/project/taskipy/)
-[![Conda Version](https://img.shields.io/conda/vn/conda-forge/taskipy.svg)](https://anaconda.org/conda-forge/taskipy)
-[![ci](https://img.shields.io/github/actions/workflow/status/taskipy/taskipy/ci.yml?style=flat-square)](https://github.com/taskipy/taskipy/actions/workflows/ci.yml)
+> taskipy2 is a continuation fork of [taskipy](https://github.com/taskipy/taskipy).
+
+[![pypi](https://img.shields.io/pypi/v/taskipy2?style=flat-square)](https://pypi.org/project/taskipy2/)
+[![pypi-downloads](https://img.shields.io/pypi/dm/taskipy2?style=flat-square)](https://pypi.org/project/taskipy2/)
-**The complementary task runner for python.**
-Every development pipeline has tasks, such as `test`, `lint` or `publish`. With taskipy, you can define those tasks in one file and run them with a simple command.
+Every development pipeline has tasks, such as `test`, `lint` or `publish`. With
+taskipy, you can define those tasks in one file and run them with a simple
+command.
For instance, instead of running the following command:
@@ -53,7 +54,8 @@ Or (if you're not using poetry):
task test
```
-In addition, you can compose tasks and group them together, and also create dependencies between them.
+In addition, you can compose tasks and group them together, and also create
+dependencies between them.
This project is heavily inspired by npm's [run script command](https://docs.npmjs.com/cli/run-script).
@@ -61,7 +63,8 @@ This project is heavily inspired by npm's [run script command](https://docs.npmj
Python 3.6 or newer.
-Your project directory should include a valid `pyproject.toml` file, as specified in [PEP-518](https://www.python.org/dev/peps/pep-0518/).
+Your project directory should include a valid `pyproject.toml` file, as
+specified in [PEP-518](https://www.python.org/dev/peps/pep-0518/).
## Usage
@@ -70,22 +73,18 @@ Your project directory should include a valid `pyproject.toml` file, as specifie
To install taskipy as a dev dependency, simply run:
```bash
-poetry add --dev taskipy
-```
-
-For Anaconda Python-based environments, taskipy is also available via conda-forge:
-
-```bash
-conda install -c conda-forge taskipy
+poetry add --group dev taskipy2
```
### Adding Tasks
In your `pyproject.toml` file, add a new section called `[tool.taskipy.tasks]`.
-The section is a key-value map, from the names of the task to the actual command that should be run in the shell.
+The section is a key-value map, from the names of the task to the actual command
+that should be run in the shell.
-There are two ways to define tasks. The easy way is to simply write the command down as a string:
+There are two ways to define tasks. The easy way is to simply write the command
+down as a string:
__pyproject.toml__
@@ -95,7 +94,8 @@ test = "python -m unittest tests/test_*.py"
lint = "pylint tests taskipy"
```
-Alternatively, you can define tasks more explicitly by declaring both the command and a helpful description using an inline table:
+Alternatively, you can define tasks more explicitly by declaring both the
+command and a helpful description using an inline table:
__pyproject.toml__
@@ -105,7 +105,8 @@ test = { cmd = "python -m unittest tests/test_*.py", help = "runs all unit tests
lint = { cmd = "pylint tests taskipy", help = "confirms code style using pylint" }
```
-The explicit notation is more verbose, but provides better context to anyone who uses the task.
+The explicit notation is more verbose, but provides better context to anyone who
+uses the task.
### Running Tasks
@@ -123,7 +124,8 @@ test python -m unittest tests/test_*.py
lint pylint tests taskipy
```
-If you declared your task explicitly, you will see the description of the task by the side of the task's name:
+If you declared your task explicitly, you will see the description of the task
+by the side of the task's name:
```bash
$ poetry run task --list
@@ -133,7 +135,8 @@ lint confirms code style using pylint
### Passing Command Line Args to Tasks
-If you want to pass command line arguments to tasks (positional or named), simply append them to the end of the task command.
+If you want to pass command line arguments to tasks (positional or named),
+simply append them to the end of the task command.
For example, running the above task like this:
@@ -149,13 +152,16 @@ python -m unittest tests/test_*.py -h
And will show unittest's help instead of actually running it.
-> ⚠️ Note: if you are using pre \ post hooks, do notice that arguments are not passed to them, only to the task itself.
+> ⚠️ Note: if you are using pre \ post hooks, do notice that arguments are not
+> passed to them, only to the task itself.
### Composing Tasks
#### Grouping Subtasks Together
-Some tasks are composed of multiple subtasks. Instead of writing plain shell commands and stringing them together, you can break them down into multiple subtasks:
+Some tasks are composed of multiple sub-tasks. Instead of writing plain shell
+commands and stringing them together, you can break them down into multiple
+sub-tasks:
```toml
[tool.taskipy.tasks]
@@ -174,7 +180,8 @@ lint_mypy = "mypy tests taskipy"
#### Pre Task Hook
-Tasks might also depend on one another. For example, tests might require some binaries to be built. Take the two following commands, for instance:
+Tasks might also depend on one another. For example, tests might require some
+binaries to be built. Take the two following commands, for instance:
```toml
[tool.taskipy.tasks]
@@ -182,7 +189,7 @@ test = "python -m unittest tests/test_*.py"
build = "make ."
```
-You could make tests depend on building, by using the **pretask hook**:
+You could make tests depend on building, by using the **pre-task hook**:
```toml
[tool.taskipy.tasks]
@@ -191,11 +198,15 @@ test = "python -m unittest tests/test_*.py"
build = "make ."
```
-The pretask hook looks for `pre_<task_name>` task for a given `task_name`. It will run it before running the task itself. If the pretask fails, then taskipy will exit without running the task itself.
+The pre-task hook looks for `pre_<task_name>` task for a given `task_name`. It
+will run it before running the task itself. If the pre-task fails, then taskipy
+will exit without running the task itself.
#### Post Task Hook
-From time to time, you might want to run a task in conjunction with another. For example, you might want to run linting after a successful test run. Take the two following commands, for instance:
+From time to time, you might want to run a task in conjunction with another. For
+example, you might want to run linting after a successful test run. Take the two
+following commands, for instance:
```toml
[tool.taskipy.tasks]
@@ -203,7 +214,7 @@ test = "python -m unittest tests/test_*.py"
lint = "pylint tests taskipy"
```
-You could make tests trigger linting, by using the **posttask hook**:
+You could make tests trigger linting, by using the **post-task hook**:
```toml
[tool.taskipy.tasks]
@@ -212,11 +223,14 @@ post_test = "task lint"
lint = "pylint tests taskipy"
```
-The posttask hook looks for `post_<task_name>` task for a given `task_name`. It will run it after running the task itself. If the task failed, then taskipy will not run the posttask hook.
+The post-task hook looks for `post_<task_name>` task for a given `task_name`. It
+will run it after running the task itself. If the task failed, then taskipy will
+not run the post-task hook.
### Using Variables
-In some cases, you might find yourself passing the same arguments over and over again. Let us take a look at the following tasks:
+In some cases, you might find yourself passing the same arguments over and over
+again. Let us take a look at the following tasks:
```toml
[tool.taskipy.tasks]
@@ -226,7 +240,8 @@ black = "black path/to/my_module"
As you can see, we provide the same path argument to both `pylint` and `black`.
-In order to encourage DRY and improve your ability to change these values later on, taskipy actually lets you declare and reuse variables in your tasks:
+In order to encourage DRY and improve your ability to change these values later
+on, taskipy actually lets you declare and reuse variables in your tasks:
```toml
[tool.taskipy.variables]
@@ -245,13 +260,17 @@ We have made the following changes to our configuration:
#### String Formatting
-The formatting of the task commands uses python's own `string.format` method, and therefore supports everything that python's [formatted string literals](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals) let you do.
+The formatting of the task commands uses python's own `string.format` method,
+and therefore supports everything that python's [formatted string literals](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals)
+let you do.
#### Always Use Variables
-Using variables is opt-in, which means that by default commands do **not** use them, and you will have to turn them on a task to task basis.
+Using variables is opt-in, which means that by default commands do **not** use
+them, and you will have to turn them on a task to task basis.
-If you want to turn on `use_vars` globally, all you need to do is to declare that under taskipy's **settings** table:
+If you want to turn on `use_vars` globally, all you need to do is to declare
+that under taskipy's **settings** table:
```toml
[tool.taskipy.settings]
@@ -267,7 +286,9 @@ black = "black {path}"
#### Recursive Variables
-If we want to use variables within other variables, we can utilize recursive variables. By default, variables are not recursive, but we can specify a variable to be recursive by setting the `recursive` key to `true`.
+If we want to use variables within other variables, we can utilize recursive
+variables. By default, variables are not recursive, but we can specify
+a variable to be recursive by setting the `recursive` key to `true`.
```toml
[tool.taskipy.settings]
@@ -285,20 +306,28 @@ In this example, we could run `task echo` and we would then see `src/package`.
### Working directory
-By default, all tasks run from the directory where they are called. This makes possible to change folder and run flexible tasks depending on the current folder.
+By default, all tasks run from the directory where they are called. This makes
+possible to change folder and run flexible tasks depending on the current
+folder.
-However, some tasks may need to always run in the same working directory, regardless from where they are called.
+However, some tasks may need to always run in the same working directory,
+regardless from where they are called.
-If you want tasks to always run relative to a specific path, you can use the `"cwd"` setting to define a current working directory of the task relative to the root of the project (where the `pyproject.toml` file is):
+If you want tasks to always run relative to a specific path, you can use the
+`"cwd"` setting to define a current working directory of the task relative to
+the root of the project (where the `pyproject.toml` file is):
```toml
[tool.taskipy.tasks]
echo = { cmd = "python -c \"import os; print(os.getcwd())\"" , cwd = "."}
```
-In this example, running `task echo` will print the directory path of the file `pyproject.toml` regardless of the folder that you call this task.
+In this example, running `task echo` will print the directory path of the file
+`pyproject.toml` regardless of the folder that you call this task.
-If you want to define `cwd` globally (setting all tasks to always run from the same working directory) you just need to declare that under taskipy's **settings** table:
+If you want to define `cwd` globally (setting all tasks to always run from the
+same working directory) you just need to declare that under taskipy's
+**settings** table:
```toml
[tool.taskipy.settings]
@@ -307,19 +336,22 @@ cwd = "."
### Using Taskipy Without Poetry
-Taskipy was created with poetry projects in mind, but actually only requires a valid `pyproject.toml` file in your project's directory. As a result, you can use it even without poetry:
+Taskipy was created with poetry projects in mind, but actually only requires
+a valid `pyproject.toml` file in your project's directory. As a result, you can
+use it even without poetry:
#### Installing With PIP
Install taskipy on your machine or in your virtualenv using:
```bash
-pip install taskipy
+pip install taskipy2
```
#### Running Tasks
-Head into your project's directory (don't forget to activate virtualenv if you're using one), and run the following command:
+Head into your project's directory (don't forget to activate virtualenv if
+you're using one), and run the following command:
```bash
task TASK
@@ -329,10 +361,13 @@ Where `TASK` is the name of your task.
### Advanced Use Cases
-If you have a more specific use case, you might not be the first to run into it! Head over to the [ADVANCED_FEATURES](./docs/ADVANCED_FEATURES.md) doc, and look it up.
+If you have a more specific use case, you might not be the first to run into it!
+Head over to the [ADVANCED_FEATURES](./docs/ADVANCED_FEATURES.md) doc, and look
+it up.
## Contribution
-All kinds of contributions are welcome! Feel free to request features and report bugs via issues, and contribute your own beautiful code via pull requests!
+All kinds of contributions are welcome! Feel free to request features and report
+bugs via issues, and contribute your own beautiful code via pull requests!
-The taskipy project is maintained by [Roy Sommer](https://github.com/illBeRoy). If you're interested in joining the team, feel free to let me know!
+The taskipy2 project is maintained by [Eugene Triguba](mailto:hello@eugenetriguba.com).