Module: module.py — badsnakes - v0.2.0 Documentation

# Module: module.py

Purpose:

  This module implements the `Module` class object which provides the primary parsing, extraction, analysis and results container for the project.

  The `Module` class is the object which stores the relevant statements extracted from the AST and their analysis results. Each AST node class contained in the `_NodeClasses` class (accessed via the `Module.nodeclasses` property) contains an iterator which enables the node classes to be called in a controlled loop and analysed.

Platform:

  Linux/Windows | Python 3.10+

Developer:

  J Berendt

Email:

  development@s3dev.uk

Comments:

  n/a

Example:

  To perform analysis on a Python module:

      >>> from badsnakes import Module

      # Create and analyse
      >>> m = Module(path='spam.py')
      >>> m.analyse()

      # Display the raw findings (debugging)
      >>> m.display()

class badsnakes.libs.module.Module(path: str)

  Bases: `object`

  Primary container class for the Python module.

  Parameters:

    path (str) – Full path to the module to be parsed and analysed.

  The `nodeclasses` property provides access to each of the relevant AST node class types which were parsed from the source code. When populated, each node class will be a list of `badsnakes.libs.containers` objects containing the analyser and detail extracted from each node.

  On class instantiation, during initialisation, the following takes place:

  > - Create instances of the following tools:

  >   - `_NodeClasses`

  >   - `Parser`

  >   - `Extractor`

  > - Call the `_init()` method of this call to perform the following tasks:

  >   - Set the module’s filepath and filename.

  >   - Call the following methods to prepare for analysis:

  >     - `_parse()`

  >     - `_extract()`

  >     - `_build()`

  Once complete, the module has been prepared for analysis and reporting.

  property ast_

    Public accessor to the module’s parsed syntax tree.

    Syntax tree parsing is provided by the `ast` builtin. This property is a direct accessor to the return value from the `ast.parse()` method.

  property classification

    Accessor to the module’s maximum severity classification.

  property code: StringIO

    Public accessor to the textual codebase.

    As the code is a stream object, the cursor (memory pointer) advances with each read access. Once exhausted, the code can be ‘rewound’ using the `rewind()` method.

    This property is an alias for the `badsnakes.libs.parser.Parser.code` property.

    Returns:

      The textual code as an `io.StringIO` object.

    Return type:

      io.StringIO

  property name: str

    Public accessor to the current Python module’s filename.

  property name_and_parent: str

    Public accessor to the module’s filename and parent directory.

    The logger and reporter use this property to display the module name and its parent directory, as this aids in clarity if a module name is used multiple times.

  property nodeclasses

    Public accessor to the AST node classes.

    Use this property to access the analyser(s) and results.

  property path: str

    Public accessor to the current Python module’s path.

  analyse()

    Call the `analyse` method for all of the node classes.

    A module is only analysed if 1) the module’s AST could be parsed and 2) if the `ast.body` list has more than 1 element.

    Once the analysis is complete, the module classification is set. The classification can be accessed through the `classification` property.

  display()

    Display the attributes extracted from the abstract syntax tree.

    Generally, this is used as a debugging mechanism and not used for production-based reporting.

    This method is an alias for the `badsnakes.libs.extractor.Extractor.display()` method.

  display_syntax_tree()

    Display the syntax tree, as provided by `ast`.

    Generally, this is used as a debugging mechanism and not used for production-based reporting.

    This method is an alias for the `badsnakes.libs.parser.Parser.display_syntax_tree()` method.

  rewind()

    Rewind the `code` text stream to be beginning.

    This method is an alias for the `badsnakes.libs.parser.Parser.rewind()` method.

  _build()

    Build the node classes object for this module.

    When this method is called, the extracted attributes from each AST node are stored into the `.items` attribute of the respective `nodeclasses` node subclass. Each subclass’ `.items` attribute will contain a list of `badsnakes.libs.containers` objects with the extracted attributes for analysis.

    Additionally, the attribute values for each node class are converted to lower case, for robust string matching.

    Node classes which are added:

    > - Argument

    > - Assignment

    > - Attribute

    > - Call

    > - Constant

    > - FunctionDef

    > - Import (and ImportFrom)

    > - CodeText

  _extract()

    Extract and store relevant attributes from a parsed AST.

  _init()

    Initialiser for this `Module` class’ instance.

    On initialisation, the following methods are called once the module’s filepath and filename have been set:

    > - `_parse()`

    > - `_extract()`

    > - `_build()`

  _parse()

    Parse a Python module into an abstract syntax tree.

  _set_classification()

    Set the severity classification for the module.

    Note

    A `filter` is used to remove any empty `.items` lists.

class badsnakes.libs.module._NodeClasses

  Bases: `object`

  An iterable class which contains the AST node classes.

  Each of the subclasses contains an `items` and `_analyser` attribute. The `.items` attribute contains the AST node classes which were parsed from the source code. The `._analyser` attribute holds the node-specific analyser class which contains a `.analyse` function to carry out the analysis.

  tolower()

    Convert specific container attributes to lower case.

    When container attributes are in lower case, this enables more robust string searches, and enables the `config.toml` file to contain only lower case strings, rather than several variations.

    The method containing the actual implementation is `badsnakes.libs.containers._NodeBase.tolower()`. This method is a simple wrapper to call this function on each node class.

class badsnakes.libs.module._NodeBase

  Bases: `object`

  Base class for all specialised AST node classes.

  These classes contain an `items` attribute which is a list holding the AST extraction containers for analysis, and the specialised AST node class analyser.

  The implementation for the analysers can be found in the `analysers` module.

  property analyser

    Public accessor to the node class’ analyser class.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

class badsnakes.libs.module._CodeText

  Bases: `_NodeBase`

  Specialised class for textual code analysis.

  analyse()

    Callable for running the analyser for the code text.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeArguments

  Bases: `_NodeBase`

  Specialised node class for AST Argument nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeAssignments

  Bases: `_NodeBase`

  Specialised node class for AST Assignment nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeAttributes

  Bases: `_NodeBase`

  Specialised node class for AST Attribute nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeCalls

  Bases: `_NodeBase`

  Specialised node class for AST Call nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeConstants

  Bases: `_NodeBase`

  Specialised node class for AST Constant nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeFunctionDefs

  Bases: `_NodeBase`

  Specialised node class for AST FunctionDef nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.

class badsnakes.libs.module._NodeImports

  Bases: `_NodeBase`

  Specialised node class for AST Import and ImportFrom nodes.

  analyse()

    Callable for running the analyser for the specific node class.

    The `items` attribute containing a list of AST node container objects is passed into the node-class-specific analyser by this method call.

  property analyser

    Public accessor to the node class’ analyser class.