A Python toolkit to help developers write professional-grade, maintainable, and clean code following clean code principles.

pycleancode is a professional-grade Python toolkit that helps developers write clean, maintainable, and scalable code following clean code principles.

Build multiple code quality tools under a single unified package architecture.

Unlike traditional linters that only focus on style violations, pycleancode implements advanced rule engines that target deeper structural and maintainability aspects of your code.

While tools like flake8, pylint, ruff, and black are excellent, most focus heavily on surface-level syntax or style violations.

pycleancode is different:

• 🔄 Designed for professional teams writing critical Python codebases.
• 🤝 Rule-based pluggable architecture to extend new structural checks.
• 🔄 AST-powered deep nesting detection.
• 🎡 Focused on long-term maintainability.
• 🦖 OSS-grade code architecture.

pycleancode 1.0.0 includes the first module: brace_linter.

The brace_linter module focuses on structural code depth and complexity. It analyzes Python code for excessive nesting and deeply nested functions that often make code harder to read, maintain, and extend.

• Max Depth Rule

  • Enforces maximum logical nesting depth.
  • Helps prevent pyramid-of-doom structures.

• Nested Function Rule

  • Enforces maximum levels of nested function definitions.
  • Prevents excessive local function scoping that can reduce readability.

• Structural Reporting

  • Full structural report of nesting tree.
  • Emoji + ASCII visualization of code structure.
  • Summary chart output for quick depth evaluation.

sandbox/test_sample.py:2: Nested functions depth 2 exceeds allowed 1
sandbox/test_sample.py:3: Depth 4 exceeds max 3

📈 Structural Report:

 🔾 ROOT (Line 0, Depth 1)
│ 🔹 FunctionDef (Line 1, Depth 2)
│ │ 🔹 FunctionDef (Line 2, Depth 3)
│ │ │ 🔹 FunctionDef (Line 3, Depth 4)

• ✅ Supported Python versions: 3.8, 3.9, 3.10, 3.11, 3.12
• ⚠ Python 3.13+ is not yet supported (due to upstream Rust dependencies)

Install via PyPI:

pip install pycleancode

Or using Poetry:

poetry add pycleancode

Run directly via CLI:

pycleancode-brace-linter path/to/your/code.py --report

Configure via pybrace.yml:

rules:
  max_depth:
    enabled: true
    max_depth: 3
  nested_function:
    enabled: true
    max_nested: 1

Pass config via CLI:

pycleancode-brace-linter your_code.py --config pybrace.yml

git clone git@github.com:YOUR_USERNAME/pycleancode.git
cd pycleancode
poetry install
pre-commit install

Run full tests:

poetry run pytest --cov=pycleancode --cov-report=term-missing

Run pre-commit:

poetry run pre-commit run --all-files

Released under the MIT License. See LICENSE.

Please see our CODE_OF_CONDUCT.md

We welcome OSS contributions. Please read our full CONTRIBUTING.md to get started!

• Clean Code Principles
• 100% Test Coverage Required
• Pre-commit Hooks Required
• Conventional Commits Required

• GitHub Discussions (coming soon)
• Issues and PRs welcomed
• PyPI release v1.0.0 live

🚀 Pycleancode: Clean Code. Professional Quality. OSS-Grade Python. Unified Modular Clean Code Toolkit.