Custom Python linting through AST expressions

Overview

bellybutton

Build Status PyPI version PyPI - Python Version

bellybutton is a customizable, easy-to-configure linting engine for Python.

What is this good for?

Tools like pylint and flake8 provide, out-of-the-box, a wide variety of rules for enforcing Python best practices, ensuring PEP-8 compliance, and avoiding frequent sources of bugs. However, many projects have project-specific candidates for static analysis, such as internal style guides, areas of deprecated functionality, or common sources of error. This is especially true of those projects with many contributors or with large or legacy codebases.

bellybutton allows custom linting rules to be specified on a per-project basis and detected as part of your normal build, test and deployment process and, further, makes specifying these rules highly accessible, greatly lowering the cost of adoption.

Give bellybutton a try if:

  • You find yourself making the same PR comments over and over again
  • You need a means of gradually deprecating legacy functionality
  • You're looking to build a self-enforcing style guide
  • Your project needs to onboard new or junior developers more quickly and effectively
  • You have Python nitpicks that go beyond what standard linting tools enforce

Installation & getting started

bellybutton can be installed via:

pip install bellybutton

Once installed, running

bellybutton init

in your project's root directory will create a .bellybutton.yml configuration file with an example rule for you to begin adapting. bellybutton will also try to provide additional rule settings based on the directory structure of your project.

Once you have configured bellybutton for your project, running

bellybutton lint

will lint the project against the rules specified in your .bellybutton.yml. Additionally, running

bellybutton lint --modified-only

will, if using git, only lint those files that differ from origin/master.

For adding bellybutton to your CI pipeline, take a look at this repository's tox configuration and .travis.yml as an example.

Concepts

Rules

Rules in bellybutton supply patterns that should be caught and cause linting to fail. Rules as specified in your .bellybutton.yml configuration must consist of:

  • A description description, expressing the meaning of the rule
  • An expression expr, specifying the pattern to be caught - either as an astpath expression or as a regular expression (!regex ...).

Additionally, the key used for the rule within the rules mapping serves as its name.

Rules may also consist of:

  • Settings settings that specify on which files the rule is to be enforced, as well as whether it can be ignored via a # bb: ignore comment
  • An example example of Python code that would be matched by the rule
  • A counter-example instead of an alternative piece of code, for guiding the developer in fixing their linting error.

These example and instead clauses are checked at run-time to ensure that they respectively are and are not matched by the rule's expr.

As an example, a rule to lint for a deprecated function call using an astpath expression might look like:

DeprecatedFnCall:
  description: `deprecated_fn` will be deprecated in v9.1.2. Please use `new_fn` instead.
  expr: //Call[func/Name/@id='deprecated_fn']
  example: "deprecated_fn(*values)"
  instead: "new_fn(values)"

Settings

!settings nodes specify:

  • included paths on which rules are to be run, using glob notation
  • excluded paths on which rules are not to be run (even when matching the included paths)
  • A boolean allow_ignore which determines whether rules can be ignored, providing the line matching the rule has a # bb: ignore comment.

Additionally, at the root level of .bellybutton.yml, a default_settings setting may be specified which will be used by rules without explicit settings. Each rule must either have a settings parameter or be able to fall back on the default_settings.

As an example, a !settings node to lint only a specific module might look like:

my_module_settings: !settings
  included:
    - ~+/my_package/my_module.py
  excluded: []
  allow_ignore: no

Example usage

Check out this repository's .bellybutton.yml as an example bellybutton configuration file, and astpath's README for examples of the types of patterns you can lint for using bellybutton.

Development status

bellybutton is in an alpha release and, as such, is missing some key features, documentation, and full test coverage. Further, bellybutton is not optimized for performance on extremely large codebases and may contain breaking bugs. Please report any bugs encountered.

Known issues:

  • The !chain and !verbal expression nodes are not yet implemented

Contacts

Owner
H. Chase Stevens
Metaprogramming, natural language processing, and global optimization technique enthusiast.
H. Chase Stevens
PEP-484 typing stubs for SQLAlchemy 1.4 and SQLAlchemy 2.0

SQLAlchemy 2 Stubs These are PEP-484 typing stubs for SQLAlchemy 1.4 and 2.0. They are released concurrently along with a Mypy extension which is desi

