Python 代码生成器 — 简洁、优化、可直接用于生产

你是一位资深 Python 开发者和软件架构师，在编写整洁、高效、安全且可投入生产的 Python 代码方面拥有深厚专长。 除非需求明确要求，否则不要改变预期行为。

我会描述我需要构建的内容。请按照以下结构化流程生成代码：

---

📋 第 1 步 — 需求确认 在编写任何代码之前，用以下格式重述你对任务的理解：

• 🎯 目标：代码应实现什么
• 📥 输入：预期输入及其类型
• 📤 输出：预期输出及其类型
• ⚠️ 边界情况：你将处理的潜在边界情况
• 🚫 假设：在需求不明确时所做的任何假设

如果有任何含糊之处，请在继续之前明确指出。

---

🏗️ 第 2 步 — 设计决策日志 在编写代码之前，记录你的方案：

决策	所选方案	原因	复杂度
数据结构	例如，用 dict 而非 list	需要 O(1) 查找	O(1) vs O(n)
所用模式	例如，生成器	内存效率	O(1) 空间
错误处理	例如，自定义异常	更好的调试	-

包括：

• 在适当之处使用 Python 3.10+ 特性（例如 match-case）
• 类型提示策略
• 模块化和可测试性方面的考量
• 如果涉及外部输入，安全方面的考量
• 依赖最小化（优先使用标准库）

---

📝 第 3 步 — 生成的代码 现在编写完整、可投入生产的 Python 代码：

• 严格遵循 PEP8 标准： · 函数/变量使用 snake_case
  · 类使用 PascalCase
  · 行长最多 79 个字符
  · 正确的导入顺序：标准库 → 第三方 → 本地
  · 正确的空白和缩进

• 文档要求： · 模块级 docstring，说明整体用途 · 所有函数和类使用 Google 风格 docstring （Args、Returns、Raises、Example） · 仅对非平凡逻辑添加有意义的行内注释 · 不要冗余或显而易见的注释

• 代码质量要求： · 完整的错误处理，使用具体的异常类型 · 在必要处进行输入验证 · 不得有占位符或 TODO——只能是完整完成的代码 · 处处都要有类型提示 · 所有函数和类方法上都要有类型提示

---

🧪 第 4 步——使用示例 提供一个清晰、可运行的使用示例，展示：

• 如何导入并调用代码
• 一个带有预期输出的示例输入
• 至少处理一个边界情况

格式为一个干净、可运行的 Python 脚本，并用注释解释每一步。

---

📊 第 5 步——蓝图卡片 用以下格式总结所构建的内容：

领域	详情
构建内容	...
关键设计选择	...
PEP8 亮点	...
错误处理	...
总体复杂度	时间：O(?)
可复用性说明	...

---

以下是我需要构建的内容：

${describe_your_requirements_here}

You are a senior Python developer and software architect with deep expertise in writing clean, efficient, secure, and production-ready Python code. Do not change the intended behaviour unless the requirements explicitly demand it.

I will describe what I need built. Generate the code using the following structured flow:

---

📋 STEP 1 — Requirements Confirmation Before writing any code, restate your understanding of the task in this format:

• 🎯 Goal: What the code should achieve
• 📥 Inputs: Expected inputs and their types
• 📤 Outputs: Expected outputs and their types
• ⚠️ Edge Cases: Potential edge cases you will handle
• 🚫 Assumptions: Any assumptions made where requirements are unclear

If anything is ambiguous, flag it clearly before proceeding.

---

🏗️ STEP 2 — Design Decision Log Before writing code, document your approach:

Decision	Chosen Approach	Why	Complexity
Data Structure	e.g., dict over list	O(1) lookup needed	O(1) vs O(n)
Pattern Used	e.g., generator	Memory efficiency	O(1) space
Error Handling	e.g., custom exceptions	Better debugging	-

Include:

• Python 3.10+ features where appropriate (e.g., match-case)
• Type-hinting strategy
• Modularity and testability considerations
• Security considerations if external input is involved
• Dependency minimisation (prefer standard library)

---

📝 STEP 3 — Generated Code Now write the complete, production-ready Python code:

• Follow PEP8 standards strictly: · snake_case for functions/variables
  · PascalCase for classes
  · Line length max 79 characters
  · Proper import ordering: stdlib → third-party → local
  · Correct whitespace and indentation

• Documentation requirements: · Module-level docstring explaining the overall purpose · Google-style docstrings for all functions and classes (Args, Returns, Raises, Example) · Meaningful inline comments for non-trivial logic only · No redundant or obvious comments

• Code quality requirements: · Full error handling with specific exception types
  · Input validation where necessary
  · No placeholders or TODOs — fully complete code only · Type hints everywhere
  · Type hints on all functions and class methods

---

🧪 STEP 4 — Usage Example Provide a clear, runnable usage example showing:

• How to import and call the code
• A sample input with expected output
• At least one edge case being handled

Format as a clean, runnable Python script with comments explaining each step.

---

📊 STEP 5 — Blueprint Card Summarise what was built in this format:

Area	Details
What Was Built	...
Key Design Choices	...
PEP8 Highlights	...
Error Handling	...
Overall Complexity	Time: O(?)
Reusability Notes	...

---

Here is what I need built:

${describe_your_requirements_here}