仅当使用另一个参数时可选的参数在 python 中的文档约定是什么

Question

假设我有一个create_person创建 person 对象的函数，现在假设我想为用户提供使用 withcreate_person('Tomer', 19, ...)或 with调用它的选项create_person(base_person=tomer_person, ...)，我应该如何正确记录此行为？这是定义函数的正确方法吗？例子：def create_person(name=None, age=None, base_person=None):    if not name and not age and base_person:        person = base_person    elif not base_person:        person = Person(name, age)    ...

Answer 1

如果你想使用numpydoc样式，一种可能的方法是：

def create_person(name=None, age=None, base_person=None):

    r"""A function to create a person.

    Using this function, a person can be created using

    either a combination of `name` and `age` or providing a `base_person`.

    Parameters

    ----------

    name : int [optional, default=None]

        The name of the person to be created. Leave this as None to create a person

        using the `base_person` keyword.

    age : int [optional, default=None]

        The age of the person to be created. Leave this as None to create a person

        using the `base_person` keyword. 

    base_person : instance of Person class [optional, default=None]

        If `age` and `name` are None, this keyword can be used to create a person

        from an instance of the `Person` class."""

就个人而言，我会创建两种不同的函数，一种是根据姓名和年龄创建人，另一种是使用对象base_person。在内部，他们可以使用正确的调用者签名调用您提供的函数。例如：

def create_person_explicit(name, age):

    return(create_person(name=name, age=age)

def create_person_from_object(base_person):

    return(create_person(base_person=base_person)

由于缺少太多信息，很难说出什么是针对您的具体问题的正确解决方案。