Ticket Distributor — Exam Question Allocation Tool

Overview

This project is a lightweight desktop application designed to solve a common student‑related task: fair distribution of exam questions (or any numbered items) among a group of students. It ensures that each student receives an equal number of tickets, with at most one student getting one extra ticket when the total is not evenly divisible.

The application was built for personal educational use, but it demonstrates a complete GUI workflow: manual input, file import, automatic distribution, and export of results.

Key goal: Provide a simple, random, and fair allocation mechanism with a clean user interface.

---

Project Highlights

• Distributes tickets (numbered from 1 to N) among an arbitrary list of students.
• Supports both manual entry and batch import from CSV or Excel files.
• Uses random shuffling to avoid any ordering bias.
• Optionally saves the final distribution to an Excel file (.xlsx) for reporting.
• Built with customtkinter for a modern, dark‑mode graphical interface.
• Designed as a modular Python project with clear separation of concerns.

---

Repository Contents

ticket-distributor/
│
├── distributor.py          # Core distribution logic (TicketDistributor class)
├── file_handler.py         # File I/O: load students from CSV/Excel, save results
├── gui.py                  # Main GUI application (customtkinter)
├── main.py                 # Entry point
├── icon.ico                # Application icon (optional)
├── example.png             # Screenshot of the running GUI
├── README.md               # This file
├── .gitignore
└── __pycache__/            # Compiled Python cache (ignored)

---

Features

• Flexible input methods

  • Type student names directly into a text area (one per line).
  • Load a list from a .csv or .xlsx file (first column, optional header row).

• Fair random distribution

  • All tickets are shuffled and distributed one by one.
  • Each student receives base = tickets // num_students tickets.
  • The first extra = tickets % num_students students (randomly chosen) receive one additional ticket.

• Export results

  • Save the allocation table as an Excel file (.xlsx) for printing or further processing.

• Modern GUI

  • Dark theme with intuitive controls (segmented buttons, checkboxes, scrollable result area).
  • Keyboard shortcuts: Ctrl+A (select all), Ctrl+X (cut), Ctrl+V (paste) in the manual input field.

• Lightweight packaging

  • Uses Python’s built‑in csv module for reading CSV files instead of heavier libraries, reducing the final executable size when compiled with tools like PyInstaller.

---

How It Works

1. User specifies the total number of tickets and the list of students (either by typing or loading a file).
2. The application shuffles all ticket numbers (1 to N) randomly.
3. It then iterates over the students, giving each the base number of tickets.
4. A random subset of students (size = N mod number_of_students) gets one extra ticket each.
5. The result is displayed in a scrollable table and optionally saved to an Excel file.

The core logic is isolated in distributor.py and is independent of the GUI, making it reusable for other front‑ends or batch scripts.

---

Technologies Used

• Python 3 – core language
• customtkinter – modern GUI framework (dark mode support)
• openpyxl – read/write Excel files (.xlsx)
• csv – built‑in module for lightweight CSV handling
• random – shuffling and sampling
• pathlib – cross‑platform path management

---

Skills Demonstrated

GUI Development

• Building interactive desktop applications with customtkinter.
• Handling user events, dynamic visibility of widgets, and keyboard shortcuts.
• Designing a responsive layout with grid and pack managers.

Software Architecture

• Separation of concerns: business logic (distributor), data access (file_handler), and presentation (gui).
• Use of static methods for utility functions.
• Error handling and user feedback via message boxes.

File Processing

• Reading and writing CSV and Excel files.
• Parsing structured data (header detection, column extraction).
• Cross‑format support (.csv, .xlsx).

Algorithm Design

• Implementing a fair distribution algorithm with random assignment.
• Managing edge cases: empty student list, zero tickets, uneven division.

Packaging & Distribution

• Consideration of executable size by using lightweight modules (csv instead of pandas, etc.).

---

Screenshots

Below is the main window of the application:

The interface allows you to:

• Enter the total number of tickets.
• Switch between manual input and file loading.
• Enable or disable file export.
• View the distribution results instantly.

---

How to Run

1. Clone the repository.
2. Install dependencies:

   pip install customtkinter openpyxl

3. Run the application:

   python main.py

Note: The application is written for Python 3.7+ and has been tested on Windows.

---

Example Use Case

A lecturer has 10 exam questions and 3 students.
The application will:

• Randomly assign tickets to each student.
• Each student gets 10 // 3 = 3 tickets.
• 10 % 3 = 1 student will receive one additional ticket (4 instead of 3).
• The final distribution is displayed and may be saved as an Excel table.

---

Key Takeaways

• Modular design makes the code easy to maintain and extend (e.g., adding support for other file formats, different distribution rules, or a web interface).
• User‑centered GUI simplifies a repetitive task, reducing manual errors and saving time.
• Lightweight implementation demonstrates awareness of deployment constraints (e.g., executable size).
• The project is a practical example of combining file handling, algorithm implementation, and desktop GUI development in Python.

---

Future Improvements

• Add support for custom ticket labels (not just numbers).
• Enable importing students from a plain text file (one per line).
• Allow the user to manually adjust the random seed for reproducible distributions.
• Provide a “print” or “copy to clipboard” feature.

---

License

This project is open‑source and free to use for educational and personal purposes.