code-explainer 0.1.0

A tool for analyzing and explaining Python code using AI

Python Code Explainer with Llama

A powerful tool that analyzes Python code and generates comprehensive documentation and explanations using the Llama language model. Available both as a Streamlit web application and a command-line interface.

✨ Features

• 🔍 Automatic extraction of functions, classes, and methods from Python code
• 📝 Detailed code analysis including arguments, return values, and docstrings
• 🤖 AI-powered non-technical explanations using Llama model
• 🖥️ Multiple interfaces: Web UI and Command Line
• 📥 Export analysis as well-formatted Word documents
• 🔄 GitHub Action for automated documentation generation
• 🧩 Modular architecture for easy extension

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Ollama server running locally (with Llama model installed)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/python-code-explainer.git
   cd python-code-explainer
   

2. Install the package in development mode:

   pip install -e .
   

   Or install the required packages directly:

   pip install -r requirements.txt
   

3. Set up Ollama:

   # Install Ollama (if not already installed)
   # Visit https://ollama.ai for installation instructions
   
   # Start Ollama server in one terminal
   ollama serve
   
   # In another terminal, pull the Llama model
   ollama pull llama2
   

📖 Usage

Web Interface

1. Start the Streamlit application:

   streamlit run app.py
   

   Or:

   python -m src.code_explainer.cli web
   

2. Open your web browser to http://localhost:8501

3. Upload a Python file and explore the analysis

Command Line Interface

Analyze a Python file:

python -m src.code_explainer.cli analyze path/to/your/file.py

Generate documentation:

python -m src.code_explainer.cli document path/to/your/file.py --output docs/

🛠️ How It Works

1. Code Analysis: The tool parses Python files to extract:

   • Function and class definitions
   • Method signatures with arguments and return types
   • Docstrings and inline comments
   • Import statements and module-level documentation

2. AI Integration: The extracted information is processed by the Llama model to generate:

   • Clear, non-technical explanations
   • Usage examples
   • Documentation in multiple formats

3. Output Generation: Results can be:

   • Viewed in the web interface
   • Exported as Word documents
   • Generated automatically via GitHub Actions

📦 Project Structure

.
├── src/
│   ├── code_explainer/
│   │   ├── __init__.py
│   │   ├── cli.py          # Command line interface
│   │   ├── code_analyzer.py # Core code analysis logic
│   │   ├── document_generator.py # Document generation
│   │   └── llm_integration.py # Llama model integration
│   ├── action.py          # GitHub Action entry point
│   └── analyzer.py        # Core analysis functionality
├── .github/workflows/     # GitHub Actions workflows
├── app.py                 # Streamlit web app
├── main.py                # Legacy entry point
├── requirements.txt       # Python dependencies
└── setup.py               # Package configuration

GitHub Actions

This project includes a GitHub Actions workflow (.github/workflows/code_analysis.yml) that:

1. Runs tests on push and pull requests
2. Performs code analysis using the Python Code Explainer
3. Generates documentation in Word format
4. Automatically commits and pushes generated documentation to the repository

Workflow Triggers

• Push to main branch: Runs tests, performs analysis, and updates documentation
• Pull requests: Runs tests and performs analysis (does not update documentation)
• Manual trigger: Can be manually triggered from the Actions tab

Generated Documentation

When the workflow runs on the main branch, it will:

1. Generate a Word document (docs/code_analysis_YYYYMMDD_HHMMSS.docx)
2. Include a summary of all analyzed code elements
3. Provide detailed explanations of the code structure
4. Automatically commit and push the generated documentation

Required Permissions

The workflow requires the following permissions:

• contents: write - To commit and push generated documentation
• pull-requests: write - To update pull request statuses
• statuses: write - To update commit statuses

These permissions are automatically provided by the default GITHUB_TOKEN. No additional configuration is needed for public repositories. For private repositories, ensure the workflow has the necessary permissions in your repository settings.

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork and clone the repository
2. Set up a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -e .[dev]
   

3. Make your changes and run tests
4. Submit a pull request

📧 Contact

For any questions or feedback, please open an issue on the GitHub repository.