python - 如何docstring kwargs及其预期类型

Question

在docstring中表达关键字参数的预期类型的​​传统方法是什么？

或者这是否是我不应该做的事情的原则？谷歌在这个问题上毫不怀疑.

(我感兴趣的是因为我发现跟踪所有变量的预期类型非常有用,因为我编码.我使用PyCharm,当参数有意外类型时,或者当自定义类属性可能未解决时,它会发出警告)

但是,我发现有时可能的keywrord参数列表列为

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')

我想使用docstring来声明预期的类型.而且我希望PyCharm警告我,莎莉的年龄是错误的.当然,我不知道PyCharm是否有能力"理解"文档字符串中的详细程度.不过我想知道传统方法是做什么的.

关于kwargs和docstrings的其他意见和建议也欢迎.

Answer 1

Pycharm 无法警告您关键字类型错误，但如果您打开了文档面板，您可以看到在文档字符串中指定的预期类型。如果不是，则快捷方式ctr+q在函数名称处带有脱字符号。一次是弹出窗口，两次是将文档面板固定在右侧。

如果类型不正确，您可以另外引发错误。

经过研究和大量测试，这是我发现的一切。拿你需要的任何东西：

from typing import Dict, Any
from warnings import warn


class Person:
    """
    a person
    """
    _ssn: int
    _data: Dict[str, Any]

    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
        if 'name' in kwargs:
            if type(kwargs['name']) is str:
                self._data['name'] = kwargs['name']
            else:
                raise TypeError("__init__() kwargs['name']: got {} but expected \
                type is str".format(type(kwargs["name"]).__name__))
        else:
            warn('This person have a default name', Warning)
            self._data['name'] = 'Smith'

        if 'age' in kwargs:
            if type(kwargs['age']) is int:
                self._data['age'] = kwargs['age']
            else:
                raise TypeError("__init__() kwargs['age']: got {} but expected \
                type is str".format(type(kwargs["age"]).__name__))
        else:
            warn('This person have a default age', Warning)
            self._data['age'] = 21

而不是key您可以使用keyword.

这个例子提供：

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

我建议你添加@property.getter和@property.setter访问_id和_data。而且 class 属性_data是矫枉过正，你应该用_nameand替换它，_age因为你更喜欢默认值而不是没有值。代码在这里。

Warning : Shadows built-in name 'id'

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

来源：PyCharm 2018.3 帮助