The configuration#
This document lists all options to configure pytask with a pyproject.toml
file.
The basics#
To learn about the basics visit the tutorial.
Examples for the TOML specification be found here or in PEP 518.
The configuration values are set under the [tool.pytask.ini_options]
section to mimic
the old ini configurations and to allow pytask leveraging the full potential of the TOML
format in the future.
[tool.pytask.ini_options]
editor_url_scheme = "vscode"
The options#
- check_casing_of_paths#
Since pytask encourages platform-independent reproducibility, it will raise a warning if you used a path with incorrect casing on a case-insensitive file system. For example, the path
TeXt.TxT
will match the actual filetext.txt
on case-insensitive file systems (usually Windows and macOS), but not on case-sensitive systems (usually Linux).If you have very strong reasons for relying on this inaccuracy, although, it is strongly discouraged, you can deactivate the warning in the configuration file with
check_casing_of_paths = false
Note
An error is only raised on Windows when a case-insensitive path is used. Contributions are welcome to also support macOS.
- database_url#
pytask uses a database to keep track of tasks, products, and dependencies over runs. By default, it will create an SQLite database in the project’s root directory called
.pytask/pytask.sqlite3
. If you want to use a different name or a different dialect supported by sqlalchemy, use eitherpytask build --database-url
ordatabase_url
in the config.database_url = "sqlite:///.pytask/pytask.sqlite3"
Relative paths for SQLite databases are interpreted as either relative to the configuration file or the root directory.
- editor_url_scheme#
Depending on your terminal, pytask is able to turn task ids into clickable links to the modules in which tasks are defined. By default, following the link will open the module with your default application. It is done with
editor_url_scheme = "file"
If you use
vscode
orpycharm
instead, the file will be opened in the specified editor and the cursor will also jump to the corresponding line.editor_url_scheme = "vscode" # or editor_url_scheme = "pycharm"
For complete flexibility, you can also enter a custom url which can use the variables
path
andline_number
to open the file.editor_url_scheme = "editor://{path}:{line_number}"
Maybe you want to contribute this URL scheme to make it available to more people.
To disable links, use
editor_url_scheme = "no_link"
- ignore#
pytask can ignore files and directories and exclude some tasks or reduce the duration of the collection.
To ignore some file/folder via the command line, use the
--ignore
flag multiple times.$ pytask --ignore some_file.py --ignore some_directory/*
Or, use the configuration file:
# For single entries only. ignore = "some_file.py" # Or single and multiple entries. ignore = ["some_directory/*", "some_file.py"]
- markers#
pytask uses markers to attach additional information to task functions. To see which markers are available, type
$ pytask markers
on the command-line interface.
If you use a marker which has not been configured, you will get a warning. To silence the warning and document the marker, provide the following information in your pytask configuration file.
[tool.pytask.ini_options.markers] wip = "Work-in-progress. These are tasks which I am currently working on."
- n_entries_in_table#
You can set the number of entries displayed in the live table during the execution to any positive integer including zero.
$ pytask build --n-entries-in-table 10
- sort_table#
You can decide whether the entries displayed in the live table are sorted alphabetically once all tasks have been executed, which can be helpful when working with many tasks. Use either
true
orfalse
. This option is only supported in the configuration file.sort_table = false # default: true
- paths#
If you want to collect tasks from specific paths without passing the names via the command line, you can add the paths to the configuration file. Paths passed via the command line will overwrite the configuration value.
# For single entries only. paths = "src" # Or single and multiple entries. paths = ["folder_1", "folder_2/task_2.py"]
- show_errors_immediately#
If you want to print the exception and tracebacks of errors as soon as they occur, set this value to true.
pytask build --show-errors-immediately
show_errors_immediately = true
- show_locals#
If you want to print local variables of each stack frame in the tracebacks, set this value to true.
pytask build --show-locals
show_locals = true
- strict_markers#
If you want to raise an error for unregistered markers, pass
pytask build --strict-markers
or set the option to a truthy value.
strict_markers = true
- task_files#
Change the pattern which identify task files.
task_files = "task_*.py" # default task_files = ["task_*.py", "tasks_*.py"]