fissionpy 0.2.2

Python 工程目录裂变迁移工具——基于 LibCST 将工程目录中的大文件按模块相关性拆分迁移

fissionpy

Python Project Fission & Migration Tool — A lossless code splitting and migration solution powered by LibCST.

Repository: https://github.com/kenny8zeng/fissionpy

Documentation:

• English | 中文

fissionpy is designed for refactoring large Python projects, safely and automatically splitting massive module files (thousands to tens of thousands of lines) into smaller, maintainable modules. Using LibCST (Concrete Syntax Tree) technology, it ensures all code changes are lossless — preserving original formatting, comments, and whitespace.

Core Features

1. Project-Level Symbol Indexing

• Recursively scans entire Python projects, parsing all .py files
• Uses LibCST to extract top-level symbols (functions, classes, variable assignments)
• Analyzes inter-symbol dependencies via LibCST ScopeProvider
• Tracks cross-file import statements, automatically identifying symbol reference chains
• SQLite persistent storage with incremental analysis (file hash-based)

2. Symbol Browsing & Dependency Visualization

• fission show: View project file list, file symbol tables, symbol details
• fission tree: Display symbol dependency relationships in tree format
• Cross-file dependency annotations: Clearly mark which symbols are referenced by other files
• Reverse dependency queries: Find what depends on a given symbol

3. Intelligent Migration Plan Generation

• Automatic grouping based on connected components of the symbol dependency graph
• Generates YAML migration plans, supporting manual editing and adjustment
• Automatically calculates import impact scope (which files need import updates)
• Supports subdirectory modules (module/deep/path → module/deep/path.py)

4. Lossless Code Extraction

• Uses LibCST CST nodes for extraction, preserving original format character-by-character
• Preserves leading_lines (comments, blank lines), decorators, base classes
• Automatically prepends necessary imports like from __future__ import annotations
• Post-extraction verification: Compares extracted text with original

5. Project-Wide Import Propagation

• Uses LibCST CSTTransformer to precisely replace import statements
• Handles complex scenarios: from X import Y, Z splitting, aliased imports
• Automatically updates all affected import statements across the project
• Supports both relative and absolute imports

6. Reorganization & Re-Export

• Backs up original files (.bak suffix)
• Removes extracted symbols, retains remaining ones
• Automatically adds re-export imports (from new_module import Symbol)
• Creates subdirectory __init__.py files

7. Triple Consistency Verification

• Symbol Integrity: All original symbols found in split files
• Format Losslessness: Extracted text matches original character-by-character
• Import Reachability: All import statement target files exist

8. Symbol Index Export

• fission export: Export indexed symbols and dependencies to JSON
• Flat JSON structure with files/symbols/dependencies/imports arrays
• File filtering with --file for targeted export
• Optional --include-source for source code text

AI Agent Skill

fissionpy provides a Skill file (SKILL.md) specifically designed for AI Agents, enabling AI programming assistants to autonomously complete large Python file splitting and migration workflows.

Skill Triggers

When users issue commands like "split this Python file", "refactor large module", or when files exceed 1000 lines, the AI Agent automatically activates the fissionpy Skill and executes the complete 7-phase workflow:

1. Analyze → fission analyze indexes all symbols and dependencies
2. Browse → fission show / fission tree explores file structure
3. Export → fission export outputs structured JSON for AI decision-making
4. Plan → fission plan creates YAML migration plan
5. Edit → Intelligently assigns symbols to modules (user-adjustable)
6. Extract → fission extract performs lossless code extraction
7. Migrate → fission migrate updates project-wide imports and verifies

Skill Capabilities

• Autonomous Execution: AI Agent can complete the full workflow from analysis to migration
• Smart Grouping: Automatically suggests module splits based on dependency connected components
• Safe Verification: Automatic validation after each step ensures code integrity
• Best Practices: Built-in module naming conventions, splitting strategies, edge case handling
• Troubleshooting: Common issue diagnostics and solutions included

Installation

uv pip install -e .

Requires Python 3.11+.

Quick Start

