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 theModule.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:
- 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 ofbadsnakes.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:
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:
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 theast.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 respectivenodeclasses
node subclass. Each subclass’.items
attribute will contain a list ofbadsnakes.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
- 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.
- 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.