Mailman 3 Add an UML class diagram to the collections.abc module documentation - Python-ideas

newer
Allow to compile debug extension...

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

older
a set of enum.Enum values rather...

Yahya Abou 'Imran

30 Dec 2017 30 Dec '17

4:11 p.m.

We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java. Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA (I think they're done with pyreverse of pylint) They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html The table could be difficult to understand, a diagram help visualize things. I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think.

Attachments:

full.png (image/png — 197.1 KB)
collections_abc.png (image/png — 103.1 KB)
attachment.htm (text/html — 1.4 KB)

Show replies by date

Stephan Houben

30 Dec 30 Dec

8:24 p.m.

Hi Yahya, I like the full.png diagram, however, I see some issues with it. Most seriously, the methods it lists don't match the documentation. E.g. if you check MappingView: https://docs.python.org/3/library/collections.abc.html#collections.abc.Mappi... you see it has only a __len__ mixin method. The other methods in the diagram are implementation details and should be removed. Some presentation points (all IMHO of course): * Get rid of the empty boxes. * Get rid of the trailing (). Since all methods have this, it adds no info. * There is no visual distinction between the abstract methods and the mixin methods. I'd suggest making the abstract methods italic or something like that. Stephan 2017-12-30 17:11 GMT+01:00 Yahya Abou 'Imran via Python-ideas < python-ideas@python.org>:

...

We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think.

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Yahya Abou 'Imran

31 Dec 31 Dec

12:25 a.m.

...

Hi Yahya, I like the full.png diagram, however, I see some issues with it.

Most seriously, the methods it lists don't match the documentation.

E.g. if you check MappingView:

https://docs.python.org/3/library/collections.abc.html#collections.abc.Mappi...

you see it has only a __len__ mixin method. The other methods in the diagram are implementation details and should be removed.

Some presentation points (all IMHO of course): * Get rid of the empty boxes. * Get rid of the trailing (). Since all methods have this, it adds no info. * There is no visual distinction between the abstract methods and the mixin methods. I'd suggest making the abstract methods italic or something like that.

Stephan

Thank you for your observations Stephan. The reason behind that is that I genretated it from a copy of the source code, and I was sondering about getting rid of it or not... But I think you'r right: let's display only the documented part. About the displaying of the abstract method, sadly it seems that pyreverse doesn't support it... It didn't find a way to hide the paranetesis either. I could make those changes whth a graphic tool though. Same thing with the empty box. Whereas it's possible with plantuml. But may be I have to use a pure python tool. What's your opinions about that? Another thing: for exemple, in the case of Collection, it asks to implement the three method __iter__, __contains__ and __sized__, but since it inherit them from Iterable, Container and Sized, they're not shown. I think it's better to make them appear since: 1. you have to implement them to inherit from it; 2. the three methods are checked during the __subclasshook__ of this ABC to know if a class is a virtual subclass of it or not (when pass as a second argument of issubclass() for example). I don't think it's an error in UML to re-display them since they are abstracts (it would be if they were concretes because it would mean that they were been overriden).

Terry Reedy

30 Dec 30 Dec

9:17 p.m.

On 12/30/2017 11:11 AM, Yahya Abou 'Imran via Python-ideas wrote:

...

We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think.

We have a few .png files in the docs. Yours look like the beginning of perhaps 2 nice additions. A. Width restrictions suggest making the async branches a separate diagram. B. Be consistent on placement of inherited versus added methods. Always list inherited first? Different fonts, as suggested, might be good. C. After discussion here, and revision, open a doc enhancement issue on bugs.python.org. -- Terry Jan Reedy

pylang

10:23 p.m.

+1 on adding these diagrams to the docs. It's great to visualize where the special methods are implemented. On Sat, Dec 30, 2017 at 4:17 PM, Terry Reedy wrote:

...

On 12/30/2017 11:11 AM, Yahya Abou 'Imran via Python-ideas wrote:

...
We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarc hy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think.

We have a few .png files in the docs. Yours look like the beginning of perhaps 2 nice additions.

A. Width restrictions suggest making the async branches a separate diagram.

B. Be consistent on placement of inherited versus added methods. Always list inherited first? Different fonts, as suggested, might be good.

C. After discussion here, and revision, open a doc enhancement issue on bugs.python.org.

-- Terry Jan Reedy

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Yahya Abou 'Imran

31 Dec 31 Dec

12:29 a.m.

Here is another version showing all that inherit from Container, Sized and Iterable. I got rid of ABCMeta, since it's not the prupose of the documentation of that page. I left the parenthesis and the end of the methods names though... [collections_abc.png]

Yahya Abou 'Imran

12:27 a.m.

...

A. Width restrictions suggest making the async branches a separate diagram.

I was thinking about it... Maybe Hashable and Callable could also be removed, since they are standalone ABCs. And they're not directly linked with the concept of Collection anyway.

...

B. Be consistent on placement of inherited versus added methods. Always list inherited first? Different fonts, as suggested, might be good.

The best may be to not follow UML guidelines but to stick with the terminology of the documentation: the first box for Abstract Methods, the second for Mixin Methods.

Stephen J. Turnbull

3:38 p.m.

Terry Reedy writes:

...

B. Be consistent on placement of inherited versus added methods. Always list inherited first? Different fonts, as suggested, might be good.

I would prefer listing added methods first.

Yahya Abou 'Imran

3:46 p.m.

...

Terry Reedy writes:

...
B. Be consistent on placement of inherited versus added methods. Always

...
list inherited first? Different fonts, as suggested, might be good.

I would prefer listing added methods first.

I don't understand why... In the table of the documentation page, the abstract methods are listed fisrt. In the source code, the abstract methods are implemented fisrt. In UML, the convention is to place the abstract methods first.

Stephen J. Turnbull

3:38 p.m.

Sorry about the premature send. Terry Reedy writes:

...

B. Be consistent on placement of inherited versus added methods. Always list inherited first? Different fonts, as suggested, might be good.

I would prefer listing overridden and added methods first, because there's a good chance I already know from the base classes what methods are inherited. On the other hand, I would list abstract methods first, as they form an agenda for implementing a concrete class. (I don't have much experience with this though.) Steve

