Pythonic Code Style

Task Objectives

• This Skill is used to: analyze and improve Python code style to make it more in line with Python language features and best practices
• Capabilities include:
  • Code Style Analysis: Identify non-Pythonic patterns and provide improvement suggestions
  • Pythonic Idioms: List comprehensions, generators, context managers, decorators, metaclasses, etc.
  • Design Pattern Application: SOLID principles, descriptor protocol, iterator protocol, etc.
  • Performance Optimization: Memory optimization, computation optimization, I/O optimization, concurrency patterns, caching strategies
  • Refactoring Guidance: Code smell detection, refactoring techniques, refactoring patterns, refactoring processes
  • Practical Templates: Provide ready-to-use code templates (140+)
• Trigger Conditions:
  • Users present code and ask "how to implement it more Pythonically"
  • Users ask "is this code Pythonic"
  • Users need code review and style improvement suggestions
  • Users ask about best practices for specific Python syntax
  • Users need performance optimization or refactoring suggestions
  • Users request advanced Python patterns or design patterns

Core Concepts

Friendly Python = User-Friendly + Maintainer-Friendly

┌──────────────────────────────────────────────────────────┐
│           FRIENDLY PYTHON = User-Friendly Python         │
├────────────────────────────────┬─────────────────────────┤
│   User-Friendly               │   Maintainer-Friendly     │
│   ─────────────────           │   ─────────────────      │
│   • Sensible defaults         │   • Single change point  │
│   • Minimal required params   │   • Registry over if-else│
│   • Hidden resource mgmt      │   • Explicit over magic  │
│   • Simple → complex path     │   • Readable & debuggable│
└────────────────────────────────┴─────────────────────────┘

Design Principles

1. User-Friendly

• Provide sensible defaults: Enable quick start without reading documentation
• Minimal required parameters: Hide complex object assembly
• Transparent resource management: Use context managers or unified entry points
• Simple to complex: Simple path is the default, complex requirements can be explicitly extended

2. Maintainer-Friendly

• Single change point: When adding new strategies/commands/implementations, converge to one modification point
• Registry instead of if-else: Use registry/plugin tables instead of conditional branch chains
• Use magic cautiously: Auto-scanning and dynamic imports need to evaluate readability and debuggability

3. Construction Patterns

• Avoid semi-finished objects: Do not recommend "instantiate then load"; use

  classmethod

  for construction
• Multiple sources and entry points: Use different construction entries for env/file/explicit scenarios, do not use flags in

  __init__

• Reduce import burden: Do not expose unnecessary names to the package top level

4. Ecosystem Expansion

• Use extension points: hooks, adapters, auth, middleware
• Avoid monkey patching: Use registration, protocols, inheritance instead
• Wrap instead of rewrite: Extend functions instead of overwriting everything

5. Explicitness

• Avoid

  __getattr__

  : Prioritize explicit fields and descriptors
• Use metaclasses cautiously: Only use when necessary
• Explicit is better than implicit: Prioritize readability over showing off skills

Operation Steps

┌─────────────────────────────────────────────────────────────┐
│  1. UNDERSTAND: Understand requirements and existing code  │
├─────────────────────────────────────────────────────────────┤
│  2. ANALYZE: Analyze code style issues and identify non-Pythonic patterns │
├─────────────────────────────────────────────────────────────┤
│  3. IMPROVE: Apply Pythonic idioms and design patterns     │
├─────────────────────────────────────────────────────────────┤
│  4. REVIEW: Check improvement plans against review checklists │
├─────────────────────────────────────────────────────────────┤
│  5. REFINE: Optimize details and provide alternative solutions and trade-off analysis │
└─────────────────────────────────────────────────────────────┘

Standard Process:

1. Code Analysis
   • Read the code provided by users and identify non-Pythonic patterns
   • Refer to the Zen of Python and specifications in references/python-rules.md
   • Focus on: naming conventions, control flow, data type usage, function design, exception handling, etc.
2. Pythonic Improvements
   • Select appropriate reference documents based on the type of problem
   • Basic Improvements: references/control-flow.md, references/data-types.md, references/functions.md
   • Advanced Features: references/decorators.md, references/advanced-patterns.md
   • Performance Optimization: references/performance-tips.md
   • Refactoring Guidance: references/refactoring-guide.md
   • Apply Pythonic idioms: list comprehensions, generators, context managers, decorators, etc.
   • Refer to standard templates in assets/templates/
