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 file text.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 either pytask build --database-url or database_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 or pycharm 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 and line_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"
hook_module#

Register additional modules containing hook implementations.

hook_modules = ["myproject.hooks", "hooks.py"]

You can use module names and paths as values. Relative paths are assumed to be relative to the configuration file or the current working directory.

This how-to guide has more information.

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 or false. 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"]