Package: taskipy
GeneralRequirementsUsageInstallationAdding TasksRunning TasksPassing Command Line Args to TasksComposing TasksGrouping Subtasks TogetherPre Task HookPost Task HookUsing VariablesString FormattingAlways Use VariablesRecursive VariablesUsing Taskipy Without PoetryInstalling With PIPRunning TasksAdvanced Use CasesMaintainers :construction:Contributors :sparkles:GeneralThe complementary task runner for python.Every development pipeline has tasks, such astest,lintorpublish. 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:python-munittesttests/test_*.pyYou can create a task calledtestand simply run:poetryruntasktestOr (if you're not using poetry):tasktestIn addition, you can compose tasks and group them together, and also create dependencies between them.This project is heavily inspired by npm'srun script command.RequirementsPython 3.6 or newer.Your project directory should include a validpyproject.tomlfile, as specified inPEP-518.UsageInstallationTo install taskipy as a dev dependency, simply run:poetryadd--devtaskipyFor Anaconda Python-based environments, taskipy is also available via conda-forge:condainstall-cconda-forgetaskipyAdding TasksIn yourpyproject.tomlfile, 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.There are two ways to define tasks. The easy way is to simply write the command down as a string:pyproject.toml[tool.taskipy.tasks]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:pyproject.toml[tool.taskipy.tasks]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.Running TasksIn order to run a task, run the following command in your terminal:$poetryruntasktestYou can also list all existing tasks by running the following:$poetryruntask--listtestpython-munittesttests/test_*.py
lintpylintteststaskipyIf you declared your task explicitly, you will see the description of the task by the side of the task's name:$poetryruntask--listtestrunsallunittests
lintconfirmscodestyleusingpylintPassing Command Line Args to TasksIf 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:poetryruntasktest-hIs equivalent to running:python-munittesttests/test_*.py-hAnd 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 TasksGrouping Subtasks TogetherSome tasks are composed of multiple subtasks. Instead of writing plain shell commands and stringing them together, you can break them down into multiple subtasks:[tool.taskipy.tasks]lint_pylint="pylint tests taskipy"lint_mypy="mypy tests taskipy"And then create a composite task:[tool.taskipy.tasks]lint="task lint_pylint && task lint_mypy"lint_pylint="pylint tests taskipy"lint_mypy="mypy tests taskipy"Pre Task HookTasks might also depend on one another. For example, tests might require some binaries to be built. Take the two following commands, for instance:[tool.taskipy.tasks]test="python -m unittest tests/test_*.py"build="make ."You could make tests depend on building, by using thepretask hook:[tool.taskipy.tasks]pre_test="task build"test="python -m unittest tests/test_*.py"build="make ."The pretask hook looks forpre_<task_name>task for a giventask_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 HookFrom 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:[tool.taskipy.tasks]test="python -m unittest tests/test_*.py"lint="pylint tests taskipy"You could make tests trigger linting, by using theposttask hook:[tool.taskipy.tasks]test="python -m unittest tests/test_*.py"post_test="task lint"lint="pylint tests taskipy"The posttask hook looks forpost_<task_name>task for a giventask_name. It will run it after running the task itself. If the task failed, then taskipy will not run the posttask hook.Using VariablesIn some cases, you might find yourself passing the same arguments over and over again. Let us take a look at the following tasks:[tool.taskipy.tasks]lint="pylint path/to/my_module"black="black path/to/my_module"As you can see, we provide the same path argument to bothpylintandblack.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:[tool.taskipy.variables]path="path/to/my_module"[tool.taskipy.tasks]lint={cmd="pylint {path}",use_vars=true}black={cmd="pylint {path}",use_vars=true}We have made the following changes to our configuration:We declared variables undertool.taskipy.variablesWe flagged the relevant task usinguse_varsto note that they should use the variablesWe replaced the repeating path with a{path}variableString FormattingThe formatting of the task commands uses python's ownstring.formatmethod, and therefore supports everything that python'sformatted string literalslet you do.Always Use VariablesUsing variables is opt-in, which means that by default commands donotuse them, and you will have to turn them on a task to task basis.If you want to turn onuse_varsglobally, all you need to do is to declare that under taskipy'ssettingstable:[tool.taskipy.settings]use_vars=true[tool.taskipy.variables]path="path/to/my_module"[tool.taskipy.tasks]lint="pylint {path}"black="black {path}"Recursive VariablesIf 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 therecursivekey totrue.[tool.taskipy.settings]use_vars=true[tool.taskipy.variables]src_dir="src"package_dir={var="{src_dir}/package",recursive=true}[tool.taskipy.tasks]echo="echo {package_dir}"In this example, we could runtask echoand we would then seesrc/package.Using Taskipy Without PoetryTaskipy was created with poetry projects in mind, but actually only requires a validpyproject.tomlfile in your project's directory. As a result, you can use it even without poetry:Installing With PIPInstall taskipy on your machine or in your virtualenv using:pipinstalltaskipyRunning TasksHead into your project's directory (don't forget to activate virtualenv if you're using one), and run the following command:taskTASKWhereTASKis the name of your task.Advanced Use CasesIf you have a more specific use case, you might not be the first to run into it! Head over to theADVANCED_FEATURESdoc, and look it up.Maintainers :construction:Roy SommerEugene TrigubaContributors :sparkles:Thanks goes to these wonderful people (emoji key):RobinFrcd💻Bernardas Ališauskas💻This project follows theall-contributorsspecification. Contributions of any kind welcome!