Add docstrings for pytm model entities

オープン
  • 何か問題がありますか？
#294 コメント 6 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 3 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
68/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
静か
技術スタック
python
領域
documentation

調査の方向性

pytm/pytm.py の Actor クラスとその init メソッドから始め、次にリクエストの対象となる他の pytm モデルエンティティクラスを特定します。リンクされている Google-style のクラスおよび関数の docstring 参照をたどり、./tm.py --list-elements と ./tm.py --describe を使って、ドキュメント化されたエンティティが有用な説明を公開していることを確認します。

索引モデルが issue の本文から書いたものです。

説明

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

主要言語
Python
スター
1.2k
フォーク
237
平均マージ
4日 2時間
マージ済み PR（30日）
9

環境構築

Codespaces で開く

このプロジェクトの開発コンテナを、あなたの GitHub アカウントでブラウザ上に起動します。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

OWASP/pytm のほかの issue

OWASP/pytm の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。