#Python 模块开发指南

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

"""用户友好型问候模块

提供公开的 `greet()` 和 `farewell()` 函数，支持自定义问候语气。
也可以通过命令行直接调用：
- 无参数：输出通用问候
- 1个参数：输出指定人名的问候
"""

__author__ = "CodeDog2024"
__version__ = "0.1.0"
__license__ = "MIT"

# 导入区（模块文档后、全局变量前）
import sys
from typing import Optional

# 常量区（全大写、下划线分隔，尽量放在导入后）
_DEFAULT_GREETING = "Hello"
_DEFAULT_FAREWELL = "Goodbye"

# 私有辅助函数/类（单下划线开头，仅内部用）
def _build_message(template: str, name: Optional[str] = None) -> str:
    """内部辅助：根据模板和人名生成完整消息"""
    if not name:
        return f"{template}!"
    return f"{template}, {name}!"

# 公开函数/类（普通命名，放在辅助之后）
def greet(name: Optional[str] = None, custom_template: Optional[str] = None) -> str:
    """生成正式/自定义的问候语
    
    Args:
        name: 要问候的对象名称，省略则输出通用问候
        custom_template: 自定义问候模板，省略用默认 "Hello"
        
    Returns:
        格式化后的问候字符串
    """
    template = custom_template or _DEFAULT_GREETING
    return _build_message(template, name)

def farewell(name: Optional[str] = None, custom_template: Optional[str] = None) -> str:
    """生成正式/自定义的告别语
    
    Args:
        name: 要告别的对象名称，省略则输出通用告别
        custom_template: 自定义告别模板，省略用默认 "Goodbye"
        
    Returns:
        格式化后的告别字符串
    """
    template = custom_template or _DEFAULT_FAREWELL
    return _build_message(template, name)

# 主入口区（仅当模块被直接执行时运行）
def main(args: list[str]) -> None:
    """处理命令行参数的主入口"""
    name = args[1] if len(args) > 1 else None
    print(greet(name))

if __name__ == "__main__":
    main(sys.argv)

# 完整导入
import greet_tool

# 调用公开函数
print(greet_tool.greet("Bob"))  # Hello, Bob!
print(greet_tool.farewell("Bob", "See you next time"))  # See you next time, Bob!

# 查看元信息
print(f"Version: {greet_tool.__version__}")  # Version: 0.1.0

# 只导入 greet 函数
from greet_tool import greet

print(greet("Charlie"))  # Hello, Charlie!
# farewell 用不了，因为没导入

# 给模块起别名
import greet_tool as gt
print(gt.greet("Dave"))

# 给函数起别名
from greet_tool import farewell as bye
print(bye("Eve"))

# 在常量区后面加
__top_secret_key = "123456"

import greet_tool

# 直接访问报错
print(greet_tool.__top_secret_key)  # AttributeError: module 'greet_tool' has no attribute '__top_secret_key'

# 但知道修饰规则就能拿到
print(greet_tool._greet_tool__top_secret_key)  # 123456

if __name__ == "__main__":
    # 快速测试逻辑
    assert greet() == "Hello!"
    assert greet("Frank") == "Hello, Frank!"
    assert greet("Frank", "Hi") == "Hi, Frank!"
    print("All quick tests passed!")

# 错误写法
import matplotlib.pyplot as plt  # 没装 matplotlib 就报错

# 正确写法
_MATPLOTLIB_AVAILABLE = False
try:
    import matplotlib.pyplot as plt
    _MATPLOTLIB_AVAILABLE = True
except ImportError:
    pass

def plot_something():
    if not _MATPLOTLIB_AVAILABLE:
        raise ImportError("Please install matplotlib: pip install matplotlib")
    # 绘图逻辑