Update examples in abc documentation to use abc.ABC

[brettcannon]

BPO	30096
Nosy	@brettcannon, @rhettinger, @merwok, @vedgar, @Mariatta, @appeltel
PRs	bpo-30096: Use ABC in abc reference examples #1220 [3.6] bpo-30096: Use ABC in abc reference examples (GH-1220) #3408

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2017-09-07.18:34:09.129>
created_at = <Date 2017-04-18.19:51:38.503>
labels = ['type-feature', '3.7', 'docs']
title = 'Update examples in abc documentation to use abc.ABC'
updated_at = <Date 2017-09-15.18:15:39.977>
user = 'https://github.com/brettcannon'

bugs.python.org fields:

activity = <Date 2017-09-15.18:15:39.977>
actor = 'eric.araujo'
assignee = 'docs@python'
closed = True
closed_date = <Date 2017-09-07.18:34:09.129>
closer = 'Mariatta'
components = ['Documentation']
creation = <Date 2017-04-18.19:51:38.503>
creator = 'brett.cannon'
dependencies = []
files = []
hgrepos = []
issue_num = 30096
keywords = []
message_count = 11.0
messages = ['291842', '291843', '291999', '301038', '301039', '301568', '301605', '301606', '302197', '302233', '302284']
nosy_count = 7.0
nosy_names = ['brett.cannon', 'rhettinger', 'eric.araujo', 'docs@python', 'veky', 'Mariatta', 'Eric Appelt']
pr_nums = ['1220', '3408']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue30096'
versions = ['Python 3.6', 'Python 3.7']

[brettcannon]

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.

[rhettinger]

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

[appeltel]

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.

[merwok]

New changeset 122e88a by Éric Araujo (Eric Appelt) in branch 'master':
bpo-30096: Use ABC in abc reference examples (bpo-1220)
122e88a

[merwok]

Thanks for the patch! Raymond approved it and I merged it after a minor change. Now let me read the doc again about backports :)

[vedgar]

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

[Mariatta]

New changeset b0d0217 by Mariatta (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-30096: Use ABC in abc reference examples (GH-1220) (GH-3408)
b0d0217

[Mariatta]

Backported to 3.6 by Miss Islington.
Closing this issue.
Thanks.

[merwok]

"Best practices" according to whom?

Well at least two senior core developers :) See the rationale in bpo-16049 when abc.ABC was first added (with Guido approving that inheritance is nicer for most people).

[vedgar]

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.