如何记录鸭子类型? [英] How to document a duck type?
问题描述
我对文档感到肿，因为每当遇到复杂的鸭子类型时，我都需要某种方式来表示这种鸭子类型"，但是却陷入了无休止的您的功能需要此输入内容的循环"中，但没有记录下来"，然后记录下来.这样会导致文件膨胀，重复，如下所示:
I'm having documentation bloat on me, as anytime I encounter a complex duck-type, I need some way to say "this duck type" but instead get caught in an endless cycle of "your function requires this of this input, but doesn't document it", and then documenting it. This results in bloated, repetitive documentation, such as the following:
def Foo(arg):
"""
Args:
arg: An object that supports X functionality, and Y functionality,
and can be passed to Z other functionality.
"""
# Insert code here.
def Bar(arg):
"""
Args:
arg: An object that supports X functionality, and Y functionality,
and can be passed to Z other functionality.
"""
# Insert code here.
依次类推，依次类推Baz，Qux和其他功能.我需要一些简短的写法"arg是(对象的类型)".
And so on, and so on, for Baz, Qux, and other functions. I need some shorter way of writing "arg is a (type of object)".
对于某些鸭子类型，这就像像字典一样的对象"一样简单:我们知道对字典的期望，因此，我们知道要传递的内容. dict或可以模仿它的东西.
For some duck types, it's as easy as "A dict-like object": we know what we expect of a dict, and so, we know what to pass. A dict, or something that can mimic it.
我觉得C ++在模板化类型上也有同样的问题. Haskell会拥有它，但是可以使用类型类的定义来对其进行记录. (注意:Haskell类！= Java/C ++/Python/etc中的类.)(注意:我并不是真的在Haskell中编程，请原谅我这是一个卑鄙的例子.)
I feel C++ has this same problem with templated types. Haskell would have it, but one can use a type class's definition to document it. (Note: Haskell classes != classes in Java/C++/Python/etc.) (Note: I don't really program in Haskell, so forgive me if it is a crappy example.)
我应该走传统的OO路线，只写一个基类，然后在文档中说像这个基类一样的东西"吗?该代码不会强制从基类派生(因为不需要从该基类派生该对象)，并且该基类除了本质上记录接口的属性外，不添加任何值.
Should I go the traditional OO route, and just write a base class, and say, "anything like this base class" in the docs? The code wouldn't enforce deriving from the base class (as there is no requirement for the object to be derived from it), and the base class adds no value except to document the properties of the interface, essentially.
另一方面，我正在编写Python，并且尝试在一种语言的习惯用法中进行编程. (因为这样做通常会很痛苦.)基类对于继承功能很有用，但是当您的基类是完全抽象的时，它似乎并没有在鸭子式语言中增加价值.
On the other hand, I'm programming Python, and I try to program within the idioms of a language. (As doing otherwise usually hurts.) Base classes are good for inheriting functionality, but when your base class is completely abstract, it doesn't seem to add value in a duck-typed language.
编辑:答案:我知道什么是鸭子输入(从帖子中可以明显看出).我要在哪里记录这是一个问题，尤其是.当不存在附加文档的类时.
EDIT: To the answers: I know what duck typing is (that should be evident from the post). Where do I document it is the question, esp. when no class exists to attach documentation to.
推荐答案
鸭子类型背后的想法是，您要证明自己期望鸭子，而其他对象则要冒充鸭子.
The idea behind duck typing is that you document that you are expecting a duck, and it is up to other objects to fake being a duck.
在文档中没有任何地方指定任何API接受StringIO对象；但是，我们可以在大多数需要文件状对象"的地方使用它们.
Nowhere in the docs does any API specify that it accepts a StringIO object; however, we can use them in most places that expect a "file-like object".
此外，在大多数情况下，标准库尝试避免命名鸭子类型所需的特定方法.这使得实现方式可以进行更改. random.sample API，用于例如，可以根据可迭代项或序列进行定义.
Also, for the most part, the standard library tries to avoid naming the specific methods demanded of a duck type. That leaves the implementation open to change. The random.sample API, for example, could have been defined in terms of iterables or in terms of sequences.
如果您想更具体一点，可以使用抽象库类. 收藏模块(例如设置为Iterable，Hashable和Sized)或数字模块(有理数，整数等) .模仿那些自己编写的东西并不难.然后，文档仅提及需要哪些ABC(例如， x 是 Iterable 和 y 是积分).
If you want to be more specific than this, you could use abstract base classes. Several are already included in the collections module (such as Iterable, Hashable, and Sized) or numbers module (Rational, Integral, etc). It is not hard to model after those to write your own. Then, the documentation simply mentions which ABCs are required (e.g. x is a Sized Iterable and y is an Integral).
这篇关于如何记录鸭子类型?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
