Add docstrings for pytm model entities

[fkromer]

The CLI based development workflow using ./tm.py --list-elements + ./tm.py --describe <element> is not convenient for threat model creation.

An easier and more efficient workflow to work with model entities (this includes custom model entities) makes use of/depends on docstrings.

E.g. when using google docstring format the Actor class (docstring reference) + __init__ method (google format docstring reference) could be documented like

class Actor(Element):
    """An entity usually initiating actions.

    Attributes:
        port (int): Default TCP port for outgoing data flows.
        protocol (str): Default network protocol for outgoing data flows.
        data (list): List of pytm.Data objects in outgoing data flows.
        inputs (list): List of incoming Dataflows.
        outputs (list): List of outgoing Dataflows.
        isAdmin (bool): Indicates if the actor is an administrator.
    """

    port = varInt(-1, doc="Default TCP port for outgoing data flows")
    protocol = varString("", doc="Default network protocol for outgoing data flows")
    data = varData([], doc="pytm.Data object(s) in outgoing data flows")
    inputs = varElements([], doc="incoming Dataflows")
    outputs = varElements([], doc="outgoing Dataflows")
    isAdmin = varBool(False)

    def __init__(self, name, **kwargs):
        """
        Initialize an Actor object.

        Args:
            name (str): The name of the actor.
            **kwargs: Additional keyword arguments.
                port (int): Default TCP port for outgoing data flows.
                protocol (str): Default network protocol for outgoing data flows.
                data (list): List of pytm.Data objects in outgoing data flows.
                inputs (list): List of incoming Dataflows.
                outputs (list): List of outgoing Dataflows.
                isAdmin (bool): Indicates if the actor is an administrator.
        """
        super().__init__(name, **kwargs)
        TM._actors.append(self)

and would result IDE-wise in something like this:

ide_docstring_preview_support.webm

[fkromer]

Is compatible with #279 .

[fkromer]

W.r.t. docstring formats it's common that people start to debate about what format to go with. Actually IMO it does not really matter. Every format has different pros and cons. For a quick overview: Google vs. reStructuredText vs NumPy vs Epytext Style. Personally I prefer the Google format due to read-ability reasons and the fact that all modern Python packages I know (e.g. pydantic) use it. The lack of formal spec no one really cares about. I do not really care about what we want to go with... it does not relate to pytm functionality. More important is to decide on something to get further from a methodology point of view. Is change-able later on in worst case still.

@izar What docstring format do you want to go for?

[shivachethanreddy]

Thanks for the detailed explanation and example, that helped a lot

I’ve added Google-style docstrings to the Actor class and its init method following the example you provided.
Would you prefer to:

1.start with Actor as a reference implementation and extend docstrings to other model entities incrementally, or
2.add docstrings for all pytm model entity classes in a single PR (keeping it docstrings-only)?
Happy to follow whatever approach you prefer.

[shivachethanreddy]

I’ve opened a PR with the Actor docstring changes as discussed. #311
I’m happy to extend this pattern to other model entities once we agree on the preferred scope.