New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation of ABCs #6004

Merged
merged 2 commits into from Dec 4, 2018

Conversation

Projects
None yet
2 participants
@JukkaL
Copy link
Collaborator

JukkaL commented Dec 4, 2018

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.

Improve documentation of ABCs
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.

@JukkaL JukkaL requested a review from gvanrossum Dec 4, 2018

@gvanrossum
Copy link
Member

gvanrossum left a comment

A few nits. Feel free to merge after fixing those without waiting for further approval. (I'm going to be in an out due to a dental appt.)

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
...

This comment has been minimized.

@gvanrossum

gvanrossum Dec 4, 2018

Member

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

``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:

This comment has been minimized.

@gvanrossum

gvanrossum Dec 4, 2018

Member

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

class Cat(Animal):
def eat(self, food: str) -> None:
... # Implementation omitted

This comment has been minimized.

@gvanrossum

gvanrossum Dec 4, 2018

Member

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

This comment has been minimized.

@gvanrossum

gvanrossum Dec 4, 2018

Member

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

@JukkaL JukkaL merged commit 2b1bb6e into master Dec 4, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

JukkaL added a commit that referenced this pull request Dec 4, 2018

Improve documentation of ABCs (#6004)
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.

@JukkaL JukkaL referenced this pull request Dec 4, 2018

Closed

Release 0.650 planning #5960

@gvanrossum gvanrossum deleted the doc-abstract branch Dec 5, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment