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.

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

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.

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

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

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

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

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

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

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.

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.