简单而复杂的Python

Python是一种简单&复杂的编程语言。简单的时候可以到极致：

print('hello world!')

另一方面，Python 也具有许多复杂的语法特性，例如面向对象编程、装饰器、迭代器、生成器等等。这些特性使得 Python 适用于各种不同的编程任务和项目。

当我好奇打开OpenAI的Python源代码时，Python的复杂性被体现的淋漓尽致。拿OpenAI经常被用到的Chat Completion接口实现文件completions.py为例。

可以从github打开源代码；如果你已经安装了OpenAI的library，那么也可以在本地直接打这个开源文件。

因为整个文件有上千行代码，中间create方法的重载也包含了很多重复的部分，这里只贴出它前边的一部分，注释部分是我自己加的：

'''
__future__ 是一个特殊的模块，用于在当前 Python 解释器中启用或禁用某些功能的特性
在当前模块中启用了 annotations 特性。
在 Python 3.7 之前，类型注解中的类型名称会被当作字符串处理，而不是真正的类型。使用 annotations 特性可以改变这种行为，使得类型注解中的类型名称被解释为真正的类型。
在 Python 3.7 及更高版本中，annotations 特性默认是启用的，因此在大多数情况下不需要显式导入。然而，如果你的代码需要与早期版本的 Python 兼容，或者你想显式表达你在代码中使用类型注解，则可以使用 from __future__ import annotations 来确保类型注解的正确行为。
'''
from __future__ import annotations
from typing import Dict, List, Union, Iterable, Optional, overload
from typing_extensions import Literal

import httpx

'''
Python中的相对导入语句。每个 . 代表包层次结构中向上一级。
...用于从当前模块相对于包层次结构至少三级深度处导入名为 _legacy_response 的模块
'''
from ... import _legacy_response
from ..._types import NOT_GIVEN, Body, Query, Headers, NotGiven
from ..._utils import (
    required_args,
    maybe_transform,
    async_maybe_transform,
)
from ..._compat import cached_property
from ..._resource import SyncAPIResource, AsyncAPIResource
from ..._response import to_streamed_response_wrapper, async_to_streamed_response_wrapper
from ..._streaming import Stream, AsyncStream
from ...types.chat import (
    ChatCompletion,
    ChatCompletionChunk,
    ChatCompletionToolParam,
    ChatCompletionMessageParam,
    ChatCompletionToolChoiceOptionParam,
    completion_create_params,
)
from ..._base_client import (
    make_request_options,
)

'''
__all__ 是一个特殊的变量，通常用于模块中，它是一个列表，用于指定在使用 from module_name import * 语句导入时，应该导入的对象的名称
不指定时，将导入模块中所有不以下划线开头的全局对象；它允许模块作者显式地控制在使用 from module_name import * 语句时导入的对象
'''
__all__ = ["Completions", "AsyncCompletions"]


class Completions(SyncAPIResource):

    '''
    这段代码定义了一个装饰器函数 cached_property。
    在这个例子中，被装饰的函数 with_raw_response 是一个属性访问器方法，它返回一个 CompletionsWithRawResponse 类型的对象。
    '''
    @cached_property
    def with_raw_response(self) -> CompletionsWithRawResponse:
        return CompletionsWithRawResponse(self)

    @cached_property
    def with_streaming_response(self) -> CompletionsWithStreamingResponse:
        return CompletionsWithStreamingResponse(self)

    '''
    @overload 是来自 typing 模块的装饰器，用于定义单个函数或方法的多个签名。它用于指示静态类型检查器create方法在不同情况下具有多个重载变体。
    方法的实际实现将跟在重载的变体后面，提供了处理不同类型输入的逻辑。
    参数列表中的 * 符号用于表示位置参数的结束和关键字参数的开始。这意味着在 * 后声明的任何参数在调用函数时必须作为关键字参数提供。
    '''
    @overload
    def create(
        self,
        *,
        messages: Iterable[ChatCompletionMessageParam],
        ...省略...
    ) -> ChatCompletion:
	...省略...

另外借助于大语言模型，我们可以对这个文件进行一些分析。比如Kimi：

这个Python文件是一个关于API客户端的代码，主要用于与某个聊天模型（如OpenAI的ChatGPT）进行交互。文件中定义了几个类，每个类都提供了不同的方法来创建和处理聊天对话的完成（completions）。以下是对文件中主要结构和功能的详细分析：

1. 模块导入：

   • 文件开始部分导入了多个模块和类型，包括httpx用于HTTP请求，typing和typing_extensions用于类型注解和重载，以及其他一些自定义模块，如_legacy_response、__types、_utils、_compat、_resource、_streaming和_base_client等。

2. 类型注解和特殊变量：

   • 使用from __future__ import annotations来确保类型注解的正确行为。
   • __all__变量定义了模块级别的公共API，即其他模块可以通过from module_name import *导入的对象名称。

3. Completions类：

   • 这个类继承自SyncAPIResource，提供了同步API请求的方法。
   • 类中定义了with_raw_response和with_streaming_response属性，它们返回对应的响应处理类实例。
   • create方法是一个重载方法，用于创建聊天对话的模型响应。它接受多个参数，包括消息、模型ID、各种生成参数（如frequency_penalty、temperature等）以及额外的请求参数（如extra_headers、extra_query等）。
   • create方法有一个特殊的装饰器@required_args，确保在调用create时必须提供某些参数。

4. AsyncCompletions类：

   • 类似于Completions，但用于异步请求。它继承自AsyncAPIResource。
   • 同样提供了with_raw_response和with_streaming_response属性。
   • create方法的异步版本，使用async def定义，允许异步地创建聊天对话的模型响应。

5. 响应处理类：

   • CompletionsWithRawResponse和AsyncCompletionsWithRawResponse类用于处理原始响应。
   • CompletionsWithStreamingResponse和AsyncCompletionsWithStreamingResponse类用于处理流式响应。

6. 其他辅助功能：

   • 文件中还包含了一些辅助函数和类，如to_streamed_response_wrapper和async_to_stream_response_wrapper，这些用于将API响应转换为特定格式。

总的来说，这个文件提供了一个API客户端的实现，允许用户通过Python代码与聊天模型进行交互，创建和获取聊天对话的完成。代码支持同步和异步请求，并提供了丰富的参数配置选项，以适应不同的使用场景和需求。