Yahya Abou 'Imran

1 Jan 1 Jan

4:45 p.m.

...

A. Width restrictions suggest making the async branches a separate diagram.

B. Be consistent on placement of inherited versus added methods. Always list inherited first? Different fonts, as suggested, might be good.

C. After discussion here, and revision, open a doc enhancement issue on bugs.python.org.

I managed to have a nice layout to have all the ABCs in this module on one diagram. I'm joining three versions to this mail. I'm thankfull to all the people that gave my their opinions. However, I insist that abstract methods should be shown first (in italic, witch is the standard in UML). And about parenthesis, it's a standard in UML to represent methods; so even if it does'nt add anything meaningfull in this situation, I prefer to stick to UML conventions as most as possible.

Brett Cannon

8:39 p.m.

While I appreciate what you're trying to accomplish, Yahya, one thing I would like to say is if we were to accept the diagram into the docs I would prefer that there be a source file that isn't an image which we can update with easily available software (e.g. like a dot file). Otherwise updating the file will either be burdensome going forward or we will simply have to drop the image at the first instance of needing to update it because no one can or be willing to put in the effort (and I'm thinking in 5 years, not soon while we can count on you to help). On Sat, Dec 30, 2017, 08:12 Yahya Abou 'Imran via Python-ideas, < python-ideas@python.org> wrote:

...

We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Yahya Abou 'Imran

9:31 p.m.

...

While I appreciate what you're trying to accomplish, Yahya, one thing I would like to say is if we were to accept the diagram into the docs I would prefer that there be a source file that isn't an image which we can update with easily available software (e.g. like a dot file). Otherwise updating the file will either be burdensome going forward or we will simply have to drop the image at the first instance of needing to update it because no one can or be willing to put in the effort (and I'm thinking in 5 years, not soon while we can count on you to help).

Of course! "Tip 23 Always Use Source Code Control Always. Even if you are a single-person team on a one-week project. Even if it's a "throw-away" prototype. Even if the stuff you're working on isn't source code. Make sure that *everything* is under source control -- documentation, phone number lists, memos to vendors, makefiles, build and release procedure, that little shell script that burns the CD master -- everything. We routinely use source code control on just about everything (including the text of this bool)." The Pragmatic Programmer, Andrew Hunt & David Thomas. Here are the files! I used plantuml.

Victor Stinner

10:32 p.m.

Hi, There is "blockdiag" which is Sphinx friendly: http://blockdiag.com/en/blockdiag/sphinxcontrib.html Look also at: * http://asciiflow.com/ * http://ditaa.sourceforge.net/ * http://asciidoctor.org/news/2014/02/18/plain-text-diagrams-in-asciidoctor/ * etc. I like ASCII Art since it doesn't require any specific tool to edit it (even if dedicated tools like asciiflow can make editing simpler). For example, I have no idea how to open a ".puml" file. What if the tool for this specific format becomes outdated or is not available on some platforms? Graphviz with "dot" files is another option. Victor 2018-01-01 21:39 GMT+01:00 Brett Cannon :

...

While I appreciate what you're trying to accomplish, Yahya, one thing I would like to say is if we were to accept the diagram into the docs I would prefer that there be a source file that isn't an image which we can update with easily available software (e.g. like a dot file). Otherwise updating the file will either be burdensome going forward or we will simply have to drop the image at the first instance of needing to update it because no one can or be willing to put in the effort (and I'm thinking in 5 years, not soon while we can count on you to help).

On Sat, Dec 30, 2017, 08:12 Yahya Abou 'Imran via Python-ideas, wrote:

...
We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Yahya Abou 'Imran

10:58 p.m.

http://plantuml.com/ You just run it with the `plantuml` command, and you have .png It has a good integration with a lot of tools (iPython for example) : http://plantuml.com/running I will look at your suggestions though. -------- Message d'origine -------- On 1 janv. 2018 23:32, Victor Stinner a écrit :

...

Hi,

There is "blockdiag" which is Sphinx friendly: http://blockdiag.com/en/blockdiag/sphinxcontrib.html

Look also at:

* http://asciiflow.com/ * http://ditaa.sourceforge.net/ * http://asciidoctor.org/news/2014/02/18/plain-text-diagrams-in-asciidoctor/ * etc.

I like ASCII Art since it doesn't require any specific tool to edit it (even if dedicated tools like asciiflow can make editing simpler).

For example, I have no idea how to open a ".puml" file. What if the tool for this specific format becomes outdated or is not available on some platforms?

Graphviz with "dot" files is another option.

Victor

2018-01-01 21:39 GMT+01:00 Brett Cannon :

...
While I appreciate what you're trying to accomplish, Yahya, one thing I would like to say is if we were to accept the diagram into the docs I would prefer that there be a source file that isn't an image which we can update with easily available software (e.g. like a dot file). Otherwise updating the file will either be burdensome going forward or we will simply have to drop the image at the first instance of needing to update it because no one can or be willing to put in the effort (and I'm thinking in 5 years, not soon while we can count on you to help).

On Sat, Dec 30, 2017, 08:12 Yahya Abou 'Imran via Python-ideas, wrote:

...
We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html http://www.falkhausen.de/Java-8/java.util/Collection-List.html

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://goo.gl/images/6xZqcA

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/ @python.org> @python.org>

Yahya Abou 'Imran

11:51 p.m.

Plantuml can also generate ASCII, so playing with ditaa I managed to have intersting things... I opened a public repo on my GitLab account to put that all so you can have a visualization of it (source files and `png`s): https://gitlab.com/yahya-abou-imran/collections-abc-uml `dot` files seems also interesting by the way...

Wes Turner

2 Jan 2 Jan

1:50 a.m.

On Monday, January 1, 2018, Yahya Abou 'Imran via Python-ideas < python-ideas@python.org> wrote:

...

Plantuml can also generate ASCII, so playing with ditaa I managed to have intersting things...

I opened a public repo on my GitLab account to put that all so you can have a visualization of it (source files and `png`s):

https://gitlab.com/yahya-abou-imran/collections-abc-uml

`dot` files seems also interesting by the way...

There is a PlantUML Sphinx extension (which requires Java): https://github.com/sphinx-contrib/plantuml/ There is GraphViz Sphinx extension: http://www.sphinx-doc.org/en/stable/ext/graphviz.html It looks like pyreverse can generate UML diagrams as DOT files: https://github.com/PyCQA/pylint/tree/master/pylint/pyreverse IDK how much post-processing or tool customization is necessary to implement the requested UML diagram styles. This generates DOT files from Django model classes (without adding a Java dependency to the Sphinx docs build): https://github.com/django-extensions/django-extensions/blob/master/django_ex... This generates PlantUML and DOT diagrams from SQLalchemy classes: https://bitbucket.org/estin/sadisplay

Wes Turner

1:51 a.m.

SVG is preferable to PNG because you can Ctrl-F SVG. On Monday, January 1, 2018, Wes Turner wrote:

...

On Monday, January 1, 2018, Yahya Abou 'Imran via Python-ideas < python-ideas@python.org> wrote:

...
Plantuml can also generate ASCII, so playing with ditaa I managed to have intersting things...

I opened a public repo on my GitLab account to put that all so you can have a visualization of it (source files and `png`s):

https://gitlab.com/yahya-abou-imran/collections-abc-uml

`dot` files seems also interesting by the way...

There is a PlantUML Sphinx extension (which requires Java): https://github.com/sphinx-contrib/plantuml/

There is GraphViz Sphinx extension: http://www.sphinx-doc.org/en/stable/ext/graphviz.html

It looks like pyreverse can generate UML diagrams as DOT files: https://github.com/PyCQA/pylint/tree/master/pylint/pyreverse

IDK how much post-processing or tool customization is necessary to implement the requested UML diagram styles.

This generates DOT files from Django model classes (without adding a Java dependency to the Sphinx docs build): https://github.com/django-extensions/django-extensions/ blob/master/django_extensions/management/modelviz.py

This generates PlantUML and DOT diagrams from SQLalchemy classes: https://bitbucket.org/estin/sadisplay

Yahya Abou 'Imran

1:25 p.m.

At the end of the day, I found that plantuml is the most suitable tool for this. Graphviz dot is interesting, but it doesn't feel natural to make class diagram with it, or at least it's less handy... I could bring several arguments to support this, but it's not the topic. Everybody wanting to try itself is welcome, but, *I* can take the commitment to maintain it over the years. Here are the 3 svg files witch are my last proposals for the moment: https://gitlab.com/yahya-abou-imran/collections-abc-uml/blob/master/plantuml... https://gitlab.com/yahya-abou-imran/collections-abc-uml/blob/master/plantuml... https://gitlab.com/yahya-abou-imran/collections-abc-uml/blob/master/plantuml...

Wes Turner

2:34 p.m.

On Tuesday, January 2, 2018, Yahya Abou 'Imran < yahya-abou-imran@protonmail.com> wrote:

...

At the end of the day, I found that plantuml is the most suitable tool for this. Graphviz dot is interesting, but it doesn't feel natural to make class diagram with it, or at least it's less handy... I could bring several arguments to support this, but it's not the topic.

Everybody wanting to try itself is welcome, but, *I* can take the commitment to maintain it over the years.

https://readthedocs.org/projects/python/ https://github.com/python/cpython/blob/master/Doc/conf.py https://github.com/python/cpython/blob/master/Doc/library/collections.abc.rs... https://devguide.python.org/#contributing https://devguide.python.org/docquality/

...

Here are the 3 svg files witch are my last proposals for the moment:

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

Thanks! Wow, now I wish that I had said PNG email attachments and SVG with fallback to PNG in the Sphinx docs.

Wes Turner

2:41 p.m.

Is there a way to generate relative links to the classes in the SVG? This would be really convenient: https://docs.python.org/3/library/collections.abc.html#collections.abc.Hasha... <a href="#collections.abc.Hashable">Hashable</a> On Tuesday, January 2, 2018, Wes Turner wrote:

...

On Tuesday, January 2, 2018, Yahya Abou 'Imran < yahya-abou-imran@protonmail.com> wrote:

...
At the end of the day, I found that plantuml is the most suitable tool for this. Graphviz dot is interesting, but it doesn't feel natural to make class diagram with it, or at least it's less handy... I could bring several arguments to support this, but it's not the topic.

Everybody wanting to try itself is welcome, but, *I* can take the commitment to maintain it over the years.

https://readthedocs.org/projects/python/

https://github.com/python/cpython/blob/master/Doc/conf.py

https://github.com/python/cpython/blob/master/Doc/ library/collections.abc.rst

https://devguide.python.org/#contributing

https://devguide.python.org/docquality/

...
Here are the 3 svg files witch are my last proposals for the moment:

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

Thanks! Wow, now I wish that I had said PNG email attachments and SVG with fallback to PNG in the Sphinx docs.

Brett Cannon

7:38 p.m.

On Tue, 2 Jan 2018 at 05:25 Yahya Abou 'Imran < yahya-abou-imran@protonmail.com> wrote:

...

At the end of the day, I found that plantuml is the most suitable tool for this.

Right, but when I look at http://plantuml.com/ I don't see any open source code to guarantee it will be available in e.g. 5 years. (I really just see a lot of ads around a free Java app).

...

Graphviz dot is interesting, but it doesn't feel natural to make class diagram with it, or at least it's less handy... I could bring several arguments to support this, but it's not the topic.

It's somewhat the topic to me, though, since people seem to have found the diagrams helpful, which means defining how to sustainably maintain them so we are willing to accept them into the documentation is important as that will be the next step in accepting them into the documentation.

...

Everybody wanting to try itself is welcome, but, *I* can take the commitment to maintain it over the years.

I personally appreciate that offer, but I also don't know you well enough to be able to take that as a guarantee, hence why I'm trying to make sure the tooling that is used will last for a very long time (next month will be the 27th anniversary of Python's first public release, so anything we do may need to last a while :) . I know this is an annoying thing to be thinking about when you already have the diagram done in plantuml, but sustaining this work for a long time is part of maintaining open source. -Brett

...

Here are the 3 svg files witch are my last proposals for the moment:

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

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

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

Barry

9:42 p.m.

...

On 2 Jan 2018, at 19:38, Brett Cannon wrote:

...
On Tue, 2 Jan 2018 at 05:25 Yahya Abou 'Imran wrote: At the end of the day, I found that plantuml is the most suitable tool for this.

Right, but when I look at http://plantuml.com/ I don't see any open source code to guarantee it will be available in e.g. 5 years. (I really just see a lot of ads around a free Java app).

I see fedora packages plantuml and says is lgpl3 licensed. Barry

...

...
Graphviz dot is interesting, but it doesn't feel natural to make class diagram with it, or at least it's less handy... I could bring several arguments to support this, but it's not the topic.

It's somewhat the topic to me, though, since people seem to have found the diagrams helpful, which means defining how to sustainably maintain them so we are willing to accept them into the documentation is important as that will be the next step in accepting them into the documentation.

...
Everybody wanting to try itself is welcome, but, *I* can take the commitment to maintain it over the years.

I personally appreciate that offer, but I also don't know you well enough to be able to take that as a guarantee, hence why I'm trying to make sure the tooling that is used will last for a very long time (next month will be the 27th anniversary of Python's first public release, so anything we do may need to last a while :) .

I know this is an annoying thing to be thinking about when you already have the diagram done in plantuml, but sustaining this work for a long time is part of maintaining open source.

-Brett

...
Here are the 3 svg files witch are my last proposals for the moment:

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

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Yahya Abou 'Imran

9:53 p.m.

...

...
Right, but when I look at http://plantuml.com/ I don't see any open source code to guarantee

...
it will be available in e.g. 5 years. (I really just see a lot of ads around a free Java app).

I see fedora packages plantuml and says is lgpl3 licensed.

Barry

On archlinux: $ pacman -Qi plantuml Name : plantuml Version : 1.2017.20-1 Description : Component that allows to quickly write uml diagrams Architecture : any URL : http://plantuml.com/ Licenses : GPL [...] Found also on debian stable in the main section (only free softwares), here is the licence: Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Upstream-Name: plantuml Upstream-Contact: Arnaud Roques Source: http://plantuml.com/download.html Files: * Copyright: 2009-2014, Arnaud Roques License: Expat Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: . The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. . THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Files: debian/plantuml.* Copyright: 2010 Ilya Paramonov License: GPL-3+ This script is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. . This script distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. . The full text of the GPL is distributed in /usr/share/common-licenses/GPL-3 on Debian systems.

Yahya Abou 'Imran

9:56 p.m.

And on the sourceforge page: https://sourceforge.net/projects/plantuml/ License GNU General Public License version 2.0 (GPLv2)

Brett Cannon

3 Jan 3 Jan

12:59 a.m.

That's great! They don't advertise this, unfortunately, at plantuml.com :/ On Tue, 2 Jan 2018 at 13:57 Yahya Abou 'Imran < yahya-abou-imran@protonmail.com> wrote:

...

And on the sourceforge page:

https://sourceforge.net/projects/plantuml/

License GNU General Public License version 2.0 (GPLv2)

Paul Rudin

9:06 a.m.

Brett Cannon writes:

...

On Tue, 2 Jan 2018 at 05:25 Yahya Abou 'Imran wrote:

At the end of the day, I found that plantuml is the most suitable tool for this.

Right, but when I look at http://plantuml.com/ I don't see any open source code to guarantee it will be available in e.g. 5 years. (I really just see a lot of ads around a free Java app).

I know nothing of this software, but https://github.com/plantuml/plantuml appears to be the source code, GPL3 licensed. Still, is a java dependency to build the python docs a good idea?

Brett Cannon

4:52 p.m.

We would check in the resulting image, so any Java dependency would only be for when we update the image. On Wed, Jan 3, 2018, 01:33 Paul Rudin, wrote:

...

Brett Cannon writes:

...
On Tue, 2 Jan 2018 at 05:25 Yahya Abou 'Imran wrote:

At the end of the day, I found that plantuml is the most suitable tool for this.

Right, but when I look at http://plantuml.com/ I don't see any open source code to guarantee it will be available in e.g. 5 years. (I really just see a lot of ads around a free Java app).

I know nothing of this software, but https://github.com/plantuml/plantuml appears to be the source code, GPL3 licensed.

Still, is a java dependency to build the python docs a good idea?

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Yahya Abou 'Imran

5 Jan 5 Jan

4:45 p.m.

Hi everybody. I would like to make a recap: It seems that we all agree that it's something nice to have. Now, we are wondering about the tools or the methodology to use them. As I said, if somebody want to give a try, I'm not against it. But what are we doing now? I've already open an issue, I would like to submit a PR to place the puml and the svg in the doc and to make the diagram appear in the suitable place. Is there a real good reason to wait? I not trying to force myself on anybody here, I just think it's a shame not to use something we have know... If we don't manage to all agree with each other, I will just let the issue open until somebody comes with an undisputed solution.

Brett Cannon

7:25 p.m.

At this point the conversation should shift to https://bugs.python.org/issue32471 . On Fri, 5 Jan 2018 at 08:51 Yahya Abou 'Imran via Python-ideas < python-ideas@python.org> wrote:

...

Hi everybody.

I would like to make a recap:

It seems that we all agree that it's something nice to have. Now, we are wondering about the tools or the methodology to use them.

As I said, if somebody want to give a try, I'm not against it. But what are we doing now? I've already open an issue, I would like to submit a PR to place the puml and the svg in the doc and to make the diagram appear in the suitable place.

Is there a real good reason to wait?

I not trying to force myself on anybody here, I just think it's a shame not to use something we have know... If we don't manage to all agree with each other, I will just let the issue open until somebody comes with an undisputed solution. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Terry Reedy

1 Jan 1 Jan

10:50 p.m.

On 1/1/2018 3:39 PM, Brett Cannon wrote:

...

While I appreciate what you're trying to accomplish, Yahya, one thing I would like to say is if we were to accept the diagram into the docs I would prefer that there be a source file that isn't an image which we can update with easily available software (e.g. like a dot file).

'dot file' was new to me. It is the input format for the dot tool of the open-source graphviz package, with binaries available for Windows, Mac, and various *nixes. After looking at http://www.ffnn.nl/pages/articles/media/uml-diagrams-using-graphviz-dot.php and seeing how easy to edit the examples are, I would require a text source file unless the result were somehow bad. Yahya, how did *you* produce your example?

...

Otherwise updating the file will either be burdensome going forward or we will simply have to drop the image at the first instance of needing to update it because no one can or be willing to put in the effort (and I'm thinking in 5 years, not soon while we can count on you to help).

The ABCs seem to change a bit with every version. -- Terry Jan Reedy

Steve Barnes

2 Jan 2 Jan

10:01 a.m.

Can I suggest that rather than manually producing or tweaking, and later updating, the diagrams it might be better to spend a little time annotating the source code and possibly adding to extra configuration files so that a tools such as DoxyGen (http://www.stack.nl/~dimitri/doxygen/) with GraphViz can be used to extract the information from the source code, produce the dot files and then produce the diagrams in whatever the desired format is. Of course Sphinx with suitable plug-ins might be able to do the same - or will eventually be able to do so. While the diagrams produced might lack the elegance of manually produced ones they would be much more useful as they would always be up to date due to being produced, and updated, automatically. DoxyGen is an open source, cross platform, tool that can parse and diagram any of C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D. It is already in use in the wxPython Phoenix project to parse the wxWidgets C++ code so as to extract the interface details for both the documentation and implementation. It can also work with MSCGEN, DIA & PLANTUML. I am attaching the diagram produced for the full inheritance of collections.abc as produced by doxygen/graphviz but I am sure that there are some options that could make this more readable/useful. Steve On 01/01/2018 20:39, Brett Cannon wrote:

...

While I appreciate what you're trying to accomplish, Yahya, one thing I would like to say is if we were to accept the diagram into the docs I would prefer that there be a source file that isn't an image which we can update with easily available software (e.g. like a dot file). Otherwise updating the file will either be burdensome going forward or we will simply have to drop the image at the first instance of needing to update it because no one can or be willing to put in the effort (and I'm thinking in 5 years, not soon while we can count on you to help).

On Sat, Dec 30, 2017, 08:12 Yahya Abou 'Imran via Python-ideas, mailto:python-ideas@python.org> wrote:

We can find very usefull class diagramm to understand the hierarchy of the builtin Collection abstract class and interface in java.

Some examples: http://www.falkhausen.de/Java-8/java.util/Collection-Hierarchy-simple.html https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.falkhausen.de%2FJava-8%2Fjava.util%2FCollection-Hierarchy-simple.html&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=tho3ojtiDKu5lqBo6cM2dRR%2BY4Cqv74WaM4W49NJjzc%3D&reserved=0 http://www.falkhausen.de/Java-8/java.util/Collection-List.html https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.falkhausen.de%2FJava-8%2Fjava.util%2FCollection-List.html&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=4h4aUHJH9CTV9RpeyrN5zfSetYIpK4sySNL2IE5aGBI%3D&reserved=0

But when I search about python's ABC, The more detailed I can find are those from the book of Luciano Ramalho Fluent Python: https://goo.gl/images/8JGjvM https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgoo.gl%2Fimages%2F8JGjvM&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=FbbDEgIsHJcZ4oRwVusZkFcepCEjHo5JuOzaj5erFz0%3D&reserved=0 https://goo.gl/images/6xZqcA https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgoo.gl%2Fimages%2F6xZqcA&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=Uwy0pQygI1R6sgtAZ6qbJOTUG8fM%2Fr76iZFRagoaytA%3D&reserved=0

(I think they're done with pyreverse of pylint)

They are fine, but I think we could provide some other more detailed in this page: https://docs.python.org/3/library/collections.abc.html https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.python.org%2F3%2Flibrary%2Fcollections.abc.html&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=FgeML0%2BLBwSmUnyEZnqZvpF4jAP94BKyKqCR5FOX138%3D&reserved=0

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

I've began working on it with plantuml and pyreverse, I'm joining to this mail what I've done so far so you can tell me what you think. _______________________________________________ Python-ideas mailing list Python-ideas@python.org mailto:Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmail.python.org%2Fmailman%2Flistinfo%2Fpython-ideas&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=AIRvO1pUs69rWu%2FbV7fZ7ab%2FvrhNnlgFjucXz4JaXSU%3D&reserved=0 Code of Conduct: http://python.org/psf/codeofconduct/ https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fpython.org%2Fpsf%2Fcodeofconduct%2F&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=jUd4UT9Usupz0chUJnItDXCd84PCZdCFkIkOQNmE6S8%3D&reserved=0

_______________________________________________ Python-ideas mailing list Python-ideas@python.org https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmail.python.org%2Fmailman%2Flistinfo%2Fpython-ideas&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=AIRvO1pUs69rWu%2FbV7fZ7ab%2FvrhNnlgFjucXz4JaXSU%3D&reserved=0 Code of Conduct: https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fpython.org%2Fpsf%2Fcodeofconduct%2F&data=02%7C01%7C%7Cdcdf2c291d0c41499c5908d5515902ef%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636504365089997045&sdata=jUd4UT9Usupz0chUJnItDXCd84PCZdCFkIkOQNmE6S8%3D&reserved=0

-- Steve (Gadget) Barnes Any opinions in this message are my personal opinions and do not reflect those of my employer.

Yahya Abou 'Imran

3:26 p.m.

...

Can I suggest that rather than manually producing or tweaking, and later updating, the diagrams it might be better to spend a little time annotating the source code [...] While the diagrams produced might lack the elegance of manually produced ones they would be much more useful as they would always be up to date due to being produced, and updated, automatically.

I think it would be a lot of changes in the source code... I would like to precise, so everybody can know it, the syntax of a .puml is realy simple. For example: test.puml: @startuml hide members show methods abstract class Iterable { {abstract} __iter__() } abstract class Iterator { {abstract} __next__() .. __iter__() } Iterable <|-- Iterator @enduml Then: $ plantuml test.puml And you have test.png I joined.

...

[...] I am attaching the diagram produced for the full inheritance of collections.abc as produced by doxygen/graphviz but I am sure that there are some options that could make this more readable/useful.

Steve

It's a blank file that I have... I've been struggling with those kind of tools these days, and realised that it's a lot more work (and pain) than a plain text file.

Barry

9:29 p.m.

After reading this thread I went off and read up about plantuml. According to its docs it produces dot files that it reandes with graphviz. So if graphviz will produce svg that part is solved. Can you creat the plantuml file automatically from the python code? Barry On 2 Jan 2018, at 15:26, Yahya Abou 'Imran via Python-ideas wrote:

...

...
Can I suggest that rather than manually producing or tweaking, and later updating, the diagrams it might be better to spend a little time annotating the source code [...] While the diagrams produced might lack the elegance of manually produced ones they would be much more useful as they would always be up to date due to being produced, and updated, automatically.

I think it would be a lot of changes in the source code...

I would like to precise, so everybody can know it, the syntax of a .puml is realy simple. For example:

test.puml:

@startuml

hide members show methods

abstract class Iterable { {abstract} __iter__() }

abstract class Iterator { {abstract} __next__() .. __iter__() }

Iterable <|-- Iterator

@enduml

Then:

$ plantuml test.puml

And you have test.png I joined.

...
[...] I am attaching the diagram produced for the full inheritance of collections.abc as produced by doxygen/graphviz but I am sure that there are some options that could make this more readable/useful.

Steve

It's a blank file that I have...

I've been struggling with those kind of tools these days, and realised that it's a lot more work (and pain) than a plain text file. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/

Steve Barnes

3 Jan 3 Jan

7:40 a.m.

You can embed plantuml directives in rst, and possibly the code, and use sphinxcontrib-plantuml which at least keeps the diagrams for documentation close to the code. pyplantuml claims to be able to extract the infromation directly from the code, (https://github.com/cb109/pyplantuml), but having tried it it seems a little flaky (and over specific in its dependencies). pyreverse by default produces a .dot file but takes some time to come up with the correct flags. https://github.com/rtfd/readthedocs.org/issues/407 makes interesting reading as well and is also relevant to this thread. On 02/01/2018 21:29, Barry wrote:

...

After reading this thread I went off and read up about plantuml. According to its docs it produces dot files that it reandes with graphviz. So if graphviz will produce svg that part is solved.

Can you creat the plantuml file automatically from the python code?

Barry

On 2 Jan 2018, at 15:26, Yahya Abou 'Imran via Python-ideas wrote:

...
...
Can I suggest that rather than manually producing or tweaking, and later updating, the diagrams it might be better to spend a little time annotating the source code [...] While the diagrams produced might lack the elegance of manually produced ones they would be much more useful as they would always be up to date due to being produced, and updated, automatically.

I think it would be a lot of changes in the source code...

I would like to precise, so everybody can know it, the syntax of a .puml is realy simple. For example:

test.puml:

@startuml

hide members show methods

abstract class Iterable { {abstract} __iter__() }

abstract class Iterator { {abstract} __next__() .. __iter__() }

Iterable <|-- Iterator

@enduml

Then:

$ plantuml test.puml

And you have test.png I joined.

...
[...] I am attaching the diagram produced for the full inheritance of collections.abc as produced by doxygen/graphviz but I am sure that there are some options that could make this more readable/useful.

Steve

It's a blank file that I have...

I've been struggling with those kind of tools these days, and realised that it's a lot more work (and pain) than a plain text file. _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fmail.python.org%2Fmailman%2Flistinfo%2Fpython-ideas&data=02%7C01%7C%7C6d32c06f38af4d40145708d55227e234%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636505253601685827&sdata=DyrMOxl32rsEHK%2ByWUW9QlvzP%2Fn%2FqHXsKlSNuT%2B0loU%3D&reserved=0 Code of Conduct: https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fpython.org%2Fpsf%2Fcodeofconduct%2F&data=02%7C01%7C%7C6d32c06f38af4d40145708d55227e234%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636505253601685827&sdata=PQTKP%2FYAkdZscYpy815VbJXBeE89K1aslWibFgGf1Ww%3D&reserved=0

-- Steve (Gadget) Barnes Any opinions in this message are my personal opinions and do not reflect those of my employer.

2302

Age (days ago)

2308

Last active (days ago)

List overview

Download

34 comments

11 participants

participants (11)

Barry
Brett Cannon
Paul Rudin
pylang
Stephan Houben
Stephen J. Turnbull
Steve Barnes
Terry Reedy
Victor Stinner
Wes Turner
Yahya Abou 'Imran

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

Stephan Houben

tags

participants (11)