Basics

Python is a language with very powerful data types. Once you know them you can achieve a great deal in only a few lines of code.

Balladeer is a domain-specific framework which will help you structure your code in order to best tell your story. It’s a simple object-oriented library with about a dozen classes in total.

Here are two which are fundamental to the Balladeer philosophy. We will see them in use soon. So let’s get some detail on them before we proceed further.

States

Whatever the genre of your narrative, it’s a safe bet that the characters you create will undergo change.

They may advance in their profession, lose weight, take up sewing, get drenched in a rainstorm, or disappear never to be seen again.

In Balladeer, you can model all these by defining and allocating State.

class balladeer.lite.types.State

A mix-in for Python’s standard enum.Enum.

Adds some convenient properties to help formatting state values as strings.

property label: str

Gives a consistent string to be used as a label even when the class defines multiple synonyms for each state value.

By way of example, here’s how you might create a state for political affiliation in the UK.

    class Politics(State, enum.Enum):
        con = ["Conservative", "Tory"]
        dem = ["Liberal Democrat", "LibDem"]
        grn = ["Green Party", "Green"]
        ind = ["Independent"]
        lab = ["Labour", "New Labour"]
        lib = ["Liberal"]
        ref = ["Reform Party"]
        res = ["Residents' Party"]
        ukp = ["UKIP", "UK Independence Party"]

Note how this class captures synonyms for the various parties. The label property gives you a preferred term for each one:

>>> Politics.ukp.label
'UKIP'

Grouping

Whether you are modelling a forest glade, a castle dungeon, or an alien space fleet, you will need to create objects for that model.

The next challenge is to organize those objects, sorting and filtering them so that you can isolate the ones you need to operate on (ie: modify their states).

This is what Grouping is for.

class balladeer.lite.types.Grouping

A subclass of Python’s standard defaultdict.

This data structure is used to return objects filtered, sorted, and grouped in a particular fashion, eg: by state or type.

classmethod typewise(items: list) defaultdict

Create a Grouping of items according to their type.

>>> pprint.pprint(Grouping.typewise([0, 1, 0.0, 1.0, True, False, None]))
Grouping(
    <class 'list'>,
    {
        <class 'bool'>: [True, False],
        <class 'float'>: [0.0, 1.0],
        <class 'int'>: [0, 1],
        <class 'NoneType'>: [None]
    }
)

Objects will be grouped against their class, as well as by any declared type (attributes type and types).

>>> pprint.pprint(Grouping.typewise([namespace(type='Cat'), namespace(types=['Feline', 'Leopard'])))
Grouping(
    <class 'list'>,
    {
        'Cat': [namespace(type='Cat')],
        'Feline': [namespace(types=['Feline', 'Leopard'])],
        'Leopard': [namespace(types=['Feline', 'Leopard'])],
         <class 'types.SimpleNamespace'>: [
            namespace(type='Cat'),
            namespace(types=['Feline', 'Leopard'])
         ]
    }
)
property all: list

Returns every entry in the grouping.

property each: list

Returns one of each entry in the grouping.