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)[source]

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()[source]

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()[source]

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()[source]

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()[source]

Rewind the code text stream to be beginning.

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

_build()[source]

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()[source]: Extract and store relevant attributes from a parsed AST.

_init()[source]

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()[source]: Parse a Python module into an abstract syntax tree.

_set_classification()[source]: Set the severity classification for the module.

Note

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

class badsnakes.libs.module._NodeClasses[source]

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()[source]

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[source]

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()[source]

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[source]

Bases: _NodeBase

Specialised class for textual code analysis.

analyse()[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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.