138 lines
4.0 KiB
Markdown
138 lines
4.0 KiB
Markdown
# CustomBingo
|
|
|
|
CustomBingo is a Python application that reads a spreadsheet with 5 columns (B, I, N, G, O) and generates user-specified number of randomized BINGO cards in PDF format for easy printing. Each box in the grid will automatically size the font to fit and center the text.
|
|
|
|
## Features
|
|
|
|
- Read data from CSV or Excel files
|
|
- Generate randomized BINGO cards from input data
|
|
- Export cards to PDF format with proper formatting
|
|
- Auto-fit text in grid cells with horizontal and vertical centering
|
|
- Support for multi-line text in cells
|
|
- Customizable number of cards to generate
|
|
- Graphical User Interface (GUI) for easy operation
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://gitea.conlon.fun/andy/CustomBingo.git
|
|
cd CustomBingo
|
|
```
|
|
|
|
2. Install dependencies using `uv`:
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
3. Install in development mode:
|
|
```bash
|
|
uv pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Command Line Interface
|
|
|
|
The application provides a command-line interface for generating BINGO cards:
|
|
|
|
```bash
|
|
uv run python src/custom_bingo/main.py --input-file <input_file> --output-file <output_file> [OPTIONS]
|
|
```
|
|
|
|
### Options
|
|
|
|
- `-i, --input-file PATH`: Input spreadsheet file (Excel/CSV) with B, I, N, G, O columns [required]
|
|
- `-o, --output-file PATH`: Output PDF file for the BINGO cards [required]
|
|
- `-n, --number-of-cards INTEGER`: Number of BINGO cards to generate (default: 1)
|
|
- `-t, --title TEXT`: Title text to display at the top of the card (default: BINGO)
|
|
- `-s, --sub-headers TEXT`: Comma-separated sub-headers for each column (e.g., "Category1,Category2,Category3,Category4,Category5")
|
|
|
|
### Example
|
|
|
|
```bash
|
|
# Generate a single BINGO card
|
|
uv run python src/custom_bingo/main.py -i data/ChristmasSongsBingo.csv -o output.pdf
|
|
|
|
# Generate multiple BINGO cards
|
|
uv run python src/custom_bingo/main.py -i data/ChristmasSongsBingo.csv -o output.pdf -n 5
|
|
|
|
# Generate a BINGO card with custom title and sub-headers
|
|
uv run python src/custom_bingo/main.py -i data/ChristmasSongsBingo.csv -o output.pdf -t "Holiday Music Bingo" -s "Traditional,Upbeat,Holy,Classic,Festive"
|
|
|
|
## GUI Usage
|
|
|
|
The application also includes a graphical user interface for easier operation:
|
|
|
|
```bash
|
|
# Run the GUI application directly
|
|
python -m src.custom_bingo.gui
|
|
|
|
# Or using the installed command (after installation)
|
|
custombingo-gui
|
|
```
|
|
|
|
The GUI provides input fields for:
|
|
- Card title
|
|
- 5 column headers (B, I, N, G, O)
|
|
- Source spreadsheet file
|
|
- Number of cards to generate
|
|
- Output PDF location
|
|
|
|
Click the "Generate PDF" button to create your BINGO cards.
|
|
```
|
|
|
|
## Input Format
|
|
|
|
The input spreadsheet must have exactly 5 columns labeled B, I, N, G, O. Each column represents a BINGO column:
|
|
|
|
- Column B: Values from 1-15
|
|
- Column I: Values from 16-30
|
|
- Column N: Values from 31-45 (with free space in the center)
|
|
- Column G: Values from 46-60
|
|
- Column O: Values from 61-75
|
|
|
|
The application supports both CSV and Excel (.xlsx, .xls) formats.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
CustomBingo/
|
|
├── src/
|
|
│ └── custom_bingo/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # Command-line interface
|
|
│ ├── card_generator.py # Logic to generate BINGO cards
|
|
│ ├── spreadsheet_reader.py # Reading input files
|
|
│ └── pdf_generator.py # PDF export functionality
|
|
├── tests/ # Unit and integration tests
|
|
├── data/ # Input data files (git-ignored)
|
|
├── pyproject.toml # Project configuration
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Development
|
|
|
|
1. Set up the development environment:
|
|
```bash
|
|
uv sync
|
|
uv pip install -e .
|
|
```
|
|
|
|
2. Run tests:
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
3. Run with a custom data file:
|
|
```bash
|
|
uv run python src/custom_bingo/main.py -i path/to/your/data.csv -o output.pdf -n 3
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- Python 3.9+
|
|
- pandas: For reading spreadsheet files
|
|
- reportlab: For PDF generation
|
|
- click: For command-line interface
|
|
- pytest: For testing (development) |