Add docstrings for pytm model entities

Abierto
  • ¿Algo no está bien?
#294 6 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 3 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
68/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
python
Área
documentation

Línea de trabajo

Comienza en pytm/pytm.py con la clase Actor y su método init, y después identifica las otras clases de entidades del modelo pytm cubiertas por la solicitud. Sigue las referencias enlazadas a los docstrings de clases y funciones de Google-style, y usa ./tm.py --list-elements y ./tm.py --describe para verificar que las entidades documentadas exponen descripciones útiles.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
Python
Estrellas
1.2k
Forks
237
Merge medio
4 d 2 h
PR fusionados (30 d)
9

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de OWASP/pytm

Todos los issues de OWASP/pytm

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.