Python Coding Standards

Unified baseline for Python code implementation phase, covering requirements for types, logging, naming and structure.

⚠️ Core Mandatory Requirements

1. Type Hints

• Use

  -> None

  for return values with no data
• Public APIs must provide complete docstrings (parameters, return values, exceptions)

2. Logging Specifications

src.logger.setup_logger

print

• Except for test sample code
• Error paths must use

  logger.error

  or

  logger.exception

AI Agent Behavior Requirements

When Creating New Files

• Must add type hints
• Must use logger (print is prohibited)

When Modifying Existing Files

• Newly added code must comply with type hint requirements
• Newly added logs must use logger

During Code Review

• Check completeness of type hints
• Check if print is used

Acceptance Criteria

• All functions, methods, and classes have type hints
• Public APIs have complete docstrings
• Logs of key modules cover normal operation and exception branches

Reference Materials

• references/type-hints.md

  - Detailed specifications for type hints

• references/logging.md

  - Detailed explanation of logging specifications

• references/naming-conventions.md

  - Detailed explanation of naming conventions

• references/code-structure.md

  - Detailed explanation of code structure