Explore the code

To explore the code repository it is best if you install the sources as editable. This means you can use the application as if it were installed normally but you can change the code and experiment.

play.py

Start exploring here

The overall plot of the Mau Mau story can be found here. This is the entry point for starting to explore the actual application. It is written in an imperative way (like a series of commands given to the computer). The code looks like a series of instructions which are to be carried out in a top down order, descending into the functions being called. The order can be influenced by loops (for ... in or while) and conditioned branches (if ... then ... else). These are the basic control flow constructs Python has. There are a few more, but not many.

Behold! The whole program in 6 lines!

def play_game(gameRules, playerSeed):
    game = setup_game(gameRules, playerSeed)
    while not game.over:
        player = game.next_turn()
        player.play(game.table)
    return game

This is the meat of the simulation. Here is where all the magic happens. if you call this function a game of Mau Mau will be simulated and a winner is determined. 6 lines of code including the function header and the return statement. You now have read the whole plot of the fascinating Mau Mau story. If you want to understand more, you can start digging deeper and visit the definitions of the functions and classes used in the play_game function. Just start to explore the code and how the objects interact in whatever non-linear way you might prefer. This gives you an idea of how a simulation of a simple turn based card game can be implemented as a program.

Modules defining the classes

These look pretty different from game.py and they are. Here is where the object oriented part of the story kicks in. If game.py contains the plot, these modules contain the descriptions of the actors and props of the story. They describe the relevant part of the virtual universe that is created to run the simulation. It contains custom data structures (a.k.a. classes) to model the problem of simulating Mau Mau. You should be able to read through the classes and get an idea of what elements are needed to simulate a card game and how they might interact.

concepts.py

Classes that stand conceptually above the objects and subjects.

objects.py and subjects.py

I know .. in Python everything is an object, so this would be meaningless. This is also not subject oriented programming. These are just good terms for what those classes describe in the context of the program: there are objects in the game which are manipulated by the subjects.

rules.py

This contains the classes that implement the rules of Mau Mau. Start reading with the MauMau class and see if you can figure out how it works. There is always one concrete rule active on the table that is valid for the currently played round. Sometimes information gets transferred from one rule to the next (e.g. if a 7 was put on a 7, the number of draws have to accumulate).

strategies.py: How to play

Classes that implement different player behaviours.

Note

A player has a strategy, but the player also attaches it to the active rule, so that it can be queried for the wanted suit if a Jack is on the table.

BasicStrategy

Player plays according to the rules and always chooses random antidotes if they have any (e.g. 7 on 7 to prevent having to draw) or normal cards. If playing a Jack it always asks for the suit it has the most of.

This can be extended upon to implement "real" strategies.

HumanStrategy

Mainly to show that the existing design makes it very easy to even add interactivity to let a human play against a computer (mau-mau human).

The impact of this is very likely to be zero on a planetary basis, as this is just a learning tool, but in general one should be very wary of implementing something just because it's easy:

I call it my billion-dollar mistake. It was the invention of the null reference in 1965. At that time, I was designing the first comprehensive type system for references in an object oriented language (ALGOL W). My goal was to ensure that all use of references should be absolutely safe, with checking performed automatically by the compiler. But I couldn't resist the temptation to put in a null reference, simply because it was so easy to implement. This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.

-- Tony Hoare

... you have been warned.

stats.py: simulate series of games and create statistics

Contains functions to run the game simulations and collect statistics. See usage examples

Peripherals

Note

These files are not part of the actual software but are still vital for helping with development, installation, testing, etc. -- this makes all that tedious stuff you need when writing software less ... tedious.

setup.py: Make program installable

This module is what is being called, when the package is installed via pip or with python3 setup.py. This is the standard way of doing it in the Python ecosystem and it is documented here.

tox.ini: Developer task automation

This INI file configures tasks that can run with the tox commands. The primary goal of tox is to automate testing and act as a frontend for CI, but it can be used for automating other developer tasks as well. See also the developer documentation for this tox.ini.

.travis.yml and appveyor.yml: CI for different versions and osses

See documentation about CI

mkdocs.yml: Documentation configuration

See the documentation for the documentation (I'm not kidding ...).

Vagrantfile

To start a VirtualBox with Linux or Windows prepared for development.