https://github.com/karped1em/pickme
A lightweight desktop app for randomly picking students and managing cooldowns
https://github.com/karped1em/pickme
flask python webview2
Last synced: about 2 months ago
JSON representation
A lightweight desktop app for randomly picking students and managing cooldowns
- Host: GitHub
- URL: https://github.com/karped1em/pickme
- Owner: KARPED1EM
- License: mit
- Created: 2025-10-15T06:04:44.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-24T12:18:03.000Z (8 months ago)
- Last Synced: 2025-10-24T12:24:53.941Z (8 months ago)
- Topics: flask, python, webview2
- Language: JavaScript
- Homepage:
- Size: 340 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PickMe
English | [δΈζ](README_zh.md)
PickMe is a random name picker tool built with FastAPI and modern web frontend. It can run as a desktop application (using WebView2) or in server mode.
## Features
- π― **Random Selection**: Pick individual students or groups with configurable cooldown periods to avoid frequent repetitions
- ποΈ **Classroom Management**: Create, switch, and delete classrooms with complete data isolation and drag-to-reorder support
- πΎ **Unified Persistence**: Desktop mode writes a single JSON file per user; server mode keeps per-visitor UUID JSON files under the server data directory while the browser only caches the latest payload
- πͺ **User-Friendly Interface**: Context menus, cooldown queue, pick history, and more for easy interaction
## Platform Support
**Official Support**: Windows (x86, x64, ARM64)
> **Note**: This application officially targets Windows across multiple architectures. Linux and macOS have not been adapted, and compatibility is unknown.
## Running the Application
### 1. Desktop Mode (WebView2)
```bash
python scripts/desktop.pyw
```
On first launch, data files will be created in `~/.pickme` (on Windows: `%USERPROFILE%\.pickme`) and the WebView2 interface will open automatically. If WebView2 Runtime is not installed, the application will prompt you to download it from the Microsoft official website.
### 2. Server / Development Mode
```bash
python -m scripts.serve --host 0.0.0.0 --port 8000
```
By default, uses server storage mode where each visitor receives a UUID backed by a JSON file on the server (e.g. `/users/{uuid}.pickme.v2.json`). The browser keeps a short-lived cached payload locally for faster startup. Available parameters:
| Parameter | Description |
| ---- | ---- |
| `--app-data-dir` | Directory used to store application data. |
| `--reload` | Enable FastAPI hot reload for development |
Windows users can also run `scripts\serve.bat` for quick startup.
## Classrooms & Data Storage
- First run includes a default classroom **"ζε·ι»ι©¬ AI Python ε°±δΈ 3ζ"** with sample student list for immediate testing.
- **Desktop Mode**: All data is stored in `~/.pickme/local.pickme.v2.json` (on Windows: `%USERPROFILE%\.pickme\local.pickme.v2.json`), a single unified JSON file that contains preferences, runtime state, classes, and students.
- **Server Mode**: Each visitor receives a UUID on first load; the backend stores the unified JSON at `~/.pickme/users/{uuid}.pickme.v2.json` (on Windows: `%USERPROFILE%\.pickme\users\{uuid}.pickme.v2.json`). The browser keeps only a refreshed runtime cache (`pickme::uuid` and `pickme::data`) to stay in sync.
- Each classroom keeps its student list, pick history, and cooldown state inside that unified file; updates persist automatically after every action.
## Building Single-File EXE
```bash
pyinstaller pickme.spec
```
The generated executable will be located at `dist/PickMe.exe`. The GitHub Actions workflow `.github/workflows/build-and-release.yml` is configured to build for x86, x64, and ARM64 architectures.
## Project Structure
```txt
scripts/desktop.pyw # WebView2 wrapper entry point (desktop mode)
scripts/serve.py # FastAPI server startup script
app/ # FastAPI application, templates, and static resources
app/metadata.py # Application metadata
```