This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Add an UML class diagram to the module documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6
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 2022-04-11 14:58 by admin. This issue is now closed.

File name Uploaded Description Edit
base.png yahya-abou-imran, 2018-01-01 05:47 UML diagramm of a part of the 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:

In this page of the documentation:

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 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:

And here is the full version with all ABCs:

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:
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.
Date User Action Args
2022-04-11 14:58:56adminsetgithub: 76652
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