Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Wes Turner]

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
>
>
>
___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Wes Turner]

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
___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Yahya Abou 'Imran via Python-ideas]

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...___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Yahya Abou 'Imran via Python-ideas]

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>___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Terry Reedy]

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

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

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Victor Stinner]

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-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] a set of enum.Enum values rather than the construction of bit-sets as the "norm"?

[Guido van Rossum]

The enum.Flag type solves all this neatly.

On Mon, Jan 1, 2018 at 2:43 PM, Barry Scott  wrote:

> I'm guessing that what this thread is about is coming up with an API rule
> that makes
> providing a set of boolean options available to a function or class in the
> least error prone way.
>
> Its the error prone nature of integer bit masks that is behind the enum
> suggestion I assume.
>
> From the C tradition we have the integer bit mask which is error prone as
> there is no type checking that the masks belong to the option flags.
>
> Some APIs use calls with lots of keyword args that you set true or false
> and even none to mean default.
>
> The suggestion for a set of enums from this thread. You would need a class
> to represent a set of a particular enum to get type safety.
>
> List of strings or enums.
>
> You could even use a class that represents the options and set up an
> instance and pass it in. Hard to get wrong.
>
> I can see that all these styles have their place and each designer will
> pick the style they think fits the API they
> are designing.
>
> Barry
>
> ___
> Python-ideas mailing list
> Python-ideas@python.org
> https://mail.python.org/mailman/listinfo/python-ideas
> Code of Conduct: http://python.org/psf/codeofconduct/
>



-- 
--Guido van Rossum (python.org/~guido)
___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] a set of enum.Enum values rather than the construction of bit-sets as the "norm"?

[Barry Scott]

I'm guessing that what this thread is about is coming up with an API rule that 
makes
providing a set of boolean options available to a function or class in the 
least error prone way.

Its the error prone nature of integer bit masks that is behind the enum 
suggestion I assume.

>From the C tradition we have the integer bit mask which is error prone as 
>there is no type checking that the masks belong to the option flags.

Some APIs use calls with lots of keyword args that you set true or false and 
even none to mean default.

The suggestion for a set of enums from this thread. You would need a class to 
represent a set of a particular enum to get type safety.

List of strings or enums.

You could even use a class that represents the options and set up an instance 
and pass it in. Hard to get wrong.

I can see that all these styles have their place and each designer will pick 
the style they think fits the API they
are designing.

Barry

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

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[Yahya Abou 'Imran via Python-ideas]

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


base.puml
Description: Binary data


full.puml
Description: Binary data


other_collections.puml
Description: Binary data
___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/

Re: [Python-ideas] Add an UML class diagram to the collections.abc module documentation

[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, <
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/
>
___
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/