Forem: Rob

The four pillars of OOP using a WW2 Sherman Tank

Rob — Fri, 19 Dec 2025 15:29:03 +0000

In which we explore the four pillars of object oriented programming by way of a World War 2 tank.

The Sherman tank in British service

In WW2 the allies needed a reliable, mass-produced piece of armour to counter the German panzers. The Americans, with all their industrial prowess, designed the M4 Sherman tank to fulfil this role. It was a good tank, well armed for its time, and proved successful on the battlefield.

The British, beleaguered and war weary, were happy to receive this new weapon under the terms of lend-lease program (whereby the Americans supplied and armed its allies in the war). Of course they had to put their own stamp on it, making a few modifications and calling it the Sherman V.

The tank served them well, but as the war progressed, the axis forces introduced newer and heavier tanks - the Panther and King Tiger. The poor Sherman struggled to penetrate the armour of these new big cats, so the decision was made by the British to up-gun the Sherman, fitting the far more deadly 17pdr.

Modelling the Sherman tank in British service

Let us now look to model the Sherman tank in British service in an object
oriented programming (OOP) language - Java. We begin by declaring a class called Sherman which will define our tank.

public class Sherman
{
    // Definition of a Sherman tank to go here.
}

When we talk of defining a class what do we actually mean? In OOP terms we are talking about the behaviour and properties of that class. Let's start with the behaviour. Our tank can move and shoot, and also the crew can bail out and abandon the tank if things get too hairy. In Java we use methods to define behaviour.

public class Sherman
{
    public void move(int miles)
    {
        // Implementation of movement to go here.
    }

    public void shoot()
    {
        // Implementation of shooting to go here.
    }

    public void bailOut()
    {
        // Implementation of bailing out to go here.
    }
}

You'll notice that we haven't yet defined an implementation for these methods. Before we do that, let us think about what properties our tank might have. If we are moving and shooting, it is fair to assume we have some need of fuel and ammunition. We also need to indicate if the tank is currently bailed out, as we cannot perform any actions if the crew have abandoned the vehicle. Let us model this state information as private properties. We will set these properties once via a constructor for the class.

public class Sherman
{
    private int milesOfFuel;

    private int ammunition;

    private boolean bailedOut;

    public Sherman(int milesOfFuel, int ammunition)
    {
        this.milesOfFuel = milesOfFuel;
        this.ammunition = ammunition;
        bailedOut = false;
    }

    public void move(int miles)
    {
        // Implementation of movement to go here.
    }

    public void shoot()
    {
        // Implementation of shooting to go here.
    }

    public void bailOut()
    {
        // Implementation of bailing out to go here.
    }
}

This idea of defining the state alongside the behaviour that acts upon it is known as encapsulation. It is one of the four pillars of OOP. The unit of encapsulation in an OOP language like Java is a class.

We can now start to implement our tank's methods. Let's cover bailing out first, as it is the simplest to do.

public void bailOut()
{
    if (bailedOut)
    {
        System.out.println("Tank already bailed out!");
    }
    else
    {
        bailedOut = true;
        System.out.println("Crew bailing out!");
    }
}

Here we use the bailedOut property from the state we defined in this class to see if we can bail the crew out or not.

Next let's look at shooting.

public void shoot()
{
    if (bailedOut)
    {
        return;
    }

    if (ammunition > 0)
    {
        ammunition = ammunition - 1;
        System.out.println("BOOM!");
    }
    else
    {
        System.out.println("Click...");
    }
}

We are querying two properties from our class state to see if we can fire - the crew are present and we have enough ammunition. If we can shoot, we modify the ammunition variable to reduce it by one.

Finally movement.

public void move(int miles)
{
    if (bailedOut)
    {
        return;
    }

    if (milesOfFuel >= miles)
    {
        milesOfFuel = milesOfFuel - miles;
        System.out.println(string.format("Driving %d miles.", miles));
    }
    else
    {
        System.out.println("Not enough fuel!");
    }
}

Let's take our tank for a spin!

var tank = new Sherman(10, 3);
tank.move(5); // Output: Driving 5 miles.
tank.shoot(); // Output: BOOM!
tank.move(10); // Output: Not enough fuel!
tank.bailOut(); // Output: Crew bailing out!

Neat. This little demonstration illustrates another of the four pillars of OOP, namely that of abstraction. Notice that we can just send simple messages to our tank like move and shoot without having to know the complexities of how they are implemented. Abstraction combined with encapsulation are powerful tools for modelling complex behaviours in a manageable way.

Time for an upgrade

As mentioned in the introduction to this article, the Sherman soon found its main gun outclassed by the armour of newer axis tanks like the Panther. To solve this problem, the British retrofitted the Sherman with the much more powerful 17pdr gun. How can we model this upgrade in our program?

The Sherman with the 17pdr gun - called a Sherman Firefly - has, for our
purposes, the same behaviour as a regular Sherman. It just made a bigger boom when shooting! Therefore we don't want to have to write a whole new class to define this newer version of our tank. If we did, we would end up duplicating the state and behaviours other than shooting. What we want is a way to say "it's the same as this class, but with this one change". Enter another pillar of OOP, inheritance.

public class ShermanFirefly extends Sherman
{
    public ShermanFirefly(int milesOfFuel, int ammunition)
    {
        super(milesOfFuel, ammunition);
    }

    @override
    public void shoot()
    {
        if (bailedOut)
        {
            return;
        }

        if (ammunition > 0)
        {
            ammunition = ammunition - 1;
            System.out.println("KABOOM!");
        }
        else
        {
            System.out.println("Click...");
        }
    }
}

Pretty neat. We have defined a new class ShermanFirefly that we told Java inherits from the existing Sherman class by using the extends keyword. We have then redefined the shoot method to output a bigger boom when firing. Notice however that we had to redefine the whole method, including the bits that didn't need to change. Can we do better than that?

public class Sherman
{
    // Other code omitted.

    public void shoot()
    {
        if (bailedOut)
        {
            return;
        }

        if (ammunition > 0)
        {
            ammunition = ammunition - 1;
            fire();
        }
        else
        {
            System.out.println("Click...");
        }
    }

    protected void fire
    {
        System.out.println("BOOM!");
    }

    // Other code omitted.
}

Here in the base Sherman class we have changed the shoot method slightly. It now delegates the actual printing of output to another method called fire. Note that this method is marked as protected. That means no one outside the class can see it. So no sneaky calling fire directly and bypassing the checks for bailed out crew and ammunition levels.

var tank = new Sherman(10, 3);
tank.shoot(); // Output: BOOM!
tank.fire(); // Won't compile.

With this new method in place, we can amend our ShermanFirefly class os it redefines the fire method and not the shoot method.

public class ShermanFirefly extends Sherman
{
    public ShermanFirefly(int milesOfFuel, int ammunition)
    {
        super(milesOfFuel, ammunition);
    }

    @override
    protected void fire()
    {
        System.out.println("KABOOM!");
    }
}

Let's try a few shots with the Firefly.

var tank = new ShermanFirefly(10, 3);
tank.shoot(); // Output: KABOOM!

Working together

Tanks seldom worked in isolation. They would be grouped together in platoons, usually of three or more tanks. The British had a problem though. The Firefly was lethal against the bigger axis tanks, but there weren't enough to equip whole platoon's of them. The solution was to equip platoons with a mix of two or three regular Shermans and one Firefly.

How can we model such a platoon of tanks in our code?

var platoon = new List<Sherman>();
platoon.add(new Sherman(10, 5));
platoon.add(new Sherman(10, 5));
platoon.add(new ShermanFirefly(10, 3));

Because the ShermanFirefly inherits from the Sherman class, we can add it to a list of type Sherman. A Firefly is-a Sherman in our model. What happens if we ask each tank in our platoon to fire its gun?

for(Sherman tank : platoon)
{
    tank.shoot();
}

// Outputs:
// BOOM!
// BOOM!
// KABOOM!

Notice how the Firefly shot differently to the other Shermans. Despite the fact we used an instance of type Sherman in our for loop, the Firefly still made its big KABOOM!. This is know as polymorphism, and is the last of the four pillars of OOP. Objects of different types can respond to the same message in different ways.

Home for tea and medals

There you have it. We used the four pillars of object oriented programming - encapsulation, abstraction, inheritance, and polymorphism - to model the World War 2 era British tank the Sherman, and its up-gunned version the Firefly.

Complete listing:

public class Sherman
{
    private int milesOfFuel;

    private int ammunition;

    private boolean bailedOut;

    public Sherman(int milesOfFuel, int ammunition)
    {
        this.milesOfFuel = milesOfFuel;
        this.ammunition = ammunition;
        bailedOut = false;
    }

    public void move(int miles)
    {
        if (bailedOut)
        {
            return;
        }

        if (milesOfFuel >= miles)
        {
            milesOfFuel = milesOfFuel - miles;
            System.out.println(string.format("Driving %d miles.", miles));
        }
        else
        {
            System.out.println("Not enough fuel!");
        }
    }

    public void shoot()
    {
        if (bailedOut)
        {
            return;
        }

        if (ammunition > 0)
        {
            ammunition = ammunition - 1;
            fire();
        }
        else
        {
            System.out.println("Click...");
        }
    }

    public void bailOut()
    {
        if (bailedOut)
        {
            System.out.println("Tank already bailed out!");
        }
        else
        {
            bailedOut = true;
            System.out.println("Crew bailing out!");
        }
    }

    protected void fire()
    {
        System.out.println("BOOM!");
    }
}

public class ShermanFirefly extends Sherman
{
    public ShermanFirefly(int milesOfFuel, int ammunition)
    {
        super(milesOfFuel, ammunition);
    }

    @override
    protected void fire()
    {
        System.out.println("KABOOM!");
    }
}

Setting up Windows for Lua development

Rob — Mon, 02 Jun 2025 18:27:47 +0000

Lua is a delightfully simple language to program in. However setting up Windows to do Lua development can be tricky. This guide walks you through the steps of getting setup with Lua on a Windows PC running Visual Studio Code.

Installing Lua

Create a directory on your PC called C:\lua. Head on over to Luabinaries and download the latest Windows Executables zip file. Unzip the file and place the contents in the folder C:\lua\binaries. You should have three executables and one DLL file.

Copy the luaXX.exe (where XX is the release number, for example Lua 5.4 would have the executable called lua54.exe). Paste it in the same directory. Rename it lua.exe. You should now have a directory listing like the following:

Adding to your PATH

One final task before we can use Lua is to add the location of the executables to your PATH variable. In your Windows search bar, type in edit the system environment variables and open the matching application. You should see a window like this:

Click the Environment Variables button to open the editing window. In this window, select the variable Path from the User variables section. Click the Edit button.

In this new editor window, click the New button. Type in the text C:\lua\binaries and press enter. Click the OK button to leave the settings.

Now open a terminal window by typing terminal into the Windows search bar and running the application it finds. In the new Terminal window that opens, run the command lua -v to check the version of Lua that is installed. You should see output like this:

You now have a working Lua interpreter setup on your PC.

Configuring Visual Studio Code

Open VS Code and click on the Extensions icon on the left-hand side. In the search bar at the top of the extensions list, type in Lua. Pick the following extension to install:

You now have code completion for the Lua language inside VS Code.

Debugging support

While in the extensions screen, search for Lua local debugger. Pick the following extension to install:

We need to configure this extension, so open the settings for it and add an entry for your Lua executable as follows:

You now have debugging support for your Lua programs in VS Code.

How to structure a solution in .NET

Rob — Mon, 30 Sep 2024 10:05:55 +0000

This article aims to show you how I organise a .NET solution. It walks through the creation of a simple web app called Fragment, and the implementation of a single feature. This app allows you to store and tag short fragments of text - ideal for use as a simple journal or notebook. Source code for the whole solution can be found on GitHub.

Assumptions

I'll be creating this solution in Visual Studio Code, but you can follow along with whatever IDE or editor you are most comfortable with. I'm using Windows, but the same should be true for Mac or Linux (bar a couple of minor points). You should be familiar with how to create a new solution, create and add projects to it, and the use of NuGet for adding packages. I will not be explaining how to do these things in this article. Ready? Let's go.

Domain

Let us start by creating an empty solution called Fragment for our code, and adding a class lib project called Domain to it. With this in place, we can create our classes for the domain model. We want to be able to store fragments of tagged text, so two classes are needed - TextFragment and Tag. Here are the classes:

namespace Fragment.Domain;

public class TextFragment
{
    private string _text;

    public string Text
    {
        get { return _text; }

        set
        {
            if (string.IsNullOrEmpty(value))
            {
                throw new ArgumentException("Text must be supplied.");
            }

            _text = value;
        }
    }

    public DateTimeOffset CreatedOn { get; protected set; }

    public ICollection<Tag> Tags { get; protected set; }

    protected TextFragment()
    {
        Tags = new List<Tag>();
        CreatedOn = DateTimeOffset.UtcNow;
    }

    public TextFragment(string text) : this()
    {
        Text = text;
    }
}

namespace Fragment.Domain;

public class Tag
{
    private string _name;

    public string Name
    {
        get { return _name; }

        set
        {
            if (string.IsNullOrWhiteSpace(value))
            {
                throw new ArgumentException("Name must be supplied.");
            }

            _name = value;
        }
    }

    public Tag(string name)
    {
        Name = name;
    }
}

We will revisit these as we work on the project. From here we can either work our way up to the web UI, or down to the persistence layer. I usually choose the latter, and get the persistence infrastructure sorted out first. With that in mind, let us introduce some interfaces to our domain model that will handle moving objects in and out of our backing store.

Add a folder called Repositories to your domain project. Add an empty code file called ITagRepository.cs and another called ITextFragmentRepository.cs. These will define the operations against our as yet unknown persistence layer. For our application, I want to be able to view all the tags we have, add new ones, and delete existing ones. Therefore I'm going to need three methods on my interface to support these operations. These should all be async methods that return a Task, as whatever backing store we end up using will likely be using disk I/O.

namespace Fragment.Domain.Repositories;

public interface ITagRepository
{
    Task<List<Tag>> GetAllAsync(CancellationToken ct);

    Task AddAsync(Tag tag, CancellationToken ct);

    Task DeleteAsync(int id, CancellationToken ct);
}

