Rejigger object tree and use objects for more things

- Verbs are now special callable objects
- Document almost everything
Cassowary Rusnov 3 months ago
parent 9390458ffb
commit 518f0101e2
  1. 112
  2. 62
  3. 59
  4. 164
  5. 7
  6. 3
  7. 8

@ -1,5 +1,10 @@
Base data and types for supporting Pyoo operations.
from collections import namedtuple
from typing import Callable, List, Tuple, Type, Sequence, Union, Iterable, Protocol
@ -20,45 +25,98 @@ PREPOSITIONS = (
"""`tuple[str]`: A list of preposition strings (equivilancies are / separated)"""
NORMALIZED_PREPS = tuple([x.split("/") for x in PREPOSITIONS])
"""A list of prepositions with equiviliants split."""
class PyooError(Exception):
"""Generic Pyoo error."""
class PyooVerbNotFound(PyooError):
"""Pyoo Error which indicates a verb was not found."""
class PyooObjectNotFound(PyooError):
"""Pyoo Error which indicates an object was not found."""
NORMALIZED_PREPS = tuple([x.split("/") for x in PREPOSITIONS])
VerbCallFrame = namedtuple("VerbCallFrame", "environment,player,verbname,dobj,dobjstr,prepstr,iobj,iobjstr,argstr")
"""Namedtuple which contains the call frame (all arguments) for a verb call."""
class Verb:
"""This is a wrapper for a callable to give it the properties required for verbs."""
def __init__(self,
function: Callable,
names: List[str],
callspec: Tuple[str, List[str], str]):
self.function = function = names[0]
self.names = names
self.callspec = callspec
def __call__(self, *args, **kwargs) -> None:
return self.function(*args, **kwargs)
def __get__(self, obj, objtype: Type):
class VerbFunction:
def __init__(self, func: Callable, obj, typ: Type, verb: "Verb"):
self._func = func
self._obj = obj
self._typ = typ
self.is_verb = True =
self.names = verb.names
self.callspec = verb.callspec
# this simple decorator adds verb metadata to a method or function
# verbname is a comma-separated list of verb names with possible woldcard
# dobjspec is 'this' or 'that' or 'none' or 'any' (this = the object which defines the verb, that = an object in the
# soup, any = any string, none = blank)
# iobjspec is 'this' or 'that' or 'none' or 'any'
# prepspec is one of prepositions strings
# verb prototypes are: (verb_callframe, argstr)
def __call__(self, *args, **kwargs):
return self._func.__get__(self._obj, self._typ)(*args, **kwargs)
def make_verb(verbname, dobjspec, prepspec, iobjspec):
def verb_decorate(verbfunc):
return VerbFunction(self.function, obj, objtype, self)
def __repr__(self) -> str:
return f"<Verb {} {self.callspec}>"
def make_verb(verbname: str, dobjspec: str, prepspec: str, iobjspec: str) -> Callable[..., Verb]:
"""This simple decorator adds verb metadata to a method or function.
verbname (str): List of verb names, comma separated, with wildcards.
dobjspec (str): 'this' or 'that' or 'none' or 'any'
(this = the object which defines the verb, that = an object in the soup, any = any string,
none = blank)
iobjspec (str): 'this' or 'that' or 'none' or 'any' (as above)
prepspec (str): one of prepositions strings (as in the PREPOSITIONS list)
def verb_decorate(verbfunc: Callable[[VerbCallFrame, ], None]) -> Verb:
names = [x.strip() for x in verbname.split(",")] = names[0]
verbfunc.names = names
ps = prepspec
if isinstance(ps, str):
if ps.find("/") > 0:
ps = ps.split("/")
if ps in p:
ps = p
verbfunc.callspec = (dobjspec, ps, iobjspec)
verbfunc.is_verb = True
return verbfunc
ps: List[str] = []
if prepspec.find("/") > 0:
ps = prepspec.split("/")
if prepspec in prep:
ps = prep
ps = [prepspec]
return Verb(verbfunc, names, (dobjspec, ps, iobjspec))
return verb_decorate
# type things
class InterpreterProtocol(Protocol):
"""Defines minimal protocol for interpreter objects."""
def update(self) -> None:
SingleMultiString = Union[Sequence[str], str, Iterable[str]]

@ -1,53 +1,78 @@
"""This module defines the basic interpreter system."""
import fnmatch
from typing import Optional, List, Set, Tuple, cast
from .things import Thing, Container, Place, Player
from .base import VerbCallFrame, PyooVerbNotFound, PyooObjectNotFound
class Interpreter(object):
def __init__(self, contents = None):
class Interpreter:
"""Base interpreter class.
Manages a collection of objects, and invoking verbs on them.
def __init__(self, contents: Optional[List[Thing]] = None):
"""Initialize an interpreter.
contents (optional list of things): The initial contents to populate the interpreter with.
if contents is None:
contents = []
self.contents = set(contents)
self.contents: Set[Thing] = set(contents)
for cont in self.contents:
cont.interpreter = self
self.content_cache = []
self.content_cache: List[Tuple[str, Thing]] = []
def add_player(self, player_object):
def add_player(self, player_object: Player) -> None:
"""Add a player to the interpreter."""
player_object.interpreter = self
def remove_player(self, player_object):
def remove_player(self, player_object: Player) -> None:
"""Remove a player from the interpreter."""
def update(self):
def update(self) -> None:
"""Do any updates required when objects are added or removed."""
def update_caches(self):
def update_caches(self) -> None:
"""Update the caches for objects contained in the interpreter, as well as updating all of the caches
on contained containers.
self.content_cache = []
for obj in self.contents:
for name in obj.names:
self.content_cache.append((name, obj))
cast(Container, obj).update_caches()
except AttributeError:
def handle_move(self, newroom, player):
def handle_move(self, newroom: Place, player: Player) -> None:
"""Move a player to a new contained room."""
if player.location:
def handle_get(self, thing):
def lookup_global_object(self, objstr):
def lookup_global_object(self, objstr: str) -> List[Tuple[str, Thing]]:
"""Find an object within the soup by objstr."""
return [x for x in self.content_cache if fnmatch.fnmatch(objstr, x[0])]
def lookup_object(self, player, objstr):
m = None
def lookup_object(self, player: Player, objstr: str) -> Optional[Thing]:
"""Find an object relative to a player
This first checks the player's inventory, and then the container which contains the
m: Optional[List[Tuple[str, Thing]]] = None
m = player.get_name_matches(objstr)
except PyooObjectNotFound:
@ -59,8 +84,8 @@ class Interpreter(object):
return None
def interpret(self, command, player):
def interpret(self, command: str, player: Player) -> None:
"""Interpret a player's command by splitting it into components and finding matching verbs."""
# FIXME make this better to support mulitple word objstrs and prepstr
if not command:
@ -91,7 +116,6 @@ class Interpreter(object):
cmdmatches = player.location.get_command_matches(command)
raise PyooVerbNotFound
cmd = cmdmatches[0]
# glob = cmd[0]
# comps = cmd[1]

@ -1,7 +1,10 @@
"""PlaceLoader is a system to load simple plain text data to build a room-based space."""
from enum import Enum
from typing import TextIO
from typing import Dict, List, TextIO, Type
from .things import Place, Thing
from .things import Place
from .interpret import Interpreter
class PlaceLoaderStates(Enum):
@ -10,31 +13,53 @@ class PlaceLoaderStates(Enum):
class PlaceLoader(object):
class PlaceLoader:
A factory which loads a simple data format containing a description of rooms, and how
they are connected, and produces room objects for each one.
The format is a plain text file containing a series of room definitions:
DESCRIPTION (multiple lines)
direction,alias ROOMNAME2
def __init__(self, in_file: TextIO, baseplace: Thing = Place):
"""Initialize the factory by loading a description file."""
def __init__(self, in_file: TextIO, baseplace: Type[Place] = Place):
"""Initialize the factory by loading a description file.
in_file: A file to load the places from.
baseplace: A type to initialize the rooms from.
self.base = baseplace
self.places = {} # indexed by name
self.places: Dict[str, Place] = {} # indexed by name
if in_file:
def process_file(self, in_file: TextIO):
"""Load any room information from the passed in file."""
def process_file(self, in_file: TextIO) -> None:
"""Load any room information from the passed in file.
in_file: The file to load the rooms from.
state = PlaceLoaderStates.START
rm = None
desc = []
desc: List[str] = []
temp_exits: Dict[Place, List[str]] = {}
for line in in_file:
line = line.strip()
if state == PlaceLoaderStates.START:
rm = self.base(line)
rm.temp_exits = list()
temp_exits[rm] = []
state = PlaceLoaderStates.DESC
desc = list()
desc = []
elif state == PlaceLoaderStates.DESC:
if line == ".":
state = PlaceLoaderStates.EXITS
@ -45,14 +70,18 @@ class PlaceLoader(object):
if line == ".":
state = PlaceLoaderStates.START
self.places[] = rm
rm = None
# assemble the exits
for place in list(self.places.values()):
for ext in place.temp_exits:
for ext in temp_exits[place]:
names, destination = ext.split(" ", 1)
for nm in names.split(","):
place.ways[nm] = self.places[destination]
def interpreter_from_placeloader(placeloader: PlaceLoader) -> Interpreter:
"""Return an interpreter intialized with the contents of a placeloader."""
return Interpreter(list(placeloader.places.values()))

@ -1,23 +1,36 @@
"""Base (Pyoo) classes which implement basic protocols."""
import fnmatch
import itertools
from .base import make_verb, PyooVerbNotFound, PyooObjectNotFound
from typing import cast, List, Optional, Tuple, Set, Dict
from .base import make_verb, PyooVerbNotFound, InterpreterProtocol, SingleMultiString, Verb, VerbCallFrame
class Thing:
"""The base of all Pyoo objects."""
def __init__(self, name: str, description: SingleMultiString = "A nondescript object."):
"""Create a Thing
class Thing(object):
def __init__(self, thingname, description="A nondescript object."):
names = [x.strip() for x in thingname.split(",")]
name (str): A string of comma-separated names for this object.
description (str): A string that describes this object.
names = [x.strip() for x in name.split(",")] = names[0]
self.names = tuple(names)
self.names: Tuple[str, ...] = tuple(names)
self.description = description
self.location = None
self.interpreter = None
self.location: Optional["Container"] = None
self.interpreter: Optional[InterpreterProtocol] = None
def tell(self, message):
def tell(self, message: SingleMultiString) -> None:
print("<tell stub>", self, message)
def verbs(self):
def verbs(self) -> List[Verb]:
"""Return a list of bound methods which denote themselves as verbs."""
verbs = list()
verbs: List[Verb] = []
for item in dir(self):
v = self.__getattribute__(item)
@ -27,20 +40,20 @@ class Thing(object):
return verbs
def verb_globs(self):
def verb_globs(self) -> List[Tuple[str, Tuple, Verb, "Thing"]]:
"""Return a list of (globstr, bound method) where commands matching globstr should call method (given that
'that' matches an object in the soup).
verbglobs = list()
verbglobs: List[Tuple[str, Tuple, Verb, "Thing"]] = []
for vrb in self.verbs():
vvars = [vrb.names]
vvars: List[Tuple] = [tuple(vrb.names)]
if vrb.callspec[0] == "this":
elif vrb.callspec[0] in ("that", "any"):
if vrb.callspec[1] != "none":
if vrb.callspec[1] != ["none"]:
if vrb.callspec[2] == "this":
@ -50,25 +63,45 @@ class Thing(object):
for combo in itertools.product(*vvars):
globstr = " ".join(combo)
verbglobs.append((globstr, tuple(combo), vrb, self))
return verbglobs
def handle_move(self, newlocation):
def handle_move(self, newlocation: "Container") -> None:
"""Handle moving this object to a new location.
Acts as a way for children to hook this occurance too.
self.location = newlocation
def handle_remove(self, oldlocation):
def handle_remove(self, oldlocation: "Container") -> None:
"""Handle removing this object from a container.
Acts as a way for children to hook this occurance too.
self.location = None
def __repr__(self):
def __repr__(self) -> str:
return "<Thing '%s' object at 0x%x>" % (, self.__hash__())
class Container(Thing):
def __init__(self, names, description=""):
"""A Pyoo object which contains other Pyoo objects."""
def __init__(self, names: str, description: SingleMultiString = ""):
"""Create a Container.
names (str): A comma-separated list of names.
description (str): A description for this object.
super().__init__(names, description)
self.contents = set()
self.name_cache = []
self.command_cache = []
self.contents: Set[Thing] = set()
self.name_cache: List[Tuple[str, Thing]] = []
self.command_cache: List[Tuple[str, Tuple, Verb, Thing]] = []
def update_caches(self):
def update_caches(self) -> None:
"""Update the internal cache of contained object's verbs and names."""
self.name_cache = []
self.command_cache = []
for obj in self.contents:
@ -80,10 +113,19 @@ class Container(Thing):
for verbglob in self.verb_globs():
if verbglob[0][0] == "#":
def get_command_matches(self, command_spec):
def get_command_matches(self, command_spec: str) -> List[Tuple[str, Tuple, Verb, Thing]]:
"""Return a list of commands which match a command_spec ordered by specificity.
command_spec (str): A command
array[tuple]: A list of command specifiers.
res = [x for x in self.command_cache if fnmatch.fnmatch(command_spec, x[0])]
# sort by ambiguity (percentage of *)
res.sort(key=lambda a: a[0].count("*") / float(len(a[0])))
@ -91,62 +133,94 @@ class Container(Thing):
raise PyooVerbNotFound
return res
def get_name_matches(self, name):
def get_name_matches(self, name: str) -> List[Tuple[str, Thing]]:
"""Return a list of objects which match a name spec.
name (str): A name of an object
array[tuple]: A list of name,thing tuples.
return [x for x in self.name_cache if fnmatch.fnmatch(name, x[0])]
def handle_exit(self, oldobj):
def handle_exit(self, oldobj: Thing) -> None:
"""Handle an object leaving the container.
This allows children to hook this occurence also.
oldobj (`pyoo.things.Thing`): The object which is exiting.
def handle_enter(self, newobj):
def handle_enter(self, newobj: Thing) -> None:
"""Handle an object entering the container.
This allows children to hook this occurence also.
newobj (`pyoo.things.Thing`): The object which is entering.
cast("Container", newobj).update_caches()
except AttributeError:
def handle_tell(self, msg, who):
def handle_tell(self, msg: SingleMultiString, who: Set[Thing]) -> None:
"""Handle processing a tell to a list of objects.
for obj in who:
def tell(self, msg):
def tell(self, msg: SingleMultiString) -> None:
"""Handle telling all content objects."""
self.handle_tell(msg, self.contents)
def __repr__(self):
def __repr__(self) -> str:
return "<Container '%s' object at 0x%x>" % (, self.__hash__())
class Place(Container):
def __init__(self, names, description=""):
"""A specialized container which models a place."""
def __init__(self, names: str, description: str = "") -> None:
"""Create a place."""
super().__init__(names, description)
self.ways = dict()
self.ways: Dict[str, Container] = dict()
def tell_only(self, message, verb_callframe):
def tell_only(self, message: SingleMultiString, verb_callframe: VerbCallFrame) -> None:
self.handle_tell(message, self.contents - {verb_callframe.player})
# this verb expects to be annotated from update_go. We never want it ot be at the top of a match list by its deault
# name either
@make_verb("#go", "none", "none", "none")
def go(self, verb_callframe):
def go(self, verb_callframe: VerbCallFrame) -> None:
self.do_go(verb_callframe.verbname, verb_callframe)
@make_verb("go,move,walk,run", "any", "none", "none")
def go_dir(self, verb_callframe):
def go_dir(self, verb_callframe: VerbCallFrame) -> None:
self.do_go(verb_callframe.dobjstr, verb_callframe)
def do_go(self, direction, verb_callframe):
def do_go(self, direction: str, verb_callframe: VerbCallFrame) -> None:
if direction in self.ways:
self.tell_only("{} moves {}".format(verb_callframe.player, direction), verb_callframe)
self.tell_only("{} moves {}".format(, direction), verb_callframe)
verb_callframe.player.tell("You move {}".format(direction))
verb_callframe.environment.handle_move(self.ways[direction], verb_callframe.player)
def handle_enter(self, newobj):
def handle_enter(self, newobj: Thing) -> None:
self.tell("{} arrives".format(
self.handle_tell("{} arrives".format(, self.contents - {newobj})
def update_go(self):
def update_go(self) -> None:
# note does no actually remove items from the go verb in case the descender is overloading.
# also note, the interpreter needs to have update() called after this is called.
for direction in self.ways:
@ -155,13 +229,13 @@ class Place(Container):
if self.interpreter:
def __repr__(self):
def __repr__(self) -> str:
return "<Place '%s' object at 0x%x>" % (, self.__hash__())
class Player(Container):
def __init__(self, names, description=""):
def __init__(self, names: str, description: str = ""):
super().__init__(names, description)
def __repr__(self):
def __repr__(self) -> str:
return "<Player '%s' object at 0x%x>" % (, self.__hash__())

@ -1,8 +1,9 @@
from pyoo.things import Place, Player
from pyoo.placeloader import PlaceLoader
from pyoo.interpret import Interpreter, PyooVerbNotFound
from pyoo.placeloader import interpreter_from_placeloader, PlaceLoader
from pyoo.interpret import PyooVerbNotFound
from pyoo.base import make_verb
class DescriptivePlace(Place):
def handle_enter(self, player):
@ -23,7 +24,7 @@ class DescriptivePlace(Place):
loader = PlaceLoader(open("roomtest.txt", "r"), DescriptivePlace)
player = Player("player")
game = Interpreter(list(loader.places.values()))
game = interpreter_from_placeloader(loader)
porch = game.lookup_global_object("Porch")[0][1]
run = True

@ -2,6 +2,7 @@ from pyoo.interpret import Interpreter
from pyoo.things import Thing, Place, Player
from pyoo.base import make_verb, PyooVerbNotFound
class Hammer(Thing):
def __init__(self):
Thing.__init__(self, "hammer", "a heavy ball-peen hammer.")
@ -40,13 +41,13 @@ class Nail(Thing):
return "You see a nail fully hammered in."
class HammerTime(Place):
def __init__(self):
Place.__init__(self, "HAMMERTIME")
@make_verb("look,l", "none", "none", "none")
def look(self, verb_callframe):
for cont in self.contents:

@ -1,12 +1,14 @@
envlist = py36, py37
envlist = py36, py37, py38, py39
deps =
commands = flake8
commands =
mypy -p pyoo
max-line-length = 120
max-complexity = 10
max-complexity = 15