Invoke Lint

Invokes Python dev tools at once.

Attention

• The development status of this package is Beta now. It may not be able to keep backward compatibility. Be careful to use, especially for CI.
• Currently, each commands require to run in project home directory.

Advantage

1. Covers major development tools and they are optional to install
2. Quick response for developer, slow but detail for CI
3. Available to place commands into your selected namespace

1. Covers major development tools and they are optional to install

You can choose which dev tool you'll install, this package doesn't force to install each of dev tools. It helps you to avoid conflicts or breaking your project's dependencies.

Supporting tools:

Linters:

• Ruff
• Bandit
• Cohesion
• dodgy
• Flake8
• mypy
• Pylint
• Semgrep
• Xenon (Optional, xenon extra)
• radon (Optional, xenon extra)
• pydocstyle (Optional, style-legacy extra)

Formatters:

• docformatter
• Ruff
• autoflake (If you want to use it instead of Ruff, style-legacy extra)
• isort (If you want to use it instead of Ruff, style-legacy extra)
• Black (If you want to use it instead of Ruff, style-legacy extra)

For test and coverage:

• pytest
• Coverage.py

Package build:

• build

2. Quick response for developer, slow but detailed for CI

The commands for each kind of tasks are designed as unified into 2 main commands:

• For developer: Runs only quick responsive dev tools at once
• For CI (or final check): Runs slow but detailed responsive tools at once

3. Available to place commands into your selected namespace

This doesn't pollute your comfortable namespaces of command line tools. Thanks to Invoke, you can place commands into your selected namespace. (See: Quickstart)

Representative commands

(Note that the namespaces of following commands can be changed as you like. See: Quickstart)

inv style

Formats code by following tools at once:

1. docformatter
2. Ruff format
3. Ruff check --fix

Optionally, you can use autoflake, isort, and Black instead of Ruff format by inv style --no-ruff:

1. docformatter
2. autoflake
3. isort
4. Black
5. Ruff check --fix

• inv style --check can only check.
• inv style --ruff can skip ruff check --fix.

inv lint

Runs following fast linters at once:

1. Ruff
2. Bandit
3. dodgy
4. Flake8

The format task (described later) also run before running above linters. You can skip them by --skip-format option. Use --xenon to enable Xenon (requires xenon extra), and --pydocstyle to enable pydocstyle (requires style-legacy extra).

inv lint.deep

Runs following slow but detailed linters at once:

1. mypy
2. Pylint
3. Semgrep

inv lint.radon

Reports radon both code complexity and maintainability index. (Requires xenon extra)

inv test

Runs fast tests (which is not marked @pytest.mark.slow) by pytest.

See:

• How to mark test functions with attributes — pytest documentation
• Working with custom markers — pytest documentation

inv test.all

Runs all tests including those marked @pytest.mark.slow by pytest.

inv test.cov

Runs all tests and report those coverage by pytest and Coverage.py.

It also can dump the coverage as XML or HTML format.

inv dist

Builds source and wheel packages into dist/ directory by build.
(Currently, not support in Windows)

See:

• Building and Distributing Packages with Setuptools - setuptools latest documentation
• Package Discovery and Namespace Packages - setuptools latest documentation

Quickstart

1. Install

We should use uv or one of the dependency management tools to resolve dependencies of many dev tools.

invokelint publishes its supported tools as pip extras, so you can pull them in directly. For example, in case when we use uv, pyproject.toml is like below:

[dependency-groups]
dev = [
    "invokelint[basic]",
]

Available extras:

then:

uv sync
source .venv/bin/activate

2. Implement

Create tasks.py in project directory:

"""Tasks for maintaining the project.

Execute 'invoke --list' for guidance on using Invoke
"""
from invoke import Collection

from invokelint import dist, lint, path, style, test

ns = Collection()
ns.add_collection(dist)
ns.add_collection(lint)
ns.add_collection(path)
ns.add_collection(style)
ns.add_collection(test)

Commands may be explicitly place with a different name than they were originally given via a name kwarg (or the 2nd regular arg):

ns.add_collection(lint, 'namespace-you-wish')

See: Constructing namespaces — Invoke documentation

3. Check installation

inv --list

4. Setup target package

This package reuses setuptools settings for package discovery for linting, formatting, and measuring coverage. You can check which package are discovered by setuptools and your project's settings, by following command:

$ inv path
Setuptools detected packages: ['invokelint', 'invokelint.path']
Root packages: ['invokelint']
Setuptools detected Python modules: ['setup', 'tasks']
Existing test packages: ['tests']
Python file or directories to lint: ['invokelint', 'setup.py', 'tasks.py', 'tests']
Python file or directories to lint excluding test packages: ['invokelint', 'setup.py', 'tasks.py']

If result is not your expected, follow official documentation of setuptools to configure pyproject.toml (recommended), setup.cfg, or setup.py.

See: Package Discovery and Namespace Packages - setuptools latest documentation

5. Set up CI/CD workflows

This package provides reusable GitHub Actions workflows. Create the following files in .github/workflows/:

.github/workflows/test.yml — runs tests and linters on push/PR to main:

name: Test
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
permissions:
  contents: read
jobs:
  call-workflow-test:
    uses: yukihiko-shinoda/reusable-workflow-invoke-lint-test/.github/workflows/workflow.yml@v1
    with:
      support-python-versions: "[ '3.14', '3.13', '3.12', '3.11', '3.10' ]"
  call-workflow-lint:
    uses: yukihiko-shinoda/reusable-workflow-invoke-lint-lint/.github/workflows/workflow.yml@v1

.github/workflows/qlty.yml — uploads coverage to Qlty on push to main:

on:
  push:
    branches:
      - main
# For OIDC token exchange with Qlty:
# - Configuring OpenID Connect in cloud providers - GitHub Docs
#   https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-cloud-providers#adding-permissions-settings
permissions:
  contents: read
  id-token: write
jobs:
  analyze:
    uses: yukihiko-shinoda/reusable-workflow-invoke-lint-qlty/.github/workflows/workflow.yml@v1
    permissions:
      contents: read
      id-token: write

.github/workflows/deploy.yml — publishes to PyPI on version tag push (v*.*.*):

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
permissions:
  contents: read
jobs:
  call-workflow:
    uses: yukihiko-shinoda/reusable-workflow-invoke-lint-deploy/.github/workflows/workflow.yml@v1
    secrets:
      pypi_password: ${{ secrets.pypi_password }}

Check the respective repositories for the latest commit hashes if you want to use them for lock:

• reusable-workflow-invoke-lint-test
• reusable-workflow-invoke-lint-lint
• reusable-workflow-invoke-lint-qlty
• reusable-workflow-invoke-lint-deploy

How do I...

Suppress B101: assert_used in Bandit and assert (S101) in Ruff only in test files?

Set below configuration in pyproject.toml:

[tool.bandit.assert_used]
skips = ["tests/*"]

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"]

Note that invoke-lint executes Bandit with option --configfile=pyproject.toml, so upper configuration will be applied.

See: Configuration — Bandit documentation

Credits

This package was created with Cookiecutter and the yukihiko-shinoda/cookiecutter-pypackage project template.