For the text fragments, I'll want to be able to add and remove a fragment. Additionally I'll want to see all fragments, but that might be a rather large list. To this end, I'll page the data and return a subset of the full list of fragments on each call.

namespace Fragment.Domain.Repositories;

public interface ITextFragmentRepository
{
    Task<TextFragment?> GetByIdAsync(int id, CancellationToken ct);

    Task<List<TextFragment>> GetPageAsync(int skip, int take, CancellationToken ct);

    Task AddAsync(TextFragment fragment, CancellationToken ct);

    Task DeleteAsync(int id, CancellationToken ct);
}

That is the repository interfaces defined. We need one more interface, a unit of work. This is an instance that tracks changes in the domain objects we are using. It then coordinates saving changes to the underlying backing store. As we will see later on, we can get this behaviour for free if we use Entity Framework Core (EF Core) and an underlying database. For now, we just need to define the interface for this object as exposing one method.

namespace Fragment.Domain.Repositories;

public interface IUnitOfWork
{
    Task CommitChangesAsync(CancellationToken ct);
}

There, we are now finished with the domain side of persistence. Next we shall implement these interfaces using SQLite as the underlying database.

Infrastructure.Sql

Add a new class lib project to your solution called Infrastructure.Sql. This will hold all the details related to persisting data in and out of our backing store. We will be using the SQLite database as our backing store. This is a simple file-based database that requires very little configuration, and is therefore very easy to work with.

To interact with the database we could write our own SQL, and execute it using ADO.Net classes. Then we could map the results from the table schema to our domain classes. This is as tedious as it sounds. Various Object Relational Mapper (ORM) solutions exist to take away this drudgery. EF Core is the one we will be using. Let's reference the following NuGet packages in our Infrastructure.Sql project:

Microsoft.EntityFrameworkCore
Microsoft.EntityFrameworkCore.Relational
Microsoft.EntityFrameworkCre.Sqlite

These three NuGet packages add EF Core to our infrastructure project. The heart of EF Core is the class DbContext. This is an abstraction over our database that we can configure in many different ways. Let's add one to our project and walk through the code in it. Add a file called FragmentDbContext.cs to the project.

using Microsoft.EntityFrameworkCore;
using Fragment.Domain.Repositories;
using Fragment.Domain;

namespace Fragment.Infrastructure.Sql;

public class FragmentDbContext : DbContext, IUnitOfWork
{
    public FragmentDbContext(DbContextOptions<FragmentDbContext> options) : base(options)
    {
    }

    public DbSet<Tag> Tags { get; set; }

    public DbSet<TextFragment> TextFragments { get; set; }

    public async Task CommitChangesAsync(CancellationToken ct)
    {
        _ = await SaveChangesAsync(ct);
    }
}

You will need to reference the Domain project we created earlier in the Infrastructure.Sql project to resolve the IUnitOfWork interface and domain classes.

So what is this code doing? We define a constructor that we will use later on (when we build the web UI project and start to wire up all our dependencies). The DbSet<T> properties define what domain models we are working with. Each set will be mapped to a table in our database (as we shall see later in this section when we create migrations).

The only method we have so far is an implementation of our IUnitOfWork interface. This delegates the commit method call to the DbContext save changes call. Why do this? Couldn't we just use the DBContext directly in our calling code instead of going via an interface? We could, but then our code higher up in the application is tightly coupled with EF Core. This may or may not be a bad thing depending on your project's size, scope, and expected lifetime. I tend to err on the side of caution, and add a layer of indirection with the unit of work and repositories.

We now have almost enough to create the database via an EF Core feature known as migrations. First, we need a way to supply a connection string to our database. Where should this live? Configuration files typically reside with the top-most layer of your solution - in our case the Web UI. We haven't created this project yet, so let's do that next before we return to finish off our work in the infrastructure layer.

Web UI configuration file

Add a new ASP.Net Core Razor Pages project called WebUI to the solution. This will most likely scaffold a number of pages and other files that we will change as we work with our solution. For now, we are interested in the appsettings.json file. Let us add content to make it look like the following:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "Fragment": "Data Source=C:\\Databases\\Fragment.db"
  }
}

The connection string we added has the key Fragment. It points to a file on disk called C:\Databases\Fragment.db. Feel free to point to another file on your machine. (Also note that this filename is one for a Windows machine. If you are running on Linux or MacOS you should use your normal filename format.)

Add the NuGet package Microsoft.EntityFrameworkCore to the WebUI project. In Program.cs add the following using statement:

using Microsoft.EntityFrameworkCore;

Next reference the Infrastructure.Sql project in the WebUI project. Add the following service registration code in Program.cs file:

builder.Services.AddDbContext<FragmentDbContext>(options =>
{
    var connectionString = builder.Configuration.GetConnectionString("Fragment");
    options.UseSqlite(connectionString);
});

Next we need to add a tool to our command line that allows us to create migrations (amongst other things) in EF Core. Run the following command from your shell:

dotnet tool install --global dotnet-ef

You should see a confirmation of the tool having been installed. Now we are ready to head back to our infrastructure project and create the database migrations.

Database migrations

Add the following NuGet package to your Infrastructure.Sql and WebUI projects:

Microsoft.EntityFrameworkCore.Design

Before we add our first migration, we need to amend the domain classes to contain some id fields. In the TextFragment.cs file add the following property:

public int Id { get; protected set; }

In the Tag.cs file add the following property:

public int Id { get; protected set; }

Next up, we need to configure how we want these domain classes mapped to tables in our database. We do this in code using a fluent interface. Create a new folder called Configurations in the Infrastructure.Sql project. Add a couple of empty files called TagConfiguration.cs and TextFragmentConfiguration.cs. Apply the code below to these two files:

using Fragment.Domain;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

namespace Fragment.Infrastructure.Sql.Configurations;

public class TagConfiguration : IEntityTypeConfiguration<Tag>
{
    public void Configure(EntityTypeBuilder<Tag> builder)
    {
        builder.Property(t => t.Name).IsRequired();
        builder.HasIndex(t => t.Name).IsUnique();
    }
}

using Fragment.Domain;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Metadata.Builders;

namespace Fragment.Infrastructure.Sql.Configurations;

public class TextFragmentConfiguration : IEntityTypeConfiguration<TextFragment>
{
    public void Configure(EntityTypeBuilder<TextFragment> builder)
    {
        builder.Property(f => f.Text).IsRequired().HasMaxLength(-1);
        builder.HasMany(f => f.Tags).WithMany().UsingEntity("TextFragmentTags");
    }
}

Now back in the FragmentDbContext.cs file, we need to pickup these configuration classes.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    base.OnModelCreating(modelBuilder);
    modelBuilder.ApplyConfigurationsFromAssembly(GetType().Assembly);
}

This snippet of code tells the model builder to scan for any configuration classes in the current assembly and apply them to the model.

We are now ready to add our migration to scaffold the database. In your command shell, run the following:

 dotnet ef migrations add --project Infrastructure.Sql/Infrastructure.Sql.csproj --startup-project WebUI/WebUI.csproj InitialMigration

This should add a new folder to the infrastructure project called Migrations. The classes in here are responsible for updating our database for us. To apply these to our database, use the following command:

dotnet ef database update --startup-project WebUI/WebUI.csproj

We now have a nice new database that can persist our domain model classes to it via EF Core. To browse the database you can open the file from disk using DB Browser. This lets you see the data (of which there is none yet) in the tables, as well as the sql used to create the database schema.

Almost done. We need to implement the repository interfaces and make them use our db context to perform the operations we defined earlier. I'll show the implementation of ITextFragmentRepository here, the code for the tag repository follows a similar pattern. Create a folder called Repositories in the Infrastructure.Sql project for the files TextFragmentRepository.cs and TagRepository.cs to live in.

using Fragment.Domain;
using Fragment.Domain.Repositories;
using Microsoft.EntityFrameworkCore;

namespace Fragment.Infrastructure.Sql.Repositories;

public class TextFragmentRepository : ITextFragmentRepository
{
    private readonly FragmentDbContext _dbContext;

    public TextFragmentRepository(FragmentDbContext dbContext)
    {
        _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext));
    }

    public async Task AddAsync(TextFragment fragment, CancellationToken ct)
    {
        if (fragment is null)
        {
            throw new ArgumentNullException(nameof(fragment));
        }

        await _dbContext.TextFragments.AddAsync(fragment, ct);
    }

    public async Task DeleteAsync(int id, CancellationToken ct)
    {
        var fragment = await _dbContext.TextFragments.SingleOrDefaultAsync(f => f.Id == id, ct);

        if (fragment is not null)
        {
            _dbContext.TextFragments.Remove(fragment);
        }
    }

    public async Task<TextFragment?> GetByIdAsync(int id, CancellationToken ct)
    {
        return await _dbContext.TextFragments.SingleOrDefaultAsync(f => f.Id == id, ct);
    }

    public async Task<List<TextFragment>> GetPageAsync(int skip, int take, CancellationToken ct)
    {
        return await _dbContext.TextFragments.Skip(skip).Take(take).ToListAsync(ct);
    }
}

We've covered a lot of ground so far just to get persistence in place. We have done so in a nicely abstracted way, so the domain is not aware of the specifics of the underlying backing store in use (in this case, SQLite; but it could be anything). Next, let's move up the stack to our Web UI and start implementing some pages.

Web UI

Back in our top-most layer, the Web UI. It's important to note that this project is performing double duty as our UI and also our composition root. The composition root is the part of an application that is responsible for wiring up all the dependencies needed in an application. We did this earlier by adding our customised DbContext to the services collection. We now need to wire up the repositories we implemented in the previous section. Open Program.cs and add the following service registrations:

builder.Services.AddScoped<ITagRepository, TagRepository>();
builder.Services.AddScoped<ITextFragmentRepository, TextFragmentRepository>();

These are scoped to the length of an HTTP request, which is the same scope as the underlying DbContext instance we registered earlier. With that done, let's turn our attention to some actual UI.

Our first page will be a listing of all the tags in the application. Add a new folder called Tags under the Pages folder. Then add a new Razor Page to this folder called List. Let's specify the UI markup first, then turn our attention to the code-behind file.

@page
@model MyApp.Namespace.ListModel
@{
    ViewData["Title"] = "List Tags";
}

<h1>Tags</h1>

@if (Model.Tags is not null)
{
    <table class="table table-striped">
        <thead>
            <tr>
                <th>Name</th>
                <th>Actions</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var tag in Model.Tags)
            {
                <tr>
                    <td>@tag.Name</td>
                    <td>
                        <a asp-page="/Tags/Delete" asp-route-tagId="@tag.Id">delete</a>
                    </td>
                </tr>
            }
        </tbody>
    </table>
}
else
{
    <p>No tags found.</p>
}

