> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# branchbutler-labs/python-quality

Python code quality automation for Branch Butler.

Provides commands and jobs for formatting, linting, static analysis,
and automated PR reviews. Includes slash command support for
interactive PR workflows.

Commands:
  - install-tools: Install pinned versions of quality tools
  - format: Auto-format with Black and isort
  - lint: Comprehensive linting with pylint, flake8, mypy, bandit
  - danger: Automated PR review
  - rebase: Smart rebasing with conflict resolution

Jobs:
  - code-quality: Full quality suite with caching
  - pr-review: Automated PR review workflow


## Commands

### danger

Run comprehensive Danger-based PR automation.
Provides automated PR review with: - PR description validation - Auto-labeling by file type and PR size - Changelog enforcement - Breaking change detection - Commit message validation - Large file warnings - TODO tracking - Test file requirements - Documentation requirements


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto-label` | boolean | true | Automatically suggest labels based on changed files |
| `check-commits` | boolean | true | Validate commit message format (conventional commits) |
| `fail-on-warnings` | boolean | false | Fail the job if Danger reports warnings |
| `github-token` | env_var_name | GITHUB_TOKEN | Environment variable name containing GitHub API token |
| `max-file-size` | integer | 500000 | Maximum file size in bytes before warning |
| `max-pr-size` | integer | 500 | Maximum lines changed before warning about PR size |
| `min-description-length` | integer | 50 | Minimum PR description length to require |
| `protected-branches` | string | main,master | Comma-separated list of protected branches requiring extra checks |
| `require-changelog` | boolean | true | Require CHANGELOG updates for PRs to main/master |
| `require-tests` | boolean | false | Require test files when source files change |

### format

Format Python code with Black and isort.
This command automatically formats your Python code according to Black's opinionated style and sorts imports using isort. Optionally commits and pushes the changes to the current branch.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto-commit` | boolean | true | Automatically commit and push formatting changes |
| `isort-profile` | string | black | isort profile to use (black, django, pycharm, google, open_stack, plone, attrs, hug) |
| `line-length` | integer | 100 | Maximum line length for Black formatter |
| `paths` | string | . | Paths to format (space-separated) |

### install-tools

Install Python quality tools with pinned versions.
Installs Black, isort, pylint, flake8, mypy, and bandit with specific versions to ensure consistency across environments. Can install all tools or selectively install subsets.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `install-formatters` | boolean | true | Install Black and isort |
| `install-linters` | boolean | true | Install pylint, flake8, mypy, and bandit |

### lint

Run comprehensive Python linting and static analysis.
Executes multiple linters including pylint, flake8, mypy, and bandit to ensure code quality, style compliance, type safety, and security.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `fail-on-error` | boolean | true | Fail the job if linting errors are found |
| `max-line-length` | integer | 100 | Maximum line length for linters |
| `paths` | string | . | Paths to lint (space-separated) |
| `run-bandit` | boolean | true | Run bandit for security vulnerability scanning |
| `run-flake8` | boolean | true | Run flake8 for style guide enforcement |
| `run-mypy` | boolean | true | Run mypy for static type checking |
| `run-pylint` | boolean | true | Run pylint for code quality checks |

### rebase

Rebase the current branch onto a target branch.
Performs a git rebase with optional automatic conflict resolution for common scenarios. Useful for keeping feature branches up to date.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto-resolve-conflicts` | boolean | false | Attempt to automatically resolve simple conflicts |
| `base-branch` | string | main | Base branch to rebase onto |
| `force-push` | boolean | true | Force push the rebased branch (uses --force-with-lease for safety) |

## Jobs

### code-quality

Run a complete code quality check suite.
This job performs formatting, linting, and optionally commits changes. Includes caching for faster subsequent runs.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto-commit` | boolean | false | Automatically commit and push formatting changes |
| `checkout-code` | boolean | true | Whether to checkout repository code |
| `line-length` | integer | 100 | Maximum line length for formatters and linters |
| `lint-fail-on-error` | boolean | false | Fail the job if linting errors are found |
| `run-format` | boolean | true | Run code formatting with Black and isort |
| `run-lint` | boolean | true | Run linting with pylint, flake8, mypy, and bandit |

### pr-review

Run comprehensive automated pull request review with Danger.
Analyzes PRs for common issues and provides automated feedback including: - PR description validation - Auto-labeling suggestions - Changelog enforcement - Breaking change detection - Commit message validation - Large file warnings - TODO/FIXME tracking - Security file detection


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto-label` | boolean | true | Automatically suggest labels based on changed files |
| `check-commits` | boolean | true | Validate commit message format (conventional commits) |
| `fail-on-warnings` | boolean | false | Fail the job if Danger reports warnings |
| `max-file-size` | integer | 500000 | Maximum file size in bytes before warning |
| `max-pr-size` | integer | 500 | Maximum lines changed before warning about PR size |
| `min-description-length` | integer | 50 | Minimum PR description length to require |
| `protected-branches` | string | main,master | Comma-separated list of protected branches requiring extra checks |
| `require-changelog` | boolean | true | Require CHANGELOG updates for PRs to main/master |
| `require-tests` | boolean | false | Require test files when source files change |

## Executors

### python

Python executor with pre-installed tools and optimized caching.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource-class` | enum | medium | Resource class for the executor |
| `tag` | string | 3.11 | Python version tag (e.g., "3.11", "3.10", "3.9") |

## Examples

### basic-formatting

Basic code formatting with auto-commit

```yaml
version: '2.1'
orbs:
  python-quality: branchbutler-labs/python-quality@1.2.0
workflows:
  format-code:
    jobs:
      - python-quality/code-quality:
          auto-commit: true
          run-format: true
          run-lint: false
```

### custom-command

Using individual commands in custom jobs

```yaml
version: '2.1'
orbs:
  python-quality: branchbutler-labs/python-quality@1.2.0
jobs:
  my-custom-job:
    executor: python-quality/python
    steps:
      - checkout
      - python-quality/install-tools:
          install-formatters: true
          install-linters: true
      - python-quality/format:
          auto-commit: true
          line-length: 120
      - python-quality/lint:
          fail-on-error: true
workflows:
  main:
    jobs:
      - my-custom-job
```

### full-quality-check

Complete code quality check with formatting and linting

```yaml
version: '2.1'
orbs:
  python-quality: branchbutler-labs/python-quality@1.2.0
workflows:
  quality-check:
    jobs:
      - python-quality/code-quality:
          auto-commit: false
          context: branchbutler
          line-length: 100
          lint-fail-on-error: true
```

### pr-automation

Automated PR review workflow

```yaml
version: '2.1'
orbs:
  python-quality: branchbutler-labs/python-quality@1.2.0
workflows:
  pr-workflow:
    jobs:
      - python-quality/code-quality:
          filters:
            branches:
              ignore: main
      - python-quality/pr-review:
          requires:
            - python-quality/code-quality
```