# Step 1: Navigate to project root directory
cd /path/to/my_project/

# Step 2: Analyze project (use relative paths from project root)
fission analyze ./backend/

# Step 3: Browse symbols
fission show
fission show --file ./backend/models.py
fission show --symbol User
fission tree --file ./backend/views.py

# Step 3.5: Export index (optional, useful for AI Agents)
fission export

# Step 4: Generate migration plan
fission plan --target ./backend/models.py --output ./fission-plan.yaml

# Step 5: Edit plan.yaml (move symbols from retain to modules)
# Edit YAML to assign symbols to target modules

# Step 6: Extract symbols
fission extract ./fission-plan.yaml

# Step 7: Migrate (update project-wide imports)
fission migrate ./fission-plan.yaml

⚠️ Important: Path Consistency

Always use relative paths from the project root directory.

Why: Supports project movement and version control.

Correct (use ./ prefix):

cd /path/to/project/
fission analyze ./backend/
fission plan --target ./backend/models.py

Wrong (absolute paths):

fission analyze /home/user/project/backend/
fission plan --target /home/user/project/backend/models.py

Command Reference

fission analyze

Analyzes project directory, indexing all files and symbols into SQLite database.

fission analyze <directory> [--db PATH] [--exclude PATTERN] [--force] [--verbose]

Option	Description
--db	SQLite database path, default ./.fission/fission.db
--exclude	Exclude directory patterns, repeatable
--force	Force re-parse all files (ignore incremental cache)
--verbose	Detailed output

⚠️ Path Note: Always execute from project root and use relative paths:

# ✅ Correct
cd /path/to/project/
fission analyze ./backend/

# ❌ Incorrect
fission analyze /home/user/project/backend/

fission show

Browse symbol information — project file list, file symbol list, symbol details and dependencies.

fission show [--file PATH] [--symbol NAME] [--db PATH] [--verbose]

Option	Description
--file	View top-level symbols and imports for specified file
--symbol	View symbol details, dependencies, and dependents
--db	SQLite database path
--verbose	Detailed output

⚠️ Path Note: Use relative paths from project root:

# ✅ Correct
fission show --file ./backend/models.py

# ❌ Incorrect
fission show --file /home/user/project/backend/models.py

Without options, displays project file overview.

fission tree

Prints symbol dependency tree for specified file.

fission tree --file PATH [--symbol NAME] [--reverse] [--db PATH] [--verbose]

Option	Description
--file	Target file path (required)
--symbol	Show only subtree for specified symbol
--reverse	Reverse view: show what depends on this symbol
--db	SQLite database path
--verbose	Detailed output

⚠️ Path Note: Use relative paths from project root:

# ✅ Correct
fission tree --file ./backend/views.py

# ❌ Incorrect
fission tree --file /home/user/project/backend/views.py

fission plan

Generates YAML migration plan template for target file. Auto-groups based on symbol dependencies, user-editable.

fission plan --target PATH [--db PATH] [--output PATH] [--verbose]

Option	Description
--target	Target file path to split (required)
--db	SQLite database path
--output	YAML output path, default ./fission-plan.yaml
--verbose	Detailed output

⚠️ Path Note: Use relative paths from project root:

# ✅ Correct
fission plan --target ./backend/models.py --output ./fission-plan.yaml

# ❌ Incorrect
fission plan --target /home/user/project/backend/models.py --output /home/user/project/fission-plan.yaml

fission extract

Executes code extraction — losslessly extracts symbols into new module files per plan.

fission extract <plan_file> [--db PATH] [--resume] [--verbose]

Option	Description
--db	SQLite database path
--resume	Resume extraction from last interruption
--verbose	Detailed output

⚠️ Path Note: Use relative paths from project root:

# ✅ Correct
fission extract ./fission-plan.yaml

# ❌ Incorrect
fission extract /home/user/project/fission-plan.yaml

fission migrate

Completes project-level migration — updates project-wide imports, backs up and reorganizes original file, runs consistency checks.

fission migrate <plan_file> [--db PATH] [--no-reexport] [--resume] [--verbose]

Option	Description
--db	SQLite database path
--no-reexport	Don't generate re-export imports in original file
--resume	Resume migration from last interruption
--verbose	Detailed output

⚠️ Path Note: Use relative paths from project root:

# ✅ Correct
fission migrate ./fission-plan.yaml

# ❌ Incorrect
fission migrate /home/user/project/fission-plan.yaml

fission export

Exports indexed symbols and dependencies to JSON file.

fission export [--file PATH] [--db PATH] [--output PATH] [--include-source] [--verbose]

Option	Description
--file	Filter export to specified file's symbols and dependencies
--db	SQLite database path, default ./.fission/fission.db
--output	JSON output path, default ./fission-index.json
--include-source	Include symbol source code text in output
--verbose	Detailed output

⚠️ Path Note: Use relative paths from project root (same as other commands):

# Export all indexed data
fission export

# Export specific file
fission export --file ./backend/models.py

# Include source code
fission export --include-source

# Custom output path
fission export --output ./my-index.json

Global option: --version displays version number.

YAML Plan Format

The YAML file structure generated by fission plan:

# fission migration plan - edit modules/symbols before running extract
project_root: .
target_file: backend/models.py
modules:
- name: _migrated/user_types
  symbols:
  - User
  - UserProfile
  - UserStatus
- name: _migrated/order_types
  symbols:
  - Order
  - OrderItem
retain:
- router
- app_config
import_impact:
- file: ./backend/views.py
  old_import: from backend.models import User
  new_import: from _migrated.user_types import User
- file: ./backend/services.py
  old_import: from backend.models import Order
  new_import: from _migrated.order_types import Order

Field	Description
project_root	Project root directory (should be . for relative paths)
target_file	Relative path to target file from project root
modules	List of modules to extract, each with name and symbols
retain	Symbols to keep in the original file
import_impact	List of import update impacts, showing affected files and old/new import pairs

How to Edit the Plan

⚠️ Critical Rules - Follow these rules to avoid extraction failures:

1. Move symbols from retain to modules:

   • Initially, all symbols are in retain
   • Move symbols you want to extract into modules
   • Each symbol can only appear in ONE place (either modules or retain)

2. Verify symbol names:

   # Check actual symbol names in the target file
   fission show --file models.py
   

   • Symbol names must match exactly (case-sensitive)
   • No typos or extra spaces

3. Validate module names:

   • Each path segment must be a valid Python identifier
   • Cannot be a Python keyword (e.g., class, def, import)
   • Cannot start with a number
   • Use / for subdirectories (e.g., _migrated/models/user)

4. Do NOT modify import_impact:

   • This section is auto-generated and read-only
   • Modifying it will cause incorrect import updates

Common Mistakes

❌ Mistake 1: Duplicate symbols

modules:
- name: models
  symbols:
  - User
- name: entities
  symbols:
  - User  # ERROR: User appears twice!
retain: []

❌ Mistake 2: Non-existent symbols

modules:
- name: models
  symbols:
  - User
  - NonExistent  # ERROR: Symbol not in target file!
retain: []

❌ Mistake 3: Invalid module names

modules:
- name: 123-bad-name  # ERROR: Cannot start with number
  symbols:
  - User
- name: class         # ERROR: Python keyword
  symbols:
  - Product
retain: []

✅ Correct example:

modules:
- name: _migrated/models
  symbols:
  - User
  - Product
- name: _migrated/services
  symbols:
  - UserService
  - ProductService
retain:
- router
- app_config

Editing Workflow

1. Generate the plan:

   cd /path/to/project/
   fission plan --target ./backend/models.py --output ./fission-plan.yaml
   

2. Review the plan:

   cat ./fission-plan.yaml
   

3. Check symbol names:

   fission show --file ./backend/models.py
   

4. Edit the plan:

   • Move symbols from retain to modules
   • Create new modules or adjust existing ones
   • Ensure no duplicates

5. Validate YAML syntax:

   python -c "import yaml; yaml.safe_load(open('./fission-plan.yaml'))"
   

