Metadata-Version: 2.4
Name: flashexam
Version: 2.0.8
Summary: Intelligent Online Examination System with AI Grading
Author: FlashExam Contributors
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/cycleuser/flashexam
Project-URL: Repository, https://github.com/cycleuser/flashexam
Project-URL: Issues, https://github.com/cycleuser/flashexam/issues
Keywords: exam,education,ai-grading,flask,online-exam,qwen
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.0
Requires-Dist: flask-login>=0.6.0
Requires-Dist: flask-session>=0.5.0
Requires-Dist: werkzeug>=3.0
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: xlrd>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: requests>=2.31
Requires-Dist: chardet>=5.0
Requires-Dist: psutil>=5.9
Requires-Dist: waitress>=2.1
Requires-Dist: jieba>=0.42
Requires-Dist: python-dateutil>=2.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# FlashExam

[![PyPI version](https://badge.fury.io/py/flashexam.svg)](https://badge.fury.io/py/flashexam)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![macOS](https://img.shields.io/badge/macOS-supported-green.svg)]()
[![Linux](https://img.shields.io/badge/Linux-supported-green.svg)]()
[![Windows](https://img.shields.io/badge/Windows-supported-green.svg)]()

**English** | [中文](README_CN.md)

---

## FlashExam - Intelligent Online Examination System with AI Grading

A Flask-based intelligent online examination system with AI grading support, compatible with macOS, Linux, and Windows.

### Features

- **Multiple Question Types**: Multiple choice, true/false, short answer, fill-in-the-blank, programming, code execution
- **AI Intelligent Grading**: Subjective question grading based on Qwen model
- **Code Execution**: Online execution support for Python, C, Java, Shell, JavaScript
- **Reading Comprehension**: TOEFL-style reading comprehension exams
- **Real-time Monitoring**: Tab switch detection and anti-cheating features
- **Batch Import**: Import questions and students via Excel/CSV
- **Admin Panel**: Teacher account management and system configuration
- **Cross-platform**: Supports macOS, Linux, Windows
- **Dark/Light Theme**: Elegant theme system with automatic system preference detection
- **Port Conflict Handling**: Automatic detection and resolution of port conflicts

### Quick Start

#### Installation

```bash
# Install from PyPI
pip install flashexam

# Or install from source
git clone https://github.com/cycleuser/flashexam.git
cd flashexam
pip install -e .
```

#### Initialize Database

```bash
flashexam --init-db
```

#### Start Server

```bash
# Development mode (default)
flashexam

# Production mode
flashexam --mode prod

# High-performance mode
flashexam --mode high-perf --workers 8

# Custom port
flashexam --port 8080

# Force start (kill process using the port)
flashexam --force
```

#### Access the System

- Homepage: http://localhost:5000
- Teacher Portal: http://localhost:5000/teacher
- Student Portal: http://localhost:5000/student
- Admin Panel: http://localhost:5000/admin

First startup requires setting up an administrator account.

### Command Line Arguments

```
flashexam [options]

Options:
  --mode {dev,prod,high-perf}  Run mode (default: dev)
  --host HOST                  Bind address (default: 0.0.0.0)
  --port PORT                  Port number (default: 5000)
  --workers N                  Worker processes (default: 4)
  --init-db                    Initialize database
  --force                      Force start (kill process using port)
  --version                    Show version information
```

### Question Import

Supports importing questions from Excel (.xlsx) and CSV files.

#### CSV Format

```csv
Number,question_type,question_text,option_A,option_B,option_C,option_D,correct_answer,score,difficulty,subject
1,choice,What is Python?,A programming language,A snake,Both A and B,None of the above,A,5,2,Computer Science
2,judge,Python is a compiled language,true,false,,false,3,1,Computer Science
```

#### Excel Format

| Number | Material | question_type | question_text | option_A | option_B | correct_answer | score | subject |
|--------|----------|---------------|---------------|----------|----------|----------------|-------|---------|
| 1 | Reading passage text... | choice | Question text | Option A | Option B | A | 5 | English |

### Project Structure

```
flashexam/
├── __init__.py          # Application factory
├── cli.py               # CLI entry point
├── database.py          # Database operations
├── teacher.py           # Teacher endpoints
├── student.py           # Student endpoints
├── auth.py              # Authentication module
├── admin.py             # Admin module
├── api.py               # API endpoints
├── code_executor.py     # Code executor
├── smart_import_manager.py  # Question import
├── models.py            # Data models
├── utils.py             # Utility functions
├── templates/           # HTML templates
├── static/              # Static resources
│   ├── css/
│   │   ├── themes.css   # Dark/light theme
│   │   └── app.css      # Custom styles
│   └── js/
└── storage/             # Data storage (not in repo)
```

### Development

#### Install Development Dependencies

```bash
pip install -e ".[dev]"
```

#### Run Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=flashexam

# Run import tests
python test_import.py
```

#### Code Style

```bash
ruff check .
ruff format .
```

### Publish to PyPI

```bash
# Linux/macOS
./upload_pypi.sh

# Windows
upload_pypi.bat
```

### Tech Stack

- **Backend**: Flask, SQLite, Flask-Login, Flask-Session
- **Frontend**: Bootstrap 5, jQuery, Bootstrap Icons
- **AI**: PyTorch, Transformers, Qwen (optional)
- **Server**: Waitress (production)

### Security Notes

- Database files are excluded from version control
- Session files are excluded from version control
- No sensitive data is uploaded to GitHub or PyPI
- Secret keys should be set via environment variables in production

### License

This project is licensed under the [GNU General Public License v3.0](LICENSE).

### Contributing

Issues and Pull Requests are welcome!

1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Create a Pull Request

### Author

FlashExam Contributors

### Links

- [GitHub](https://github.com/cycleuser/flashexam)
- [PyPI](https://pypi.org/project/flashexam/)
- [Issues](https://github.com/cycleuser/flashexam/issues)
