有没有办法描述/类型提示函数参数的内容？

Question

我正在尝试学习如何更好地记录我的代码。描述一个函数并只是暗示它接收dict 似乎让任何未来的读者都缺乏信息。

执行以下操作很常见吗？或者是否有另一种方式我错过了关于这个主题的阅读？

    def add_control(self, ctrl_data: dict):
        """

        :param ctrl_data:
            - name: str
            - channel: int
            - control_channel_id: int
            - default_position: int
        :type ctrl_data: dict
        """

编辑：在盲目地将其称为重复问题之前，请实际阅读一下该问题。我的问题已经表明我知道什么是类型提示，我正在寻找关于在处理参数中的嵌套对象时类型提示如何工作的一个非常具体的部分的答案。

Answer 1

• 如果你想使用字典，你应该查看TypedDict。 TypedDict: Type Hints for Dictionaries with a Fixed Set of Keys。

from typing import TypedDict

class CtrlData(TypedDict):
  name: str
  channel: int
  control_channel_id: int
  default_position: int

def add_control(self, ctrl_data: CtrlData):
  ...

• 为了更好地记录代码，您应该添加返回类型。

def add_control(self, ctrl_data: CtrlData) -> TReturn:
  ...

• 您还可以更改函数签名并让调用者解压字典。我会说只有几个参数时会更清楚。

def add_control(
  self,
  name: str,
  channel: int,
  control_channel_id: int,
  default_position: int
  ) -> TReturn:
  ...