aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2022-02-06 05:53:02 -0600
committerGitHub <noreply@github.com>2022-02-06 13:53:02 +0200
commit8ee47d5a4db18d9aa5a8fcac2cd90c8f360266d3 (patch)
treecd5f59455c4de9753de0c13194c1a04cacd241ca /README.md
parentUpdate README.md (diff)
downloadtaskipy2-8ee47d5a4db18d9aa5a8fcac2cd90c8f360266d3.zip
Fix maintainers/contributors TOC links (#42)
Diffstat (limited to 'README.md')
-rw-r--r--README.md79
1 files changed, 62 insertions, 17 deletions
diff --git a/README.md b/README.md
index 7080ebf..5a955d4 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,30 @@
<p align="center">
-
-<img src="https://github.com/illBeRoy/taskipy/raw/master/logo.svg" width="150" />
-
+ <img src="./logo.svg" width="150" />
</p>
- [General](#general)
- [Requirements](#requirements)
- [Usage](#usage)
- * [Installation](#installation)
- * [Adding Tasks](#adding-tasks)
- * [Running Tasks](#running-tasks)
- * [Passing Command Line Args to Tasks](#passing-command-line-args-to-tasks)
- * [Composing Tasks](#composing-tasks)
- * [Using Variables](#using-variables)
- * [Using Taskipy Without Poetry](#using-taskipy-without-poetry)
- * [Advanced Use Cases](#advanced-use-cases)
-- [Maintainers 🚧](#maintainers---)
-- [Contributors ✨](#contributors--)
+ - [Installation](#installation)
+ - [Adding Tasks](#adding-tasks)
+ - [Running Tasks](#running-tasks)
+ - [Passing Command Line Args to Tasks](#passing-command-line-args-to-tasks)
+ - [Composing Tasks](#composing-tasks)
+ - [Grouping Subtasks Together](#grouping-subtasks-together)
+ - [Pre Task Hook](#pre-task-hook)
+ - [Post Task Hook](#post-task-hook)
+ - [Using Variables](#using-variables)
+ - [String Formatting](#string-formatting)
+ - [Always Use Variables](#always-use-variables)
+ - [Using Taskipy Without Poetry](#using-taskipy-without-poetry)
+ - [Installing With PIP](#installing-with-pip)
+ - [Running Tasks](#running-tasks-1)
+ - [Advanced Use Cases](#advanced-use-cases)
+- [Maintainers :construction:](#maintainers-construction)
+- [Contributors :sparkles:](#contributors-sparkles)
## General
+
[![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/)
[![ci](https://img.shields.io/github/workflow/status/illberoy/taskipy/Taskipy%20Test%20CI?style=flat-square)](https://github.com/illBeRoy/taskipy/actions?query=workflow%3A%22Taskipy+Test+CI%22)
@@ -29,16 +35,19 @@
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:
+
```bash
python -m unittest tests/test_*.py
```
You can create a task called `test` and simply run:
+
```bash
poetry run task test
```
Or (if you're not using poetry):
+
```bash
task test
```
@@ -48,18 +57,23 @@ In addition, you can compose tasks and group them together, and also create depe
This project is heavily inspired by npm's [run script command](https://docs.npmjs.com/cli/run-script).
## Requirements
+
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/).
## Usage
+
### Installation
+
To install taskipy as a dev dependency, simply run:
+
```bash
poetry add --dev taskipy
```
-### Adding Tasks
+### 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.
@@ -67,6 +81,7 @@ The section is a key-value map, from the names of the task to the actual command
There are two ways to define tasks. The easy way is to simply write the command down as a string:
__pyproject.toml__
+
```toml
[tool.taskipy.tasks]
test = "python -m unittest tests/test_*.py"
@@ -76,6 +91,7 @@ lint = "pylint tests taskipy"
Alternatively, you can define tasks more explicitly by declaring both the command and a helpful description using an inline table:
__pyproject.toml__
+
```toml
[tool.taskipy.tasks]
test = { cmd = "python -m unittest tests/test_*.py", help = "runs all unit tests" }
@@ -85,12 +101,15 @@ 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.
### Running Tasks
+
In order to run a task, run the following command in your terminal:
+
```bash
$ poetry run task test
```
You can also list all existing tasks by running the following:
+
```bash
$ poetry run task --list
test python -m unittest tests/test_*.py
@@ -98,6 +117,7 @@ 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:
+
```bash
$ poetry run task --list
test runs all unit tests
@@ -105,14 +125,17 @@ 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.
For example, running the above task like this:
+
```bash
poetry run task test -h
```
Is equivalent to running:
+
```bash
python -m unittest tests/test_*.py -h
```
@@ -122,8 +145,11 @@ 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.
### 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:
+
```toml
[tool.taskipy.tasks]
lint_pylint = "pylint tests taskipy"
@@ -131,6 +157,7 @@ lint_mypy = "mypy tests taskipy"
```
And then create a composite task:
+
```toml
[tool.taskipy.tasks]
lint = "task lint_pylint && task lint_mypy"
@@ -139,7 +166,9 @@ 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:
+
```toml
[tool.taskipy.tasks]
test = "python -m unittest tests/test_*.py"
@@ -147,6 +176,7 @@ build = "make ."
```
You could make tests depend on building, by using the **pretask hook**:
+
```toml
[tool.taskipy.tasks]
pre_test = "task build"
@@ -157,7 +187,9 @@ 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.
#### Post Task Hook
+
From time to time, you might want to run a task in conjuction 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]
test = "python -m unittest tests/test_*.py"
@@ -165,6 +197,7 @@ lint = "pylint tests taskipy"
```
You could make tests trigger linting, by using the **posttask hook**:
+
```toml
[tool.taskipy.tasks]
test = "python -m unittest tests/test_*.py"
@@ -175,6 +208,7 @@ 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.
### 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:
```toml
@@ -197,14 +231,17 @@ black = { cmd = "pylint {path}", use_vars = true }
```
We have made the following changes to our configuration:
+
1. We declared variables under `tool.taskipy.variables`
2. We flagged the relevant task using `use_vars` to note that they should use the variables
3. We replaced the repeating path with a `{path}` variable
#### 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.
#### 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.
If you want to turn on `use_vars` globally, all you need to do is to declare that under taskipy's **settings** table:
@@ -222,25 +259,32 @@ black = "black {path}"
```
### 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 eithout poetry:
#### Installing With PIP
+
Install taskipy on your machine or in your virtualenv using:
+
```bash
pip install taskipy
```
#### Running Tasks
+
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
```
+
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.
-## Maintainers 🚧
+## Maintainers :construction:
<table>
<tr>
@@ -248,7 +292,7 @@ If you have a more specific use case, you might not be the first to run into it!
</tr>
</table>
-## Contributors ✨
+## Contributors :sparkles:
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -267,4 +311,5 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
+specification. Contributions of any kind welcome!