# 第 3-1 课完整示例：Python 与 Java 的类和对象
#
# 本示例不重复讲解通用的面向对象概念，而是集中展示 Python 与 Java 的写法差异。
# 运行程序时，每一段输出都会再次提醒对应差异，便于只看代码和结果也能掌握重点。


class Agent:
    """表示一个简单的 Agent，并演示 Python 类的核心语法。"""

    # Python 的类属性类似 Java 的 static 字段，由所有实例共同访问。
    platform = "Codex"

    def __init__(self, name: str, model: str = "gpt-5") -> None:
        """初始化实例属性；__init__ 的作用接近 Java 构造器，但它不是类名同名方法。"""
        # Python 通常直接在 __init__ 中创建实例属性，不需要提前声明字段。
        # self 类似 Java 的 this，但在实例方法定义中必须显式写出来。
        self.name = name
        self.model = model

    def describe(self) -> str:
        """返回当前对象的说明文字。"""
        return f"{self.name} 使用 {self.model}，运行平台：{self.platform}"

    @classmethod
    def from_config(cls, config: dict[str, str]) -> "Agent":
        """通过配置创建对象；cls 指向当前类，作用类似可继承的命名工厂。"""
        return cls(config["name"], config.get("model", "gpt-5"))

    @staticmethod
    def is_valid_name(name: str) -> bool:
        """校验名称；该方法不需要访问某个对象或当前类。"""
        return bool(name.strip())


def main() -> None:
    """创建对象并输出 Python 与 Java 的关键差异。"""
    code_agent = Agent("代码助手", "gpt-5.2")
    review_agent = Agent.from_config({"name": "审查助手"})

    print("差异 1：Python 使用 __init__ 初始化对象，不写与类同名的构造器。")
    print(code_agent.describe())
    print()

    print("差异 2：self 类似 Java 的 this，但定义实例方法时必须显式声明。")
    print(f"通过对象访问实例属性：{code_agent.name}")
    print()

    print("差异 3：实例属性通常在运行时创建，不需要像 Java 字段那样预先声明。")
    code_agent.status = "工作中"
    print(f"动态添加的 status：{code_agent.status}")
    print()

    print("差异 4：类属性类似 static 字段，但也能通过实例读取。")
    print(f"通过类读取：{Agent.platform}；通过实例读取：{review_agent.platform}")
    print()

    print("差异 5：Python 不使用 new，直接调用类即可创建对象。")
    print(review_agent.describe())
    print(f"名称是否合法：{Agent.is_valid_name(review_agent.name)}")


if __name__ == "__main__":
    main()