203 lines
4.9 KiB
Markdown
203 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
./fix-lint-deps.sh
|
|
```
|
|
|
|
Or install dependencies manually:
|
|
|
|
```bash
|
|
pip install -r requirements-dev.txt
|
|
pre-commit install
|
|
```
|
|
|
|
2. Run the linting script:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
pip install setuptools>=65.5.0
|
|
```
|
|
|
|
Or simply run the fix script:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```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.
|