separate-monolithic-python

Break large Python files (>500 LOC) into smaller, well-organized modules with proper package structure. Use when a Python file is too large, monolithic, or needs refactoring. Triggered by requests mentioning "too large", "separate", "split", "break up", or "refactor" for Python files.

⭐13stars🔀2forks📁View on GitHub🕐Updated Dec 31, 2025

When & Why to Use This Skill

This Claude skill automates the transformation of monolithic Python scripts into modular, maintainable package structures. It specializes in refactoring large files (>500 LOC) by analyzing dependencies and redistributing code into logical components such as models, services, and utilities, ensuring high cohesion and low coupling according to Python best practices.

Use Cases

  • Refactoring a single-file FastAPI or Flask application into a structured directory with separate routes, database models, and business logic.
  • Breaking down complex data science or automation scripts that have become too large to navigate, improving readability and team collaboration.
  • Resolving circular dependency issues in existing projects by extracting shared logic into dedicated 'constants' or 'shared' modules.
  • Modernizing legacy Python codebases by implementing professional package standards, including proper __init__.py exports and relative import structures.
nameseparate-monolithic-python
descriptionBreak large Python files (>500 LOC) into smaller, well-organized modules with proper package structure. Use when a Python file is too large, monolithic, or needs refactoring. Triggered by requests mentioning "too large", "separate", "split", "break up", or "refactor" for Python files.

Separate Monolithic Python Code

Break large Python files into maintainable modules following Python best practices.

Workflow

Step 1: Analyze

  1. Read entire file to understand structure
  2. Identify components (classes, function groups, constants)
  3. Count lines (>500 LOC needs separation)
  4. Map dependencies (what depends on what)

Step 2: Plan Structure

Choose a separation pattern:

By Responsibility (Recommended):

mypackage/
├── __init__.py       # Public API exports
├── models.py         # Data models/classes
├── services.py       # Business logic
├── utils.py          # Helper functions
└── constants.py      # Configuration

By Feature:

mypackage/
├── __init__.py
├── feature_a/
│   ├── __init__.py
│   ├── models.py
│   └── logic.py
└── feature_b/

By Layer (Domain-driven):

mypackage/
├── __init__.py
├── domain/          # Core models
├── application/     # Use cases
└── infrastructure/  # External deps

Present plan to user before proceeding.

Step 3: Create Structure

mkdir mypackage
touch mypackage/__init__.py mypackage/models.py mypackage/services.py

Step 4: Extract Code

Extract in dependency order:

  1. Constants (no dependencies)
  2. Models (minimal dependencies)
  3. Utilities (depend on constants/models)
  4. Services (depend on everything)
  5. Main (orchestrate all)

Step 5: Update Imports

In new modules:

# models.py
from .constants import DEFAULT_ROLE
from .utils import validate_email

In __init__.py (public API):

from .models import User, Product
from .services import create_user

__all__ = ['User', 'Product', 'create_user']

In external files:

# Before: from monolith import User
# After:  from mypackage import User

Step 6: Validate

ruff check mypackage/
mypy mypackage/
python -c "from mypackage import User"
pytest tests/

Key Principles

High Cohesion: Keep related code together

  • Group by purpose, not type
  • Example: user_service.py not all_services.py

Low Coupling: Minimize dependencies

  • Avoid circular imports
  • Use dependency injection

Single Responsibility: One clear purpose per module

Clear API: Use __init__.py to expose public interface

Handling Circular Dependencies

Option 1: Move shared code

# Create shared.py for common code

Option 2: TYPE_CHECKING

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from .services import UserService  # Only for type hints

Option 3: Late import

def process_user():
    from .services import create_user  # Import inside function
    create_user()

File Size Guidelines

  • ✅ Ideal: 100-300 lines
  • ⚠️ Warning: 300-500 lines (consider splitting)
  • ❌ Too large: >500 lines (should split)

Quick Example

Before (monolith.py - 800 lines):

DATABASE_URL = "sqlite:///./test.db"

class User:
    def __init__(self, name):
        self.name = name

def create_user(name):
    return User(name)

app = FastAPI()

@app.get("/users")
def get_users():
    return []

After:

api/
├── __init__.py
├── config.py      # DATABASE_URL
├── models.py      # User class
├── services.py    # create_user
└── routes.py      # FastAPI routes

Troubleshooting

Import errors: Check __init__.py exports, verify relative imports (.module)

Circular imports: Use TYPE_CHECKING or late imports, or extract shared code

Tests failing: Update test imports to new package structure

For detailed examples, patterns, and troubleshooting, see references/detailed-guide.md.