You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
30
36
31
37
For instance, instead of running the following command:
38
+
32
39
```bash
33
40
python -m unittest tests/test_*.py
34
41
```
35
42
36
43
You can create a task called `test` and simply run:
44
+
37
45
```bash
38
46
poetry run task test
39
47
```
40
48
41
49
Or (if you're not using poetry):
50
+
42
51
```bash
43
52
task test
44
53
```
@@ -48,25 +57,31 @@ In addition, you can compose tasks and group them together, and also create depe
48
57
This project is heavily inspired by npm's [run script command](https://docs.npmjs.com/cli/run-script).
49
58
50
59
## Requirements
60
+
51
61
Python 3.6 or newer.
52
62
53
63
Your project directory should include a valid `pyproject.toml` file, as specified in [PEP-518](https://www.python.org/dev/peps/pep-0518/).
54
64
55
65
## Usage
66
+
56
67
### Installation
68
+
57
69
To install taskipy as a dev dependency, simply run:
70
+
58
71
```bash
59
72
poetry add --dev taskipy
60
73
```
61
74
62
-
### Adding Tasks
75
+
### Adding Tasks
76
+
63
77
In your `pyproject.toml` file, add a new section called `[tool.taskipy.tasks]`.
64
78
65
79
The section is a key-value map, from the names of the task to the actual command that should be run in the shell.
66
80
67
81
There are two ways to define tasks. The easy way is to simply write the command down as a string:
68
82
69
83
__pyproject.toml__
84
+
70
85
```toml
71
86
[tool.taskipy.tasks]
72
87
test = "python -m unittest tests/test_*.py"
@@ -76,6 +91,7 @@ lint = "pylint tests taskipy"
76
91
Alternatively, you can define tasks more explicitly by declaring both the command and a helpful description using an inline table:
77
92
78
93
__pyproject.toml__
94
+
79
95
```toml
80
96
[tool.taskipy.tasks]
81
97
test = { cmd = "python -m unittest tests/test_*.py", help = "runs all unit tests" }
@@ -85,34 +101,41 @@ lint = { cmd = "pylint tests taskipy", help = "confirms code style using pylint"
85
101
The explicit notation is more verbose, but provides better context to anyone who uses the task.
86
102
87
103
### Running Tasks
104
+
88
105
In order to run a task, run the following command in your terminal:
106
+
89
107
```bash
90
108
$ poetry run task test
91
109
```
92
110
93
111
You can also list all existing tasks by running the following:
112
+
94
113
```bash
95
114
$ poetry run task --list
96
115
test python -m unittest tests/test_*.py
97
116
lint pylint tests taskipy
98
117
```
99
118
100
119
If you declared your task explicitly, you will see the description of the task by the side of the task's name:
120
+
101
121
```bash
102
122
$ poetry run task --list
103
123
test runs all unit tests
104
124
lint confirms code style using pylint
105
125
```
106
126
107
127
### Passing Command Line Args to Tasks
128
+
108
129
If you want to pass command line arguments to tasks (positional or named), simply append them to the end of the task command.
109
130
110
131
For example, running the above task like this:
132
+
111
133
```bash
112
134
poetry run task test -h
113
135
```
114
136
115
137
Is equivalent to running:
138
+
116
139
```bash
117
140
python -m unittest tests/test_*.py -h
118
141
```
@@ -122,15 +145,19 @@ And will show unittest's help instead of actually running it.
122
145
> ⚠️ Note: if you are using pre \ post hooks, do notice that arguments are not passed to them, only to the task itself.
123
146
124
147
### Composing Tasks
148
+
125
149
#### Grouping Subtasks Together
150
+
126
151
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:
Tasks might also depend on one another. For example, tests might require some binaries to be built. Take the two following commands, for instance:
171
+
143
172
```toml
144
173
[tool.taskipy.tasks]
145
174
test = "python -m unittest tests/test_*.py"
146
175
build = "make ."
147
176
```
148
177
149
178
You could make tests depend on building, by using the **pretask hook**:
179
+
150
180
```toml
151
181
[tool.taskipy.tasks]
152
182
pre_test = "task build"
@@ -157,14 +187,17 @@ build = "make ."
157
187
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.
158
188
159
189
#### Post Task Hook
190
+
160
191
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:
192
+
161
193
```toml
162
194
[tool.taskipy.tasks]
163
195
test = "python -m unittest tests/test_*.py"
164
196
lint = "pylint tests taskipy"
165
197
```
166
198
167
199
You could make tests trigger linting, by using the **posttask hook**:
200
+
168
201
```toml
169
202
[tool.taskipy.tasks]
170
203
test = "python -m unittest tests/test_*.py"
@@ -175,6 +208,7 @@ lint = "pylint tests taskipy"
175
208
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.
176
209
177
210
### Using Variables
211
+
178
212
In some cases, you might find yourself passing the same arguments over and over again. Let us take a look at the following tasks:
We have made the following changes to our configuration:
234
+
200
235
1. We declared variables under `tool.taskipy.variables`
201
236
2. We flagged the relevant task using `use_vars` to note that they should use the variables
202
237
3. We replaced the repeating path with a `{path}` variable
203
238
204
239
#### String Formatting
240
+
205
241
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.
206
242
207
243
#### Always Use Variables
244
+
208
245
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.
209
246
210
247
If you want to turn on `use_vars` globally, all you need to do is to declare that under taskipy's **settings** table:
@@ -222,33 +259,40 @@ black = "black {path}"
222
259
```
223
260
224
261
### Using Taskipy Without Poetry
262
+
225
263
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:
226
264
227
265
#### Installing With PIP
266
+
228
267
Install taskipy on your machine or in your virtualenv using:
268
+
229
269
```bash
230
270
pip install taskipy
231
271
```
232
272
233
273
#### Running Tasks
274
+
234
275
Head into your project's directory (don't forget to activate virtualenv if you're using one), and run the following command:
276
+
235
277
```bash
236
278
task TASK
237
279
```
280
+
238
281
Where `TASK` is the name of your task.
239
282
240
283
### Advanced Use Cases
284
+
241
285
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.
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
254
298
@@ -267,4 +311,5 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
267
311
<!-- prettier-ignore-end -->
268
312
<!-- ALL-CONTRIBUTORS-LIST:END -->
269
313
270
-
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
314
+
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
0 commit comments