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

Clone the repository:

git clone https://gitea.conlon.fun/andy/CustomBingo.git
cd CustomBingo

Install dependencies using uv:
```
uv sync
```
Install in development mode:
```
uv pip install -e .
```

Usage

Command Line Interface

The application provides a command-line interface for generating BINGO cards:

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

# 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 .

Run tests:
```
uv run pytest
```

Run with a custom data file:

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)

4.0 KiB Raw Permalink Blame History