Data Structure Sustainability Analyser

This repository contains the implementation of a static analysis tool developed as part of a final-year dissertation project. The tool detects inefficient use of data structures in Python code and provides suggestions to improve performance and computational sustainability. It includes both a command-line interface (CLI) and a web-based interface built with Flask.

Project Overview

Suboptimal data structure usage in Python can significantly affect software performance and maintainability. This project introduces a tool that statically analyses Python code using the Abstract Syntax Tree (AST), detects inefficient patterns, and suggests more sustainable alternatives. The system supports:

• Detection of inefficient data structure patterns (e.g. list for membership checks)
• Rule-based suggestions with code examples
• Automated source code fixing via AST rewriting
• Generation of Markdown and CSV reports
• Visual analytics through charts
• Web-based interactive interface

Project Structure

File/Directory	Description
analyser.py	Performs AST-based analysis to detect data structure patterns.
rules.py	Defines the conditions and logic for optimisation suggestions.
suggestor.py	Applies rules to the analysed code structures.
auto_fixer.py	Rewrites inefficient code segments into optimised forms.
cli.py	Command-line interface to run analysis and generate reports.
batch_run.py	Runs analysis in batch mode and verifies outputs.
generate_chart.py	Produces charts from the usage log.
report_generator.py	Builds a Markdown report summarising suggestions.
usage_data.py	Logs analysis metadata and exports to CSV.
app.py	Web server (Flask) providing the graphical interface.
index.html, script.js, style.css	Frontend files for the web interface.
examples/	Test examples with expected reports.
user_submissions/	Folder for uploaded user files (used during batch mode).

Setup Instructions

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation

Install the required dependencies by running:

pip install flask pandas matplotlib astor pygments

Note: You may use a virtual environment if preferred.

Running the Tool

1. Running the CLI (Command-Line Interface)

Analyse a Python file and generate suggestions:

python cli.py --input path/to/file.py --report report.md --score --verbose

Optional CLI flags:

• --report : Save Markdown report to specified path
• --score : Display sustainability score (0–100)
• --verbose : Print suggestions and fixes in the console
• --export-csv : Save analysis and suggestions as CSV
• --auto-fix : Automatically rewrite inefficient code (saves a new _autofixed.py version)

Example:

python cli.py --input examples/user_submissions/example1.py --report my_report.md --score --auto-fix

2. Running the Web App (Graphical Interface)

Start the web server locally:

python app.py

Then visit in your browser:

http://127.0.0.1:5000

You can upload .py files or paste code into the editor to receive suggestions, fix code, view charts, and download results.

3. Running Batch Testing

To analyse all files in the user_submissions/ directory and compare results to expected reports:

python batch_run.py

To update the expected reports (for regeneration):

python batch_run.py --refresh

4. Running Chart Generation (Standalone)

If you have a populated sustainability_log.csv, you can generate charts using:

python cli.py --chart

or directly:

python generate_chart.py

Charts will be saved in:

web_gui/static/

Outputs

• Markdown Report: Human-readable summary of each suggestion
• CSV Log: Structured data for usage tracking and charting
• Score (0–100): Penalised based on number of suggestions
• Auto-fixed Code: Optimised version of source code (if applicable)
• Charts: Visualisations of structure usage and suggestion types

Testing and Evaluation

This tool has been evaluated via:

• Unit testing of each module
• Batch testing with known inputs and expected reports
• Manual inspection of Markdown reports and auto-fix results

Test examples and expected outputs are located in the examples/ directory.

Academic Context

This work investigates automated detection and remediation of inefficient Python data structures as part of sustainable software practices. It draws from static code analysis, compiler theory, and software engineering education to provide an accessible and impactful tool for developers and students alike.

Submission Information

This submission includes:

• All developed Python source code files
• A README file detailing build and run instructions
• A working web interface (via Flask)
• CLI tooling with batch testing
• Test inputs and reports in the examples/ directory

All required content has been zipped for submission and is under 40MB as required.

Author

[Kabir Suri]
[K21082509]