classification
Title: Update examples in abc documentation to use abc.ABC
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Eric Appelt, brett.cannon, docs@python, rhettinger
Priority: normal Keywords:

Created on 2017-04-18 19:51 by brett.cannon, last changed 2017-04-20 21:30 by Eric Appelt.

Pull Requests
URL Status Linked Edit
PR 1220 open Eric Appelt, 2017-04-20 21:26
Messages (3)
msg291842 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2017-04-18 19:51
I noticed that the documentation for the abc module (https://docs.python.org/3/library/abc.html) has all example classes use ABCMeta instead of ABC which is what most people probably want. To keep things simple the docs should probably be updated to inherit from abc.ABC.
msg291843 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-04-18 21:28
+1 It would be nice to have the examples show the usual best practices.

That said, in the doc for abc.ABC itself, it would be nice to show an brief example both ways (much like we do for the property() docstring) to show the relationship between the two.  In other words, I want people to inherit from ABC but don't want the knowledge of ABCMeta to be lost.
msg291999 - (view) Author: Eric Appelt (Eric Appelt) * Date: 2017-04-20 21:30
I created a PR to update the documentation to use this pattern and follow Raymond's suggestion of showing both ways to define an abc.

In order to make the examples comprehensible when read from beginning to end, I reordered the classes so that abc.ABC is described first.
History
Date User Action Args
2017-04-20 21:30:24Eric Appeltsetnosy: + Eric Appelt
messages: + msg291999
2017-04-20 21:26:04Eric Appeltsetpull_requests: + pull_request1343
2017-04-18 21:28:05rhettingersetnosy: + rhettinger
messages: + msg291843
2017-04-18 19:51:38brett.cannoncreate