Python Import Optimizer

Hook Content

The main content for this hook.

post-tool-use.json

json

{
  "hookConfig": {
    "hooks": {
      "postToolUse": {
        "script": "./.claude/hooks/python-import-optimizer.sh",
        "matchers": [
          "write",
          "edit"
        ]
      }
    }
  },
  "scriptContent": "#!/bin/bash\n\n# Read the tool input from stdin\nINPUT=$(cat)\nTOOL_NAME=$(echo \"$INPUT\" | jq -r '.tool_name')\nFILE_PATH=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // .tool_input.path // \"\"')\n\nif [ -z \"$FILE_PATH\" ]; then\n  exit 0\nfi\n\n# Check if this is a Python file\nif [[ \"$FILE_PATH\" == *.py ]]; then\n    echo \"🐍 Python Import Optimizer - Processing Python file...\"\n    echo \"📄 File: $FILE_PATH\"\n    \n    # Check if file exists\n    if [ ! -f \"$FILE_PATH\" ]; then\n        echo \"⚠️ File not found: $FILE_PATH\"\n        exit 1\n    fi\n    \n    # Step 1: Sort imports with isort\n    echo \"📋 Sorting imports with isort...\"\n    if command -v isort >/dev/null 2>&1; then\n        if isort \"$FILE_PATH\" --profile black --line-length 88 --check-only --diff; then\n            echo \"✅ Imports are already sorted\"\n        else\n            echo \"🔄 Sorting imports...\"\n            isort \"$FILE_PATH\" --profile black --line-length 88\n            echo \"✅ Imports sorted successfully\"\n        fi\n    else\n        echo \"⚠️ isort not found. Install with: pip install isort\"\n    fi\n    \n    # Step 2: Remove unused imports with autoflake (optional)\n    echo \"🧹 Removing unused imports...\"\n    if command -v autoflake >/dev/null 2>&1; then\n        # Check for unused imports first\n        if autoflake --check \"$FILE_PATH\" --remove-unused-variables --remove-all-unused-imports; then\n            echo \"✅ No unused imports found\"\n        else\n            echo \"🔄 Removing unused imports...\"\n            autoflake --in-place \"$FILE_PATH\" --remove-unused-variables --remove-all-unused-imports\n            echo \"✅ Unused imports removed\"\n        fi\n    else\n        echo \"ℹ️ autoflake not found (optional). Install with: pip install autoflake\"\n    fi\n    \n    # Step 3: Additional import analysis\n    echo \"🔍 Analyzing import structure...\"\n    \n    # Count different types of imports\n    STDLIB_IMPORTS=$(grep -c \"^import \\(os\\|sys\\|re\\|json\\|datetime\\|collections\\|itertools\\|functools\\|pathlib\\)\" \"$FILE_PATH\" 2>/dev/null || echo 0)\n    THIRD_PARTY_IMPORTS=$(grep -c \"^\\(import\\|from\\) \\(numpy\\|pandas\\|requests\\|flask\\|django\\|fastapi\\)\" \"$FILE_PATH\" 2>/dev/null || echo 0)\n    RELATIVE_IMPORTS=$(grep -c \"^from \\.[.]*\" \"$FILE_PATH\" 2>/dev/null || echo 0)\n    \n    echo \"📊 Import Summary:\"\n    echo \"  • Standard Library: $STDLIB_IMPORTS\"\n    echo \"  • Third Party: $THIRD_PARTY_IMPORTS\"\n    echo \"  • Relative: $RELATIVE_IMPORTS\"\n    \n    # Check for potential issues\n    if grep -q \"^import \\*\" \"$FILE_PATH\" 2>/dev/null; then\n        echo \"⚠️ Warning: Star imports detected (import *) - consider specific imports\"\n    fi\n    \n    if [ \"$(grep -c '^import\\|^from' \"$FILE_PATH\" 2>/dev/null || echo 0)\" -gt 20 ]; then\n        echo \"💡 Tip: Consider grouping related imports or using a package structure\"\n    fi\n    \n    echo \"\"\n    echo \"💡 Python Import Tips:\"\n    echo \"  • Use absolute imports when possible\"\n    echo \"  • Group imports: stdlib, third-party, local\"\n    echo \"  • Avoid star imports (import *)\"\n    echo \"  • Use 'from module import specific_function' for clarity\"\n    \n    echo \"\"\n    echo \"🎯 Python import optimization complete!\"\n    \nelse\n    echo \"ℹ️ File is not a Python file: $FILE_PATH\"\nfi\n\nexit 0"
}

Features

Key capabilities and functionality

Automatic import sorting with isort
PEP 8 compliant import organization
Unused import removal
Black profile compatibility
Import grouping by type
Code formatting integration

Installation

Setup instructions and requirements

Claude Code Setup

Create hooks directory: mkdir -p .claude/hooks
Create hook script: .claude/hooks/python-import-optimizer.sh
Add hook configuration to your Claude Code config
Make script executable: chmod +x .claude/hooks/python-import-optimizer.sh
Restart Claude Code to activate the hook

Configuration Paths

project

.claude/hooks/

user

~/.claude/hooks/

Requirements

Claude Code CLI
Bash shell
Hook-specific dependencies (e.g., jq, prettier)

Hook Configuration