3. Code Comparison and Explanation
   • Show code comparison before and after improvement
   • Explain the reasons for improvement and the Pythonic principles followed
   • Illustrate improvements in performance, readability, and maintainability
   • Provide alternative solutions and trade-off analysis when necessary
4. Best Practices and Advanced Suggestions
   • Provide design principle suggestions based on references/solid-principles.md
   • Handle edge cases with reference to references/edge-cases.md
   • Provide learning resources and further optimization directions for related Pythonic patterns

Optional Branches:

• Basic Style Issues: Use basic reference documents to provide improvement suggestions
• Advanced Feature Application: Recommend using advanced patterns such as descriptors, metaclasses, iterator protocols, etc.
• Performance Optimization Requirements: Combine performance optimization reference documents to provide suggestions
• Refactoring Requirements: Use refactoring guides to provide systematic improvement plans
• Code is already good: Identify details that can be further optimized and provide advanced optimization suggestions

Review Checklist

Recommended and Avoided Patterns

Recommended Patterns

with

@classmethod

Avoided Patterns

__init__

__getattr__

Response Format

## Summary
[Summary of completed work]

## Changes Made
- [Improvement 1]: [Explanation]
- [Improvement 2]: [Explanation]

## Design Decisions
- [Why certain patterns were chosen]

## Review Checklist
- [x] Single-point extensibility
- [x] Reasonable default values
- [x] Progressive complexity
- [x] Correct use of extension points
- [x] Explicitness over magic

## Suggestions (if any)
- [Areas for further improvement]

Resource Index

Basic References

• Friendly Patterns: See references/friendly-patterns.md (Friendly Python concept, user-friendly patterns, maintainer-friendly patterns, construction patterns, registry patterns, context managers)
• Python Rules: See references/python-rules.md (Zen of Python, PEP 8 specifications)
• Variable Naming: See references/variables-naming.md (Naming principles, boolean variable naming, loop variable naming, temporary variables)
• Control Flow: See references/control-flow.md (if-else optimization, guard clauses, early returns, walrus operator, loop optimization, match-case)
• Numbers and Strings: See references/data-types.md (Number operations, string processing, formatting, regular expressions, type conversion)
• Container Types: See references/container-types.md (Best practices for lists, dictionaries, sets, tuples, comprehensions, collections module)
• Function Design: See references/functions.md (Function design principles, parameter design, return value design, type hints, higher-order functions)
• Exception Handling: See references/exceptions.md (Best practices for exception handling, context managers)
• Decorators: See references/decorators.md (In-depth application of decorators, class decorators, parameterized decorators)
• Cyclic Imports: See references/cyclic-imports.md (Definition, causes, consequences, and solutions for cyclic imports)
• File Operations: See references/file-operations.md (File reading and writing, path handling, pathlib)

Advanced References

• SOLID Principles: See references/solid-principles.md (Object-oriented design principles, design patterns)
• Advanced Patterns: See references/advanced-patterns.md (Metaclasses, descriptors, iterator protocols, concurrency, magic methods)
• Performance Optimization: See references/performance-tips.md (Performance analysis, memory optimization, computation optimization, concurrency, caching)
• Refactoring Guide: See references/refactoring-guide.md (Code smells, refactoring techniques, refactoring patterns, refactoring tools)
• Edge Cases: See references/edge-cases.md (Exception and edge case handling)

Code Templates

• Basic Templates: See assets/templates/naming-patterns.py, assets/templates/control-flow-patterns.py, assets/templates/string-number-operations.py, assets/templates/container-operations.py, assets/templates/exception-handling.py
• Advanced Templates: See assets/templates/advanced-patterns.py (Advanced patterns such as metaclasses, descriptors, iterators, decorators, concurrency, etc.)
• Performance Templates: See assets/templates/performance-patterns.py (Performance patterns such as caching, batching, lazy evaluation, parallel processing, etc.)

Core Principles

• Beautiful is better than ugly: Prioritize concise and elegant solutions
• Explicit is better than implicit: Code should be clear and easy to understand, avoid over-design
• Simple is better than complex: Use minimal code to complete tasks, avoid unnecessary complexity
• Complex is better than complicated: Use organized complex structures instead of messy code
• Flat is better than nested: Reduce nesting levels to improve code readability
• Sparse is better than dense: Reasonable blank lines and spaces make code easier to read
• Readability counts: Code is for people to read, clarity comes first
• Special cases aren't special enough to break the rules: But practicality beats purity
• User-Friendly + Maintainer-Friendly: APIs are easy to use, code is easy to maintain

