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¶

SQLite is the legacy state format. pytask uses pytask.lock as the primary state backend for change detection. When no lockfile exists, pytask reads the configured database and writes pytask.lock. For downgrade compatibility, pytask build also keeps the legacy database state updated.

The database_url option remains for backward compatibility and controls the legacy database location and dialect (supported by sqlalchemy).

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¶

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.

paths = ["folder_1", "folder_2/task_2.py"]

pdbcls¶

If you want to use a custom debugger instead of the standard Python debugger, you can specify it with the pdbcls option. The value must be in the format module_name:class_name.

$ pytask build --pdbcls=IPython.terminal.debugger:TerminalPdb

Or, use the configuration file:

pdbcls = "IPython.terminal.debugger:TerminalPdb"

This is particularly useful when working with enhanced debuggers like pdbpp or pdbp that provide additional features such as syntax highlighting and tab completion:

pdbcls = "pdbp:Pdb"

The custom debugger will be used when you invoke the --pdb flag for post-mortem debugging or when using breakpoint() in your task code.

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"]