Hook setup and script content

post-tool-use-config.json

json

{
  "hooks": {
    "postToolUse": {
      "script": "./.claude/hooks/python-import-optimizer.sh",
      "matchers": [
        "write",
        "edit"
      ]
    }
  }
}

post-tool-use-script.sh

bash

#!/bin/bash

# Read the tool input from stdin
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')

if [ -z "$FILE_PATH" ]; then
  exit 0
fi

# Check if this is a Python file
if [[ "$FILE_PATH" == *.py ]]; then
    echo "🐍 Python Import Optimizer - Processing Python file..."
    echo "📄 File: $FILE_PATH"
    
    # Check if file exists
    if [ ! -f "$FILE_PATH" ]; then
        echo "⚠️ File not found: $FILE_PATH"
        exit 1
    fi
    
    # Step 1: Sort imports with isort
    echo "📋 Sorting imports with isort..."
    if command -v isort >/dev/null 2>&1; then
        if isort "$FILE_PATH" --profile black --line-length 88 --check-only --diff; then
            echo "✅ Imports are already sorted"
        else
            echo "🔄 Sorting imports..."
            isort "$FILE_PATH" --profile black --line-length 88
            echo "✅ Imports sorted successfully"
        fi
    else
        echo "⚠️ isort not found. Install with: pip install isort"
    fi
    
    # Step 2: Remove unused imports with autoflake (optional)
    echo "🧹 Removing unused imports..."
    if command -v autoflake >/dev/null 2>&1; then
        # Check for unused imports first
        if autoflake --check "$FILE_PATH" --remove-unused-variables --remove-all-unused-imports; then
            echo "✅ No unused imports found"
        else
            echo "🔄 Removing unused imports..."
            autoflake --in-place "$FILE_PATH" --remove-unused-variables --remove-all-unused-imports
            echo "✅ Unused imports removed"
        fi
    else
        echo "ℹ️ autoflake not found (optional). Install with: pip install autoflake"
    fi
    
    # Step 3: Additional import analysis
    echo "🔍 Analyzing import structure..."
    
    # Count different types of imports
    STDLIB_IMPORTS=$(grep -c "^import \(os\|sys\|re\|json\|datetime\|collections\|itertools\|functools\|pathlib\)" "$FILE_PATH" 2>/dev/null || echo 0)
    THIRD_PARTY_IMPORTS=$(grep -c "^\(import\|from\) \(numpy\|pandas\|requests\|flask\|django\|fastapi\)" "$FILE_PATH" 2>/dev/null || echo 0)
    RELATIVE_IMPORTS=$(grep -c "^from \.[.]*" "$FILE_PATH" 2>/dev/null || echo 0)
    
    echo "📊 Import Summary:"
    echo "  • Standard Library: $STDLIB_IMPORTS"
    echo "  • Third Party: $THIRD_PARTY_IMPORTS"
    echo "  • Relative: $RELATIVE_IMPORTS"
    
    # Check for potential issues
    if grep -q "^import \*" "$FILE_PATH" 2>/dev/null; then
        echo "⚠️ Warning: Star imports detected (import *) - consider specific imports"
    fi
    
    if [ "$(grep -c '^import\|^from' "$FILE_PATH" 2>/dev/null || echo 0)" -gt 20 ]; then
        echo "💡 Tip: Consider grouping related imports or using a package structure"
    fi
    
    echo ""
    echo "💡 Python Import Tips:"
    echo "  • Use absolute imports when possible"
    echo "  • Group imports: stdlib, third-party, local"
    echo "  • Avoid star imports (import *)"
    echo "  • Use 'from module import specific_function' for clarity"
    
    echo ""
    echo "🎯 Python import optimization complete!"
    
else
    echo "ℹ️ File is not a Python file: $FILE_PATH"
fi

exit 0

Use Cases

Common scenarios and applications

Organize Python imports according to PEP 8 standards
Remove unused imports automatically
Group imports by type (standard library, third-party, local)
Maintain consistent import formatting across projects
Integrate with Black code formatter
Clean up import statements in Python files
Ensure import consistency in team projects
Optimize Python file organization

Troubleshooting

Common issues and solutions

isort conflicts with Black formatter settings
Hook already uses --profile black flag for compatibility. Ensure Black and isort versions are current. Add .isort.cfg with profile = black and line_length = 88 for project-wide consistency.
autoflake removes imports that are actually used
Add # noqa comments to imports that should be preserved. Configure autoflake to exclude specific files with --exclude in hook script, or use __all__ exports to signal intentional module-level imports.
Hook processes __init__.py and breaks package exports
Exclude __init__.py from autoflake processing by modifying hook to check filename. Add special handling for package files where import * is intentional for re-exporting.
Relative imports get converted to absolute incorrectly
Configure isort with known_first_party setting in setup.cfg or pyproject.toml. Use --src-path flag in hook to help isort determine project root for proper import classification.

Reviews (0)

Sort by:

Loading reviews...

Automate with Claude Hooks

Get the latest automation hooks delivered weekly.

Join our community of Claude power users. No spam, unsubscribe anytime.

Claude Code Setup

Configuration Paths

Requirements

Reviews (0)

Category

Source

Accessibility Checker

API Endpoint Documentation Generator

Auto Code Formatter Hook