pyscn - Python Code Quality Analyzer

pyscn is an intelligent Python code quality analyzer that performs deep structural analysis to help you write cleaner, more maintainable code.

What Can It Do For You?

• 🔍 Find Complex Code - Identify functions that are hard to test and maintain
• 🧹 Remove Dead Code - Detect unreachable code that clutters your codebase
• 📋 Detect Duplicates - Find copy-pasted code for refactoring opportunities
• 🔗 Analyze Dependencies - Understand module relationships and coupling
• 📊 Validate Architecture - Ensure your code follows architectural patterns
• 📈 Generate Reports - Export findings in HTML, JSON, YAML, or CSV

Quick Start

# Run analysis without installation
uvx pyscn analyze .
# or
pipx run pyscn analyze .

Common Commands

pyscn analyze

Run comprehensive analysis with HTML report

pyscn analyze .                              # All analyses with HTML report
pyscn analyze --json .                       # Generate JSON report
pyscn analyze --select complexity .          # Only complexity analysis
pyscn analyze --select deps .                # Only dependency analysis
pyscn analyze --select complexity,deps,deadcode . # Multiple analyses

pyscn check

Fast CI-friendly quality gate

pyscn check .                      # Quick pass/fail check
pyscn check --max-complexity 15 .  # Custom thresholds

pyscn init

Create configuration file

pyscn init                         # Generate .pyscn.toml

💡 Run pyscn --help or pyscn <command> --help for complete options

Configuration

Create a .pyscn.toml file or add [tool.pyscn] to your pyproject.toml:

# .pyscn.toml
[complexity]
max_complexity = 15

[dead_code]
min_severity = "warning"

[output]
directory = "reports"

⚙️ Run pyscn init to generate a full configuration file with all available options

Installation

# Install with pipx (recommended)
pipx install pyscn

# Or run directly with uvx
uvx pyscn

Alternative installation methods

Build from source

git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build

Go install

go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest

CI/CD Integration

# .github/workflows/code-quality.yml
name: Code Quality
on: [push, pull_request]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install pyscn
      - name: Quick quality check
        run: pyscn check .
      - name: Generate detailed report
        run: pyscn analyze --json --select complexity,deadcode,deps src/
      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: code-quality-report
          path: .pyscn/reports/

---

Documentation

📚 Development Guide • Architecture • Testing

License

MIT License — see LICENSE

---

Built with ❤️ using Go and tree-sitter