Pylint Plugin Utilities

0.9.0 · active · verified Thu Apr 09

Pylint Plugin Utilities (version 0.9.0) provides a collection of helper functions and classes designed to simplify the development of custom Pylint checkers and transformers. It abstracts away common boilerplate and provides tools for AST manipulation and message suppression. The library maintains a steady release cadence, typically aligning with Pylint's own major versions to ensure compatibility.

Warnings

breaking Pylint version compatibility changed; `pylint-plugin-utils` 0.9.0 now requires `Pylint >= 2.16`.
Fix: Ensure your `Pylint` installation is version 2.16 or newer. Upgrade `Pylint` using `pip install --upgrade pylint`.
breaking The `register_linter_extension` function has been removed.
Fix: This function was deprecated in 0.8.0. Plugins should use the standard `register(linter)` function in their module, and within it, call `linter.register_checker()` or similar methods directly.
breaking The `fix_pythonpath` function has been removed.
Fix: This function was primarily used for older Pylint setups to manipulate `sys.path`. Ensure your plugin's dependencies are correctly available on `PYTHONPATH` or use Pylint's `--init-hook` option for path manipulation if necessary.
gotcha Pylint plugins are not automatically discovered by default; they must be explicitly loaded.
Fix: To enable a plugin, Pylint must be invoked with `--load-plugins=your_plugin_module`. For more persistent configuration, define plugins in your `pyproject.toml` or `.pylintrc` file under the `[MASTER]` section using the `load-plugins` option.

Install

pip install pylint-plugin-utils Install stable version

Imports

suppress_message
```
from pylint_plugin_utils.utils import suppress_message
```
Decorator to suppress specific Pylint messages on functions or methods.
add_message
```
from pylint_plugin_utils.messages import add_message
```
Helper to add a Pylint message from within a checker instance.
AstBuilder
```
from pylint_plugin_utils.ast_builder import AstBuilder
```
Utility for programmatically building Abstract Syntax Trees (ASTs).

Quickstart

This quickstart demonstrates how to create a basic Pylint checker using `pylint-plugin-utils` to detect direct calls to `print`. It also shows the use of the `suppress_message` decorator to exempt specific code from Pylint's default checks. The `register` function is the standard entry point for Pylint plugins.

# my_plugin.py
from pylint.checkers import BaseChecker
from pylint_plugin_utils.messages import add_message
from pylint_plugin_utils.utils import suppress_message

# Define a custom message ID and details
MY_MSG = 'W9999'
MY_MSG_ID = 'no-direct-print'
MY_MSG_STR = 'Avoid calling "print" directly in production code.'

class NoPrintChecker(BaseChecker):
    """
    Checks for direct calls to the 'print' function.
    """
    name = 'no-print-checker'
    priority = -1
    msgs = {
        MY_MSG: (
            MY_MSG_STR,
            MY_MSG_ID,
            'Avoid using print for logging in production; use a proper logger instead.',
        )
    }

    def visit_call(self, node):
        """Called for every function call."""
        if node.func.as_string() == 'print':
            add_message(self, MY_MSG_ID, node=node)

# Example of using suppress_message decorator
@suppress_message('invalid-name')
def ThisFunctionIsAllowedToHaveAnInvalidName():
    pass

def register(linter):
    """Register the checker with Pylint."""
    linter.register_checker(NoPrintChecker(linter))

# To run this plugin:
# 1. Save the above code as `my_plugin.py`.
# 2. Create a test file, e.g., `test_code.py`:
#    print("Hello, World!")
#    ThisFunctionIsAllowedToHaveAnInvalidName()
# 3. Run Pylint with the plugin: `pylint --load-plugins=my_plugin test_code.py`
#    This will report 'no-direct-print' for `print` and suppress 'invalid-name' for the function.

view raw JSON →