classification
Title: Add an UML class diagram to the collections.abc module documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, levkivskyi, rhettinger, yahya-abou-imran
Priority: normal Keywords: patch

Created on 2018-01-01 05:47 by yahya-abou-imran, last changed 2019-08-22 06:24 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
base.png yahya-abou-imran, 2018-01-01 05:47 UML diagramm of a part of the collections.abc module
base.puml yahya-abou-imran, 2018-01-01 05:55
Pull Requests
URL Status Linked Edit
PR 5133 closed yahya-abou-imran, 2018-01-07 17:59
Messages (8)
msg309318 - (view) Author: Yahya Abou Imran (yahya-abou-imran) * Date: 2018-01-01 05:47
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.
msg309319 - (view) Author: Yahya Abou Imran (yahya-abou-imran) * Date: 2018-01-01 05:55
Here is the .puml
msg309393 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2018-01-02 19:59
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.
msg309428 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2018-01-03 19:17
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.
msg309431 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-01-03 20:50
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.
msg309629 - (view) Author: Yahya Abou Imran (yahya-abou-imran) * Date: 2018-01-07 17:34
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...
msg310684 - (view) Author: Yahya Abou Imran (yahya-abou-imran) * Date: 2018-01-25 16:15
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
msg350163 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-08-22 06:24
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.
History
Date User Action Args
2019-08-22 06:24:44rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg350163

stage: patch review -> resolved
2018-01-25 16:15:23yahya-abou-imransetmessages: + msg310684
2018-01-07 17:59:35yahya-abou-imransetkeywords: + patch
stage: patch review
pull_requests: + pull_request4994
2018-01-07 17:34:28yahya-abou-imransetmessages: + msg309629
2018-01-05 16:57:08levkivskyisetnosy: + levkivskyi
2018-01-03 20:50:56rhettingersetnosy: + rhettinger
messages: + msg309431
2018-01-03 19:17:18brett.cannonsetmessages: + msg309428
2018-01-02 19:59:39brett.cannonsetnosy: + brett.cannon
messages: + msg309393
2018-01-01 05:55:05yahya-abou-imransetfiles: + base.puml

messages: + msg309319
2018-01-01 05:47:34yahya-abou-imrancreate