Skip to content

Docstrings guide

Implementing Docstrings in Python Code

When you write or modify Python code in the codebase, it's important to add or update the docstrings accordingly. If you wish to display these docstrings in the documentation, follow these steps.

Suppose the docstrings are located in the following path: docs/Submodules/IntelOwl/api_app/analyzers_manager/classes, and you want to show the description of a class, such as BaseAnalyzerMixin.

To include this in the documentation, use the following command:

:::docs.Submodules.IntelOwl.api_app.analyzers_manager.classes.BaseAnalyzerMixin

Warning

Make sure your path is correct and syntax is correct. If you face any issues even path is correct then read the Submodules Guide.

This is how it would look in documentation:

Bases: Plugin

Abstract Base class for Analyzers. Never inherit from this branch, always use either one of ObservableAnalyzer or FileAnalyzer classes.

Source code in docs/Submodules/IntelOwl/api_app/analyzers_manager/classes.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class BaseAnalyzerMixin(Plugin, metaclass=ABCMeta):
    """
    Abstract Base class for Analyzers.
    Never inherit from this branch,
    always use either one of ObservableAnalyzer or FileAnalyzer classes.
    """

    HashChoices = HashChoices
    ObservableTypes = ObservableTypes
    TypeChoices = TypeChoices

    @classmethod
    @property
    def config_exception(cls):
        return AnalyzerConfigurationException

    @property
    def analyzer_name(self) -> str:
        return self._config.name

    @classmethod
    @property
    def report_model(cls):
        return AnalyzerReport

    @classmethod
    @property
    def config_model(cls):
        return AnalyzerConfig

    def get_exceptions_to_catch(self):
        """
        Returns additional exceptions to catch when running *start* fn
        """
        return (
            AnalyzerConfigurationException,
            AnalyzerRunException,
        )

    def _validate_result(self, result, level=0, max_recursion=190):
        """
        function to validate result, allowing to store inside postgres without errors.

        If the character \u0000 is present in the string, postgres will throw an error

        If an integer is bigger than max_int,
        Mongodb is not capable to store and will throw an error.

        If we have more than 200 recursion levels, every encoding
        will throw a maximum_nested_object exception
        """
        if level == max_recursion:
            logger.info(
                f"We have reached max_recursion {max_recursion} level. "
                f"The following object will be pruned {result} "
            )
            return None
        if isinstance(result, dict):
            for key, values in result.items():
                result[key] = self._validate_result(
                    values, level=level + 1, max_recursion=max_recursion
                )
        elif isinstance(result, list):
            for i, _ in enumerate(result):
                result[i] = self._validate_result(
                    result[i], level=level + 1, max_recursion=max_recursion
                )
        elif isinstance(result, str):
            return result.replace("\u0000", "")
        elif isinstance(result, int) and result > 9223372036854775807:  # max int 8bytes
            result = 9223372036854775807
        return result

    def after_run_success(self, content):
        super().after_run_success(self._validate_result(content, max_recursion=15))

get_exceptions_to_catch()

Returns additional exceptions to catch when running start fn

Source code in docs/Submodules/IntelOwl/api_app/analyzers_manager/classes.py 
57
58
59
60
61
62
63
64
def get_exceptions_to_catch(self):
    """
    Returns additional exceptions to catch when running *start* fn
    """
    return (
        AnalyzerConfigurationException,
        AnalyzerRunException,
    )