classification
Title: Update examples in abc documentation to use abc.ABC
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Eric Appelt, Mariatta, brett.cannon, docs@python, eric.araujo, rhettinger, veky
Priority: normal Keywords:

Created on 2017-04-18 19:51 by brett.cannon, last changed 2017-09-15 18:15 by eric.araujo. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 1220 merged Eric Appelt, 2017-04-20 21:26
PR 3408 merged python-dev, 2017-09-07 00:18
Messages (11)
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.
msg301038 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-08-30 22:47
New changeset 122e88a8354e3f75aeaf6211232dac88ac296d54 by Éric Araujo (Eric Appelt) in branch 'master':
bpo-30096: Use ABC in abc reference examples (#1220)
https://github.com/python/cpython/commit/122e88a8354e3f75aeaf6211232dac88ac296d54
msg301039 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-08-30 22:50
Thanks for the patch!  Raymond approved it and I merged it after a minor change.  Now let me read the doc again about backports :)
msg301568 - (view) Author: Vedran Čačić (veky) * Date: 2017-09-07 04:48
"Best practices" according to whom?

Inheritance is one thing, metaclass changing is another thing. They should look different. Yes, I appreciate the fact that I can write "(Blah)" instead of "(metaclass=BlahMeta)" in quick and dirty scripts, but my feeling is that that practice shouldn't be promoted in the docs.

Please read http://bugs.python.org/issue26988#msg273076 for another perspective.
msg301605 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-09-07 18:32
New changeset b0d0217c0e4c1512a06ef306928b2fd8f82d046e by Mariatta (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-30096: Use ABC in abc reference examples (GH-1220) (GH-3408)
https://github.com/python/cpython/commit/b0d0217c0e4c1512a06ef306928b2fd8f82d046e
msg301606 - (view) Author: Mariatta Wijaya (Mariatta) * (Python committer) Date: 2017-09-07 18:34
Backported to 3.6 by Miss Islington.
Closing this issue.
Thanks.
msg302197 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-09-14 18:45
> "Best practices" according to whom?

Well at least two senior core developers :)  See the rationale in #16049 when abc.ABC was first added (with Guido approving that inheritance is nicer for most people).
msg302233 - (view) Author: Vedran Čačić (veky) * Date: 2017-09-15 05:40
Well, actually, Raymond was proposing an alternative to Py2's special __metaclass__ attribute assignment syntax, which honestly _is_ an abomination (and the big part of reason why that was changed in Py3 to a keyword argument in a class definition).

And Guido missed the point that in frameworks such as Django, the inheritance is the main thing people want, metaclasses just being a technical implementation detail (the easiest proof is that with modern descriptors with __set_name__ and ordered class namespaces, it's unnecessary to use metaclasses in Django model implementation at all). Here it is exactly the opposite.

As I said in the linked comment, I think we missed the opportunity to make Python much more powerful, practically shunning the idea of keyword arguments in a class definition totally. But as it is said, Guido's will  be done. :-) Thanks for the link.
msg302284 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2017-09-15 18:15
Keyword arguments in a class definition are supported: https://www.python.org/dev/peps/pep-3115/#specification

Anyway, this ticket is closed, a mailing list such as python-ideas would be a better venue to discuss base classes vs metaclasses in a general way.
History
Date User Action Args
2017-09-15 18:15:39eric.araujosetmessages: + msg302284
2017-09-15 05:40:10vekysetmessages: + msg302233
2017-09-14 18:45:10eric.araujosetmessages: + msg302197
2017-09-07 18:34:09Mariattasetstatus: open -> closed
resolution: fixed
messages: + msg301606

stage: backport needed -> resolved
2017-09-07 18:32:09Mariattasetnosy: + Mariatta
messages: + msg301605
2017-09-07 04:48:57vekysetnosy: + veky
messages: + msg301568
2017-09-07 00:18:50python-devsetpull_requests: + pull_request3409
2017-08-30 22:50:00eric.araujosetstage: needs patch -> backport needed
messages: + msg301039
versions: + Python 3.6
2017-08-30 22:47:57eric.araujosetnosy: + eric.araujo
messages: + msg301038
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