有没有办法 describe/type-hint 函数参数的内容？

Question

我正在努力学习如何更好地记录我的代码。描述一个函数并只是暗示它接收到 dict 似乎留下了任何未来 reader 相当短的信息。

执行以下操作是否很常见？还是我错过了有关该主题的阅读的另一种方式？

    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):
  ...

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

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

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

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

有没有办法 describe/type-hint 函数参数的内容？

Is there a way to describe/type-hint the contents of a function's parameters?

python

docstring

code-documentation

type-hinting