API Reference

This API lets you customise the rehearsal of a Folder of Turberfield dialogue. You can modify how this performance is presented in your game by customising or replacing a handler function which processes events from the scene script files.

If you need to integrate with a game event loop, then create a Performer object instead. This separates event generation from sequencing.

The scene scripts themselves also have an API, allowing you to interact with the process by which entities are selected and cast to roles.

There is also a simple Matcher class which you can use to compare folder metadata.

Folders

SceneScript.Folder (pkg, description, metadata, paths, interludes)

Parameters:

• pkg –

  The dotted (importable) name of the package which installs the scene script folder.

  Absent proper packaging, you must set this parameter to __name__. The Python module which declares the folder will act as the anchor location for scene files, and all referencing paths will need to be made relative to the module.

• description (str) – A free text description of the contents of the folder.

• metadata –

  An optional sequence or mapping containing application-specific metadata.

  This parameter is for the purposes of searching or filtering collections of folders against particular criteria.

• paths –

  A list of strings, each of which is the path to a scene script file relative to the object declared in the parameter pkg.

  Path separator is always “/” notwithstanding the local Operating System.

• interludes –

  A sequence of function objects. The sequence should be such as to provide one object for each of the scene script files declared in the parameter paths.

  A function object will be called when its corresponding scene script file has been performed.

  See Interludes for the required signature of an interlude function object.

Scene scripts

class turberfield.dialogue.model.SceneScript(fP, metadata=None, doc=None)

Gives access to a Turberfield scene script (.rst) file.

This class allows discovery and classification of scene files prior to loading them in memory.

Once loaded, it allows entity selection based on the role definitions in the file. Casting a selection permits the script to be iterated as a sequence of dialogue items.

classmethod scripts(pkg, metadata, paths=[], **kwargs)

This class method is the preferred way to create SceneScript objects.

Parameters:

• pkg (str) – The dotted name of the package containing the scripts.

• metadata – A mapping or data object. This parameter permits searching among scripts against particular criteria. Its use is application specific.

• paths (list(str)) – A sequence of file paths to the scripts relative to the package.

You can satisfy all parameter requirements by passing in a Folder object like this:

SceneScript.scripts(**folder._asdict())

The method generates a sequence of SceneScript objects.

static read(text, name=None)

Read a block of text as a docutils document.

Parameters:

• text (str) – Scene script text.

• name (str) – An optional name for the document.

Returns:

A document object.

select(personae, relative=False, roles=1)

Select a persona for each entity declared in the scene.

Parameters:

• personae – A sequence of Personae.

• relative (bool) – Affects imports from namespace packages. Used for testing only.

• roles (int) – The maximum number of roles allocated to each persona.

Returns:

An OrderedDict of {Entity: Persona}.

cast(mapping)

Allocate the scene script a cast of personae for each of its entities.

Parameters:

mapping – A dictionary of {Entity, Persona}

Returns:

The SceneScript object.

run()

Parse the script file.

Return type:

Model

Events

class turberfield.dialogue.model.Model(fP, document)

This class registers the necessary extensions to the docutils document model.

It also defines the types which are returned on iterating over a scene script file.

Model.Shot (name, scene, items)

An event which signals the beginning of a shot in a scene.

Model.Property (entity, object, attr, val)

An event which signals a property is to be accessed.

Model.Audio (package, resource, offset, duration, loop)

An event which signals an audio cue.

Model.Still (package, resource, offset, duration, loop, label, width, height)

An event which signals a still image cue.

Model.Video (package, resource, offset, duration, loop, label, width, height, poster, url)

An event which signals a video cue.

Model.Memory (subject, object, state, text, html)

An event which signals a memory directive.

Model.Line (persona, text, html)

An event which signals a line of dialogue.

Model.Condition (object, attr, val, operator)

An event which evaluates a conditional expression.

Interludes

An interlude is a callable object (either a function, an instance method or a Python object with a callable interface).

It is called by a handler at the end of the performance of a scene script file. That is the current scene file as referred to below.

Here is an example to show the signature of parameters required.

def my_interlude(folder, index, ensemble, log=None, loop=None):

Parameters:

• folder – A Folder object.

• index (int) – The index position into folder.paths of the current scene script file.

• ensemble – A sequence of Python objects. It is guaranteed to contain all the objects cast to roles in the current scene. It will be used to select entities for the next.

• log – If supplied, this will be a logging.Logger object which should be used in preference over any other for logging messages from within your interlude function.

• loop – If supplied, this will be an instance of asyncio.BaseEventLoop. That will signal to your function that it operates in an asynchronous environment and that no blocking function should be called within it.

Returntype:

dict

