Using the CLI¶

The CLI of dwas is the main interface with which you would normally interact. Using it efficiently is key, and we aim to make it as natural and easy to use as possible.

Here we will be focusing on explaining some parts of it that might not be as easy to discover as we would like.

Note

The output from the cli examples can be reproduces by running it in the docs/examples/cli directory.

But first, this is the full help for reference:

$ dwas --help
usage: dwas [-h] [--version] [--config CONFIG] [-o] [-e EXCEPT_STEPS] [-l]
            [--list-dependencies] [-v] [-q] [-j JOBS] [--setup-only |
            --no-setup] [--ff] [-c] [--colors | --no-colors]
            [--cache-path CACHE_PATH] [--log-path LOG_PATH]
            [--skip-missing-interpreters]
            [step [--args ARGS]] ... [step -- ARGS]

positional arguments:
  steps                 Specifies the steps to run, and optionally specify
                        arguments for the steps. Can be specified either as
                        `<step> --args='<args> ...'`, or `<step> -- <args>`

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --config CONFIG       The configuration file to use (default: ./dwasfile.py)
  -o, --only            Only run the specified step(s), even if they have
                        dependencies
  -e, --except EXCEPT_STEPS
                        Don't run the following step(s), even if they are
                        required
  -l, --list            Only list all available steps. Don't execute
  --list-dependencies   When listing, also show step dependencies
  -v, --verbose         Be more verbose
  -q, --quiet           Be more quiet
  -j, --jobs JOBS       Number of jobs to run in parallel, 0 uses the number
                        of cpus on the machine (default: 1)
  --setup-only          Only run setup actions, don't run
  --no-setup            Don't run setup actions, only the rest
  --ff, --fail-fast     Stop at the first error
  -c, --clean           Clear the cache before running
  --colors, --no-colors
                        Force or prevent a colored output (default: true if
                        stdin is a tty, false otherwise)
  --cache-path CACHE_PATH
                        Directory where to store the persistent cache
                        (default: ./.dwas)
  --log-path LOG_PATH   Directory where to store the log files (default:
                        <cache-path>/logs)
  --skip-missing-interpreters
                        Don't report a missing interpreter as a failure, and
                        skip the step instead

Environment variables:
  DWAS_ADDOPTS		Extra command line arguments, prepended to other arguments

Getting to know a project¶

When working on a new project, you often need to understand what testing setup or documentation building exist for this project.

dwas makes this easy. In order to know what automation is available for a project, you can run:

$ dwas --list
dwas > Available steps (* means selected, - means skipped):
dwas > 	- black:fix   
dwas > 	- fix         
dwas > 	- isort:fix   
dwas > 	* lint        
dwas > 	* mypy        
dwas > 	* package     
dwas > 	* pylint      
dwas > 	* pytest      
dwas > 	* pytest[3.10]
dwas > 	* pytest[3.11]
dwas > 	* pytest[3.9] 
dwas > Logs can be found at /home/docs/checkouts/readthedocs.org/user_builds/dwas/checkouts/v0.1.0/docs/examples/cli/.dwas/logs/main.log

You can also know which steps run in which order:

$ dwas --list-dependencies
dwas > Available steps (* means selected, - means skipped):
dwas > 	- black:fix    --> isort:fix                              
dwas > 	- fix          --> black:fix, isort:fix                   
dwas > 	- isort:fix                                               
dwas > 	* lint         --> mypy, pylint                           
dwas > 	* mypy                                                    
dwas > 	* package                                                 
dwas > 	* pylint                                                  
dwas > 	* pytest       --> pytest[3.10], pytest[3.11], pytest[3.9]
dwas > 	* pytest[3.10] --> package                                
dwas > 	* pytest[3.11] --> package                                
dwas > 	* pytest[3.9]  --> package                                
dwas > Logs can be found at /home/docs/checkouts/readthedocs.org/user_builds/dwas/checkouts/v0.1.0/docs/examples/cli/.dwas/logs/main.log

It is also possible to get more information on each step, providing the project did add a description. For this, use a more verbose mode:

$ dwas --list --verbose
dwas > Pipeline definition found at ./dwasfile.py
dwas > Step pytest[3.9] requested a passthrough of environment variable TERM, but it is not in the environment
dwas > Step pytest[3.10] requested a passthrough of environment variable TERM, but it is not in the environment
dwas > Step pytest[3.11] requested a passthrough of environment variable TERM, but it is not in the environment
dwas > Available steps (* means selected, - means skipped):
dwas > 	- black:fix   
dwas > 	- fix         	[Fix all auto-fixable issues on the project]
dwas > 	- isort:fix   
dwas > 	* lint        	[Run linter on the project]
dwas > 	* mypy        
dwas > 	* package     
dwas > 	* pylint      
dwas > 	* pytest      	[Run tests for all supported python versions]
dwas > 	* pytest[3.10]	[Run tests for python 3.10]
dwas > 	* pytest[3.11]	[Run tests for python 3.11]
dwas > 	* pytest[3.9] 	[Run tests for python 3.9]
dwas > Logs can be found at /home/docs/checkouts/readthedocs.org/user_builds/dwas/checkouts/v0.1.0/docs/examples/cli/.dwas/logs/main.log

Controlling steps execution more closely¶

You might sometimes want to control more explicitly which steps run or not, or even some part of steps.

dwas offer multiple ways of getting more control:

Preventing some steps to run using --except <step>
Running only some specific steps using --only
Only running the setup part of each step using --setup-only
Skipping the setup part of each step, with --no-setup
Aborting upon the first failure --fail-fast

–except <step>¶

For example, you might be working on writing tests, and the sources of your project are not changing, at which point, you might not want to re-run the packaging step. This is where --except is useful

dwas --exclude package pytest[3.10]

–only¶

If you want to run a single (or multiple) step(s) explicitly, without any previous one, you can use --only:

dwas --only pytest[3.9] pytest[3.10]

–setup-only¶

If you want to just run the setup phase of your steps (e.g. to create the virtual environments and install dependencies, without running anything else), you can use --setup-only

dwas --setup-only pytest

–no-setup¶

This is the corollary to --setup-only, and allows you to skip the setup phase. This can be useful if you know your environments are already correct, and you want your steps to run faster.

Note

dependent setup from previous step always run when using --no-setup

dwas --no-setup pytest

–fail-fast¶

In the cases you don’t want to wait when you get an error, and just want to fix it as soon as possible, you can use --fail-fast, which will abort a run at the first issue.

dwas --fail-fast pytest