or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/pypi-flake8-builtins

Flake8 plugin that detects when Python built-in functions, classes, or modules are being shadowed by variable names, function parameters, or imports

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/flake8-builtins@3.0.x

To install, run

npx @tessl/cli install tessl/pypi-flake8-builtins@3.0.0

Flake8 Builtins

A Flake8 plugin that detects when Python built-in functions, classes, or modules are being shadowed by variable names, function parameters, class attributes, imports, or lambda arguments. This plugin helps prevent subtle bugs that can occur when developers accidentally use built-in names like list, dict, max, or zip as variable names, which can lead to unexpected behavior and hard-to-debug errors.

Package Information

Package Name: flake8-builtins
Package Type: Flake8 plugin
Language: Python
Installation: pip install flake8-builtins

Core Imports

This package integrates automatically with Flake8 through the plugin discovery system. No direct imports are needed in user code.

Basic Usage

Once installed, the plugin is automatically discovered and activated by Flake8:

# Install the plugin
pip install flake8-builtins

# Run flake8 on your Python files
flake8 myfile.py

# Configure ignore list for specific builtins
flake8 --builtins-ignorelist id,copyright myfile.py

# Configure allowed module names
flake8 --builtins-allowed-modules logging,socket myfile.py

Example violations detected:

def my_method(object, list, dict):  # A002 errors
    max = 5                         # A001 error
    min = 3                         # A001 error
    zip = (4, 3)                   # A001 error

class MyClass:
    list = []                      # A003 error
    
import json as dict                # A004 error

lambda max, min: max + min         # A006 errors

Configuration Options

Command-line Options

--builtins-ignorelist: Comma-separated list of builtins to skip checking
--builtins-allowed-modules: Comma-separated list of builtin module names to allow

Configuration File Support

Options can be configured in setup.cfg, tox.ini, or pyproject.toml:

[flake8]
builtins-ignorelist = id,copyright,_
builtins-allowed-modules = logging,socket

Error Codes

The plugin reports six different error codes for builtin name shadowing:

A001: Variable is shadowing a Python builtin
A002: Argument is shadowing a Python builtin
A003: Class attribute is shadowing a Python builtin
A004: Import statement is shadowing a Python builtin
A005: Module is shadowing a Python builtin module
A006: Lambda argument is shadowing a Python builtin

Capabilities

Plugin Entry Point

The main checker class that Flake8 discovers and loads automatically.

class BuiltinsChecker:
    """
    Main Flake8 plugin class for detecting builtin name shadowing.
    
    Attributes:
    - name (str): Plugin identifier 'flake8_builtins'
    - version (str): Plugin version '1.5.2'
    - assign_msg (str): Error message template for variable assignments (A001)
    - argument_msg (str): Error message template for function arguments (A002)
    - class_attribute_msg (str): Error message template for class attributes (A003)
    - import_msg (str): Error message template for import statements (A004)
    - module_name_msg (str): Error message template for module names (A005)
    - lambda_argument_msg (str): Error message template for lambda arguments (A006)
    - default_line_number (int): Default line number for errors (1)
    - default_column_offset (int): Default column offset for errors (1)
    - names (list): List of builtin names to check against
    - ignore_list (set): Set of builtin names to ignore by default
    - ignored_module_names (set): Set of module names to ignore
    - module_names (set): Set of stdlib module names to check against (Python 3.10+)
    """
    
    def __init__(self, tree, filename):
        """
        Initialize checker with AST tree and filename.
        
        Parameters:
        - tree: AST tree of the file being checked
        - filename (str): Path to the file being checked
        """
    
    @classmethod
    def add_options(cls, option_manager):
        """
        Add command-line options to Flake8.
        
        Parameters:
        - option_manager: Flake8's option manager instance
        """
    
    @classmethod
    def parse_options(cls, options):
        """
        Parse and process configuration options.
        
        Parameters:
        - options: Parsed options from Flake8
        """
    
    def run(self):
        """
        Main entry point that yields error tuples for detected violations.
        
        Yields:
        Tuple of (line_number, column_offset, message, checker_class)
        """

Error Detection Methods

Methods that check different AST node types for builtin name shadowing.

def check_assignment(self, statement):
    """
    Check assignment statements for builtin shadowing (A001/A003).
    
    Parameters:
    - statement: AST assignment node (Assign, AnnAssign, or NamedExpr)
    
    Yields:
    Error tuples for violations found
    """

def check_function_definition(self, statement):
    """
    Check function definitions and arguments (A001/A002/A003).
    
    Parameters:
    - statement: AST function definition node (FunctionDef or AsyncFunctionDef)
    
    Yields:
    Error tuples for violations found
    """

def check_lambda_definition(self, statement):
    """
    Check lambda function arguments for builtin shadowing (A006).
    
    Parameters:
    - statement: AST Lambda node
    
    Yields:
    Error tuples for violations found
    """

def check_for_loop(self, statement):
    """
    Check for loop target variables for builtin shadowing (A001).
    
    Parameters:
    - statement: AST For or AsyncFor node
    
    Yields:
    Error tuples for violations found
    """

def check_with(self, statement):
    """
    Check with statement context variables for builtin shadowing (A001).
    
    Parameters:
    - statement: AST With or AsyncWith node
    
    Yields:
    Error tuples for violations found
    """

def check_exception(self, statement):
    """
    Check exception handler variable names for builtin shadowing (A001).
    
    Parameters:
    - statement: AST excepthandler node
    
    Yields:
    Error tuples for violations found
    """

def check_comprehension(self, statement):
    """
    Check comprehension target variables for builtin shadowing (A001).
    
    Parameters:
    - statement: AST comprehension node (ListComp, SetComp, DictComp, GeneratorExp)
    
    Yields:
    Error tuples for violations found
    """

def check_import(self, statement):
    """
    Check import statement names for builtin shadowing (A004).
    
    Parameters:
    - statement: AST Import or ImportFrom node
    
    Yields:
    Error tuples for violations found
    """

def check_class(self, statement):
    """
    Check class definition names for builtin shadowing (A001).
    
    Parameters:
    - statement: AST ClassDef node
    
    Yields:
    Error tuples for violations found
    """

def check_module_name(self, filename: str):
    """
    Check if module name shadows builtin module (A005).
    
    Parameters:
    - filename (str): Path to the module file
    
    Yields:
    Error tuples for violations found
    """

def error(self, statement=None, variable=None, message=None):
    """
    Generate error tuple for Flake8.
    
    Parameters:
    - statement: AST node where error occurred (optional)
    - variable (str): Variable name causing the violation (optional)
    - message (str): Error message template (optional)
    
    Returns:
    Tuple of (line_number, column_offset, formatted_message, checker_class)
    """

Default Ignore List

The plugin ignores these builtin names by default:

__name__
__doc__
credits
_

Additional builtins can be ignored using the --builtins-ignorelist option.

Python Version Support

Minimum Python Version: 3.9
Supported Versions: 3.9, 3.10, 3.11, 3.12, 3.13
Implementations: CPython, PyPy3

Dependencies

Required: flake8 (runtime dependency)
Optional: pytest (development/testing)

Integration

The plugin integrates with Flake8 through the entry point system defined in pyproject.toml:

[project.entry-points."flake8.extension"]
A00 = "flake8_builtins:BuiltinsChecker"

This allows Flake8 to automatically discover and load the plugin when installed, making it seamlessly integrate into existing Flake8 workflows and CI/CD pipelines.