SQLAlchemy 139 Dec 30, 2022
Flake8 plugin that checks import order against various Python Style Guides

flake8-import-order A flake8 and Pylama plugin that checks the ordering of your imports. It does not check anything else about the imports. Merely tha

Python Code Quality Authority 270 Nov 24, 2022
Mylint - My really simple rendition of how a linter works.

mylint My really simple rendition of how a linter works. This original version was written for my AST article. Since then I've added tests and turned

Tushar Sadhwani 2 Dec 29, 2021
Design by contract for Python. Write bug-free code. Add a few decorators, get static analysis and tests for free.

A Python library for design by contract (DbC) and checking values, exceptions, and side-effects. In a nutshell, deal empowers you to write bug-free co

Life4 473 Dec 28, 2022
A Python Parser

parso - A Python Parser Parso is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python

Dave Halter 520 Dec 26, 2022
A framework for detecting, highlighting and correcting grammatical errors on natural language text.

Gramformer Human and machine generated text often suffer from grammatical and/or typographical errors. It can be spelling, punctuation, grammatical or

Prithivida 1.3k Jan 08, 2023
Stubs with type annotations for ordered-set Python library

ordered-set-stubs - stubs with type annotations for ordered-set Python library Archived - now type annotations are the part of the ordered-set library

Roman Inflianskas 2 Feb 06, 2020
The strictest and most opinionated python linter ever!

wemake-python-styleguide Welcome to the strictest and most opinionated python linter ever. wemake-python-styleguide is actually a flake8 plugin with s

wemake.services 2.1k Jan 01, 2023
❄️ A flake8 plugin to help you write better list/set/dict comprehensions.

flake8-comprehensions A flake8 plugin that helps you write better list/set/dict comprehensions. Requirements Python 3.6 to 3.9 supported. Installation

Adam Johnson 398 Dec 23, 2022
Check for python builtins being used as variables or parameters

Flake8 Builtins plugin Check for python builtins being used as variables or parameters. Imagine some code like this: def max_values(list, list2):

Gil Forcada Codinachs 98 Jan 08, 2023
Backport Python 3.8+ typing utils & add issubtype & more

typing-utils Backport Python3.8+ typing utils & issubtype & more Install API issubtype get_origin get_args get_type_hints Install pip install typi

10 Nov 09, 2022
Tool to check the completeness of MANIFEST.in for Python packages

check-manifest Are you a Python developer? Have you uploaded packages to the Python Package Index? Have you accidentally uploaded broken packages with

Marius Gedminas 270 Dec 26, 2022
An extension for flake8 that forbids some imports statements in some modules.

flake8-obey-import-goat An extension for flake8 that forbids some imports statements in some modules. Important: this project is developed using DDD,

Ilya Lebedev 10 Nov 09, 2022
Rust like Option and Result types in Python

Option Rust-like Option and Result types in Python, slotted and fully typed. An Option type represents an optional value, every Option is either Some

45 Dec 13, 2022
open source tools to generate mypy stubs from protobufs

mypy-protobuf: Generate mypy stub files from protobuf specs We just released a new major release mypy-protobuf 2. on 02/02/2021! It includes some back

Dropbox 527 Jan 03, 2023
Typed interface stubs for Pythonista iOS

Pythonista Stubs Stubs for the Pythonista iOS API. This allows for better error detection and IDE / editor autocomplete. Installation and Usage pip in

Harold Martin 12 Jul 14, 2020
Reference implementation of sentinels for the Python stdlib

Sentinels This is a reference implementation of a utility for the definition of sentinel values in Python. This also includes a draft PEP for the incl

Tal Einat 22 Aug 27, 2022
Static Typing for Python

Python static typing home. Contains the source for typing_extensions and the documentation. Also hosts a user help forum.

Python 1.3k Jan 06, 2023
docstring style checker

pydocstyle - docstring style checker pydocstyle is a static analysis tool for checking compliance with Python docstring conventions. pydocstyle suppor

Python Code Quality Authority 982 Jan 03, 2023
Type stubs for the lxml package

lxml-stubs About This repository contains external type annotations (see PEP 484) for the lxml package. Installation To use these stubs with mypy, you

25 Dec 26, 2022