A web-based random number generator built with FastAPI. It ensures fairness by picking numbers from a pre-defined pool and removing them until the pool is empty. It features a large, easy-to-read UI suitable for presentations or events.

Features

Two Draw Modes:
- Fair Mode (No Repeat): Each number is drawn only once from the specified range.
- Pure Random Mode: Numbers are drawn randomly and may repeat.
Repeat Detection: In Pure Random mode, a "Repeat!" badge appears if a number has been drawn before.
Auto Zero-padding: Numbers are automatically padded with leading zeros based on the maximum value (e.g., 001 to 100).
Bilingual Support: Supports both English and Traditional Chinese (Default: Traditional Chinese).
Large & Compact UI: Optimized for high visibility while remaining compact for presentation screens.
Smart Persistence: Remembers your range and mode settings even when resetting or toggling modes.
Process Management: Automatically closes existing instances on port 80 when starting to ensure a smooth launch.
Session-based: Keeps track of drawn numbers and remaining pool within the session.
Security: Uses cryptographically strong random numbers (Python's secrets module) and limits range to 10,000 to prevent OOM.
Fairness Verification: Includes a script to verify the uniform distribution of results.

Fairness Mechanism

This app ensures fairness through two layers:

Logical Fairness (Pool-based): Instead of just picking a random number, the app creates a "pool" containing all numbers in the specified range. When a number is picked, it is removed from the pool. This guarantees that every number is drawn exactly once, and no number is repeated or skipped.
Statistical Fairness (Cryptographic Randomness):
- Desktop App: Uses Python's secrets module (secrets.randbelow) to select the index from the pool. Unlike the standard random module, secrets is designed for cryptography and provides high-quality randomness.
- Web App (GitHub Pages): Uses the browser's crypto.getRandomValues() API, which provides the same level of cryptographic security as the Python version, ensuring high-quality randomness in a client-side environment.

You can run the verification script yourself to see the distribution:

uv run python tests/verify_fairness.py

🌐 Live Demo (GitHub Pages)

You can run this app directly in your browser without installing anything! 👉 Click here to open the Web App

Quick Start (Executable)

If you don't want to install Python, you can download the latest version from GitHub Releases.

Download RandomPicker.exe.
Verify file integrity immediately after download:
Use Windows built-in certutil to generate a CRC/SHA256 hash:
```
certutil -hashfile RandomPicker.exe SHA256
```
Compare the output with the hash provided on GitHub Releases.
⚠️ If the hash does not match, do NOT run the program. Delete or re-download the file to ensure safety.
Double-click to run it.
Open your browser and navigate to http://127.0.0.1.

Installation (From Source)

Requirement: Python 3.13+ and uv.
Install dependencies:
```
uv sync
```

Usage (From Source)

Run the application:
```
uv run python exec.py
```
Open your browser and navigate to http://127.0.0.1.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

繁體中文

說明

一個基於 FastAPI 開發的網頁版隨機抽號器。它透過從預定義的池中抽取號碼並移除，直到所有號碼都被抽完，從而確保公平性。具備超大字體介面，非常適合在簡報、抽獎或各種活動中使用。

功能特點

雙重抽選模式：
- 公平模式 (不重複)：確保在指定範圍內，每個數字只會被抽中一次。
- 純隨機模式：每次抽取均為獨立隨機，數字可能會重複出現。
重複偵測：在「純隨機模式」下，若抽中已出現過的號碼，會顯示「重複！」標籤提示。
自動補零：根據最大值自動補齊前導零（例如：範圍 1-100 時顯示 001）。
雙語支持：支援英文與繁體中文（預設為繁體中文）。
清晰緊緻 UI：針對高能見度優化的超大字體，同時保持版面緊緻，適配各種簡報螢幕。
智慧設定記憶：在重置範圍或切換模式時，系統會自動保留您的輸入數值與模式選擇。
行程自動清理：啟動時會自動偵測並關閉舊有佔用 80 端口的行程，確保順利執行。
會話管理：在瀏覽器會話中記錄已抽出的號碼與剩餘數量。
安全性：使用密碼學等級的隨機數生成器（Python 的 secrets 模組），並限制範圍上限為 10,000 以防止記憶體溢出。
公平性驗證：內建驗證腳本，可測試結果的均勻分佈。

公平性機制

本應用程式透過兩個層面確保公平性：

邏輯公平（基於號碼池）：程式並非單純隨機抽號，而是先建立一個包含範圍內所有號碼的「號碼池」。每當抽到一個號碼，就會將其從池中移除。這保證了每個號碼在一個循環內只會被抽中一次，不會重複也不會遺漏。
統計公平（密碼學等級隨機性）：
- 電腦版 (Desktop App)：程式使用 Python 的 secrets 模組 (secrets.randbelow) 來從池中挑選索引。與標準的 random 模組不同，secrets 模組是專為密碼學設計的，提供高品質且難以預測的隨機性。
- 網頁版 (Web App)：使用瀏覽器的 crypto.getRandomValues() API。這同樣是密碼學等級的強隨機數來源，與電腦版具有相同的安全性與不可預測性。

您可以自行執行驗證腳本來查看分佈情況：

uv run python tests/verify_fairness.py

🌐 線上試用 (GitHub Pages)

您可以直接在瀏覽器中執行此應用程式，無需安裝任何內容！ 👉 點此開啟網頁版應用程式

快速開始 (執行檔)

如果您不想安裝 Python，可以從 GitHub Releases 下載最新版本。

下載 RandomPicker.exe。
檢查檔案完整性：
使用 Windows 內建的 certutil 生成 CRC/SHA256 雜湊值：
```
certutil -hashfile RandomPicker.exe SHA256
```
將輸出與 GitHub Releases下載檔案時所提供的雜湊值比對。
⚠️ 如果雜湊值不一致，請不要執行程式。 建議刪除或重新下載檔案，以確保安全。
雙擊執行該程式。
開啟瀏覽器並造訪 http://127.0.0.1。

安裝步驟 (從原始碼)

需求：Python 3.13+ 以及 uv。
安裝依賴：
```
uv sync
```

使用方式 (從原始碼)

啟動應用程式：
```
uv run python exec.py
```
開啟瀏覽器並造訪 http://127.0.0.1。

授權條款

本專案採用 Apache License 2.0 授權。詳情請參閱 LICENSE 檔案。

README.md Unescape Escape

Fair Random Number Generator | 公平隨機抽號器

English

Description