penpot-mcp-server/LINTING.md

Linting Guide

This document provides guidelines on how to work with the linting tools configured in this project.

Overview

The project uses the following linting tools:

• flake8: Code style and quality checker
• isort: Import sorting
• autopep8: PEP 8 code formatting with auto-fix capability
• pyupgrade: Upgrades Python syntax for newer versions
• pre-commit: Framework for managing pre-commit hooks

Quick Start

1. Use the setup script to install all dependencies and set up pre-commit hooks:

./fix-lint-deps.sh

Or install dependencies manually:

pip install -r requirements-dev.txt
pre-commit install

2. Run the linting script:

# Check for issues
./lint.py

# Fix issues automatically where possible
./lint.py --autofix

Dependencies

The linting tools require specific dependencies:

• flake8 and flake8-docstrings: For code style and documentation checking
• isort: For import sorting
• autopep8: For automatic PEP 8 compliance
• pyupgrade: For Python syntax upgrading
• setuptools: Required for lib2to3 which is used by autopep8

If you encounter a ModuleNotFoundError: No module named 'lib2to3' error, make sure you have setuptools installed:

pip install setuptools>=65.5.0

Or simply run the fix script:

./fix-lint-deps.sh

Configuration

The linting tools are configured in the following files:

• setup.cfg: Contains settings for flake8, autopep8, etc.
• .pre-commit-config.yaml: Configuration for pre-commit hooks
• .editorconfig: Editor settings for consistent code formatting

Linting Rules

Code Style Rules

We follow PEP 8 with some exceptions:

• Line Length: Max line length is 100 characters
• Ignored Rules:
  • E203: Whitespace before ':' (conflicts with Black)
  • W503: Line break before binary operator (conflicts with Black)

Documentation Rules

All public modules, functions, classes, and methods should have docstrings. We use the Google style for docstrings.

Example:

def function(param1, param2):
    """Summary of function purpose.

    More detailed explanation if needed.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ExceptionType: When and why this exception is raised.
    """
    # function implementation

Import Sorting

Imports should be sorted using isort with the black profile. Imports are grouped in the following order:

1. Standard library imports
2. Related third-party imports
3. Local application/library specific imports

With each group sorted alphabetically.

Auto-Fixing Issues

Many issues can be fixed automatically:

• Import Sorting: isort can sort imports automatically
• PEP 8 Formatting: autopep8 can fix many style issues
• Python Syntax: pyupgrade can update syntax to newer Python versions

Run the auto-fix command:

./lint.py --autofix

Troubleshooting

If you encounter issues with the linting tools:

1. Missing dependencies: Run ./fix-lint-deps.sh to install all required dependencies
2. Autopep8 errors: Make sure setuptools is installed for lib2to3 support
3. Pre-commit hook failures: Run pre-commit run --all-files to see which files are causing issues

Pre-commit Hooks

Pre-commit hooks run automatically when you commit changes. They ensure that linting issues are caught before code is committed.

If hooks fail during a commit:

1. The commit will be aborted
2. Review the error messages
3. Fix the issues manually or using auto-fix
4. Stage the fixed files
5. Retry your commit

Common Issues and Solutions

Disabling Linting for Specific Lines

Sometimes it's necessary to disable linting for specific lines:

# For flake8
some_code = "example"  # noqa: E501

# For multiple rules
some_code = "example"  # noqa: E501, F401

Handling Third-Party Code

For third-party code that doesn't follow our style, consider isolating it in a separate file or directory and excluding it from linting.

IDE Integration

VSCode

Install the Python, Flake8, and EditorConfig extensions. Add to settings.json:

{
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "editor.formatOnSave": true,
    "python.formatting.provider": "autopep8",
    "python.sortImports.args": ["--profile", "black"]
}

PyCharm

Enable Flake8 in: Settings → Editor → Inspections → Python → Flake8

Configure isort: Settings → Editor → Code Style → Python → Imports

Customizing Linting Rules

To modify linting rules:

1. Edit setup.cfg for flake8 and autopep8 settings
2. Edit .pre-commit-config.yaml for pre-commit hook settings
3. Run pre-commit autoupdate to update hook versions

Continuous Integration

Linting checks are part of the CI pipeline. Pull requests that fail linting will not be merged until issues are fixed.