pyIFBabel is a pure-Python implementation of the Treaty of Babel, a standard for identifying and handling the metadata of interactive fiction files. This module was originally written for Grotesque but it has been packaged separately to be easily used by other developers.
There are two primary ways to use this library. The first way is via the
treatyofbabel.ifiction modules. The
babel module contains
functions for extracting metadata from interactive fiction story files. Until proper
documentation is written, it is best to use Python’s introspection capabilities to
view the available functions (
dir(treatyofbabel.babel)). In general, you will pass
these functions a string referring to the file’s location. So, for example, to
determine the format of the file (ie glulx, tads2, etc.), you would do:
To calculate the IFID(s) of a file, you would do:
ifiction module contains functions for working with IFiction files. These are
simply XML files, so the module essentially just consists of IFiction-specific
convenience functions. The functions typically return objects belonging to the built-in
xml.dom.minidom, though you generally won’t have to do anything with
these other than pass them between
ifiction functions. One can build up an IFiction
>>> ifdom = ifiction.create_ifiction_dom() >>> story = ifiction.add_story(ifdom) >>> ifiction.add_identification(ifdom, story, list_of_ifids, story_format, story_bafn) >>> ifiction.add_bibliographic(ifdom, story, truncate=False, title="My Story", author="Pat Smith")
…and so on. Alternatively, given an IFiction file, you can extract information from it:
>>> ifdom = ifiction.get_ifiction_dom("path/to/file.ifiction") >>> assert ifiction.is_ifiction(ifdom): >>> stories = ifiction.get_all_stories(ifdom) >>> story = stories >>> ident = ifiction.get_identification(story)
…and so on.
There is another, object-oriented means of doing this, contained in the
treatyofbabel.ifstory module. This module defines the IFStory class, which has fields
corresponding to the information contained in an IFiction file. There are various ways
you can use this class. You can build up a story description manually:
>>> story = ifstory.IFStory() >>> story.ifid_list = ["ZCODE-88-840726-A129"] >>> story.bibliographic["title"] = "Zork I"
This is tedious, though, so better options are available. If you have an IFiction file, you can use that to fill in all of the fields:
>>> ifdom = ifiction.get_ifiction_dom("path/to/file.ifiction") >>> story_node = ifiction.get_all_stories(ifdom) >>> story = ifstory.IFStory(ific_story_node=story_node) >>> print story.bibliographic["title"] "Zork I"
You can use the capabilities provided by the
treatyofbabel.babel module to automatically
fill in some information (note that for most formats, this will only be able to generate
an IFID and determine the story format):
>>> story = ifstory.IFStory(story_file="path/to/storyfile") >>> story.load_from_story_file() >>> print story.ifid_list ["ZCODE-88-840726-A129"]
Given an IFID, you may fill in the rest of the fields and optionally fetch cover art by remotely querying the IFDB (http://ifdb.tads.org) [continuing from the last example]:
>>> story.load_from_ifdb() >>> print story.bibliographic["title"] "Zork I' >>> print story.cover.img_format "jpg" >>> with open("ZorkI.jpg", "wb") as img_handle: ... img_handle.write(story.cover.data) >>> with open("ZorkI.ifiction", "w") as ific_handle: ... ific_handle.write(story.to_ifiction())
Once again, until proper documentation has been written, it is recommended to use introspection or to read the (hopefully readable) code to see all of the functions available.
pyIFBabel is an included script which mimics the
babel commandline utility
that is included from the official Treaty of Babel site. Run
$ pyIFBabel --help from the
commandline to see its options.
Current version: 0.2.2
This module is currently in beta. The necessary functionality to handle all of
the story formats and wrappers covered by the Treaty of Babel exists and is
well-tested. Some IFiction XML file handling functions, particularly the
verification and lint routines covered by the official
babel commandline tool,
have not been written yet. Finally, the module does not yet handle creating
Please note that the module API might change slightly as it is developed.
Please visit the download page.
You can fork the git repository at Gitorious.