Why Automate Linting and Formatting?#

Automating code quality checks offers significant advantages for development teams and projects:

• Consistency: Ensures all code committed to the repository adheres to the same style standards, improving readability and maintainability. Black is particularly effective at enforcing strict, opinionated formatting.
• Early Error Detection: Flake8 identifies common programming errors and potential issues before the code is even run or reviewed, reducing the likelihood of bugs reaching production.
• Reduced Review Overhead: Code reviewers can focus on the logic and functionality of the code rather than spending time pointing out style violations or obvious errors that could be caught automatically. Studies have shown that automated checks can reduce the number of trivial comments in code reviews, allowing reviewers to concentrate on more significant architectural or logical issues.
• Enforcing Standards: Provides a consistent enforcement mechanism for project coding standards, which is particularly valuable in larger teams or open-source projects with many contributors.
• Faster Feedback Loop: Developers receive immediate feedback on their code changes directly within the GitHub interface, allowing for quick corrections before the code is merged.

Essential Tools: Flake8 and Black#

A brief overview of the tools used in this automated workflow:

Introducing GitHub Actions#

GitHub Actions is a CI/CD platform that enables automation of software workflows directly within a GitHub repository. Workflows are defined using YAML files placed in the .github/workflows directory.

A workflow is composed of one or more jobs. Each job runs in a virtual environment (like Ubuntu, Windows, or macOS) and consists of a sequence of steps. Steps can run commands, set up environments, or use pre-built actions from the GitHub Marketplace.

For automating Python linting and formatting, a workflow is configured to trigger on specific events (like push or pull_request), set up a Python environment, install the necessary tools (Flake8 and Black), and then execute the linter and formatter checks using command-line steps.

Building the GitHub Action Workflow#

Creating the GitHub Action involves defining a workflow in a YAML file within the .github/workflows directory of the Python project’s repository.

1
name: Python Lint and Format Check
2

3
on:
4
  push:
5
    branches: [ main, master ] # Trigger on push to main or master
6
  pull_request:
7
    branches: [ main, master ] # Trigger on pull request targeting main or master
8

9
jobs:
10
  lint-format-check:
11
    runs-on: ubuntu-latest # Specify the operating system for the job
12

13
    steps:
14
    - name: Checkout code # Step 1: Get the code from the repository
15
      uses: actions/checkout@v4
16

17
    - name: Set up Python # Step 2: Configure Python environment
18
      uses: actions/setup-python@v5
19
      with:
20
        python-version: '3.10' # Specify the Python version to use. '3.x' is also an option.
21

22
    - name: Install dependencies # Step 3: Install Flake8 and Black
23
      run: |
24
        python -m pip install --upgrade pip
25
        pip install flake8 black
26

27
    - name: Run Flake8 # Step 4: Execute Flake8 checks
28
      run: |
29
        # Stop the build if there are Python syntax errors or undefined names
30
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
31
        # Exit-code 0 means no errors, > 0 means problems
32
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=120 --statistics
33

34
    - name: Run Black check # Step 5: Execute Black check (does not reformat code)
35
      run: |
36
        # Check if code is formatted according to Black's rules
37
        # The --check flag makes Black exit with a non-zero code if formatting is needed
38
        # The --diff flag shows the proposed changes
39
        black . --check --diff

Handling Formatting Changes#

The workflow above is designed to verify code formatting. It does not automatically apply Black’s formatting changes to the code and commit them back. This is a standard practice because automatically committing formatting changes from a CI server can create merge conflicts and complicate the commit history.

The intended workflow is:

1. A developer writes code and makes a commit.
2. The developer runs black . locally on their machine before committing to format the code.
3. The developer pushes the formatted code.
4. The GitHub Action runs black . --check --diff.
5. If the code was formatted correctly locally (Step 2), the Black check passes.
6. If the developer forgot to run Black locally, the check fails, and the --diff output shows what needs to be changed. The developer then runs black . locally, commits the formatting changes, and pushes again.

This approach ensures that formatting changes are part of the developer’s commit history and are addressed directly by the developer.

Configuration for Flake8 and Black#

Both Flake8 and Black can be configured to customize their behavior. Common configurations include:

• Ignoring files or directories: Preventing the tools from checking certain paths (e.g., build artifacts, generated code).
• Setting line length: Customizing the maximum line length (often done for Black).
• Ignoring specific error codes: Disabling particular checks in Flake8.

Configuration is typically done using configuration files like pyproject.toml (preferred for modern projects, used by both Black and Flake8), setup.cfg, or .flake8. The tools automatically detect these files in the project root. For example, to set a line length of 100 for both:

1
[tool.black]
2
line-length = 100
3
include = '\.pyi?$'
4
exclude = '''
5
/(
6
    \.git
7
  | \.hg
8
  | \.mypy_cache
9
  | \.tox
10
  | \.venv
11
  | _build
12
  | build
13
  | dist
14
)/
15
'''
16

17
[flake8]
18
max-line-length = 100
19
exclude = .git,__pycache__,build,dist,venv,.venv,.mypy_cache,.tox
20
ignore = W503,E501 # Example ignores: line break before binary operator, line too long (if handled by Black)

The GitHub Action workflow automatically respects these configuration files when running flake8 . and black . --check --diff from the project root.

Real-World Application: Pull Request Integration#

The most impactful application of this GitHub Action is its integration with pull requests. When a developer opens or updates a pull request, the workflow automatically runs. The status of the lint-format-check job is displayed prominently on the pull request page.

If the job completes successfully, a green checkmark appears, signaling that the code meets the defined quality and style standards. If the job fails (due to Flake8 errors or Black finding unformatted code), a red cross appears. Developers and reviewers can click on the status to view the detailed output logs from Flake8 and Black, which pinpoint the exact files and lines that need correction.

This immediate, automated feedback loop embedded within the pull request workflow streamlines the review process and ensures that only compliant code is merged into the main branches.

Key Takeaways#

• Automating Python code linting (Flake8) and formatting (Black) improves code quality, consistency, and maintainability.
• GitHub Actions provides a platform to integrate these checks into the CI/CD pipeline.
• A GitHub Action workflow is defined in a YAML file in the .github/workflows directory.
• The workflow typically checks out the code, sets up a Python environment, installs Flake8 and Black, and then runs the tools.
• Black should be run with the --check --diff flags in the action to verify formatting without changing files. Failure indicates the developer needs to run Black locally.
• Configuration for Flake8 and Black can be managed via pyproject.toml or other configuration files.
• Integrating the action with pull requests provides critical, automated feedback on code changes.