All the core logic for playing/simulating the popular game 'Housie' (also known as 'Bingo' or 'Tambola')
Provides all the core models and logic required to simulate and play the classic game 'Housie' (also known as 'Bingo' or 'Tambola').
All the code is well segregated, so should be a breeze if you want to reuse and build upon any of the components.
Also provided is a simple terminal-driven menu that let's you generate tickets and play the game, if that's all you want to do.
Core Features Provided:
- Generating Housie Tickets to play the game (Ticket format is accurate! Numbers are exactly where they are supposed to be).
- Maintaining state of the Housie board and displaying the board visually in terminal.
- Randomly picking numbers on the board, for when you're hosting a game with friends.
- Auto-marking the numbers on your tickets, for when you are following a game hosted by someone else.
Installation and Setup
- Make sure you have python 3 installed. (If not you can get it here -> https://www.python.org/downloads/)
- Then install housie using pip:
pip install --upgrade housie
If you are just looking to play the game, it's pretty simple. Just open terminal and run the following command.
python -m housie.game
This will start up the game and show you the main menu.
You have a few options here like: Host a game, Generate tickets, Follow a game. Each of these is explained in the following section.
This section explains each of the features present in the main menu of the game.
Host a New Game
- This mode displays the housie board on the screen and lets you randomly pick numbers.
- This mode is for when you are playing a game with friends.
- The board is constantly updated with the selected numbers.
- Before using this mode, you may want to generate and distribute tickets among your friends.
- As the name suggests, this mode allows you to generate tickets.
- You specify the names of players and the number of tickets per player, and the program generates and prints out the tickets on the screen.
- The generated tickets are also stored in
data/generated_tickets.jsonin the current directory from which you ran the game.
Follow a Game
This mode was built as a convenience mode for when playing games that are hosted by someone else. It auto-marks your tickets as you enter the numbers called out. (NOTE: It's not as fun to play housie this way xD but it is helpful if you're playing with multiple tickets)
Before starting this mode, you need to create a json file representing the tickets you want to use for the game. You must name your file
followed_tickets.json. Use the sample file as a reference. Create a folder named
datain the current directory from where you intend to run the game and place your file into that folder. These steps are important because the program expects to find the
followed_tickets.jsonfile inside a
datafolder in the current directory.
Then start up this mode. You will see the housie board displayed along with your tickets.
Enter the numbers called out by the host and these numbers will be automatically crossed out in your tickets.
Note: This mode persists game state (i.e. even if you shut the program suddenly and start up again, you can continue where you left off). If you want to start a new followed game, just delete the
Using the Underlying models and modules
This section will provide some details on accessing and manipulating the underlying models and modules in order to use them in your own projects.
There are only two core models involved:
This model is for representing and manipulating the state of the housie board. It stores which numbers have been called out, and which are left in the pool. It provides methods to randomly or manually pick numbers from the remaining pool, list the last 5 numbers that were picked, and also exposes a convenience method to display the board visually in the terminal.
It can be imported as shown below:
from housie import Board
You can then create and use it as follows:
board = Board() # Initialize an empty board board.pick_next() # Picks and returns a number at random and updates the state of the board board.display_board() # Display the board visually in the terminal board.last_5_selected() # Returns a list of the last 5 numbers that were selected
You can also initialize the board with some numbers already called out:
board = Board([1,22,34,55,64,32]) # Initialize board with some numbers called out
You can also manually select numbers on the board
board.pick_manual(5) # Adds 5 to the pool of selected numbers
This model is for representing and manipulating the state of a housie ticket. Stores the 15 numbers that make up the ticket, along with those numbers which have been marked/crossed out. Provides methods to mark numbers and to display the ticket visually in the terminal.
It can be imported from
housie.models as shown below:
from housie.models import Ticket
You can create a Ticket in a couple of ways:
1. Manually by passing in the 15 numbers row-wise to the Ticket constructor. (Although this is not recommended, as
there are very specific rules for selecting and placing the numbers in each of the rows/columns)
ticket = Ticket([[11, 24, 48, 54, 82], [14, 32, 56, 69, 86], [2, 26, 36, 59, 73]])
2. You could rather use the generate_ticket() function to create your tickets. This function adheres
to all the rules for generating tickets and creates a completely random ticket for you each time you call it.
from housie import generate_ticket ticket = generate_ticket()
3. You could also use the load_tickets() function to load your tickets from a json file (provided they are in the
correct format. For a sample file, refer here). This function returns a
dictionary in which the key is the name of the user and the value is the list of tickets belonging to that user.
from housie import load_tickets ticket_data = load_tickets('ticket_data.json') for name, tickets in ticket_data.items(): print(name) for ticket in tickets: print(ticket.display_ticket)
You can cross out numbers in your tickets:
And display your ticket:
Extending and Adding new functionality
The purpose of this package is to provide the core models and logic required to play/simulate the game. Keeping this in mind, I have tried to segregate the code as per functionality and reusability.
Feel free to add upon this base layer.
Aaron Alphonso (https://github.com/aaronalphonso) Email: firstname.lastname@example.org
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.