撰写时扩展或覆盖文档字符串 类
Extending or overwriting a docstring when composing classes
我有一个 class MyClass
:
class MyClass(object):
def __init__(self):
pass
def my_function(self, x):
# MyClass.my_function.__doc__ is not writable!
# Otherwise, I could just set it here.
Origin.func(self, x)
class 借鉴自 Origin
:
class Origin(object):
def func(obj, x):
"""This is a function
"""
# do stuff
pass
如何自动将文档字符串从 Origin.func 复制到 MyClass.my_function 以便 Sphinx Autodoc 识别它?我怎样才能用几个词扩展原始文档字符串?
编辑:
Afaik,我不能在函数定义后更改 __doc__
,因为 Sphinx 那时找不到它。或者,如果有,"docfix" 会去哪里?
我不清楚 Sphinx 的具体工作原理,但假设它是从 __doc__
读取而不是解析源代码,那么有很多选择。
考虑更简单的示例...
def add(x, y):
return x + y
...这实际上等同于...
add = lambda x, y: x + y
在任何一种情况下,您都不能在其定义中引用符号 add
,因为该符号未在该点定义。您也不能引用符号 add
最终将引用的 function
对象,因为它尚未创建。
因此,您只能在符号定义后修改add.__doc__
...
def add(x, y):
return x + y
add.__doc__ = 'This is my docstring'
...但这可能比我们希望的要冗长一点。
另一种选择是利用 Python 装饰器语法...
@my_decorator
def add(x, y):
return x + y
...等同于...
def add(x, y):
return x + y
add = my_decorator(add)
...也就是说,虽然它放在函数定义之前,但它是在函数定义之后执行的,所以你可以引用装饰器函数体内的function
对象。
装饰函数需要 return 一个可调用对象,但考虑到我们不需要改变 add
函数的行为,我们可以 return 参数它被传递给装饰器,所以给定装饰器函数...
def set_fixed_docstring(func):
func.__doc___ = 'This is my docstring'
return func
...像...一样使用
@set_fixed_docstring
def add(x, y):
return x + y
...等同于...
def add(x, y):
return x + y
add = set_fixed_docstring(add)
...或...
def add(x, y):
return x + y
add.__doc__ = 'This is my docstring'
add = add
显然,固定的文档字符串在这里用处不大,所以我们需要参数化装饰器,这有点复杂。
在这种情况下,我们需要我们的装饰器函数可以使用字符串参数调用,和到return一个将目标函数作为参数的可调用对象.
最常见的做法是在装饰函数中定义另一个函数,这样内部函数就可以引用外部函数中定义的符号。所以函数...
def set_docstring_to(docstring):
def wrapper(func):
func.__doc___ = docstring
return func
return wrapper
...像...一样使用
@set_docstring_to('This is my docstring')
def add(x, y):
return x + y
...等同于...
def add(x, y):
return x + y
add = set_docstring_to('This is my docstring')(add)
...归结为与之前相同的代码...
def add(x, y):
return x + y
add.__doc__ = 'This is my docstring'
add = add
把所有这些放在一起,如果你要使用像这样的装饰器...
def copy_docstring_from(source):
def wrapper(func):
func.__doc__ = source.__doc__
return func
return wrapper
...那么你就可以...
class Origin(object):
def func(obj, x):
"""This is a function
"""
# do stuff
pass
class MyClass(object):
def __init__(self):
pass
@copy_docstring_from(Origin.func)
def my_function(self, x):
# MyClass.my_function.__doc__ is not writable!
# Otherwise, I could just set it here.
Origin.func(self, x)
...应该可以用最少的代码达到预期的效果。
我有一个 class MyClass
:
class MyClass(object):
def __init__(self):
pass
def my_function(self, x):
# MyClass.my_function.__doc__ is not writable!
# Otherwise, I could just set it here.
Origin.func(self, x)
class 借鉴自 Origin
:
class Origin(object):
def func(obj, x):
"""This is a function
"""
# do stuff
pass
如何自动将文档字符串从 Origin.func 复制到 MyClass.my_function 以便 Sphinx Autodoc 识别它?我怎样才能用几个词扩展原始文档字符串?
编辑:
Afaik,我不能在函数定义后更改 __doc__
,因为 Sphinx 那时找不到它。或者,如果有,"docfix" 会去哪里?
我不清楚 Sphinx 的具体工作原理,但假设它是从 __doc__
读取而不是解析源代码,那么有很多选择。
考虑更简单的示例...
def add(x, y):
return x + y
...这实际上等同于...
add = lambda x, y: x + y
在任何一种情况下,您都不能在其定义中引用符号 add
,因为该符号未在该点定义。您也不能引用符号 add
最终将引用的 function
对象,因为它尚未创建。
因此,您只能在符号定义后修改add.__doc__
...
def add(x, y):
return x + y
add.__doc__ = 'This is my docstring'
...但这可能比我们希望的要冗长一点。
另一种选择是利用 Python 装饰器语法...
@my_decorator
def add(x, y):
return x + y
...等同于...
def add(x, y):
return x + y
add = my_decorator(add)
...也就是说,虽然它放在函数定义之前,但它是在函数定义之后执行的,所以你可以引用装饰器函数体内的function
对象。
装饰函数需要 return 一个可调用对象,但考虑到我们不需要改变 add
函数的行为,我们可以 return 参数它被传递给装饰器,所以给定装饰器函数...
def set_fixed_docstring(func):
func.__doc___ = 'This is my docstring'
return func
...像...一样使用
@set_fixed_docstring
def add(x, y):
return x + y
...等同于...
def add(x, y):
return x + y
add = set_fixed_docstring(add)
...或...
def add(x, y):
return x + y
add.__doc__ = 'This is my docstring'
add = add
显然,固定的文档字符串在这里用处不大,所以我们需要参数化装饰器,这有点复杂。
在这种情况下,我们需要我们的装饰器函数可以使用字符串参数调用,和到return一个将目标函数作为参数的可调用对象.
最常见的做法是在装饰函数中定义另一个函数,这样内部函数就可以引用外部函数中定义的符号。所以函数...
def set_docstring_to(docstring):
def wrapper(func):
func.__doc___ = docstring
return func
return wrapper
...像...一样使用
@set_docstring_to('This is my docstring')
def add(x, y):
return x + y
...等同于...
def add(x, y):
return x + y
add = set_docstring_to('This is my docstring')(add)
...归结为与之前相同的代码...
def add(x, y):
return x + y
add.__doc__ = 'This is my docstring'
add = add
把所有这些放在一起,如果你要使用像这样的装饰器...
def copy_docstring_from(source):
def wrapper(func):
func.__doc__ = source.__doc__
return func
return wrapper
...那么你就可以...
class Origin(object):
def func(obj, x):
"""This is a function
"""
# do stuff
pass
class MyClass(object):
def __init__(self):
pass
@copy_docstring_from(Origin.func)
def my_function(self, x):
# MyClass.my_function.__doc__ is not writable!
# Otherwise, I could just set it here.
Origin.func(self, x)
...应该可以用最少的代码达到预期的效果。