API Reference

This API gives you a simple function for creating a performance from 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.

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

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Parse the script file.

Return type:Model

Events

class turberfield.dialogue.model.Model(fP, document)[source]

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.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.

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 file as referred to below.

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

def my_interlude(folder, index, ensemble, branches, 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.
  • branches – A sequence of Folder objects. from which to pick a branch in the action.
  • 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.
Returns:

A Folder object. If this is the same object as supplied to the function, it signals that performance of this folder should continue. You could return another folder to request a branching of the narrative, or else None to stop it.

Handler

class turberfield.dialogue.handlers.TerminalHandler(terminal, dbPath=None, pause=1.5, dwell=0.2, log=None)[source]

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)[source]

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, branches, loop=None, **kwargs)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Handle a scene script event.

Parameters:obj – A Folder object.
Returns:The supplied object.
handle_shot(obj)[source]

Handle a shot event.

Parameters:obj – A Shot object.
Returns:The supplied object.

Player

turberfield.dialogue.player.rehearse(folder, references, handler, repeat=0, roles=1, strict=False, branches=None, loop=None)[source]

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

Parameters:
  • folder – A turberfield.dialogue.model.SceneScript.Folder.
  • 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.
  • branches (list) – Supplies the folders from which an interlude may pick a branch in the action.

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