From Newsgroup: comp.lang.python

Hello community,

I have created a Python code where a main algorithm uses three different modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?


[image: checkso.PNG]

Could it be improved for better description and readability?


Thanks!
--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

the diagram is also attached here
Le mar. 24 déc. 2024 à 18:27, marc nicole <mk1853387@gmail.com> a écrit :

Hello community,

I have created a Python code where a main algorithm uses three different modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?

[image: checkso.PNG]

Could it be improved for better description and readability?

Thanks!

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

marc nicole <mk1853387@gmail.com> wrote or quoted:

Could it be improved for better description and readability?

ASCII art is very readable in Usenet.

With Unicode:


┌─────────────────┐ ┌─────────────────┐
│ Component A │ │ Component B │
│ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Interface │<>┼──────┼─>│ Interface │ │
│ └───────────┘ │ │ └───────────┘ │
│ │ │ │ └─────────────────┘ └─────────────────┘
│ │
│ │
│ │
▼ ▼ ┌─────────────────┐ ┌─────────────────┐
│ Component C │ │ Component D │
│ │ │ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Interface │<>┼──────┼─>│ Interface │ │
│ └───────────┘ │ │ └───────────┘ │
│ │ │ │ └─────────────────┘ └─────────────────┘

With plain ASCII:

.----------------. .----------------.
| Component A | | Component B |
| | | |
| .-----------. | | .-----------. |
| | Interface |<+------+->| Interface | |
| '-----------' | | '-----------' |
| | | |
'----------------' '----------------'
| |
| |
| |
v v
.----------------. .----------------.
| Component C | | Component D |
| | | |
| .-----------. | | .-----------. |
| | Interface |<+------+->| Interface | |
| '-----------' | | '-----------' |
| | | |
'----------------' '----------------'

With turtles (there are some errors, but one get's the idea!):

import turtle

def draw_box(t, width, height):
for _ in range(2):
t.forward(width)
t.right(90)
t.forward(height)
t.right(90)

def draw_component(t, x, y, label):
t.penup()
t.goto(x, y)
t.pendown()
draw_box(t, 160, 100)

# Draw interface
t.penup()
t.goto(x + 20, y - 40)
t.pendown()
draw_box(t, 120, 30)

# Write component label
t.penup()
t.goto(x + 80, y + 70)
t.write(label, align="center", font=("Arial", 12, "normal"))

def draw_arrow(t, start_x, start_y, end_x, end_y):
t.penup()
t.goto(start_x, start_y)
t.pendown()
t.goto(end_x, end_y)

# Draw arrowhead
t.setheading(t.towards(end_x, end_y))
t.right(150)
t.forward(10)
t.backward(10)
t.left(300)
t.forward(10)

def main():
screen = turtle.Screen()
screen.setup(800, 600)
screen.title("Component Diagram")

t = turtle.Turtle()
t.speed(0) # Fastest drawing speed

# Draw components
draw_component(t, -200, 150, "Component A")
draw_component(t, 100, 150, "Component B")
draw_component(t, -200, -100, "Component C")
draw_component(t, 100, -100, "Component D")

# Draw arrows
draw_arrow(t, -40, 125, 100, 125)
draw_arrow(t, -120, 50, -120, -100)
draw_arrow(t, 180, 50, 180, -100)
draw_arrow(t, -40, -125, 100, -125)

t.hideturtle()
screen.exitonclick()

if __name__ == "__main__":
main()






--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

On 12/24/24 10:27 AM, marc nicole via Python-list wrote:

the diagram is also attached here

This text-only mailing list does not allow attachments, just FYI.

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

it is here https://i.sstatic.net/ykk5Wd0w.png
Le mar. 24 déc. 2024 à 20:03, Michael Torrie via Python-list < python-list@python.org> a écrit :

On 12/24/24 10:27 AM, marc nicole via Python-list wrote:

the diagram is also attached here

This text-only mailing list does not allow attachments, just FYI.

--
https://mail.python.org/mailman/listinfo/python-list

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

On 25/12/24 08:00, Michael Torrie via Python-list wrote:

On 12/24/24 10:27 AM, marc nicole via Python-list wrote:

the diagram is also attached here

This text-only mailing list does not allow attachments, just FYI.

Many devs use Markdown (or similar) text-only file-formats for technical documentation. A tool for including block-graphics in these is "Mermaid" (https://mermaid.js.org/intro/).
--
Regards,
=dn
--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

On 25/12/24 06:27, marc nicole via Python-list wrote:

Hello community,

I have created a Python code where a main algorithm uses three different modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?

[image: checkso.PNG]

Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?

Given that the three modules are subordinate contributors to the script/algorithm, place the three modules inside a larger "Algorithm" shape.
--
Regards,
=dn
--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the requirement: basically the structure of my code and how the modules relate
to each other.
Le mar. 24 déc. 2024 à 21:56, dn via Python-list <python-list@python.org> a écrit :

On 25/12/24 06:27, marc nicole via Python-list wrote:

Hello community,

I have created a Python code where a main algorithm uses three different modules (.py) after importing them.

To illustrate and describe it I have created the following component diagram?

[image: checkso.PNG]

Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram redacted! What messages do you want to communicate with this diagram?

Given that the three modules are subordinate contributors to the script/algorithm, place the three modules inside a larger "Algorithm"
shape.

--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

The full python package (pypi) being represented as the outermost frame
here including the 4 sub-frames)
Le mar. 24 déc. 2024 à 22:05, marc nicole <mk1853387@gmail.com> a écrit :

I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the requirement: basically the structure of my code and how the modules relate
to each other.

Le mar. 24 déc. 2024 à 21:56, dn via Python-list <python-list@python.org>
a écrit :

On 25/12/24 06:27, marc nicole via Python-list wrote:

Hello community,

I have created a Python code where a main algorithm uses three different >> > modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?


[image: checkso.PNG]

Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?

Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.

--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

On 12/24/2024 4:08 PM, marc nicole via Python-list wrote:

The full python package (pypi) being represented as the outermost frame
here including the 4 sub-frames)