Implementation Instructions

• Code Analysis and Improvement: The agent directly analyzes code and provides Pythonic improvement suggestions
• Template Recommendation: Select appropriate templates from

  assets/templates/

  and demonstrate usage methods
• Best Practice Guidance: Provide detailed guidance and examples based on reference documents

Usage Examples

Example 1: Friendly Pattern Application

• Function Description: Apply registry pattern to replace if-else branches and improve code extensibility
• Execution Method: Analyze existing code structure and refactor to registry pattern
• Reference Document: references/friendly-patterns.md
• Key Points:
  • Identify a large number of if-else branches
  • Use registry decorators to replace conditional chains
  • Adding new features only requires registration, no need to modify core code
  • Maintain code readability and maintainability

Example 2: Basic Loop Improvement

• Function Description: Convert traditional for loops to list comprehensions or generator expressions
• Execution Method: The agent analyzes code and provides improvement suggestions
• Reference Document: references/control-flow.md
• Key Points:
  • Identify convertible loop patterns
  • Use list comprehensions to simplify code
  • Use generator expressions for large data
  • Maintain code readability

Example 2: Naming Convention Optimization

• Function Description: Improve naming of variables, functions, and classes
• Execution Method: Provide clearer and more descriptive naming suggestions
• Reference Document: references/variables-naming.md
• Template Reference: assets/templates/naming-patterns.py
• Key Points:
  • Use meaningful names
  • Follow naming conventions (snake_case, CamelCase)
  • Avoid abbreviations and ambiguities
  • Use verbs for function names, nouns for class names

Example 3: Exception Handling Improvement

• Function Description: Improve exception handling methods and resource management
• Execution Method: Recommend more Pythonic exception handling patterns
• Reference Document: references/exceptions.md
• Template Reference: assets/templates/exception-handling.py
• Key Points:
  • Catch specific exception types
  • Use context managers to manage resources
  • Provide useful error messages
  • Avoid bare except

Example 4: Function Design Optimization

• Function Description: Optimize function design and parameter passing
• Execution Method: Provide function rewriting suggestions
• Reference Document: references/functions.md
• Key Points:
  • Follow single responsibility principle
  • Use default parameters and variable parameters reasonably
  • Use type hints to improve readability
  • Return consistent result types

Example 5: Advanced Pattern Application

• Function Description: Apply advanced patterns such as metaclasses, descriptors, iterator protocols, etc.
• Execution Method: Analyze requirements and recommend appropriate advanced patterns
• Reference Document: references/advanced-patterns.md
• Template Reference: assets/templates/advanced-patterns.py
• Key Points:
  • Understand applicable scenarios and trade-offs
  • Correctly implement protocols and magic methods
  • Maintain code readability and maintainability
  • Avoid over-design

Example 6: Performance Optimization

• Function Description: Provide performance optimization suggestions
• Execution Method: Analyze code and provide optimization solutions
• Reference Document: references/performance-tips.md
• Template Reference: assets/templates/performance-patterns.py
• Key Points:
  • Use performance analysis tools to identify bottlenecks
  • Select appropriate data structures and algorithms
  • Use caching and batching
  • Consider concurrency and asynchronous processing

Example 7: Code Refactoring

• Function Description: Systematically improve code structure and quality
• Execution Method: Provide refactoring plans and steps
• Reference Document: references/refactoring-guide.md
• Key Points:
  • Identify code smells
  • Refactor in small steps, keep tests passing
  • Extract methods and classes to reduce duplication
  • Simplify conditions and complex logic

Notes

• Prioritize using Python built-in functions and standard libraries, avoid reinventing the wheel
• Pythonic does not mean the shortest code, balance conciseness and readability
• Follow PEP 8 code style specifications
• Make full use of Python's dynamic features and syntactic sugar
• Consider code performance and maintainability, avoid over-optimization
• Understand SOLID principles and write maintainable object-oriented code
• Correctly handle edge cases and exceptions
• Consider applicable scenarios and maintainability when using advanced patterns
• Measure before performance optimization, avoid premature optimization
• Keep tests passing during refactoring, improve gradually
• Follow the "User-Friendly + Maintainer-Friendly" design concept
• Use review checklists to ensure code quality
• Prioritize recommended patterns and avoid anti-patterns