Skip to content

Format

invoke_tasklib.formatting

Code, docstring and shell script formatting tasks (format.*).

The Python code is formatted with ruff, the docstrings with docformatter and the shell scripts with shellcheck and shfmt.

Naming convention: check_<target> tasks are read-only (they fail without modifying files); fix_<target> tasks modify files in place. Every fix_<target> has a matching check_<target> (the lint of the shell scripts, check_shell, has no fixer).

The module is named formatting so that it does not shadow the format builtin; its namespace is format, see NAMESPACE.

invoke_tasklib.formatting.check_docstrings

check_docstrings(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Check docstring format with docformatter.

The files are not modified.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to docformatter.

None
paths str | None

The files or directories to check instead of paths.src.

None

Raises:

Type Description
Exit

With the code 2 if paths is not set and paths.src does not exist.

invoke_tasklib.formatting.check_python

check_python(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Check code format with ruff without modifying files.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to ruff.

None
paths str | None

The files or directories to check instead of the whole project (.).

None

invoke_tasklib.formatting.check_shell

check_shell(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Check shell scripts with shellcheck.

The scripts are the *.sh files of the project (the files that git tracks, or all the files outside the excluded directories when the project is not a git work tree). If there is none, the task prints a ⏭️ line and succeeds. The files are not modified.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to shellcheck.

None
paths str | None

The scripts to check instead of every *.sh file of the project.

None

invoke_tasklib.formatting.check_shell_format

check_shell_format(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Check the format of shell scripts with shfmt.

It is the read-only counterpart of format.fix-shell: shfmt -d prints a diff and fails if a script would be reformatted, but never changes a file. Like format.check-shell, it skips (and succeeds) when the project has no *.sh file.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to shfmt.

None
paths str | None

The scripts to check instead of every *.sh file of the project.

None

invoke_tasklib.formatting.fix_docstrings

fix_docstrings(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Format docstrings in source code with docformatter.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to docformatter.

None
paths str | None

The files or directories to format instead of paths.src.

None

Raises:

Type Description
Exit

With the code 2 if paths is not set and paths.src does not exist.

Note

This modifies files in place. Ensure your work is committed before running this task.

invoke_tasklib.formatting.fix_python

fix_python(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Format code in place with ruff.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to ruff.

None
paths str | None

The files or directories to format instead of the whole project (.).

None
Note

This modifies files in place. Ensure your work is committed before running this task.

invoke_tasklib.formatting.fix_shell

fix_shell(
    c: Context,
    *,
    args: str | None = None,
    paths: str | None = None,
) -> None

Format shell scripts in place with shfmt.

It runs shfmt -l -w on the *.sh files of the project, so it lists the files that it rewrites. It skips (and succeeds) when there is no script.

Parameters:

Name Type Description Default
c Context

The invoke context.

required
args str | None

Extra arguments passed to shfmt.

None
paths str | None

The scripts to format instead of every *.sh file of the project.

None
Note

This modifies files in place. Ensure your work is committed before running this task.