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
|
None
|
Raises:
| Type | Description |
|---|---|
Exit
|
With the code 2 if |
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 |
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 |
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
|
None
|
Raises:
| Type | Description |
|---|---|
Exit
|
With the code 2 if |
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 |
None
|
Note
This modifies files in place. Ensure your work is committed before running this task.