PEP 8 Speaks

A GitHub app to automatically review Python code style over Pull Requests

Installation
Example
Main features
Configuration
Popular Users
Miscellaneous features
Private repos
How to fix PEP 8 issues?
Release announcements
Contributing

Installation

Go to the homepage of the app - https://github.com/apps/pep8-speaks
Click on the Configure button
Add repositories or organizations to activate PEP 8 Speaks

Example

Main features

The bot makes a single comment on the Pull Request and keeps updating it on new commits. No hustle on emails !
The bot comments only if Python files are involved. So, install the integration on all of your repositories. The bot would not comment where it should not.
By default, the bot does not comment if there are no PEP 8 issues. You can change this in configuration.
You can use choose between pycodestyle or flake8 as your linter. The bot can read configurations for both.
The bot can read your setup.cfg for [flake8] and [pycodestyle] sections. Check out the Configuration section below.

Configuration

A config file is not required for the integration to work. However it can be configured additionally by adding a .pep8speaks.yml file in the root of the project. Here is an example :

# File : .pep8speaks.yml

scanner:
    diff_only: True  # If False, the entire file touched by the Pull Request is scanned for errors. If True, only the diff is scanned.
    linter: pycodestyle  # Other option is flake8

pycodestyle:  # Same as scanner.linter value. Other option is flake8
    max-line-length: 100  # Default is 79 in PEP 8
    ignore:  # Errors and warnings to ignore
        - W504  # line break after binary operator
        - E402  # module level import not at top of file
        - E731  # do not assign a lambda expression, use a def
        - C406  # Unnecessary list literal - rewrite as a dict literal.
        - E741  # ambiguous variable name

no_blank_comment: True  # If True, no comment is made on PR without any errors.
descending_issues_order: False  # If True, PEP 8 issues in message will be displayed in descending order of line numbers in the file

message:  # Customize the comment made by the bot
    opened:  # Messages when a new PR is submitted
        header: "Hello @{name}! Thanks for opening this PR. "
                # The keyword {name} is converted into the author's username
        footer: "Do see the [Hitchhiker's guide to code style](https://goo.gl/hqbW4r)"
                # The messages can be written as they would over GitHub
    updated:  # Messages when new commits are added to the PR
        header: "Hello @{name}! Thanks for updating this PR. "
        footer: ""  # Why to comment the link to the style guide everytime? :)
    no_errors: "There are currently no PEP 8 issues detected in this Pull Request. Cheers! :beers: "

Notes:

Default settings are in data/default_pep8speaks.yml. Your .pep8speaks.yml will override these values.
For every Pull Request, the bot looks for .pep8speaks.yml in the base branch (the existing one). If the file is not found, it then searches the head branch (the incoming changes).
Set the value of scanner.linter to either pycodestyle or flake8
- flake8 is a wrapper around pycodestyle with additional enforcements.
For linter configurations (like ignore or max-line-length), PEP8Speaks will look and prioritize configurations in the following order :
- pycodestyle: or flake8: section of .pep8speaks.yml.
  - This depends upon the scanner.linter value.
- [pycodestyle] or [flake8] section of setup.cfg file in the root of the project.
  - This is independent of scanner.linter. So, [flake8] section of setup.cfg will also work for pycodestyle.
Read more on pycodestyle and flake8 documentation.

Popular Users

Pandas

SunPy

Astropy

Scikit Learn Contrib

Scikit Image

Spyder IDE

See the complete list of organizations and users.

Miscellaneous features

Comment @pep8speaks suggest diff in a comment of the PR, and it will comment a gist of diff suggesting fixes for the PR. Example
Comment @pep8speaks pep8ify on the PR and it will create a Pull Request with changes suggested by autopep8 against the branch of the author of the PR. autopep8 fixes most of the errors reported by pycodestyle.
Add [skip pep8] anywhere in the commit message, PR title or PR description to prohibit pep8speaks from commenting on the Pull Request.

Private repos

This app will only work for publicly hosted repositories. So if you are looking to deploy a fork or use the app for private repositories, here are the instructions.

How to fix PEP 8 issues?

Check the errors locally by the command line tool pycodestyle (previously known as pep8).
autopep8 is another command line tool to fix the issues.
Also, see black

Release announcements

Updates to the app are announced using the GitHub Release feature over here. A lot of major changes are made as the community grows bigger. Click on Watch -> Releases only on top of the page, to get notified about new configurations or feature updates.

Usually, the master branch is deployed as soon as Pull Requests are merged in the repository. However, on every Friday, I make a release and make sure the latest code is deployed. You do not need to do anything to use the latest version. If you use a fork of PEP 8 Speaks, check out the Release space.

Contributing

You can support the project by contributing to its development. If you have any suggestions for new features or improvements, please create an issue. Pull Requests are most welcome ! Read CONTRIBUTING doc to understand how the project works and how you can make changes.

The project requires to be hosted on a server and due to which, it needs financial support as well.

Please read the case for funding PEP 8 Speaks.