Here we are creating a table to display all tag names, with a link to delete the tag (this goes to a page we haven't created yet, so clicking the link will do nothing). Let us see what the code-behind looks like to support this markup.

using Fragment.Domain;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace MyApp.Namespace;

public class ListModel : PageModel
{
    public List<Tag> Tags { get; set; }

    public void OnGet()
    {
        // TODO: Load tags into list.
    }
}

OK, so how are we to load the list of tags in a nicely decoupled way? We might be tempted to inject an instance of our repository class into the code-behind and use it to load our domain model instances. That poses a problem, as the UI is then tightly coupled to the domain classes. What we need is an indirect way of getting the data. Enter the Application project.

Application

In order to insulate our UI from our domain, we need a new project. Add a new project called Application to the solution. Notice how in the code-behind file in our UI page that we referenced the Tag class from the domain project. We need to break this coupling. Instead, the UI will work on a Data Transfer Object (DTO) that is defined in the Application project. Add a new folder called Dtos to the Application project. Then add a file called TagDto.cs with the following content:

namespace Fragment.Application.Dtos;

public class TagDto
{
    public int Id { get; set; }

    public string Name { get; set; }
}

OK, so isn't this just the same as our Tag domain class? Yes and no. Yes it currently has the same shape (public properties) as our domain class, but there is no reason why it has to. It can evolve in a different way to the domain class. The application code we will write shortly is responsible for mapping from the domain instance to a dto instance.

We need something to do the work of calling the tag repository and mapping to our dto. This will be a class known as a handler. The Web UI will pass a request - encapsulated as an object - to an instance of this handler. The handler will talk to the repository, map the result to a dto, and then return a response. We could (quite easily) write the code for all this ourselves. However there is an elegant library called MediatR that does this job already. Lets use it.

Install the following NuGet package in the Application project:

MediatR

We are going to organise our application project in to use cases. A use case is a specific action a user can perform in your application. Create a folder called ListTags and add a new file called ListTagsRequest.cs. This will be where we encapsulate the request information for the handler. The code for it is as follows:

using Fragment.Application.Dtos;
using MediatR;

namespace Fragment.Application.ListTags;

public class ListTagsRequest : IRequest<List<TagDto>>
{
}

There isn't any logic or properties here. We implement the marker interface IRequest<T> and give it our return type List<TagDto>. Next add a file for the handler to the same folder called ViewTagsHandler.cs. Add the code as follows:

using Fragment.Application.Dtos;
using Fragment.Domain.Repositories;
using MediatR;

namespace Fragment.Application.ListTags;

public class ListTagsHandler : IRequestHandler<ListTagsRequest, List<TagDto>>
{
    private readonly ITagRepository _tagRepository;

    public ListTagsHandler(ITagRepository tagRepository)
    {
        _tagRepository = tagRepository ?? throw new ArgumentNullException(nameof(tagRepository));
    }

    public async Task<List<TagDto>> Handle(ListTagsRequest request, CancellationToken cancellationToken)
    {
        var tags = await _tagRepository.GetAllAsync(cancellationToken);

        return tags.Select(t => new TagDto { Id = t.Id, Name = t.Name}).ToList();
    }
}

You'll need to reference the Domain project in order to pick up the repository interface from earlier. We now have our application logic nicely encapsulated in our handler class, and not in the UI. Next we need to wire up the handler in the Program.cs file in the Web.UI project. Add the following service registration:

builder.Services.AddMediatR(c => c.RegisterServicesFromAssemblyContaining<ListTagsHandler>());

You'll need to reference the Application project in the WebUI project for the AddMediatR method to be picked up. This uses assembly scanning to add all the handlers we have (or will in future) define in the Application project. We can now turn our attention back to the page in the UI for viewing the tags.

The code-behind file for our page can now use MediatR to pass off it's request to the handler and get a DTO in response.

using Fragment.Application.Dtos;
using Fragment.Application.ListTags;
using MediatR;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace MyApp.Namespace;

public class ListModel : PageModel
{
    private readonly IMediator _mediator;

    public ListModel(IMediator mediator)
    {
        _mediator = mediator ?? throw new ArgumentNullException(nameof(mediator)); 
    }

    public List<TagDto> Tags { get; set; }

    public async Task<IActionResult> OnGetAsync()
    {
        var request = new ListTagsRequest();
        var response = await _mediator.Send(request);
        Tags = response;

        return Page();
    }
}

Run the WebUI project and browse to the page /Tags/List. We should see an empty table. If you debug the OnGetAsync() call you can trace the execution of the request through the application layer, into the infrastructure and back again. Our UI has no knowledge of the application logic or the SQL infrastructure.

Architecture

There are four projects in our solution now. It is worth observing the dependencies between them in a little more details. Take a look at the source code in the finished repository. First up is the Domain. This houses our entities with their associated domain logic, and the interfaces for our repositories. This project depends on none of the others. It could be reused as-is in another project.

Next is Infrastructure.Sql. This encapsulates all of the EF Core dependencies and database specific code. It's only dependency is on the Domain project for the repository interfaces. We could very easily add a new infrastructure project that uses a different type of backing store, and the effects would not be felt by the rest of the application.

In Application we encapsulate (via the use of MediatR) the use-case specific logic in our solution. The handlers are just entry points into the application layer. You can introduce other objects in the layer to perform other tasks, and the handlers will use them to coordinate processing the request and providing a response.

Finally the WebUI project is our user interface. The use of MediatR keeps it loosely coupled with the Application project. You could introduce a new UI project - say a command line or desktop app - and have it re-use the rest of the solution without having to change anything else. Note that this project does contain references to the other projects, but this is because it is also acting as the composition root of our application. This is the wiring up of dependencies in the Program.cs file. This should be the only place in our WebUI project that we use those references.

I hope this walkthrough and the finished code has helped you understand how I build a loosely coupled solution in .NET.

Fizz-Buzz

Rob — Tue, 17 Sep 2024 15:55:08 +0000

The programmer's Stairway to Heaven, there is no escaping Fizz Buzz. Cropping up in interviews everywhere, it's also a useful little task to write when learning a new language. This has the added benefit of potentially changing how you look at the problem.

My usual C# solution is very straightforward.

public static string FizzBuzz(int num)
{
    var divBy3 = num % 3 == 0;
    var divBy5 = num % 5 == 0;
    string word;

    if (divBy3 && divBy5)
    {
         word = "FizzBuzz";
    }
    else if (divBy3)
    {
        word = "Fizz";
    }
    else if (divBy5)
    {
        word = "Buzz";
    }
    else
    {
        word = num.ToString();
    }

    return word;
}

public static void Main(string[] args)
{
    for(var i=1; i<=100; i++)
    {
        var word = FizzBuzz(i);
        Console.Write($"{word} ");
    }
}

It wasn't until I wrote this in C that I realised how wasteful this approach is. Memory management in C is handled manually, so it was immediately obvious what the issue was. In the C# code we create a string for each call to FizzBuzz. This happens in a loop, so we rapidly allocate several strings. However each one is only used once in the loop. After that we have to wait for the garbage collector to notice this and reclaim the memory used by the string.

In C I decided to pass a buffer into the function instead. Each time through the loop we clear the buffer, write to it, then print it out. There is more work expected of the caller, but we are much more effecient in our usage of memory.

void fizzBuzz(int num, char *buf)
{
    bool isFizz = num % 3 == 0;
    bool isBuzz = num % 5 == 0;

    if (isFizz && isBuzz)
    {
        sprintf(buf, "%s", "FizzBuzz");
    }
    else if(isFizz)
    {
        sprintf(buf, "%s", "Fizz");
    }
    else if(isBuzz)
    {
        sprintf(buf, "%s", "Buzz");
    }
    else
    {
        sprintf(buf, "%d", num);
    }
}

int main()
{
    const size_t BUF_MAX = 128;
    char *buf = (char *)malloc(sizeof(char) * BUF_MAX);

    for (int i=1; i<100; i++)
    {
        memset(buf, '\0', BUF_MAX);
        fizzBuzz(i, buf);
        printf("%s ", buf);
    }

    free(buf);
    buf = NULL;

    return 0;
}

Taking time to write even simple things in other languages can change our perspective.

Zero, one, or many?

Rob — Tue, 17 Sep 2024 15:45:57 +0000

Cardinality is an issue that comes up frequently in software design. How many of each thing should there be in your system? Over time I have found the maxim zero, one, or many to be a great guide in this area. This boils the problem down to two questions:

Do we need the thing at all?
Is there going to be more than one of them?

In my experience if a design limits something to three instances, as soon as you ship your product there will be a need for it to allow four. If you find yourself specifying specific cardinalities, tread carefully. Consider if such limits are really necessary. There may be more value in being flexible.

Beginners guide to Python

Rob — Tue, 17 Sep 2024 15:25:59 +0000

For Hugo. Choose your own doors to open.

What is this article?

Think of this article as a taster session. By the end of it you will have:

Written a complete program in Python to play a game.
Learnt enough Python to write your own simple programs.
Encountered the sorts of problems programmers have to deal with every day, and seen how to solve them.

Hopefully you will enjoy it. If you do there a number of suggestions for further learning at the end. If you don't you will at least understand what it is a programmer does, and the effort it takes to make a computer do what you want it to. Above all the aim is to help you realize that you can learn to program a computer, if you want to.

A joke

Did you hear the one about the programmer's wife? She asked her husband to go to the supermarket and buy a loaf of bread. As he headed out the door, she said "if they have eggs, get a dozen". The programmer dutifully came home with twelve loaves of bread.

Confused? Don't worry, it's most likely because you don't know how to think like a computer programmer (yet).

Hello, world!

We learn best by doing. Let's write some code. We will use the Python programming language as it is simple to read and write. To keep setup to a minimum, we will use the free online Python programming environment at trinket.io. You can use any device with an internet connection and you don't need to install anything.

Task

Go to the trinket.io website. Click the Sign Up link at the top. Fill out the form to create a free account.

Once you have completed the sign up process, you need to login to the website.

Task

Click the Log In link at the top. Enter your username and password on the form.

Trinket refers to each program you write as a trinket. To create a new program click the blue New Trinket and select Python from the list.

Task

Create a new trinket, select Python from the available options.

You should now see the program editor page. The left hand side of the screen is where you will type in Python code. It has a tab named main.py. We will call this the code pane. The right hand side of the screen is where you will see the output from running your code. We will call this the output pane. At the moment this is blank. Up top there should be space for giving this trinket a name. It currently has the text untitled.

Task

Give your trinket the name hello world by clicking on the untitled text and typing it in. Click the save button to save your changes.

You are now ready to write a Python program.

Task

In the code pane carefully enter the following two lines of text, including all the punctuation marks.

#!/bin/python3

print("Hello world!")

Save your changes by clicking the Save button again. Get in to the habit of saving your work regularly. The internet is mostly reliable but sometimes things go wrong. We don't want to lose our work.

We've typed in a program! But nothing happened. We need to tell Python to run our program. Running a program makes Python read each line of our code, and turn it into instructions the computer can understand.

Task

Click the large triangle button at the top of the code pane. This is the Run button. See what happens.

Did it work?

If all went well you should have seen the text Hello world! in the output pane. Don't worry if you didn't. I'll help you to diagnose and fix the problem.

Fixing problems in your code is called debugging and programmers do it a lot. Even if your code worked it is still worth reading through the steps below. Sooner or later you'll need to use them.

Python should give you an error message when something goes wrong. This is shown in a pale red box at the bottom of the screen.
The error message will often include the number of the line in your code Python had a problem with. This is the best place to start looking for a bug.
Double check that what you typed in on that line matches the code given in the example. Punctuation is important, as are letters being upper case or lower case. In some cases spacing is also important (we will cover these later).
Correct the line so it matches the code in the example. Save your changes and run your program again.

It's common to have to go through these steps several times before you get a working program, especially when learning. As you get familiar with Python code this will happen less often, so don't worry.

Task

If your program didn't work, go through the process outlined above until you see the message Hello world! in the output pane.

What's with the funny looking first line?

Our program actually only has one line of code that does something, the one with the print() command on it. The first line is a special one that tells the computer to use version 3 of Python. This is the most up to date version of Python and is the one we will be using.

Printing other things

The print statement we saw in the previous program can be used to say any number of things on the screen. The message we want to display appears between the beginning and end quote marks ".

Task

Change the print() command in your program to say different things. Run your program after each change to see if Python will print out your new message.

Are there any things it can't print out? Do some messages cause an error?

This sort of trial and error approach to writing code is a useful way of learning a new feature of a language. Hopefully you got Python to successfully print out another message.

You might also have discovered that trying to print out a message that included the double quote " symbol caused an error. This is because we use " to mark the beginning and end of the message. If we want to print out a message that includes a " we have two options:

Use a single quote ' to mark the beginning and end of the message instead of a double quote. For example print('A "word" in double quote marks.').
Precede the double quotes in the message with a backslash \ character. For example print("Another \"word\" in double quote marks.").

Task

Type in both of the examples for printing a message with double quote marks in it. Add these lines to the end of your program. Run your program and check the messages shown on screen include the quote marks.

Using a backslash to print a quote mark is known as escaping. It tells Python to ignore the special meaning of the quote mark that follows. The print() command supports a number of different escape sequences for printing out difficult characters. The following ones often come in handy.

Escape sequence     Output
-------------------------------------------------------------------------------
\\                  A backslash.
\'                  A single quote mark.
\"                  A double quote mark.
\n                  A newline.
\t                  A tab.

Task

Write a print() command for each of the following messages. Add the necessary escape sequences to each one. For example, the first one needs a newline added to it.

This is on one line. This is on another.

This "message" has double and 'single' quotes in it.

These words each have a tab between them.

There's a \ in this message.

Sometimes we want to write a lot of text spanning several lines. When this is the case Python lets us begin and end the block of text with three of the same quote marks - either """ or '''. Messages written in this way will be printed out as is.

print("""This is a very long
message that will be 
printed
out across several lines!""")

Task

Write a print() command that uses the triple quotes for its message. Make the message span several lines. Run your program and see how Python outputs it on screen.

Can you use any of the escape sequences in your triple quoted message?

Asking questions

So far our program can output messages to the screen. It would be useful if we could also receive input from somewhere too.

The input() command lets us do just this. We can use it to prompt for input from the keyboard.

Task

Add the following lines of code to the end of your program. Save your changes.

name = input("What is your name?")
print("Hello", name)

Task

Run your program. In the output pane type in your name when prompted and press enter. Your program should say hello to you.

What just happened?

Despite only being two lines of code, quite a lot just happened. Let's break it down.

We created a variable called name. A variable is a label we use to remember things in a program.
We got some input from the keyboard using the input() command, and assigned it to name using the equals = sign. Assignment is like putting a sticky label on something. In this case we put the label name on to some input from the keyboard.
We passed two arguments to the print() command. One was the message Hello, the other was the name variable.

Note how Python didn't print out the word name, but instead whatever we typed in at the keyboard and had assigned to name.

Task

Try running your program several times typing in something different each time. We called our variable name but Python lets us type in any text we like.

Anything we want to remember in a program must be assigned to a variable. You can have as many variables as you like in a program, the only limit is the amount of memory present on the computer.

Making decisions

Alongside input and output another basic ability our programs need is to make decisions. Programs typically look at the content of one or more variables and then decide what to do. Python uses the if statement for this purpose.

#!/bin/python3

birthplace = input("Where were you born?")

if birthplace == "England":
    print("So was I!")

In the code above Python will print out the message So was I! only if you enter a birthplace of England (with a capital letter E).

The statement birthplace == "England" is known as a condition. Conditions can be true or false. When the condition is true the code associated with the if runs.

How does Python know what lines to run when the if statement is true? First we end the line with a colon :. Then we indent the lines it should run with a single tab. Any lines that are indented Python considers to be part of the if statement.

We use a double equals == to see if one thing is the same as another in Python. It's a common mistake to get this mixed up with the single equals = which is used for assignment to a variable (as we saw with the input() command earlier).

Task

Create a new trinket and give it the name Questions. Type in the lines from the example above and save your changes.

Task

Run your program twice - once with "England" as the input and once with somewhere else. See that the message is only printed out for England.

Making more than one decision

We can add additional statements to the basic if to check for other conditions. The simplest of these is else. Lines associated with an else only run when the if condition isn't true. Let's expand our example.

#!/bin/python3

birthplace = input("Where were you born?")

if birthplace == "England":
    print("So was I!")
else:
    print(birthplace, "is a nice place.")

Task

Change your birthplace program to look like the one above. Note the use of else: and the indentation of the second print() command with a tab.

If we run this new version of our program we should see that it prints out one message or the other depending on if we input England or something else.

Task

Run your program several times with different place names. See which message gets printed out for each palce.

We can also add conditions with elif, which is short for else if. The program below shows how to do this.

#!/bin/python3

birthplace = input("Where were you born?")

if birthplace == "England":
    print("So was I!")
elif birthplace == "Ireland":
    print ("Next door to me.")
else:
    print(birthplace, "is a nice place.")

Task

Modify your program again, this time adding in the elif statement and associated print() command.

Running this new program we should see one of three messages in the output pane, depending on if we enter England, Ireland, or somewhere else when prompted.

Task

Run your program several times with different place names. See which message gets printed out for each place.

Making a game

Believe it or not we now know (almost) enough Python to write a game. With input, output, and decisions we can play Rock, Paper, Scissors!

For those unfamiliar with the game, a quick summary. A game for two players, on the count of three both pick one of rock, paper, or scissors by making an appropriate shape with their hand. The winner is determined as follows:

Rock blunts scissors.
Paper wraps rock.
Scissors cut paper.

If both players make the same choice the game is a draw.

In our version of the game you will be one player and the computer the other. We'll need a way for the computer to make a choice. Also we can't use hand shapes (at the time of writing computers don't come with hands), so we'll have to find some other way to represent the choices you and the computer make.

Task

Create a new trinket and call it Rock, Paper, Scissors. Write the funny first line that tells the computer to use Python version 3. Save your changes.

An algorithm

Before starting to write code we should get a clear idea of what we want our program to do. Let's write out the steps needed to play the game in plain English.

Make the computer pick a random choice between rock, paper, or scissors.
Remember the choice in a variable.
Ask the player to choose either rock, paper, or scissors.
Remember the choice in a variable.
Print both choices on screen - for example rock vs scissors.
Compare the two variables to see who has won, or if the game is a draw.
Print out a message to say if the player won, drew, or lost the game.

The description we just wrote is our algorithm for playing Rock, Paper, Scissors. An algorithm helps us get a clear understanding of what our program is trying to do before we sit down to write code. If ever we get stuck coding, we can refer to our algorithm to remind us what to do next.

Task

Write out each line of the algorithm in the code pane, putting a hash # symbol at the start of each line. This symbol tells Python the line is a comment. Comments are there to help the programmer with useful information and are ignored by Python.

#!/bin/python3

# 1. Make the computer pick a random choice between rock, paper, or scissors.
# 2. Remember the choice in a variable.
# 3. Ask the player to choose either rock, paper, or scissors.
# 4. Remember the choice in a variable.
# 5. Print both choices on screen - for example `rock vs scissors`.
# 6. Compare the two variables to see who has won, or if the game is a draw.
# 7. Print out a message to say if the player won, drew, or lost the game.

The computer's choice

Python is often described as coming with batteries included. This is because there is a large library of pre-written code that you can use in your programs. Such code can do useful things for us without having to work out how to do it for ourselves. Generating random things is one of those useful functions we can find in the Python library.

To use a part of the Python library we must first import it into our program by name. Parts of the library are known as modules and they all have a unique name to identify them. To make the computer pick something at random we will import the random module.

Task

Add the line below to your program, after the comments describing the algorithm, to import the random module.

import random

The first port of call when using a new module is to take a look at the documentation for it. This gives details on all the functions contained in the module. Functions are pieces of named code that do specific things. The print() and input() commands we have been using so far are actually functions. From now on we will use the term function instead of command.

Task

Trinket has built in documentation for some Python modules. To access it click on the hamburger menu (the three horizontal lines) above your code pane. Click the Modules link to open the documentation. Scroll down the list and click on the random entry.

Have a look at the information but don't worry if it doesn't make sense just yet! To get back to your code, click the hamburger menu again and click on Modules to close the documentation.

It may look quite intimidating but after some practice coding, the documentation will become easier to understand. For now, know that we are interested in the function random.randint(). This function is used to make the computer generate a random number between a minimum and maximum that we decide.

How does this help us with our game? Well we can't get the computer to pick the words rock, paper, or scissors, but we can use the numbers 1, 2, and 3 to represent the choices.

1 rock
2 paper
3 scissors

Let's do this in our program now.

Task

Add the following lines to the end of your program.

# Get computer choice.
comp_choice = random.randint(1,3)

Here we ask the randint() function for a random number between 1 and 3, and assign it to a variable named comp_choice (short for computer choice).

The player's choice

One choice down one to go. We can prompt the player for their choice using the input() function, like we did in previous exercises. As with the computer we want the player to choose a number between 1 and 3.

player_choice = input ("1 rock, 2 paper, 3 scissors?")

This will capture the keyboard input and assign it to the player_choice variable. There is however a problem. To understand it we need to expand our knowledge of variables a little.

Types of things

All variables in Python have a type associated with them. The type describes what sort of data the variable refers to. Our comp_choice variable is of type int which is short for integer. An integer is a whole number (one without a decimal point in it). 1, 23, and 2006 are all examples of integers.

On the other hand our player_choice variable is of type str which is short for string. A string is any piece of text. "Hello", "nice to meet you", and "tasty bacon" are all examples of strings.

When we come to work out who has won the game we are going to need to compare both choices. It is here that the problem arises. The integer 1 is not the same as the string "1". So how do we solve this problem?

Python provides functions for converting one type of data to another. We can use the int() function on a string to to turn it into an integer, and assign this to a new variable.

Confused? Let's see an example.

# Get player choice.
input_str = input ("1 rock, 2 paper, 3 scissors? ")
player_choice = int(input_str)

This revised code for getting the players choice first assigns the keyboard input (which is a string) to the variable input_str. It then uses the int() function to turn the string in to an integer, and assigns it to the variable player_choice.

Task

Add the code for getting the player's choice given in the sample above to the end of your program. Run your program and enter a number between 1 - 3. There wont be any output yet, but neither should there be any errors.

Showing both choices

Now that we have both choices we can print out a message along the lines of rock vs paper on screen. Alas we now have another issue relating to how choices are represented in our program. Both choices are numbers, and printing out 1 vs 2 isn't what we want to see. What we want to see is rock vs paper.

Using if, elif, and else we can write code to print out the correct word for each choice.

# Show player choice.
if player_choice == 1:
    print("rock", end=" ")
elif player_choice == 2:
    print("paper", end=" ")
else:
    print("scissors", end=" ")

What's with the extra end=" " argument in the call to print()? Normally the print function will automatically add a newline to the end of the text we give it. For us that is a problem as we want rock vs paper to appear all on one line, and we haven't finished writing it all out to the screen yet. We can change this behaviour by giving the print function an end argument that has a different character to use at the end of a line. We will use a single space instead of the default newline.

Task

Add the code to print out the players choice to the end of your program. Run your program and see that it successfully prints out your choice as a word.

Our message is halfway there. Let's print out the computer's choice to finish the job.

# Show computer choice.
if comp_choice == 1:
    print("vs rock")
elif comp_choice == 2:
    print("vs paper")
else:
    print("vs scissors")

In this case we can let the print function add a newline to the end, as we have now written out the full message.

Task

Add the code to print out the computer's choice to the end of your program. Run your program and see that it successfully prints out both choices on one line.

Winners and losers

The only thing left to do is determine the outcome of the game. Before writing any code for this we need to work out how many possible outcomes there are. Both players can make one of three choices, so there are nine possible outcomes for our game.

player      computer    winner
--------------------------------
rock        rock        draw
rock        paper       computer
rock        scissors    player
paper       rock        player
paper       paper       draw
paper       scissors    computer
scissors    rock        computer
scissors    paper       player
scissors    scissors    draw

Once again we can use if statements to work out the correct message to display.

Task

Given the list above, work out how many if statements we will need to check all possible outcomes of the game. Don't write any code just yet, instead see if you can work it out on paper or in your head.

Can we use less than 9 if statements (one for each outcome of the game)?

The first thing to notice is the three draw outcomes can be handled with one condition player_choice == comp_choice. It doesn't matter if the game is rock vs rock, paper vs paper, or scissors vs scissors. What matters is if the choices are the same as each other.

Our first if statement looks like this.

# Determine who won.
if player_choice == comp_choice:
    print("A draw.")

Let's look at winning next. From the table of outcomes we can see three ways the player can win. We will need to check for each of these outcomes separately.

So far our if statements have only checked if one thing equals another, as in some_variable == "this value". However to work out if a player has won the game, we will need to check both the player_choice and comp_choice in one if statement. Its no good just checking the player's choice.

We can check both choice variables in one if statement by using the and operator. and joins two conditions together returning true only when both conditions are true. For example player_choice == 1 and comp_choice == 3 checks if the player chose 1 (rock) and the computer chose 3 (paper). Remember, our choice variables contain the numbers of each choice not the word.

Lets add the three winning conditions to our code for determining the outcome of the game.

# Determine who won.
if player_choice == comp_choice:
    print("A draw.")
elif player_choice == 1 and comp_choice == 3:
    print("Rock blunts scissors. You win!")
elif player_choice == 2 and comp_choice == 1:
    print("Paper wraps rock. You win!")
elif player_choice == 3 and comp_choice == 2:
    print("Scissors cut paper. You win!")

That just leaves the three outcomes where the player loses. However in this case we don't need to check all three possibilities. We have already checked for a draw and winning. This means if none of those conditions have matched, whatever combination of choices is left must be a loss for the player.

In other words, if you didn't draw and you didn't win, you must have lost.

This can be written using the else statement. Our final code for determining the outcome of the game is as follows.

# Determine who won.
if player_choice == comp_choice:
    print("A draw.")
elif player_choice == 1 and comp_choice == 3:
    print("Rock blunts scissors. You win!")
elif player_choice == 2 and comp_choice == 1:
    print("Paper wraps rock. You win!")
elif player_choice == 3 and comp_choice == 2:
    print("Scissors cut paper. You win!")
else:
    print("You lose :(")

It turns out we only needed 5 statements to cover all possible outcomes of the game. Is this how many you thought would be needed? If not, can you see where the code is different to your approach?

Task

Add the final version of the code given above for checking the outcome of the game to the end of your program.

That's it, we have a complete game of Rock, Paper, Scissors written in Python!

Try running your program several times to make sure it works correctly. In particular see if:

The message on screen matches the choices made by the player and computer.
The program correctly reports the outcome of the game.

Go through the debugging steps outlined earlier if you have any errors. Keep testing and debugging your code until it plays the game correctly.

Reviewing our game

We have a complete game, which is an achievement to appreciate. However programmers are forever on the look out for ways to improve their work, so let's take a step back and cast a critical eye over our program.

Only once

The most obvious limitation of our game is that it only lets you play once. Sure we can run the program again, but it would be nice if we could keep playing. If we did this we might even be able to write a tougher computer opponent, one that remembers each game and makes a choice more likely to beat you, instead of picking numbers at random.

Let's keep a list of all the potential improvements we could make to our game. Programmers often refer to such a list as a backlog. It's common to have more in the backlog than you have time for! Part of being a progrmmer is accepting there is always more that could be done to improve things.

Backlog for Rock, Paper, Scissors

- Feature: Let the game be played more than once, until the player decides to stop.

Invalid input

When playing the game you may have noticed a bug. What happens if you entered a number other than 1, 2, or 3? The input() function just reads the keys entered on the keyboard. It does nothing to validate the input, to make sure it is one of the numbers our program recognises. In fact we could enter a letter, word, or a whole line of text instead of a number. This gives our program a real headache.

Task

Run your program and enter a letter instead of a number when prompted. See the error that Python reports at the bottom of the screen.

Good programs are written to cope with such invalid input. Instead of erroring they gently prompt the user again until a proper choice is made. Let's make our program one of the good ones.

Backlog for Rock, Paper, Scissors

- Feature: Let the game be played more than once, until the player decides to stop.

- Bug: Player can enter an invalid choice, causing an error. Make sure the game only plays when 1, 2, or 3 is chosen.

Improving the code

Finally you may have noticed a lot of the code in our program was to do with mapping between the numbers of the choice variables, and printing out the words rock, paper, and scissors. Here's all of the code we used for that.

if player_choice == 1:
    print("rock", end=" ")
elif player_choice == 2:
    print("paper", end=" ")
else:
    print("scissors", end=" ")

if comp_choice == 1:
    print("vs rock")
elif comp_choice == 2:
    print("vs paper")
else:
    print("vs scissors")

That's nearly half of our program! If the Python library had a function called choice_to_word() that gave us the correct word for each number, we could simplify this code a great deal.

player_word = choice_to_word(player_choice)
comp_word = choice_to_word(comp_choice)
print(player_word, "vs", comp_word)

Python's library doesn't have such a function. However we can write one to do just that. Writing our own functions lets us use the same code in many places in a program without having to write it all again. The less code, the less chance of errors.

Backlog for Rock, Paper, Scissors

- Feature: Let the game be played more than once, until the player decides to stop.

- Bug: Player can enter an invalid choice, causing an error. Make sure the game only plays when 1, 2, or 3 is chosen.

- Feature: Write a function to map the numbers 1, 2, and 3, to the words `rock`, `paper`, and `scissors`.

So that's our backlog. Of the three items it's fair to say the bug should be our first priority. Deciding which of the two features we do next is a bit harder. Playing the game many times is an improvement that players will notice. Whereas writing our own function doesn't change the game, but improves our code. Some programmers prioritise new features, others like to have cleaner code. Either choice is valid.

Personally I would add the function first, then tackle the feature to play the game many times.

Making improvements

The top item on our backlog is to fix the bug caused by an invalid player choice. Let's remind ourselves of the code we use to get the choice.

input_str = input ("1 rock, 2 paper, 3 scissors? ")
player_choice = int(input_str)

We get the input from the keyboard with the first line, and turn it into an integer with the second. The important thing to note is the input() function simply reads whatever is typed on the keyboard until the return key is pressed. Our message prompts for a number from 1 to 3, but the player is free to type in anything.

So what kinds of input could we end up with in our input_str variable?

A valid number between 1 and 3.
An invalid number, less than 1 or greater than 3.
Something that isn't a number at all.

There are two types of bad input we want to avoid here: a number outside the range we want, and something that isn't a number at all. Ideally our program should keep asking the player for their choice until we get something we can use. Let's write out an algorithm that describes this process.

An algorithm for getting the player's choice

Prompt for player input from the keyboard and assign it to input_str.
If input_str is a number, convert it and assign to player_choice as before.
If input_str is not a number, assign zero to player_choice.
Repeat these steps while player_choice is not 1, 2, or 3.

It might not be obvious why we need step three. If something other than a number is added, we know this is invalid input. Setting the player_choice variable to zero makes our check in step four simpler. We only have to check if the number is outside the range we want. (Don't worry, this will make more sense when you see the code.)

To implement this in code we need to know two new things in Python.

How to check if a variable refers to a number.
How to repeat running some code until a condition is satisfied.

The first can be done with a function called isnumeric(). The second requires us to learn about looping, which is the term programmers use for running some code multiple times.

Asking variables questions

Some variables allow us to call functions on them. Functions called in this way are known as methods. Let's see an example.

my_str = "3"
my_str.isnumeric() # This is True.
my_other_str = "h"
my_other_str.isnumeric() # This is False.

For now it is enough to know that methods exist on some types of variables, and you call them by putting a dot . after the variable name, followed by the method name and it's arguments. Using the isnumeric() method our code for getting the player's choice now looks as follows.

# Get player choice.
player_choice = 0
input_str = input ("1 rock, 2 paper, 3 scissors? ")
if input_str.isnumeric():
    player_choice = int(input_str)

Task

Find the following lines of code in your program, and replace them with the new code given above for getting the player's choice.

# Get player choice.
input_str = input ("1 rock, 2 paper, 3 scissors? ")
player_choice = int(input_str)

Repeating code with `while`

We are almost finished with our improved way of getting the player's choice. The last piece of the puzzle is for our program to keep asking the player until their choice is a valid one.

Python offers multiple ways to repeat blocks of code. What we would like to say here is "while the player's choice is outside the range 1 to 3, ask them for their input again". The key word here is while, and Python has a while loop that does just what we need.

Using a while loop our code to get the player's choice now looks as follows.

# Get player choice.
player_choice = 0
while player_choice < 1 or player_choice > 3:
    input_str = input ("1 rock, 2 paper, 3 scissors? ")
    if input_str.isnumeric():
        player_choice = int(input_str)

Note the new line starting with the word while. This introduces the loop. Immediately afterwards we give two conditions, joined with an or. This code will keep running while the player_choice variable is less than 1 or greater than 3. In other words outside our range of 1 to 3.

Task

Change your program again, this time adding in the line with the while loop on it. Make sure you add it in the correct place, immediately after we set player_choice = 0. Pay attention to the indentation of lines. Note how the lines under the while are indented with a tab, and the line under the if statement is indented with two tabs. This spacing is important to Python.

Writing our own function

Programmers are lazy (in the best possible way) and like to save time and effort where they can. Writing our own functions lets us use the same code in many places in a program, without having to write it all again.

Defining a function is done with def. Here is an example that defines a function called say().

def say():
    print("Inside our own function!")
    print("Time to leave.")

Note that Python does not run the code inside the function until we call it. The def merely defines the function.

We can call this function in the same way we do print() and other built-in ones. Here is part of a program that uses the say() function.

print("Outside the function.")
say()
print("Outside again.")

The above program would output:

Outside the function.
Inside our own function!
Time to leave.
Outside again.

We can also define functions that expect arguments. These act as input to the function, and are assigned to variables only it can use. To write a function like this we need to add variable names to the function definition. We can then use these variables inside the function.

def say(message):
    print("The message is:")
    print(message)

When defining functions in this way, we say that the list of variables given in the definition are the function's parameters. A function defined with parameters must be given arguments for them when called. Let's see that in action in a complete program.

#!/bin/python3

def say(message):
    print("The message is:")
    print(message)

say("hi there!")
say("goodbye...")

If you were to run this program you would see the following output.

The message is:
hi there!
The message is:
goodbye...

Finally we can also return values from a function. This is done with the return statement. Here is a program that defines a function to add two numbers and return the result to the caller.

#!/bin/python3

def add(a, b):
    total = a + b
    return total

print("10 + 20 =", end=" ")
result = add(10,20)
print(result)
print("5 + 6 =", end=" ")
result = add(5,6)
print(result)

When run we see the output.

10 + 20 = 30
5 + 6 = 11

Writing the choice to word function

Now we know how to write a function that takes input in the form of arguments and returns a result, we can implement our choice_to_word() function. Recall that this function will greatly reduce the code we need in our program to print out the player and computer choices to screen.

Our function will take a single parameter called choice, which is a number from 1 to 3. It will return the word relating to that number in our game as a string (one of Rock, Paper, or Scissors).

# Map the numbers 1,2,3 to the words Rock, Paper, Scissors. 
def choice_to_word(choice):
    if choice == 1:
        word = "Rock"
    elif choice == 2:
        word = "Paper"
    else:
        word = "Scissors"
    return word

Task

Add the definition for the choice_to_word() to your program. Functions must be defined before they are used. Therefore it is good practice to place function definitions at the top of your code. Add the function definition after the comments you wrote outlining our algorithm, and before the line starting import random.

Now we can replace all of this code...

# Show player choice.
if player_choice == 1:
    print("rock", end=" ")
elif player_choice == 2:
    print("paper", end=" ")
else:
    print("scissors", end=" ")
# Show computer choice.
if comp_choice == 1:
    print("vs rock")
elif comp_choice == 2:
    print("vs paper")
else:
    print("vs scissors")

...with these lines.

# Show player and computer choice.
player_word = choice_to_word(player_choice)
comp_word = choice_to_word(comp_choice)
print(player_word, "vs", comp_word)

Task

Delete the old code for printing out the player and computer choices, and replace it with the lines that use our new function. Test your program to see that it still prints out the correct choices for a game. Remember to follow the debugging steps if you have errors.

Play again?

The final task remaining on our backlog is to make the game playable many times. It would be nice if, after a game, we ask the player whether they want to play again. This will require two changes to our program: a prompt to get player input, and another while loop to make the game code keep running.

We have already seen how a while loop can be used to repeat a block of code. If we wrap all our code for playing the game in such a loop, we can play multiple times.

Task

After the line import random in your program, add the following two lines of code. Note the colon : at the end of the second line.

playing = True
while playing:

Task

Indent the start of every line that comes after the while playing: line with an extra tab. Your code should look as follows.

#!/bin/python3

# 1. Make the computer pick a random choice between rock, paper, or scissors.
# 2. Remember the choice in a variable.
# 3. Ask the player to choose either rock, paper, or scissors.
# 4. Remember the choice in a variable.
# 5. Print both choices on screen - for example `rock vs scissors`.
# 6. Compare the two variables to see who has won, or if the game is a draw.
# 7. Print out a message to say if the player won, drew, or lost the game.

# Map the numbers 1,2,3 to the words Rock, Paper, Scissors. 
def choice_to_word(choice):
    if choice == 1:
        word = "Rock"
    elif choice == 2:
        word = "Paper"
    else:
        word = "Scissors"
    return word

import random
playing = True
while playing:
    # Get computer choice.
    comp_choice = random.randint(1,3)
    # ... rest of lines are also indented ...

After we have printed out the message telling the player the outcome of the game, we can use the input() function to ask if they want to play again. Inputting anything other than a y for yes will cause our game loop to stop. We do this by setting the playing variable to False.

# Ask player for another game.
again = input("Play again? ")
if again != "y":
    playing = False

The next time the while loop evaluates it's condition it will be false. Python will run whatever code comes immediately after the block associated with the loop. Let's add a goodbye message to the very end of our program.

# Say goodbye.
print("Thank you for playing!")

Task

Add the code for the play again prompt and goodbye message to your program. Remember that the play again prompt is part of the while loop block, so must be indented. The goodbye message is outside the loop, so doesn't require indentation. Your whole program should look as follows.

#!/bin/python3

# 1. Make the computer pick a random choice between rock, paper, or scissors.
# 2. Remember the choice in a variable.
# 3. Ask the player to choose either rock, paper, or scissors.
# 4. Remember the choice in a variable.
# 5. Print both choices on screen - for example `rock vs scissors`.
# 6. Compare the two variables to see who has won, or if the game is a draw.
# 7. Print out a message to say if the player won, drew, or lost the game.

# Map the numbers 1,2,3 to the words Rock, Paper, Scissors. 
def choice_to_word(choice):
    if choice == 1:
        word = "Rock"
    elif choice == 2:
        word = "Paper"
    else:
        word = "Scissors"
    return word

import random
playing = True
while playing:
  # Get computer choice.
  comp_choice = random.randint(1,3)
  # Get player choice.
  player_choice = 0
  while player_choice < 1 or player_choice > 3:
      input_str = input ("1 rock, 2 paper, 3 scissors? ")
      if input_str.isnumeric():
          player_choice = int(input_str)
  # Show player and computer choice.
  player_word = choice_to_word(player_choice)
  comp_word = choice_to_word(comp_choice)
  print(player_word, "vs", comp_word)
  # Determine who won.
  if player_choice == comp_choice:
      print("A draw.")
  elif player_choice == 1 and comp_choice == 3:
      print("Rock blunts scissors. You win!")
  elif player_choice == 2 and comp_choice == 1:
      print("Paper wraps rock. You win!")
  elif player_choice == 3 and comp_choice == 2:
      print("Scissors cut paper. You win!")
  else:
      print("You lose :(")
  # Ask player for another game.
  again = input("Play again? ")
  if again != "y":
      playing = False
# Say goodbye.
print("Thank you for playing!")

That's it! We have tackled all the items on our backlog for improving our game. Our game now handles invalid input from the player and lets us play for as long as we want to. Take some time to study the final code listing and make sure you are happy with how it all works.

A better computer player

Rock, paper, scissors is not a very complex game, but there is still room for a bit of strategy. Playing against another human being we tend to pick up, at least subconsciously, on all sorts of things. Perhaps the other person likes to play rock more often than the other choices. Maybe after they lose a round, they always change the choice they make to something else. As a human being it is unlikely that you would remember all the outcomes of all the games, but you would develop some intuition or gut feeling about how the other person plays.

Sadly our computer player is a little simple in this regard. It just picks a choice at random every time it plays. Can we make it a better player? What if we could make it behave more like a human? Whatever it is that gives us as humans the ability to develop intuition, to have a hunch, or gut feeling about something, whatever that spark is, computers do not have it.

So is random the best we can do for our computer player? As it turns out, no. We can do better. Computers may not have gut feelings like humans, but they excel at remembering things. In fact we can make our computer player remember every choice the human player makes. In the absence of intuition we can use statistics to help the computer make a better choice, and ultimately be a more rewarding opponent.

Retrospective

A retrospective is a term programmers use to mean looking back on the work they have just done. Typically a retrospective is held at the end of a piece of work. The aim is to see what went well, went went wrong, and what new things can be tried next time. We will use our retrospective to review all the Python we have learnt in the previous parts, fill in a few blanks in our knowledge, and give some links to resources for further learning.

What exactly is Python?

Python is an interpreter that sits between us and the computer. The code we write is read one line at a time by Python and turned into instructions the computer can understand. Technically speaking then we do not program the computer, we program Python.

Because Python runs our code in this way, any errors will only be reported when Python tries to read a line it doesn't understand. The following program contains a bug that illustrates this behaviour.

#!/bin/python3

secret_word = "cheeseburger"
guess = input("Guess >")
if guess == secret_word:
    prnt("Correct!")
else:
    print("Incorrect")

The first branch of the if statement contains a typo - prnt instead of print. So if we run this program Python will give us an error right? Maybe.

The line with the error will only run when the condition guess == secret_word is True. So if we run the program and type in something else for our guess, Python will never read the line with the error. It will look like our program is working correctly.

These kinds of bugs can be hard to find, especially when you have a lot of code. The best way to find them is to test each path of execution in your program. The program given above has two paths through it, one when the guess is cheeseburger and one when it is anything else. Running the program multiple times and giving input for both branches would uncover the error.

How much should I know?

The first function we saw was print() and we used it in multiple ways.

print("Hello world!")
print("Hello", name)
print("rock", end=" ")

All of the above are valid ways of calling the print() function. Different functions expect different arguments. A significant part of learning a language is becoming familiar with its functions and how to call them with the correct arguments. (Reading the Python documentation can help with this.)

As we have seen already you can write complete programs knowing very few functions. Python's library is rather large, so don't get hung up trying to learn it all. Most professional programmers only know a small portion of it. It's about learning what you can do with the little you do know. Above all remember to have fun while learning!

Limitations of `trinket.io`

The trinket website is a fantastic resource for learning Python. It requires no setup on your part and is free. The downside to that is it only has a small subset of the full Python library available. This is unlikely to cause you any issues when learning the basics, the people behind trinket have made the most useful modules of the library available. Just bear in mind that some more advanced Python programs may not work under trinket because of this limitation.

To see a list of the available modules, open up any trinket and click the hamburger menu (three stacked lines) on the left of the code pane. Click the Modules link to see the list.

Further learning

If you want to take your understanding of Python further, now would be a good time to follow up with a more detailed tutorial. Here are some of the most accessible:

If you prefer to work on specific project instead of follow a tutorial, the Code Club website has several that are free to use.

Once you get a firm grasp of the basics, it helps to have some problems to try and solve. This is a list of some problem sets that can be fun to try and solve in Python:

Hopefully that will help you on your way to Python proficiency!

Dependency injection explained

Rob — Tue, 17 Sep 2024 15:18:04 +0000

Dependency injection (or DI as it is often abbreviated), is the act of passing the things a class depends on to it instead of letting that class source them itself. It is one way of achieving the Inversion of Control (or IoC) principle.

Lets take an example:

public class Foo
{
    public void DoStuff()
    {
        DoTheThing();
        DoTheOtherThing();

        var notifier = new Notifier();
        notifier.SendNotification("Blah");
    }
}

Here we have a class Foo, that uses an instance of class Notifier to send a notification. We say that Notifier is a dependency of Foo; Foo needs it to complete its work.

So what is wrong with this code?

Its not possible to know Foo depends on Notifier without looking at the implementation of Foo's methods.
Its not possible to unit test the DoStuff() method without also testing the SendNotification method of Notifier.

How does DI help us here?

DI makes dependcies explicit in the signature of a class's constructor or method calls.
DI allows us to easily pass in mock instances of dependencies during unit testing.

Let's apply DI to our earlier example:

public class Foo
    private readonly INotifier _notifier;

    public Foo(INotifier notifier)
    {
        _notifier = notifier
            ?? throw new ArgumentNullException(nameof(notifier));
    }

    public void DoStuff()
    {
        DoTheThing();
        DoTheOtherThing();
        _notifer.SendNotification("Blah");
    }

The first thing to observe is the notifier dependency is expressed as an interface. Classes should depend on abstractions not concrete types. We have made the INotifer dependency something that is passed to the class Foo instead of created by it. In this instance we have done it via the constructor. This is known as constructor injection.

It opens up a lot of flexibility for us as programmers. Firstly we can see from the constructor what dependencies this class has. Secondly we can vary the implementation we pass to the class, for example when we do unit testing, or as the result of some configuration option.

So what creates the INotifier instance that is passed to Foo? The client code that uses Foo is now responsible for that. So havent we just moved the problem? No. The client code is free to define it's dependencies via injection as well.

Taken to its logical conclusion then, the entry point to your program is now responsible for newing up all the dependencies in your program. This point in your code is known as a composition root.

Manually newing up all this can be tedious and error prone. It is here that the use of a dependency injection container is useful. A container allows you to register dependencies with it, and takes over the role of newing up things as they are requested.

Asp.Net Core is a good example of this in the .NET world. The container is configured at application startup. Dependencies are passed into your controller instances via their constructor, and so on down the classes.

DI is a very common technique in static languages. It allows great flexibility in configuring the behaviour of your application. It also helps us to unit test our code.

Programming Hangman in Python

Rob — Tue, 17 Sep 2024 15:15:29 +0000

For those that don't know, Hangman is a word guessing game traditionally played with pen and paper. A word is secretly picked, and the only thing known about it is the number of letters it has. The player than guesses a letter and, if it it's in the word, it's position is revealed. Incorrect guesses count against the player. If you guess the word you win, make too many wrong guesses and it's game over.

Right, now we all know what the game entails, let's see how this might look when played in Python.

Word: ---
Wrong guesses: 
Guess a letter > a

Word: -a-
Wrong guesses: 
Guess a letter > g

Word: -a-
Wrong guesses: g
Guess a letter > t

Word: -at
Wrong guesses: g
Guess a letter > c

Word: cat
Well done! You guessed the word with 1 wrong guesses.

Getting started

Let's start a new Python program to make this game. We'll need a word to guess and a way to keep track of correct and incorrect guesses.

word = "something"
guessed_letters = []
incorrect_letters = []

What's with the square brackets? That's Python speak for a new list. A list is a variable that can store more than one value. In this case we are going to store letters in the lists, but Python will let you put anything in there.

Our game is essentially going to be a loop that shows the player the parts of the word guessed so far, and then asks them for another guess. We can use a while loop to implement this. But what should our condition be for ending the loop? Well there are two reasons we would want to end the game:

The player has guessed all the correct letters.
The player has made too many wrong guesses.

The first condition is met when the number of letters in the guessed_letters list is the same as the number of letters in the word. So our loop needs to run while that is not the case. In Python this can be written as len(guessed_letters) != len(word). The len() function tells you the length of a list or string.

The second condition is met when the number of letters in the incorrect_letters list is more than the maximum number of allowed guesses. So our loop needs to also run while that is not the case. In Python this can be written as len(incorrect_letters) < MAX_WRONG_GUESSES. We'll add another variable to our program for the MAX_WRONG_GUESSES value.

Putting it all together, our while loop starts like this.

# Game loop.
MAX_WRONG_GUESSES = 5

while len(guessed_letters) != len(word) and len(incorrect_letters) < MAX_WRONG_GUESSES:

Inside our loop we will need to do four things:

Show the word to the player.
Show the list of wrong guesses.
Get a guess from the player.
Record whether the guess is correct or incorrect.

Let's tackle them in order.

Showing the word

We need to show the word to the player, but only the letters they have correctly guessed should be revealed. The rest of the letters should be replaced by a dash - character. Let's write a function that does this for us. It will take two arguments, the word to show and a list of correctly guessed letters.

def show_word(word, letters):
    print("Word: ", end="")
    for letter in word:
        if letter in letters:
            print(letter, end="")
        else:
            print("-", end="")
    print()

We loop over each letter in the word by using a for loop. We then check if the letter is in the list of letters using the in operator. If it is, we print it. If not, we print a dash instead. We use the end="" argument in the print calls to stop a newline from being printed.

Showing the wrong guesses

Let's write another function to show the wrong guesses. This one is much simpler than the last. It takes a single argument, the list of wrong guesses, and uses a for loop again to print out each one.

def show_wrong_guesses(guesses):
    print("Wrong guesses: ", end="")
    for letter in guesses:
        print(letter, end="")
    print()

Getting the player's guess

Our next function is going to get a guess from the player. To make sure that the player actually types something in we are going to use a while loop. We will keep asking them for a guess until they type one in. Finally a guess should just be a single letter, so we only return the first character they type in.

def get_letter():
    letter = ""
    while letter == "":
        letter = input("Guess a letter > ")
    return letter[0]

Recording the guess

Once we have a letter from the player we can decide which of our two lists we should add it too. If the letter is in the word, it is a correct guess. We can add it to the guessed_letters list using the append() method. If it is not in the word, it should be added to the incorrect_letters list. But we should also check if the letter has already been guessed before. We do this by checking if it is one of the lists with the in operator. (This way each guess is only recorded once.)

if letter in word and letter not in guessed_letters:
    guessed_letters.append(letter)
elif letter not in incorrect_letters:
    incorrect_letters.append(letter)

Finishing the game

Last but not least we need to display a suitable message to the player when the game loop ends. Depending on whether they guessed the word or not, the message will be one of success or failure. How do we know if they guessed the word correctly? The number of letters in the guessed_letters list will be the same length as the word.

# End of game message.
if len(guessed_letters) == len(word):
    show_word(word, guessed_letters)
    print(f"Well done! You guessed the word with {len(incorrect_letters)} wrong guesses.")
else:
    print(f"Too many wrong guesses! The word was '{word}'")

That's it! We have a complete game of Hangman. To make the game harder or easier, change the number of wrong guesses allowed.

Complete program listing

def show_word(word, letters):
    print("Word: ", end="")
    for letter in word:
        if letter in letters:
            print(letter, end="")
        else:
            print("-", end="")
    print()


def show_wrong_guesses(guesses):
    print("Wrong guesses: ", end="")
    for letter in guesses:
        print(letter, end="")
    print()


def get_letter():
    letter = ""
    while letter == "":
        letter = input("Guess a letter > ")
    return letter[0]


word = "something"
guessed_letters = []
incorrect_letters = []


# Game loop.
MAX_WRONG_GUESSES = 5

while len(guessed_letters) != len(word) and len(incorrect_letters) < MAX_WRONG_GUESSES:
    show_word(word, guessed_letters)
    show_wrong_guesses(incorrect_letters)
    letter = get_letter()
    if letter in word and letter not in guessed_letters:
        guessed_letters.append(letter)
    elif letter not in word and letter not in incorrect_letters:
        incorrect_letters.append(letter)

# End of game message.
if len(guessed_letters) == len(word):
    show_word(word, guessed_letters)
    print(f"Well done! You guessed the word with {len(incorrect_letters)} wrong guesses.")
else:
    print(f"Too many wrong guesses! The word was '{word}'")

Building a cache in Python

Rob — Tue, 17 Sep 2024 15:13:32 +0000

Caching. Useful stuff. If you're not familiar with it, it's a way to keep data around in memory (or on disk) for fast retrieval. Think of querying a database for some information. Rather than do that every time an application asks for data, we can do it once and keep the result in a cache. Subsequent calls for the data will return the copy from cache instead of making a database query. In theory this improves the performance of your application.

Let's build a simple cache for use in Python programs.

Cache API

I'll start by creating a new module called simplecache, and defining a class Cache in it. I'll not implement anything yet, I just want to define the API my cache will use.

class Cache:
    """ A simple caching class that works with an in-memory or file based
    cache. """


    def __init__(self, filename=None):
        """ Construct a new in-memory or file based cache."""
        pass


    def update(self, key, item, ttl=60):
        """ Add or update an item in the cache using the supplied key. Optional
        ttl specifies how many seconds the item will live in the cache for. """
        pass


    def get(self, key):
        """ Get an item from the cache using the specified key. """
        pass


    def remove(self, key):
        """ Remove an item from the cache using the specified key. """
        pass


    def purge(self, all=False):
        """ Remove expired items from the cache, or all items if flag is set. """
        pass


    def close(self):
        """ Close the underlying connection used by the cache. """
        pass

So far so good. We can tell the cache to create a new in-memory or file based cache via the __init__ method. We can add items to the cache using update - which will overwrite the item if it already exists. We can get an item using a key get. Finally we can remove items by key remove, or empty the cache of expired items using purge (which optionally allows purging all items).

Where to cache the data?

So where is this class going to cache data? Sqlite ships with the Python standard library, and is ideal for this sort of thing. In fact one of the suggested use cases for Sqlite is caching. It allows us to create an in-memory or file based SQL database, which is both our use cases covered. Let's design a SQL table that can hold our cached data.

CREATE TABLE 'Cache' (
    'Key' TEXT NOT NULL UNIQUE,
    'Item' BLOB NOT NULL,
    'CreatedOn' TEXT NOT NULL,
    'TimeToLive' TEXT NOT NULL,
    PRIMARY KEY("Key"))
);

To break this down, we have a table called Cache that has four fields. The Key is a string, and will act as a unique primary key on the table. Next up our Item field is a blob of binary data - I'm thinking here that we will serialise objects added to the cache before saving them in the database. The last two fields are used to determine the lifetime of the item in the cache - CreatedOn is the timestamp of when the item was added, and TimeToLive is the length of time we need to hang on to the item for.

Constructing the cache

Let's start by importing the Sqlite library into our module.

import sqlite3

Then we need to turn our attention to the __init__ method. We have two scenarios to support: one where we are given a filename, and one where we are not.

def __init__(self, filename=None):
    """ Construct a new in-memory or file based cache."""
    if filename is None:
        self._connection = sqlite3.connect(":memory:")
    else:
        self._connection = sqlite3.connect(filename)
    self._create_schema()

We can open a connection and keep it around for the lifetime of the class. Therefore we set the self._connection property to hold the connection instance, before calling an internal method _create_schema (more on that in a little while).

Bootstrapping the schema

If we are using an in-memory database, then our schema will not exist yet. However for file based databases that may not be the case. This may be an existing file that has already been setup with our schema. Let's see the code that handles this process.

def _create_schema(self):
    table_name = "Cache"
    cursor = self._connection.cursor()
    result = cursor.execute(
        "SELECT name FROM sqlite_master WHERE type = 'table' and name = ?",
        (table_name,))
    cache_exists = result.fetchone() is not None
    if cache_exists:
        return    
    sql = """
        CREATE TABLE 'Cache' (
        'Key' TEXT NOT NULL UNIQUE,
        'Item' BLOB NOT NULL,
        'CreatedOn' TEXT NOT NULL,
        'TimeToLive' TEXT NOT NULL,
        PRIMARY KEY('Key'))
    """
    cursor.execute(sql)
    cursor.close()

First we define our table name and open a cursor to perform some database operations. Next we check for the existence of our table in the master table. If it's there we exit the method, otherwise we execute a CREATE TABLE... statement to build our table in the database.

We can now instantiate our Cache class with either an in-memory or file based database to cache objects in.

Adding to the cache

Let us now turn our attention to adding items to the cache. Recall our Update method from our API will be responsible for this. If a key already exists in the cache, we are going to replace its entry with whatever is supplied.

def update(self, key, item, ttl=60):
    """ Add or update an item in the cache using the supplied key. Optional
    ttl specifies how many seconds the item will live in the cache for. """
    sql = "SELECT Key FROM 'Cache' WHERE Key = ?"
    cursor = self._connection.cursor()
    result = cursor.execute(sql, (key,))
    row = result.fetchone()
    if row is not None:
        sql = "DELETE FROM 'Cache' WHERE Key = ?"
        cursor.execute(sql, (key,))
        connection.commit()
    sql = "INSERT INTO 'Cache' values(?, ?, datetime(), ?)"
    pickled_item = pickle.dumps(item)
    cursor.execute(sql, (key, pickled_item, ttl))
    self._connection.commit()
    cursor.close()

First we get the in-memory database connection. We then test for the existence of the the supplied key value in the cache. If it exists, it is removed from the cache. Next we pickle the supplied item value, turning it into a binary blob. We then insert the key, picked item, and ttl into the cache.

Getting data from the cache

Our behaviour for getting an item from the cache is mostly straight forward. We look for an entry with the specified key and unpickle the associated item. The complication in this process arises when the ttl value has expired. That is, the date of creation plus the ttl are less than the current time. If this is the case, then the item has expired and should be removed from the cache.

There is a philosophical issue with this method. There is a school of thought that says methods should either return a value (read) or perform a mutation of data (write). Here we are potentially doing both. We are deliberately introducing a side effect (deleting an expired item). I think it is OK in this case, but other programmers might argue otherwise.

def get(self, key):
    """ Get an item from the cache using the specified key. """
    sql = "SELECT Item, CreatedOn, TimeToLive FROM 'Cache' WHERE Key = ?"
    cursor = self._connection.cursor()
    result = cursor.execute(sql, (key,))
    row = result.fetchone()
    if row is None:
        return
    item = pickle.loads(row[0])
    expiry_date = datetime.datetime.fromisoformat(row[1]) + datetime.timedelta(seconds=int(row[2]))
    now = datetime.datetime.now()
    if expiry_date <= now:
        sql = "DELETE FROM 'Cache' WHERE Key = ?"
        cursor.execute(sql, (key,))
        self._connection.commit()
        item = None
    cursor.close()
    return item

Removing and purging items in the cache

Removing an item is simple - in fact we have already done it (twice) in our other two methods. That's an ideal candidate for refactoring (which we will look at later on). For now, we will implement the method directly.

def remove(self, key):
    """ Remove an item from the cache using the specified key. """
    sql = "DELETE FROM 'Cache' WHERE Key = ?"
    cursor = self._connection.cursor()
    cursor.execute(sql, (key,))
    self._connection.commit()
    cursor.close()

Purging items is a little more complex. We have two scenarios to support - purging all items and purging only expired items. Let's see how we can achieve this.

def purge(self, all=False):
    """ Remove expired items from the cache, or all items if flag is set. """
    cursor = self._connection.cursor()
    if all:
        sql = "DELETE FROM 'Cache'"
        cursor.execute(sql)
        self._connection.commit()
    else:
        sql = "SELECT Key, CreatedOn, TimeToLive from 'Cache'"
        for row in cursor.execute(sql):
            expiry_date = datetime.datetime.fromisoformat(row[1]) + datetime.timedelta(seconds=int(row[2]))
            now = datetime.datetime.now()
            if expiry_date <= now:
                sql = "DELETE FROM 'Cache' WHERE Key = ?"
                cursor.execute(sql, (key,))
                self._connection.commit()
    cursor.close()

Deleting all is simple enough. We simply run SQL to delete everything in our Cache table. For the expired only items we need to loop through each row, compute the expiry date, and determine if it should be deleted. Again, this latter piece of code has been repeated from one of our other methods (get in this case). Another candidate for refactoring.

Refactoring

We have a working cache implementation that satisfies our original API specification. There is however some repeated code, which we can factor out into their own methods. Lets start with the delete logic that is present in get, update, remove, and purge methods. These instances can all be replaced with a call to the following new method.

def _remove_item(self, key, cursor):
    sql = "DELETE FROM 'Cache' WHERE Key = ?"
    cursor.execute(sql, (key,))
    cursor.connection.commit()

We can see this has a big impact on our code. Four other methods are now calling the one common _remove_item method. Next let's take a look at the expiry date checking code.

def _item_has_expired(self, created, ttl):
    expiry_date = datetime.datetime.fromisoformat(created) + datetime.timedelta(seconds=int(ttl))
    now = datetime.datetime.now()
    return expiry_date <= now


def get(self, key):
    """ Get an item from the cache using the specified key. """
    sql = "SELECT Item, CreatedOn, TimeToLive FROM 'Cache' WHERE Key = ?"
    cursor = self._connection.cursor()
    result = cursor.execute(sql, (key,))
    row = result.fetchone()
    if row is None:
        return
    item = pickle.loads(row[0])
    if self._item_has_expired(row[1], row[2]):
        self._remove_item(key, cursor)
        item = None
    cursor.close()
    return item


def purge(self, all=False):
    """ Remove expired items from the cache, or all items if flag is set. """
    cursor = self._connection.cursor()
    with self.__class__.lock:
        if all:
            sql = "DELETE FROM 'Cache'"
            cursor.execute(sql)
            self._connection.commit()
        else:
            sql = "SELECT Key, CreatedOn, TimeToLive from 'Cache'"
            for row in cursor.execute(sql):
                if self._item_has_expired(row[1], row[2]):
                    self._remove_item(row[0], cursor)
    cursor.close()

Great. That's two more places we have reduced code repetition in.

Thread safety with locks

We are almost done. For this to be a robust class, we need to ensure we are thread safe. Caches can often surface as singleton instances in an application, so thread safety is important. We will achieve this by using locks around the destructive cache operations. This is how our whole class looks with locking added. Note the with blocks around the add and delete operations. These ensure the lock is released even if something goes wrong.

#! /usr/bin/env python3


import datetime
import pickle
import sqlite3
import threading


class Cache:
    """ A simple caching class that works with an in-memory or file based
    cache. """

    _lock = threading.Lock()

    def __init__(self, filename=None):
        """ Construct a new in-memory or file based cache."""
        if filename is None:
            self._connection = sqlite3.connect(":memory:")
        else:
            self._connection = sqlite3.connect(filename)
        self._create_schema()


    def _create_schema(self):
        table_name = "Cache"
        cursor = self._connection.cursor()
        result = cursor.execute(
            "SELECT name FROM sqlite_master WHERE type = 'table' and name = ?",
            (table_name,))
        cache_exists = result.fetchone() is not None
        if cache_exists:
            return    
        sql = """
            CREATE TABLE 'Cache' (
            'Key' TEXT NOT NULL UNIQUE,
            'Item' BLOB NOT NULL,
            'CreatedOn' TEXT NOT NULL,
            'TimeToLive' TEXT NOT NULL,
            PRIMARY KEY('Key'))
        """
        cursor.execute(sql)
        cursor.close()


    def update(self, key, item, ttl=60):
        """ Add or update an item in the cache using the supplied key. Optional
        ttl specifies how many seconds the item will live in the cache for. """
        sql = "SELECT Key FROM 'Cache' WHERE Key = ?"
        cursor = self._connection.cursor()
        result = cursor.execute(sql, (key,))
        row = result.fetchone()
        with self.__class__._lock:
            if row is not None:
                self._remove_item(key, cursor)
            sql = "INSERT INTO 'Cache' values(?, ?, datetime(), ?)"
            pickled_item = pickle.dumps(item)
            cursor.execute(sql, (key, pickled_item, ttl))
            self._connection.commit()
        cursor.close()


    def _remove_item(self, key, cursor):
        sql = "DELETE FROM 'Cache' WHERE Key = ?"
        cursor.execute(sql, (key,))
        cursor.connection.commit()


    def get(self, key):
        """ Get an item from the cache using the specified key. """
        sql = "SELECT Item, CreatedOn, TimeToLive FROM 'Cache' WHERE Key = ?"
        cursor = self._connection.cursor()
        result = cursor.execute(sql, (key,))
        row = result.fetchone()
        if row is None:
            return
        item = pickle.loads(row[0])
        if self._item_has_expired(row[1], row[2]):
            with self.__class__._lock:
                self._remove_item(key, cursor)
            item = None
        cursor.close()
        return item


    def _item_has_expired(self, created, ttl):
        expiry_date = datetime.datetime.fromisoformat(created) + datetime.timedelta(seconds=int(ttl))
        now = datetime.datetime.now()
        return expiry_date <= now


    def remove(self, key):
        """ Remove an item from the cache using the specified key. """
        cursor = self._connection.cursor()
        with self.__class__._lock:
            self._remove_item(key, cursor)
        cursor.close()


    def purge(self, all=False):
        """ Remove expired items from the cache, or all items if flag is set. """
        cursor = self._connection.cursor()
        with self.__class__._lock:
            if all:
                sql = "DELETE FROM 'Cache'"
                cursor.execute(sql)
                self._connection.commit()
            else:
                sql = "SELECT Key, CreatedOn, TimeToLive from 'Cache'"
                for row in cursor.execute(sql):
                    if self._item_has_expired(row[1], row[2]):
                        with self.__class__._lock:
                            self._remove_item(row[0], cursor)
        cursor.close()


    def close(self):
        """ Close the underlying connection used by the cache. """
        self._connection.close()

Testing the cache

Time to test our cache. We can do this be spinning up an interactive session as follows.

python -i simplecache.py

Now we can new up an in-memory cache and test our methods.

>>> c = Cache()
>>> c.update("key", "some value")
>>> c.update("key2", [1, 2, 3], 300)
>>> c.get("key")
'some vlaue'
>>> c.remove("key")
>>> c.purge()
>>> c.get("key2")
[1, 2, 3]
>>> c.purge(True)
>>> c.get("key2")
>>> c.close()
>>>

Exercises for the reader

Write a suite of unit tests for the Cache class. How easy is it to test? Do you need to make any changes to accommodate testing?
Make the time to live a sliding window instead of a fixed time. That is, whenever an item is retrieved from the cache, its time to live value starts over.
Add a method to write the contents of the cache out to the screen.

Rock, paper, scissors, fight!

Rob — Tue, 17 Sep 2024 15:10:03 +0000

Rock, paper, scissors is a great game. Simple to grasp, yet surprisingly complex in terms of strategy. It's an ideal coding challenge to write a computer player capable of consistently winning the game. First though, we need a way to play the game.

Representing the game

We start with two players:

PLAYER1 = 1
PLAYER2 = 2

We then have three choices to play each round:

ROCK = 3
PAPER = 4
SCISSORS = 5

And a set of possible outcomes:

WIN = 6
LOSE = 7
DRAW = 8

With these symbols in place we can model the game state. That is, every possible way a round can end. Let us do this using a Python dictionary, mapping the two player choices (as a tuple) to the game outcome.

GAME_STATES = {
    (ROCK, PAPER): LOSE,
    (ROCK, SCISSORS): WIN,
    (ROCK, ROCK): DRAW
    (PAPER, SCISSORS): LOSE,
    (PAPER, ROCK): WIN,
    (PAPER, PAPER): DRAW,
    (SCISSORS, ROCK): LOSE,
    (SCISSORS, PAPER): WIN,
    (SCISSORS, SCISSORS): DRAW
}

Now we can write a simple function to play one round of the game. We are going to assume each player is an instance of a class that we will define later. For now it is enough to know how this class is called, if not how it will be implemented.

def play_round(p1, p2):
    """ Play one round of the game with the two supplied players. """
    p1_choice = p1.pick()
    p2_choice = p2.pick()
    p1_outcome = GAME_STATES[(p1_choice, p2_choice)]
    p2_outcome = GAME_STATES[(p2_choice, p1_choice)]
    p1.record((p1_choice, p2_choice, p1_outcome))
    p2.record((p2_choice, p1_choice, p2_outcome))
    winner = 0
    if p1_outcome == WIN:
        winner = PLAYER1
    elif p2_outcome == WIN:
        winner = PLAYER2
    return winner

The game round is very simple. We ask each player object to pick a choice to play. We then lookup the result for each player in the GAME_STATES dictionary. We ask each player object to record the result of the game. Finally we return the winner to the caller, or zero if there was a draw.

So what does a player look like? First we define a base class to perform some common initialisation, and recording of the game round data.

class Player:
    """ Base class for a player of the game. """
    def __init__(self, name):
        self.name = name
        self.history = []


    def pick(self):
        """Return one of the three choices: ROCK, PAPER, SCISSORS."""
        raise NotImplementedError()


    def record(self, game_details):
        """Record the details of the round."""
        self.history.append(game_details)

Next we can inherit from this class and implement our picking strategy. Here we have a player that always plays ROCK:

class AlwaysRockPlayer(Player):
    """ Player who always chooses ROCK. """
    def pick(self):
        return ROCK

Not a great strategy I'm sure you'll agree, but we start with the simplest thing we can do. Let's write a slightly more complex player for our rock steady one to go up against:

class RandomPlayer(Player):
    """ Player who always makes a random choice. """
    def pick(self):
        import random
        random.seed()
        return random.randint(ROCK, SCISSORS)

That at least gives us some variety in proceedings! It's still a very simple player though, as it ignores the game history completely. Let's pit these two players against each other in a few rounds.

>>> p1 = AlwaysRockPlayer("The Rock")
>>> p2 = RandomPlayer("Random Rick")
>>> play_round(p1, p2)
0
>>> play_round(p1, p2)
1
>>> play_round(p1, p2)
2
>>> play_round(p1, p2)
2
>>> play_round(p1, p2)
1

OK, so things are working. But to really get a feel for how they perform we need to run them for longer. Let's write a quick loop to run a 100 rounds between these two fearsome opponents:

>>> results = []
>>> for i in range(1,101):
...     results.append(play_round(p1, p2))
...     print(results[i-1], end='')
...     if i % 10 == 0:
...             print()
...
0102201112
0112202100
0121012101
1211200212
0110021121
0000120222
0102000202
2020021110
1112010101
1121020010

Better. A quick tot up of the results shows that... player 1 is the winner! Who'd have thought always playing ROCK was a viable game strategy? OK, so the rock's random opponent is a little dumb in this regard. A human player would soon spot the pattern and counter it consistently. We need better players, and a proper arena for them to duel it out in.

New Arena

The new arena will play a game over several rounds between two players. It will print the game statistics at the end, so we can easily see how well each player has performed. The new code makes use of our existing play_round function, and the code is given below:

def play_game(p1, p2, rounds=100):
    """ Play several rounds of the game, reporting statistics at the end. """
    print(f"{p1.name} vs {p2.name}")
    results = []
    for i in range(rounds):
        results.append(play_round(p1, p2))
        print(".", end="")
    p1_total = len([x for x in results if x == PLAYER1])
    p2_total = len([x for x in results if x == PLAYER2])
    no_total = len([x for x in results if x == 0])
    total = float(len(results))
    print("")
    print(f"{p1.name}: {(p1_total / total) * 100}%")
    print(f"{p2.name}: {(p2_total / total) * 100}%")
    print(f"Drawn games: {(no_total / total) * 100}%")

Let's pit our two players against each other in this new arena and see if The Rock can retain its crown.

>>> p1 = AlwaysRockPlayer("The Rock")
>>> p2 = RandomPlayer("Random Rick")
>>> play_game(p1, p2)
The Rock vs Random Rick
....................................................................................................
The Rock: 39.0%
Random Rick: 31.0%
Drawn games: 30.0%
>>>

A more even spread this time. Let's try running for a 1000 rounds and see if that makes a difference.

>>> play_game(p1, p2, 1000)
The Rock vs Random Rick
........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
The Rock: 34.300000000000004%
Random Rick: 34.5%
Drawn games: 31.2%
>>>

Huh, a much more even spread. In fact this is what we should have expected. With The Rock always picking, well, ROCK, the variation we are seeing is solely down to Random Rick. If the PRNG (pseudo random number generator) in Python is any good, it'll be picking each choice roughly equally. The more rounds we play, the closer to an even split we would get.

No two ways about it, we still need a smarter player.

Remembering

We need a player that can learn from history without becoming predictable. But how to do that? Instead of picking a choice at random, the player picks an entry from its history at random. Then it plays whatever would have beaten its opponent in that round. In theory, if the opponent is playing one choice more than the others, this should give us the edge.

Let's see what that looks like in code:

class RandomHistoryPlayer(Player):
    """ Player who picks at random from historical options of their opponent. """
    BEATEN_BY = {
        ROCK: PAPER,
        PAPER: SCISSORS,
        SCISSORS: ROCK
    }

    def pick(self):
        import random
        random.seed()
        total_rounds = len(self.history)
        if total_rounds == 0:    
            choice = random.randint(ROCK, SCISSORS)
        else:
            idx = random.randint(0, len(self.history) - 1)
            opponents_choice = self.history[idx][1]
            choice = self.__class__.BEATEN_BY[opponents_choice]
        return choice

When playing the first round, we don't have any history to work from, so we fallback to playing at random.

OK, moment of truth. Hoe does it perform?

>>> p1 = RandomHistoryPlayer("Historical Henry")
>>> p2 = AlwaysRockPlayer("The Rock")
>>> play_game(p1, p2)
Historical Henry vs The Rock
....................................................................................................
Historical Henry: 99.0%
The Rock: 0.0%
Drawn games: 1.0%
>>>

It obliterates The Rock. With the exception of the random choice it makes first round, it won every other game. How does it perform against Random Rick?

>>> p1 = RandomHistoryPlayer("Historic Henry")
>>> p2 = RandomPlayer("Random Rick")
>>> play_game(p1, p2)
Historic Henry vs Random Rick
....................................................................................................
Historic Henry: 32.0%
Random Rick: 41.0%
Drawn games: 27.0%
>>>

Oh dear. Best of three? So it fails against a purely random opponent. Surely we can do better?

Forgetting

The trouble with remembering everything is you can get stuck in old ways of thinking. We humans have learnt to forget, or at least discount, things that happened in the dim distant past. What we need is a way to weight the historical results, so that more recent games have a greater influence. Yes, that ought to do it. I'm sure this will give us the intelligent player we seek.

class WeightedHistoryPlayer(Player):
    """ Computer player that linearly weights the past opponents choices. """
    BEATEN_BY = {
        ROCK: PAPER,
        PAPER: SCISSORS,
        SCISSORS: ROCK
    }


    def pick(self):
        import random
        random.seed()
        total_rounds = len(self.history)
        if total_rounds == 0:
            choice = random.randint(ROCK, SCISSORS)
        else:
            weighted_outcomes = [(i / total_rounds, o) for i, o in enumerate(self.history)]
            totals = { ROCK: 0, PAPER: 0, SCISSORS: 0 }
            totals[ROCK] = sum([w for (w,o) in weighted_outcomes if o[1] == ROCK])
            totals[PAPER] = sum([w for (w,o) in weighted_outcomes if o[1] == PAPER])
            totals[SCISSORS] = sum([w for (w,o) in weighted_outcomes if o[1] == SCISSORS])
            opponents_choice = max(totals, key=totals.get)
            choice = self.__class__.BEATEN_BY[opponents_choice]
        return choice

Is it better than Historical Henry?

>>> p1 = WeightedHistoryPlayer("Forgetful Fiona")
>>> p2 = RandomHistoryPlayer("Historical Henry")
>>> play_game(p1, p2)
Forgetful Fiona vs Historical Henry
....................................................................................................
Forgetful Fiona: 43.0%
Historical Henry: 43.0%
Drawn games: 14.000000000000002%
>>>

A dead heat! How about taking on the current champion Random Rick?

>>> p1 = WeightedHistoryPlayer("Forgetful Fiona")
>>> p2 = RandomPlayer("Random Rick")
>>> play_game(p1, p2)
Forgetful Fiona vs Random Rick
....................................................................................................
Forgetful Fiona: 35.0%
Random Rick: 38.0%
Drawn games: 27.0%
>>>

Drat! Random Rick still retains his crown. We need something else.

Looking for patterns

There must be a pattern in Random Rick that we can exploit. Despite his seemingly random nature, I suspect he is harbouring predictable patterns. How can we write a player to take advantage of them?

N-grams can allow us to look for recurring sequences of symbols. Think of it as a sliding window over the opponents choices. We look at n choices, and then record what the n+1 choice was. Lets show an example using trigrams (n-grams of size 3).

Sequence of opponents moves:

ROCK ROCK PAPER SCISSORS ROCK ROCK ROCK PAPER SCISSORS ROCK ROCK PAPAER

Trigrams:

    ROCK ROCK PAPER     -> SCISSORS
    ROCK PAPER SCISSORS -> ROCK
    PAPER SCISSORS ROCK -> ROCK
    SCISSORS ROCK ROCK  -> ROCK
    ROCK ROCK ROCK      -> PAPER
    ROCK ROCK PAPER     -> SCISSORS
    ROCK PAPER SCISSORS -> ROCK
    PAPER SCISSORS ROCK -> ROCK
    SCISSORS ROCK ROCK  -> PAPER

To predict the next move the opponent makes given the example above, we would look at the latest trigram in the sequence - ROCK ROCK PAPER, look it up in the list of trigrams, and see what has previously come next - SCISSORS. We would play whatever beats that choice, in this case ROCK.

Lets look at some code for this strategy:

class TrigramPlayer(Player):
    """ Computer player that uses trigrams to look for patterns in the opponents choices. """
    BEATEN_BY = {
        ROCK: PAPER,
        PAPER: SCISSORS,
        SCISSORS: ROCK
    }


    def __init__(self, id):
        super().__init__(id)
        self.trigrams = {}


    def pick(self):
        import random
        random.seed()
        total_rounds = len(self.history)
        if total_rounds < 4:
            choice = random.randint(ROCK, SCISSORS)
        else:
            sequence = [x[1] for x in self.history]
            current_trigram = tuple(sequence[-4:-1])
            previous_choices = self.trigrams.get(current_trigram, [])
            if len(previous_choices) > 1:
                idx = random.randint(0, len(previous_choices) - 1)
                choice = previous_choices[idx]
            else:
                choice = random.randint(ROCK, SCISSORS)
        return choice


    def record(self, game_details):
        super().record(game_details)
        round_num = len(self.history)
        if round_num > 3:
            sequence = [x[1] for x in self.history]
            trigram = tuple(sequence[-4:-1])
            choice = sequence[-1]
            targets = self.trigrams.get(trigram, [])
            targets.append(choice)
            self.trigrams[trigram] = targets

We allow some randomness to creep in here:

When we have more than one match for our current trigram.
Before round 4, as there simply isn't enough data to build a trigram entry.
If we don't find a match in the trigram dictionary.

OK, in at the deep end. How does it perform against Random Rick?

>>> p1 = TrigramPlayer("Trigram Tracy")
>>> p2 = RandomPlayer("Random Rick")
>>> play_game(p1, p2)
Trigram Tracy vs Random Rick
....................................................................................................
Trigram Tracy: 31.0%
Random Rick: 34.0%
Drawn games: 35.0%
>>>

I give up. It seems that as far as rock, paper, scissors goes, randomness is the winning strategy.

Only human

So looking for patterns in the choices of Random Rick failed. But can Trigram Tracy find subconscious patterns in the pinnacle of intellect? Not ChatGPT, a human.

Let us write a human player class to interactively prompt for input.

class HumanPlayer(Player):
    """ Human player at a keyboard. """
    CHAR_2_INT = { "r": ROCK, "p": PAPER, "s": SCISSORS }


    def pick(self):
        choice = ""
        while choice not in ['r', 'p', 's']:
            choice = input("(r)ock, (p)aper, or (s)cissors? ")
        return self.__class__.CHAR_2_INT[choice]

Lets see who will win:

>>> p1 = HumanPlayer("Human Rob")
>>> p2 = TrigramPlayer("Trigram Tracy")
>>> play_game(p1, p2)
Human Rob vs Trigram Tracy

... cut lots of prompts for choices ...

Human Rob: 32.0%
Trigram Tracy: 32.0%
Drawn games: 36.0%

Well there you have it. I'm officially as intelligent as a short Python script when it comes to playing Rock, Paper, Scissors. Hardly a ringing endorsement of our AI either.

What have we learnt

There are a lot of possible strategies for playing rock, paper, scissors. Some simple, some more complex. We have learnt that a player picking at random can defeat a more sophisticated artificial intelligence, by virtue of being unpredictable.

Out of curiosity let's ask the font of all modern knowledge - ChatGPT - what it thinks is the best strategy to adopt for playing Rock, Paper, Scissors:

The best strategy for playing Rock, Paper, Scissors against a computer opponent is to play as randomly as possible. This is because computer programs often build strategies based on your play patterns or draw techniques from a massive database of previously recorded rounds. By picking your answer blindly, you render the program’s collected patterns about your behavior useless, and should be able to tie the machine in the long run.

Sometimes being clever is over rated!

Complete program listing

#! /usr/bin/env python3


# Players.
PLAYER1 = 1
PLAYER2 = 2


# Choices.
ROCK = 3
PAPER = 4
SCISSORS = 5


# Outcomes.
WIN = 6
LOSE = 7
DRAW = 8


# All possible game states.
GAME_STATES = {
    (ROCK, PAPER) : LOSE,
    (ROCK, SCISSORS) : WIN,
    (ROCK, ROCK) : DRAW,
    (PAPER, SCISSORS) : LOSE,
    (PAPER, ROCK) : WIN,
    (PAPER, PAPER) : DRAW,
    (SCISSORS, ROCK) : LOSE,
    (SCISSORS, PAPER) : WIN,
    (SCISSORS, SCISSORS) : DRAW
}


class Player:
    """ Base class for a player of the game. """
    def __init__(self, name):
        self.name = name
        self.history = []


    def pick(self):
        """Return one of the three choices: ROCK, PAPER, SCISSORS."""
        raise NotImplementedError()


    def record(self, game_details):
        """Record the details of the round."""
        self.history.append(game_details)


class AlwaysRockPlayer(Player):
    """ Player who always chooses ROCK. """
    def pick(self):
        return ROCK


class RandomPlayer(Player):
    """ Player who always makes a random choice. """
    def pick(self):
        import random
        random.seed()
        return random.randint(ROCK, SCISSORS)


class RandomHistoryPlayer(Player):
    """ Player who picks at random from historical options of their opponent. """
    BEATEN_BY = {
        ROCK: PAPER,
        PAPER: SCISSORS,
        SCISSORS: ROCK
    }


    def pick(self):
        import random
        random.seed()
        total_rounds = len(self.history)
        if total_rounds == 0:    
            choice = random.randint(ROCK, SCISSORS)
        else:
            idx = random.randint(0, len(self.history) - 1)
            opponents_choice = self.history[idx][1]
            choice = self.__class__.BEATEN_BY[opponents_choice]
        return choice


class WeightedHistoryPlayer(Player):
    """ Computer player that linearly weights the past opponents choices. """
    BEATEN_BY = {
        ROCK: PAPER,
        PAPER: SCISSORS,
        SCISSORS: ROCK
    }


    def pick(self):
        import random
        random.seed()
        total_rounds = len(self.history)
        if total_rounds == 0:
            choice = random.randint(ROCK, SCISSORS)
        else:
            weighted_outcomes = [(i / total_rounds, o) for i, o in enumerate(self.history)]
            totals = { ROCK: 0, PAPER: 0, SCISSORS: 0 }
            totals[ROCK] = sum([w for (w,o) in weighted_outcomes if o[1] == ROCK])
            totals[PAPER] = sum([w for (w,o) in weighted_outcomes if o[1] == PAPER])
            totals[SCISSORS] = sum([w for (w,o) in weighted_outcomes if o[1] == SCISSORS])
            opponents_choice = max(totals, key=totals.get)
            choice = self.__class__.BEATEN_BY[opponents_choice]
        return choice


class TrigramPlayer(Player):
    """ Computer player that uses trigrams to look for patterns in the opponents choices. """
    BEATEN_BY = {
        ROCK: PAPER,
        PAPER: SCISSORS,
        SCISSORS: ROCK
    }


    def __init__(self, id):
        super().__init__(id)
        self.trigrams = {}


    def pick(self):
        import random
        random.seed()
        total_rounds = len(self.history)
        if total_rounds < 4:
            choice = random.randint(ROCK, SCISSORS)
        else:
            sequence = [x[1] for x in self.history]
            current_trigram = tuple(sequence[-4:-1])
            previous_choices = self.trigrams.get(current_trigram, [])
            if len(previous_choices) > 1:
                idx = random.randint(0, len(previous_choices) - 1)
                choice = previous_choices[idx]
            else:
                choice = random.randint(ROCK, SCISSORS)
        return choice


    def record(self, game_details):
        super().record(game_details)
        round_num = len(self.history)
        if round_num > 3:
            sequence = [x[1] for x in self.history]
            trigram = tuple(sequence[-4:-1])
            choice = sequence[-1]
            targets = self.trigrams.get(trigram, [])
            targets.append(choice)
            self.trigrams[trigram] = targets


class HumanPlayer(Player):
    """ Human player at a keyboard. """
    CHAR_2_INT = { "r": ROCK, "p": PAPER, "s": SCISSORS }


    def pick(self):
        choice = ""
        while choice not in ['r', 'p', 's']:
            choice = input("(r)ock, (p)aper, or (s)cissors? ")
        return self.__class__.CHAR_2_INT[choice]


def play_round(p1, p2):
    """ Play one round of the game with the two supplied players. """
    p1_choice = p1.pick()
    p2_choice = p2.pick()
    p1_outcome = GAME_STATES[(p1_choice, p2_choice)]
    p2_outcome = GAME_STATES[(p2_choice, p1_choice)]
    p1.record((p1_choice, p2_choice, p1_outcome))
    p2.record((p2_choice, p1_choice, p2_outcome))
    winner = 0
    if p1_outcome == WIN:
        winner = PLAYER1
    elif p2_outcome == WIN:
        winner = PLAYER2
    return winner


def play_game(p1, p2, rounds=100):
    """ Play several rounds of the game, reporting statistics at the end. """
    print(f"{p1.name} vs {p2.name}")
    results = []
    for i in range(rounds):
        results.append(play_round(p1, p2))
        print(".", end="")
    p1_total = len([x for x in results if x == PLAYER1])
    p2_total = len([x for x in results if x == PLAYER2])
    no_total = len([x for x in results if x == 0])
    total = float(len(results))
    print("")
    print(f"{p1.name}: {(p1_total / total) * 100}%")
    print(f"{p2.name}: {(p2_total / total) * 100}%")
    print(f"Drawn games: {(no_total / total) * 100}%")

Forem: Rob

The four pillars of OOP using a WW2 Sherman Tank

The Sherman tank in British service

Modelling the Sherman tank in British service

Time for an upgrade

Working together

Home for tea and medals

Setting up Windows for Lua development

Installing Lua

Adding to your PATH

Configuring Visual Studio Code

Debugging support

How to structure a solution in .NET

Assumptions

Domain

Infrastructure.Sql

Web UI configuration file

Database migrations

Web UI

Application

Architecture

Fizz-Buzz

Zero, one, or many?

Beginners guide to Python

What is this article?

A joke

Hello, world!

Did it work?

What's with the funny looking first line?

Printing other things

Asking questions

What just happened?

Making decisions

Making more than one decision

Making a game

An algorithm

The computer's choice

The player's choice

Types of things

Showing both choices

Winners and losers

Reviewing our game

Only once

Invalid input

Improving the code

Making improvements

An algorithm for getting the player's choice

Asking variables questions

Repeating code with while

Writing our own function

Writing the choice to word function

Play again?

A better computer player

Retrospective

What exactly is Python?

How much should I know?

Limitations of trinket.io

Further learning

Dependency injection explained

Programming Hangman in Python

Getting started

Showing the word

Showing the wrong guesses

Getting the player's guess

Recording the guess

Finishing the game

Complete program listing

Building a cache in Python

Cache API

Where to cache the data?

Constructing the cache

Bootstrapping the schema

Adding to the cache

Getting data from the cache

Removing and purging items in the cache

Refactoring

Thread safety with locks

Testing the cache

Exercises for the reader

Rock, paper, scissors, fight!

Repeating code with `while`

Limitations of `trinket.io`