extract methods

[mskoenz]

First: awesome package, thx a lot ^^

Second: am I not finding the option, or is is currently not possible to extract the methods of classes?

Best regards
mskoenz

[lucsorel]

Hi @mskoenz,

Thank you for your interest, I am glad if this library is of any help to you.

Unfortunately you are right: py2puml does not extract the methods of the parsed classes yet. I initially wrote it to document a folder of tangled dataclasses representing the domain model of an application that I started to work for. I needed to see composition relationships between the dataclasses.

But it makes totally sense to improve the library so that it exports methods too. Would you like to contribute?

[jonykalavera]

I'd like to give this a try. will create a pull request. @lucsorel: any ideas you already have about this?

[jonykalavera]

Some basic goal would be to cover this point in the plantuml docs https://plantuml.com/class-diagram#090967fbee930909

[jonykalavera]

how should it look?

@startuml
class Example {
   some_attr : int
   some_method(some_param: int = 1) -> date
}
@enduml

[jonykalavera]

Singature could be done as the first example here https://docs.python.org/3/library/inspect.html#introspecting-callables-with-the-signature-object

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)  # LIKE THIS
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

[jonykalavera]

will wait for feedback to proceed. ✌️

[lucsorel]

hi @jonykalavera
Thank you for proposing your help, which I appreciate a lot. I was on holidays but I am back. However, I am not available a lot these days (young dad + busy time for the vegetable garden). Please, don't take it personally and be patient if I am slow to answer back 🙏

A couple answers and thoughts:

1. yes, signature inspection seems to me the way to go
2. about the way to type signature parameters and the return type, I am not sure
   1. you suggested some_method(some_param: int = 1) -> date which seems pythonesque (with the arrow)
   2. but the UML convention seems to be date some_method(some_param: int = 1) and void method_returning_nothin(some_param: int = 1); but I would prefer leaving the return type empty rather than indicating void (unless the return type is set to -> None in the code), because using type annotations for the return type of methods is not a common practice. What do you think?
3. about relationships: if a.some_method() returns an instance of class B, should we draw an UML relationship between classes A and B? If yes, should it be an association relationship? I would suggest not to add relationship at all when handling methods and leave them for the constructors, what do you think?
4. we should distinguish instance/class methods from static methods. I would add {static} in front of static methods only, and leave class methods without UML decoration: class methods (receiving the class as their first parameter) do not exist in the UML syntax
5. when I created this library, I was interested only in the class/instance attributes because they tell how the business domain is structured. I am ok with adding the methods since it is a wish of the community. However, I am wondering whether it is time to introduce some options to py2puml to let the people express what should be output (attributes, methods, etc.). It may be premature to decide what is optional (and what would be the default choice!), but I would like to know what you think about that, if you please

[jonykalavera]

hi @jonykalavera Thank you for proposing your help, which I appreciate a lot. I was on holidays but I am back. However, I am not available a lot these days (young dad + busy time for the vegetable garden). Please, don't take it personally and be patient if I am slow to answer back 🙏

No problem. I assume you do this in your free time. :)

A couple answers and thoughts:

1. yes, signature inspection seems to me the way to go
   👍

2. about the way to type signature parameters and the return type, I am not sure

3. you suggested some_method(some_param: int = 1) -> date which seems pythonesque (with the arrow)

yeah, I think it is ok because, when no explicit {method} is set, the distinguishing criteria is the presence of the parenthesis. and I like it sticks to the python typing syntax. Although for our purposes it's probably better to explicitly prefix them with {method} anyway.

2. but the UML convention seems to be date some_method(some_param: int = 1) and void method_returning_nothin(some_param: int = 1);

AFAIK there are no hard rules about the typing order; at least according to the docs: https://plantuml.com/class-diagram#090967fbee930909

Note that the syntax is highly flexible about type/name order.

but I would prefer leaving the return type empty rather than indicating void (unless the return type is set to -> None in the code), because using type annotations for the return type of methods is not a common practice. What do you think?
I think we should reflect the pythonic way to show it since the documentation Well I think if it is there we should show it

I'm with you. In short: let's not use void, I like staying pythonic. let's leave type empty if not hinted, and show it if it is.
IMHO I think regardless of general practices the tool should just reflect what is there. for me, the value of this tool is that it can be a trusty mirror that lets me constantly reflect upon the architecture and general shape of my project at a high level. WDYT?

3. about relationships: if a.some_method() returns an instance of class B, should we draw a UML relationship between classes A and B? If yes, should it be an association relationship? I would suggest not to add relationships at all when handling methods and leave them for the constructors, what do you think?

I agree. but maybe I am biased. in any case, I think we should leave it out of the scope of this PR.

4. we should distinguish instance/class methods from static methods. I would add {static} in front of static methods only, and leave class methods without UML decoration: class methods (receiving the class as their first parameter) do not exist in the UML syntax

I agree. it should not be too hard to do. similar to how we dealt with abstract classes. also, I noticed that the signature shows the self and cls parameters too. which at first I thought to remove but then maybe they are useful to distinguish them. WDYT?

5. when I created this library, I was interested only in the class/instance attributes because they tell how the business domain is structured. I am ok with adding the methods since it is a wish of the community. However, I am wondering whether it is time to introduce some options to py2puml to let the people express what should be output (attributes, methods, etc.). It may be premature to decide what is optional (and what would be the default choice!), but I would like to know what you think about that if you please

I totally agree. we should provide customization options. especially if the pr about functions gets merged. I want that one but i can imagine some might not. for now, if we want to keep the expected behavior, we can add one option to the command default false.

Will wait for your comments to proceed