Functional Interfaces¶

This page documents the public functional interfaces for using pytask from Python.

For end-to-end usage examples, see the how-to guide on the functional interface.

Build Workflow¶

pytask.build(, capture=CaptureMethod.FD, check_casing_of_paths=True, config=None, database_url='', debug_pytask=False, disable_warnings=False, dry_run=False, editor_url_scheme='file', explain=False, expression='', force=False, ignore=(), marker_expression='', max_failures=float('inf'), n_entries_in_table=15, paths=(), pdb=False, pdb_cls='', log_date_format='%H:%M:%S', log_cli=False, log_cli_date_format=None, log_cli_format=None, log_cli_level=None, log_file=None, log_file_date_format=None, log_file_format=None, log_file_level=None, log_file_mode='w', log_format='%(levelname)-8s %(name)s:%(filename)s:%(lineno)d %(message)s', log_level=None, s=False, show_capture=ShowCapture.ALL, show_errors_immediately=False, show_locals=False, show_traceback=True, sort_table=True, stop_after_first_failure=False, strict_markers=False, tasks=(), task_files=('task_.py',), trace=False, verbose=1, **kwargs) ¶

Run pytask.

This function is the programmatic interface to pytask build.

Parameters:

Name	Type	Description	Default
`capture`	`Literal['fd', 'no', 'sys', 'tee-sys'] \| CaptureMethod`	The capture method for stdout and stderr.	`FD`
`check_casing_of_paths`	`bool`	Whether errors should be raised when file names have different casings.	`True`
`config`	`Path \| None`	A path to the configuration file.	`None`
`database_url`	`str`	A URL to the database that tracks the status of tasks.	`""`
`debug_pytask`	`bool`	Whether debug information should be shown.	`False`
`disable_warnings`	`bool`	Whether warnings should be disabled and not displayed.	`False`
`dry_run`	`bool`	Whether a dry-run should be performed that shows which tasks need to be rerun.	`False`
`editor_url_scheme`	`Literal['no_link', 'file', 'vscode', 'pycharm'] \| str`	A URL scheme that allows task, node, and file names to become clickable links.	`'file'`
`explain`	`bool`	Explain why tasks need to be executed by showing what changed.	`False`
`expression`	`str`	Same as `-k` on the command line. Select tasks via expressions on task ids.	`""`
`force`	`bool`	Run tasks even though they would be skipped since nothing has changed.	`False`
`ignore`	`Iterable[str]`	A pattern to ignore files or directories. Refer to `pathlib.Path.match` for more information.	`()`
`marker_expression`	`str`	Same as `-m` on the command line. Select tasks via marker expressions.	`""`
`max_failures`	`float`	Stop after some failures.	`float("inf")`
`n_entries_in_table`	`int`	How many entries to display in the table during the execution. Tasks which are running are always displayed.	`15`
`paths`	`Path \| Iterable[Path]`	A path or collection of paths where pytask looks for the configuration and tasks.	`()`
`pdb`	`bool`	Start the interactive debugger on errors.	`False`
`pdb_cls`	`str`	Start a custom debugger on errors. For example: `--pdbcls=IPython.terminal.debugger:TerminalPdb`	`""`
`log_date_format`	`str`	The date format used for captured logs.	`"%H:%M:%S"`
`log_cli`	`bool`	Whether log records should be streamed to the terminal while tasks run.	`False`
`log_cli_date_format`	`str \| None`	The date format used for live logs. Falls back to `log_date_format`.	`None`
`log_cli_format`	`str \| None`	The format used for live logs. Falls back to `log_format`.	`None`
`log_cli_level`	`int \| str \| None`	The level of messages streamed live to the terminal. Falls back to `log_level`.	`None`
`log_file`	`Path \| str \| None`	A path to a file where logs from executed tasks should be written.	`None`
`log_file_date_format`	`str \| None`	The date format used for exported logs. Falls back to `log_date_format`.	`None`
`log_file_format`	`str \| None`	The format used for exported logs. Falls back to `log_format`.	`None`
`log_file_level`	`int \| str \| None`	The level of messages written to the log file. Falls back to `log_level`.	`None`
`log_file_mode`	`Literal['w', 'a']`	The file mode used for the exported log file.	`"w"`
`log_format`	`str`	"%(message)s" The format used for captured logs.	`"%(levelname)-8s %(name)s:%(filename)s:%(lineno)d "`
`log_level`	`int \| str \| None`	The level of messages to capture. If not set, the logger configuration is used.	`None`
`s`	`bool`	Shortcut for `capture="no"`.	`False`
`show_capture`	`Literal['no', 'stdout', 'stderr', 'log', 'all'] \| ShowCapture`	Choose which captured output should be shown for failed tasks.	`ALL`
`show_errors_immediately`	`bool`	Show errors with tracebacks as soon as the task fails.	`False`
`show_locals`	`bool`	Show local variables in tracebacks.	`False`
`show_traceback`	`bool`	Choose whether tracebacks should be displayed or not.	`True`
`sort_table`	`bool`	Sort the table of tasks at the end of the execution.	`True`
`stop_after_first_failure`	`bool`	Stop after the first failure.	`False`
`strict_markers`	`bool`	Raise errors for unknown markers.	`False`
`tasks`	`Callable[..., Any] \| PTask \| Iterable[Callable[..., Any] \| PTask]`	A task or collection of tasks as callables or `pytask.PTask` instances.	`()`
`task_files`	`Iterable[str]`	A pattern to describe modules that contain tasks.	`("task_*.py",)`
`trace`	`bool`	Enter debugger in the beginning of each task.	`False`
`verbose`	`int`	Set pytask verbosity: 0 = quiet, 1 = default, 2 = verbose.	`1`
`**kwargs`	`Any`	Additional configuration forwarded to pytask's configuration pipeline.	`{}`

Returns:

Type	Description
`Session`	The session captures all the information of the current run.

DAG Construction¶

`pytask.build_dag(raw_config)` ¶

Build the DAG.

This function is the programmatic interface to pytask dag.