Add docstrings for pytm model entities
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.2k
- Forks
- 229
- PR merge metrics
- No merged PRs in 30d
Description
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:
https://github.com/user-attachments/assets/9ede76e1-3689-4906-bd39-b2af7e0333af
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in pytm/pytm.py with the Actor class and its init method, then identify the other pytm model entity classes covered by the request. Follow the linked Google-style class and function docstring references, and use ./tm.py --list-elements and ./tm.py --describe to verify that the documented entities expose useful descriptions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100