Autofix

Automatically fix common package issues

Autofix

pycmdcheck can automatically fix certain issues it detects in your Python package. This feature helps you quickly address common problems without manual intervention.

Quick Start

To automatically fix issues in your package:

pycmdcheck --fix

To preview what would be fixed without making changes:

pycmdcheck --fix --dry-run

How It Works

When you run pycmdcheck --fix:

  1. Check Detection: pycmdcheck runs all configured checks to identify failures
  2. Fixability Assessment: For each failure, it determines if automatic fixing is possible
  3. Fix Application: Fixable issues are automatically resolved
  4. Report: A summary shows what was fixed, what couldn’t be fixed, and any errors

Fixable Checks

Not all checks support automatic fixing. The following checks can be auto-fixed:

Check ID Name What Gets Fixed
ST001 HasReadme Creates a README.md template
ST002 HasLicense Creates an MIT LICENSE file
DC002 HasDocsDirectory Creates docs/index.md
CQ002 HasTypeHints Creates py.typed marker file
RL001 HasChangelog Creates CHANGELOG.md template

Command Options

--fix

Apply fixes to failing checks where automatic fixing is available.

pycmdcheck --fix

--dry-run

Preview what would be fixed without modifying any files. Use with --fix.

pycmdcheck --fix --dry-run

Combining with Other Options

You can combine --fix with other pycmdcheck options:

# Only fix structure checks
pycmdcheck --fix --only-group structure

# Skip specific checks during fix
pycmdcheck --fix --skip CQ002

# Get fix results as JSON
pycmdcheck --fix --format json

Output Formats

Rich Output (Default)

The rich output shows a categorized summary:

Fixed:
  - ST001
  - ST002

Cannot auto-fix (manual fix required):
  - MT003

Summary: 2 check(s) fixed

JSON Output

With --format json, you get structured output:

{
  "mode": "fix",
  "fixed": ["ST001", "ST002"],
  "would_fix": [],
  "unfixable": ["MT003"],
  "already_passing": ["ST003", "RL001"],
  "errors": []
}

What Each Fix Creates

ST001: README.md

Creates a README template with: - Package name as heading - Installation instructions - Basic usage example - License reference

# my-package

A Python package.

## Installation

\```bash
pip install my-package
\```

## Usage

\```python
import my_package
\```

## License

See [LICENSE](LICENSE) for details.

ST002: LICENSE

Creates an MIT License file with the current year:

MIT License

Copyright (c) 2024 [Author Name]

Permission is hereby granted, free of charge...

DC002: docs/index.md

Creates a docs directory with a starter documentation file:

# my-package Documentation

Welcome to the my-package documentation.

## Getting Started

...

CQ002: py.typed

Creates an empty py.typed marker file in the package directory (per PEP 561).

RL001: CHANGELOG.md

Creates a changelog following Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Initial release

Exit Codes

Code Meaning
0 All fixes applied successfully
1 One or more fix errors occurred

Best Practices

  1. Preview First: Always use --dry-run to see what will change before applying fixes
  2. Review Changes: After running --fix, review the generated files and customize them
  3. Version Control: Run --fix on a clean git working tree so you can review the diff
  4. Incremental Fixes: Use --only-group or --only to fix issues incrementally

Limitations

  • Fixes create template files that should be customized
  • Author information in LICENSE uses placeholder [Author Name]
  • URLs in CHANGELOG.md use placeholder GitHub paths
  • Some checks (like code quality checks that require refactoring) cannot be auto-fixed