Improve documentation of ABCs #6004
Conversation
It's a common error to forget to implement an abstract method, and mypy doesn't immediately generate an error. Explain this explicitly in the documentation, since this behavior can be confusing.
| def f(self, x: int, y: int) -> None: # Error: too many arguments | ||
| ... | ||
|
|
||
| class D(A): | ||
| class Derived3(Base): | ||
| def f(self, x: int) -> None: # OK | ||
| ... |
There was a problem hiding this comment.
Maybe also add an example that shows you can change the signature contravariantly, e.g.
class D4(Base):
def f(self, x: float) -> None: # OK because mypy treats int as a subtype of float
class D5(Base):
def f(self, x: int, *args: Any) -> None: # OK because it accepts more than the base class method
Also, the note about covariantly overriding the return type below ought to get some examples (and object vs. int feels a bit abstract).
docs/source/class_basics.rst
Outdated
| ``abc.abstractproperty`` function decorators. Example: | ||
| by any *concrete* (non-abstract) subclass. You can define abstract base | ||
| classes using the ``abc.ABCMeta`` metaclass, and the ``abc.abstractmethod`` | ||
| and ``abc.abstractproperty`` function decorators. Example: |
There was a problem hiding this comment.
Actually @abstractproperty has been deprecated since 3.3 -- just put@property above @abstractmethod: https://docs.python.org/3/library/abc.html?highlight=abstractproperty#abc.abstractproperty . (However, in 2.7 you still need @abstractproperty.)
docs/source/class_basics.rst
Outdated
|
|
||
| class Cat(Animal): | ||
| def eat(self, food: str) -> None: | ||
| ... # Implementation omitted |
There was a problem hiding this comment.
This comment is confusing, since the point of this example is about whether a method is implemented in a subclass or not. If you think a comment is needed, you could use "Body omitted".
| As shown above, the class definition will not generate an error | ||
| in this case, but any attempt to construct an instance will be | ||
| flagged as an error. | ||
|
|
||
| A class can inherit any number of classes, both abstract and | ||
| concrete. As with normal overrides, a dynamically typed method can |
There was a problem hiding this comment.
At some point (not now) I would like to overhaul the docs and somehow change the terminology regarding statically typed and dynamically typed functions and methods. There are flags (e.g. --check-untyped-defs) that blur the difference, and when we talk amongst ourselves or with users we never describe the distinction -- instead we'll use "unannotated" (even though my spell checker doesn't think that's a word :-). It's also not clear to me whether an unannotated method can still override an annotated method if the signatures differ wildly (e.g. no correspondence in argument count).
It's a common error to forget to implement an abstract method, and mypy doesn't immediately generate an error. Explain this explicitly in the documentation, since this behavior can be confusing.
It's a common error to forget to implement an abstract
method, and mypy doesn't immediately generate an error.
Explain this explicitly in the documentation, since this
behavior can be confusing.