Add an UML class diagram to the collections.abc module documentation

[yahya-abou-imran]

BPO	32471
Nosy	@brettcannon, @rhettinger, @ilevkivskyi, @yahya-abou-imran
PRs	bpo-32471: Add class diagram to collections.abc doc #5133
Files	base.png: UML diagramm of a part of the collections.abc module base.puml

^{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 2019-08-22.06:24:44.615>
created_at = <Date 2018-01-01.05:47:34.565>
labels = ['type-feature', '3.7', 'docs']
title = 'Add an UML class diagram to the collections.abc module documentation'
updated_at = <Date 2019-08-22.06:24:44.612>
user = 'https://github.com/yahya-abou-imran'

bugs.python.org fields:

activity = <Date 2019-08-22.06:24:44.612>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-08-22.06:24:44.615>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2018-01-01.05:47:34.565>
creator = 'yahya-abou-imran'
dependencies = []
files = ['47357', '47358']
hgrepos = []
issue_num = 32471
keywords = ['patch']
message_count = 8.0
messages = ['309318', '309319', '309393', '309428', '309431', '309629', '310684', '350163']
nosy_count = 5.0
nosy_names = ['brett.cannon', 'rhettinger', 'docs@python', 'levkivskyi', 'yahya-abou-imran']
pr_nums = ['5133']
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32471'
versions = ['Python 3.6', 'Python 3.7']

[yahya-abou-imran]

From python-ideas: https://mail.python.org/pipermail/python-ideas/2017-December/048492.html

In this page of the documentation:
https://docs.python.org/3/library/collections.abc.html

The table could be difficult to understand, a diagram help visualize things.

I'm joining the last version of my work, and the .puml I used to generate it.

Opinions about details (fonts, displaying...) are being discussed on the mailist right now.

[yahya-abou-imran]

Here is the .puml

[brettcannon]

I brought this up on python-ideas, but I think discussing it here may be better: I think we may need to use a data file format that has an open source implementation. The tool Yahya used (plantuml) doesn't appear to be open source, which is a problem for the long-term maintainability of the diagram. If I'm wrong about open source tools for reading .puml files to generate SVG files then my worries are alleviated, but if there aren't any then something like a dot file may be better long-term.

[brettcannon]

I should mention that over on python-ideas people found the open source code to plantuml, so I think the format is acceptable for use in the docs.

[rhettinger]

This is a nice looking diagram. Nice work. The existing table is great when you care about knowing what a particular ABC does, but the diagram nicely gives an overview of whole ecosystem all at once.

If the collections.abc module continues its unabated growth, the diagram will become a spaghetti bowl. But for now, it reads nicely.

[yahya-abou-imran]

I have generated SVG files.

Here is the rest of the ABCs present in the module:

https://gitlab.com/yahya-abou-imran/collections-abc-uml/blob/master/plantuml/other_collections.svg

And here is the full version with all ABCs:

https://gitlab.com/yahya-abou-imran/collections-abc-uml/blob/master/plantuml/full.svg

What do you prefer?

I'm gonna submit a PR with the full version right now. I will correct it if you think it's too big.

But I don't know how to run the server of the documentation locally, so I can't test it to see...

[yahya-abou-imran]

I succeed in submitting a PR and building the doc locally.

But there is a little problem of consistency with the abstract methods:
in some classes, the inherited one are mentioned (Collection, Sequence, Mapping), but not in some others (Coroutine, Reversible).

So I don't not what to show and what to hide.

I opened an other issue for this:
https://bugs.python.org/issue32621

[rhettinger]

See the rationale in the closed PR. I rather liked this idea but it didn't prove to be a net win during user testing.