6. Run extraction:

   fission extract ./fission-plan.yaml
   

Subdirectory Support

Use / in module names to create subdirectory structures:

• _migrated/types → Output file _migrated/types.py, auto-creates _migrated/ directory and __init__.py
• _migrated/models/user → Output file _migrated/models/user.py, auto-creates all intermediate __init__.py files

Each path segment must be a valid Python identifier, not a keyword. The corresponding Python import statement replaces / with ., e.g., _migrated.types.

Multi-Level Directory Examples

Example 1: Two-level directory

modules:
- name: _migrated/models
  symbols:
  - User
  - Product
- name: _migrated/services
  symbols:
  - UserService
  - ProductService

Output structure:

project/
├── _migrated/
│   ├── __init__.py
│   ├── models.py
│   └── services.py
└── backend/
    └── models.py (original file, reorganized)

Example 2: Three-level directory

modules:
- name: _migrated/models/user
  symbols:
  - User
  - UserProfile
- name: _migrated/models/order
  symbols:
  - Order
  - OrderItem
- name: _migrated/services
  symbols:
  - UserService
  - OrderService

Output structure:

project/
├── _migrated/
│   ├── __init__.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── order.py
│   └── services.py
└── backend/
    └── models.py (original file, reorganized)

Import statements after migration:

# In other files
from _migrated.models.user import User
from _migrated.models.order import Order
from _migrated.services import UserService

Rules for Subdirectory Module Names

1. Path segments must be valid Python identifiers:

   • ✅ _migrated/models/user
   • ✅ internal/utils
   • ❌ 123-bad-name
   • ❌ my-module (hyphens not allowed)

2. Cannot use Python keywords:

   • ✅ models/classifier
   • ❌ models/class (class is a keyword)

3. Auto-creation of __init__.py:

   • All intermediate directories get __init__.py automatically
   • Makes the directory a valid Python package

4. Import path conversion:

   • YAML: _migrated/models/user
   • Python import: from _migrated.models.user import User

Key Features

• LibCST Lossless Extraction: CST-based code extraction preserves comments, formatting, and whitespace
• CSTTransformer Import Updates: Precise import modification using CSTTransformer, never regex
• Incremental Analysis: File hash-based incremental parsing, unchanged files auto-skipped
• Cross-File Dependency Tracking: Automatically identifies and records cross-file symbol dependencies
• Triple Verification: Post-migration automatic validation of symbol integrity, format losslessness, and import reachability

Real-World Case: Splitting a 12,775-Line FastAPI File

fissionpy successfully processed a 12,775-line presales_api.py file (FastAPI router module), splitting it into 7 modules:

# Navigate to project root
cd /home/user/project/

# Analyze 158 files, 3190 symbols (65 seconds)
fission analyze ./backend/

# Generate plan, manually edit to distribute 454 symbols into 7 modules
fission plan --target ./app/presales_api.py --output ./fission-plan.yaml

# Extract 127 symbols into 6 new modules (21 seconds)
fission extract ./fission-plan.yaml

# Migrate and update imports in 2 dependent files (80 seconds)
fission migrate ./fission-plan.yaml

Results:

File	Lines	Description
app/presales_api.py	8,783	Reorganized (reduced 3,992 lines, 31%)
app/_di.py	157	DI config + router + providers
app/case_api.py	2,171	Case API endpoints
app/knowledge_api.py	758	Knowledge base API endpoints
app/mailbox_api.py	462	Mailbox sync API
app/template_api.py	421	Template & FAQ API
app/misc_api.py	413	Miscellaneous API

Total: ~3 minutes to complete lossless splitting and migration of a 12,775-line large file, all verifications passed.

Development

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests (63 tests, <1 second)
cd /path/to/project/
pytest ./tests/

Tech Stack

• LibCST: Python concrete syntax tree parsing, supports lossless code operations
• Typer: CLI framework, type-safe wrapper around Click
• SQLite: Lightweight relational database, stores project symbol index
• ruamel.yaml: Round-trip YAML parser
• pytest: Testing framework, 63 unit + integration tests

License

MIT License