doit - Automation Tool

Warnings

• breaking Version 0.37.0 dropped support for Python 3.8 and 3.9. The minimum required Python version is now 3.10. Prior versions also dropped support for older Python versions (e.g., 0.35.0 dropped 3.6/3.7).
  Fix: Ensure your project uses Python 3.10 or newer. Check the `CHANGES` file for specific version requirements if upgrading from older `doit` releases.
• breaking Version 0.36.0 introduced several backward-incompatible changes, including the removal of the deprecated `doit.cmd_base.py:TaskLoader`, a switch from `toml` to `tomli` for configuration parsing, changes to how plugins are handled, and a restructuring of internal error classes (e.g., `CatchedException` renamed to `BaseFail`).
  Fix: Review the `CHANGES` file for version 0.36.0 on the official GitHub repository. Update custom task loaders, plugin integrations, or exception handling code accordingly. Consider adding `tomli` if directly interacting with TOML files for configuration.
• gotcha Tasks without explicitly defined `file_dep` (file dependencies) or `targets` will always be considered 'out-of-date' and re-run every time `doit` is executed, even if their actions have no side effects. This can lead to unnecessary re-execution.
  Fix: For tasks that produce output or depend on specific inputs, always specify `file_dep` and `targets` to enable `doit`'s incremental build capabilities. If a task truly should run every time, explicitly add `uptodate=False` to its return dictionary.
• gotcha Configuration files (`pyproject.toml`, `doit.cfg`, `dodo.py`'s `DOIT_CONFIG` variable) and command-line arguments have a specific precedence. Misunderstanding this hierarchy can lead to unexpected behavior where settings are not applied as intended, or `doit` fails to find tasks.
  Fix: Consult the `doit` documentation on configuration options and precedence. For global project configuration, `pyproject.toml` (`[tool.doit]` section) or a `DOIT_CONFIG` dictionary in `dodo.py` are common. Ensure paths are correctly handled, especially when using `src` layouts or non-standard `dodo.py` locations.

Install

• pip install doit Install doit

Imports

• Task Definition

  def task_my_task(): return {'actions': ['echo "hello"']}

  Tasks are typically defined as functions named `task_*` in a `dodo.py` file, which `doit` discovers and runs directly from the command line. Direct Python imports of a 'main' doit object are not the primary usage pattern.
• doit.tools

  from doit.tools import result_dep

  For advanced task configurations, utilities like `result_dep`, `run_once`, or `config_changed` are imported from `doit.tools`.
• DOIT_CONFIG

  DOIT_CONFIG = {'verbosity': 2}

  Global configuration for doit is typically set in a `DOIT_CONFIG` dictionary directly in `dodo.py` or through `pyproject.toml`. While `doit_api.doit_config` exists for programmatically creating config, directly defining the dict is common. Old modules for config factories might be deprecated.

Quickstart

Create a file named `dodo.py` with task definitions. `doit` automatically discovers tasks named `task_*`. Tasks are Python functions that return a dictionary describing their actions, dependencies (`file_dep`), and outputs (`targets`). Running `doit` from the command line executes these tasks, honoring dependencies and skipping up-to-date tasks.

import os

def task_hello():
    """create a greeting file"""
    return {
        'actions': ['echo "Hello from doit" > hello.txt'],
        'targets': ['hello.txt'],
        'clean': True,
    }

def task_shout():
    """convert greeting to uppercase"""
    return {
        'actions': ['tr a-z A-Z < hello.txt > shout.txt'],
        'file_dep': ['hello.txt'],
        'targets': ['shout.txt'],
        'clean': True,
    }

# To run this, save as dodo.py and execute in terminal:
# $ doit
# $ cat shout.txt
# $ doit clean
# (Note: 'tr' command is Unix-like, might need alternatives on Windows)