Returning this object gives you the option to control branching of your narrative.

The dictionary data you pass back is matched against the metadata of each folder. The folder whose metadata matches closest is the next folder to run.

Return None to stop the performance.

Handler

class turberfield.dialogue.handlers.TerminalHandler(terminal, dbPath=None, pause=1.2, dwell=0.3, log=None)

The default handler for events from scene script files. It generates output for a console terminal.

The class is written to be a callable, stateful object. Its __call__ method delegates to handlers specific to each type of event. You can subclass it and override those methods to suit your own application.

Parameters:

• terminal – A stream object.

• dbPath (str) – An optional URL to the internal database.

• pause (float) – The time in seconds to pause on a line of dialogue.

• dwell (float) – The time in seconds to dwell on a word of dialogue.

• log – An optional log object.

static handle_audio(obj, wait=False)

Handle an audio event.

This function plays an audio file. Currently only .wav format is supported.

Parameters:

• obj – An Audio object.

• wait (bool) – Force a blocking wait until playback is complete.

Returns:

The supplied object.

handle_interlude(obj, folder, index, ensemble, loop=None, **kwargs)

Handle an interlude event.

Interlude functions permit branching. They return a folder which the application can choose to adopt as the next supplier of dialogue.

This handler calls the interlude with the supplied arguments and returns the result.

Parameters:

• obj – A callable object.

• folder – A Folder object.

• index (int) – Indicates which scene script in the folder is being processed.

• ensemble – A sequence of Python objects.

• branches – A sequence of Folder objects. from which to pick a branch in the action.

Returns:

A Folder object.

handle_line(obj)

Handle a line event.

This function displays a line of dialogue. It generates a blocking wait for a period of time calculated from the length of the line.

Parameters:

obj – A Line object.

Returns:

The supplied object.

handle_memory(obj)

Handle a memory event.

This function accesses the internal database. It writes a record containing state information and an optional note.

Parameters:

obj – A Memory object.

Returns:

The supplied object.

handle_property(obj)

Handle a property event.

This function will set an attribute on an object if the event requires it.

Parameters:

obj – A Property object.

Returns:

The supplied object.

handle_scene(obj)

Handle a scene event.

This function applies a blocking wait at the start of a scene.

Parameters:

obj – A Shot object.

Returns:

The supplied object.

handle_scenescript(obj)

Handle a scene script event.

Parameters:

obj – A Folder object.

Returns:

The supplied object.

handle_shot(obj)

Handle a shot event.

Parameters:

obj – A Shot object.

Returns:

The supplied object.

Matcher

class turberfield.dialogue.matcher.Matcher(folders=None)

static mapping_key(obj)

A keying function which allows nested objects to be sorted.

__init__(folders=None)

Match Turberfield Folders by their metadata.

This class has methods to normalise arbitrary dictionaries. It provides a search API, so you can discover which folders are a metadata match.

Parameters:

folders – A sequence of turberfield.dialogue.model.SceneScript.Folder objects.

options(data)

Generate folders to best match metadata.

The results will be a single, perfectly matched folder, or the two nearest neighbours of an imperfect match.

Parameters:

data (dict) – metadata matching criteria.

This method is a generator. It yields turberfield.dialogue.model.SceneScript.Folder objects.

Performer

class turberfield.dialogue.performer.Performer(folders, ensemble)

property stopped

Is True when none of the folders can be cast, False otherwise.

__init__(folders, ensemble)

An object which can select actors for a scene and run a performance.

Parameters:

• folders – A sequence of Folder objects.

• ensemble – A sequence of Python objects.

run(react=True, strict=True, roles=1)

Select a cast and perform the next scene.

Parameters:

• react (bool) – If True, then Property directives are executed at the point they are encountered. Pass False to skip them so they can be enacted later on.

• strict (bool) – Only fully-cast scripts to be performed.

• roles (int) – Maximum number of roles permitted each character.

This method is a generator. It yields events from the performance.

If a Condition is encountered, it is evaluated. No events are generated while the most recent condition is False.

A new Shot resets the current condition.

Player

turberfield.dialogue.player.rehearse(folders, references, handler, repeat=0, roles=1, strict=False, loop=None)

Cast a set of objects into a sequence of scene scripts. Deliver the performance.

Parameters:

• folders – A sequence of turberfield.dialogue.model.SceneScript.Folder objects.

• references – A sequence of Python objects.

• handler – A callable object. This will be invoked with every event from the performance.

• repeat (int) – Extra repetitions of each folder.

• roles (int) – Maximum number of roles permitted each character.

• strict (bool) – Only fully-cast scripts to be performed.

This function is a generator. It yields events from the performance.