Le mar. 24 déc. 2024 à 22:05, marc nicole <mk1853387@gmail.com> a écrit :

I want to convey the idea that main.py (main algorithm) imports 3 modules
(V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the
requirement: basically the structure of my code and how the modules relate >> to each other.

As is, the diagram doesn't convey any of that. For example, main.py is
a program, not an algorithm. we can't tell that main.py imports three
modules. They might just as well be internal classes. If you want to communicate something you need to say or show what that thing is.

This might be close to what you have said (I only show 2 of the 3
modules and I didn't have the page width for the bottom left-hand label) -

------------
| main.py | --implements--> Agorithm A
------------
/ \
imports imports
| |
↓ ↓
--------- --------
| V.py | | S.py | --implements--> Subalgorithm A.2
--------- --------

Le mar. 24 déc. 2024 à 21:56, dn via Python-list <python-list@python.org> >> a écrit :

On 25/12/24 06:27, marc nicole via Python-list wrote:

Hello community,

I have created a Python code where a main algorithm uses three different >>>> modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?


[image: checkso.PNG]

Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?

Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.

--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

marc nicole via Python-list <python-list@python.org> ezt írta (időpont:
2024. dec. 24., K 22:09):

The full python package (pypi) being represented as the outermost frame
here including the 4 sub-frames)

Le mar. 24 déc. 2024 à 22:05, marc nicole <mk1853387@gmail.com> a écrit :

I want to convey the idea that main.py (main algorithm) imports 3 modules (V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the requirement: basically the structure of my code and how the modules

relate

to each other.

Le mar. 24 déc. 2024 à 21:56, dn via Python-list <python-list@python.org

a écrit :

On 25/12/24 06:27, marc nicole via Python-list wrote:

Hello community,

I have created a Python code where a main algorithm uses three

different

modules (.py) after importing them.

To illustrate and describe it I have created the following component
diagram?


[image: checkso.PNG]

Could it be improved for better description and readability?

Possibly - so little detail as to topic and any hints in the diagram
redacted! What messages do you want to communicate with this diagram?

Given that the three modules are subordinate contributors to the
script/algorithm, place the three modules inside a larger "Algorithm"
shape.

--
Regards,
=dn
--
https://mail.python.org/mailman/listinfo/python-list

--
https://mail.python.org/mailman/listinfo/python-list

Hi,
also there are some tools which can generate class hierarchy diagram from
code.
for example here is a post https://stackoverflow.com/questions/77421030/how-to-generate-the-uml-diagram-from-the-python-code
pyreverse is now part of pylint if I remember well.
BR
George


--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

On 12/24/2024 3:42 PM, marc nicole via Python-list wrote:

it is here https://i.sstatic.net/ykk5Wd0w.png

This diagram does not make much sense to me:

1. What is the purpose of the diagram and who is it intended for?
2. A module and an algorithm are different kinds of things, yet they are connected together as if they are the same.
3. Connecting lines should always be labeled, preferably with direction indicators that augment the labels. Otherwise the viewer has to imagine
what the nature of the connection is.
4. It's better if different kinds of things look different. That could
be a different box shape, a different color, or some other visual
difference. Here I am thinking about the box labeled "Algorithm". We
can't tell if it is intended to mean "A library module that implements a certain algorithm", "An algorithm that the three components cooperate to implement", "The top-level module for computing an algorithm that
contains three modules", or something else.

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

the purpose of the diagram is to convey a minimalistic idea about the
structure of the code/implementation/software
Le mer. 25 déc. 2024 à 01:49, Thomas Passin via Python-list < python-list@python.org> a écrit :

On 12/24/2024 3:42 PM, marc nicole via Python-list wrote:

it is here https://i.sstatic.net/ykk5Wd0w.png

This diagram does not make much sense to me:

1. What is the purpose of the diagram and who is it intended for?
2. A module and an algorithm are different kinds of things, yet they are connected together as if they are the same.
3. Connecting lines should always be labeled, preferably with direction indicators that augment the labels. Otherwise the viewer has to imagine
what the nature of the connection is.
4. It's better if different kinds of things look different. That could
be a different box shape, a different color, or some other visual
difference. Here I am thinking about the box labeled "Algorithm". We
can't tell if it is intended to mean "A library module that implements a certain algorithm", "An algorithm that the three components cooperate to implement", "The top-level module for computing an algorithm that
contains three modules", or something else.

--
https://mail.python.org/mailman/listinfo/python-list

--- Synchronet 3.20a-Linux NewsLink 1.114

From Newsgroup: comp.lang.python

On 25/12/24 10:05, marc nicole wrote:

I want to convey the idea that main.py (main algorithm) imports 3
modules (V, S, M) (each of them containing .py scripts related to
different functionalities) and use their methods accordingly as per the requirement: basically the structure of my code and how the modules
relate to each other.

On 25/12/24 23:08, marc nicole via Python-list wrote:

the purpose of the diagram is to convey a minimalistic idea about the structure of the code/implementation/software

In which case, and assuming the "algorithm" is the application's script,
what will the diagram say that is not conveyed by the three import
statements which (almost) head-up the script?

The difficulty you are presenting to respondents (and to eventual
readers) is the paucity of information: block-labels, line/arrow labels, diagram title, expected reader(s), ...


PS would it be better to keep the conversation to one Discussion List?

Le mer. 25 déc. 2024 à 01:49, Thomas Passin via Python-list < python-list@python.org> a écrit :

On 12/24/2024 3:42 PM, marc nicole via Python-list wrote:

it is here https://i.sstatic.net/ykk5Wd0w.png

This diagram does not make much sense to me:

1. What is the purpose of the diagram and who is it intended for?
2. A module and an algorithm are different kinds of things, yet they are
connected together as if they are the same.
3. Connecting lines should always be labeled, preferably with direction
indicators that augment the labels. Otherwise the viewer has to imagine
what the nature of the connection is.
4. It's better if different kinds of things look different. That could
be a different box shape, a different color, or some other visual
difference. Here I am thinking about the box labeled "Algorithm". We
can't tell if it is intended to mean "A library module that implements a
certain algorithm", "An algorithm that the three components cooperate to
implement", "The top-level module for computing an algorithm that
contains three modules", or something else.

--
https://mail.python.org/mailman/listinfo/python-list

--
Regards,
=dn
--- Synchronet 3.20a-Linux NewsLink 1.114