如何记录 kwargs 及其预期类型

Question

在文档字符串中表达关键字参数的预期类型的常规方法是什么？

或者这是出于原则我根本不应该做的事情吗？谷歌在这个问题上似乎没有提供任何信息。

（我对此很感兴趣，因为我发现在编码时跟踪所有变量的预期类型非常有帮助。我使用 PyCharm，它会在参数具有意外类型或自定义类属性可能无法解析等时向我发出警告。 )

但是，我发现有时可能的关键字参数列表列出为

def foo(bar, parameter_1: int=1, paramter_2: str='', ...etc )

可能会变得又长又难以阅读..

考虑以下代码

class Person:
    def __init__(self, id: int, **kwargs):
        """
        :param id: social security number
        :type id: int
        :param **name: person's first name
        :type **name: str
        :param **age: person's age in years, rounded down
        :type **age: int
        """
        self.data = kwargs


bob = Person(123456568, name='Bob', age=48)
sally = Person(1245654568, name='Sally', age='22')

我想使用文档字符串来说明预期的类型。我希望 PyCharm 警告我 sally 的年龄类型错误。当然，我不知道 PyCharm 是否有能力“理解”文档字符串中的这种详细程度。不过我想知道传统的方法是什么。

也欢迎有关 kwargs 和文档字符串的其他评论和建议。

Answer 1

Pycharm 无法警告您关键字的类型错误，但如果您打开文档面板，您可以看到预期的类型（如果在文档字符串中指定）。如果没有，快捷键是

ctr+q

，函数名称处带有插入符号。一次用于弹出窗口，两次将文档面板固定到右侧。

如果类型不正确，您也可以提出错误。

经过研究和大量测试，这是我发现的一切。 需要什么就拿什么：

from typing import TypedDict


class PersonData(TypedDict):
    name: str
    age: int


class Person:
    """
    a person
    """
    _ssn: int
    _data: PersonData

    def __init__(self, ssn: int, *args, **kwargs) -> None:
        """
        Create an instance of Person

        :param ssn: social security number
        :type ssn: int
        :key name: person's first name, should be a str
        :key age: person's age in years, rounded down, should be an int
        :return: __init__ should return None
        :rtype: None
        """
        self._ssn = ssn

        try:
            if not isinstance(kwargs['name'], str):
                name_type = type(kwargs["name"]).__name__
                raise TypeError(f"Person() kwargs['name']: got {name_type} but"
                                " expected type is str")
        except KeyError:
            raise KeyError("Person() missing required keyword argument 'name'")
        self._data['name'] = kwargs['name']

        try:
            age_type = type(kwargs["age"]).__name__

            if not isinstance(kwargs['age'], int):
                raise TypeError(f"Person() kwargs['age']: got {age_type} but "
                                "expected type is int")
        except KeyError:
            raise KeyError("Person() missing required keyword argument 'age'")
        self._data['age'] = kwargs['age']

您可以使用

key

代替

keyword

。

此示例提供：

• PyCharm 使用完整记录的文档字符串来生成文档
• 类型检查+引发类型错误
• 默认值（奖励：警告用户设置了默认值）

我建议您添加

@property.getter

和

@property.setter

来访问

_id

和

_data

。 并且类属性

_data

太过分了，您应该将其替换为

_name

和

_age

，因为您更喜欢默认值而不是无值。 代码在这里。

Warning : Shadows built-in name 'id'

我建议使用 ssn 作为社会安全号码。

来源：PyCharm 2018.3 帮助