Add autodoc strings to Team, Person, Player, and Observer classes.

Author: GraylinKim

sc2reader/objects.py

@@ -24,6 +24,27 @@ def __str__(self):
         return self.name
 
 class Team(object):
+    """
+    The team object primarily a container object for organizing :class:`Player`
+    objects with some metadata. As such, it implements iterable and can be
+    looped over like a list::
+
+        for player in team:
+            print player
+
+    :param interger number: The team number as recorded in the replay
+    """
+
+    #: The team number as recorded in the replay
+    number = int()
+
+    #: A list of the :class:`Player` objects on the team
+    players = list()
+
+    #: The result of the game for this team.
+    #: One of "Win", "Loss", or "Unknown"
+    result = str()
+
     def __init__(self,number):
         self.number = number
         self.players = list()
@@ -73,9 +94,41 @@ def __repr__(self):
         return str(self)
 
     def __str__(self):
-        return "%s: %s" % (self.name, self.value)
+        return "[%s] %s: %s" % (self.player, self.name, self.value)
 
 class Person(object):
+    """
+    The person object is never actually instanciated but instead acts as a
+    parent class for the :class:`Observer` and :class:`Player` classes.
+
+    :param integer pid: The person's unique id in this game.
+    :param string name: The person's battle.net name
+    """
+
+    #: The person's unique in this game
+    pid = int()
+
+    #: The person's battle.net name
+    name = str()
+
+    #: A flag indicating the player's observer status.
+    #: Really just a shortcut for isinstance(obj, Observer).
+    is_observer = bool()
+
+    #: A list of :class:`ChatEvent` objects representing all of the chat
+    #: messages the person sent during the game
+    messages = list()
+
+    #: A list of :class:`Event` objects representing all the game events
+    #: generated by the person over the course of the game
+    events = list()
+
+    #: A flag indicating if this person was the one who recorded the game.
+    recorder = bool()
+
+    #: A flag indicating if the person is a computer or human
+    is_human = bool()
+
     def __init__(self, pid, name):
         self.pid = pid
         self.name = name
@@ -87,35 +140,46 @@ def __init__(self, pid, name):
         self.recorder = False # Actual recorder will be determined using the replay.message.events file
 
 class Observer(Person):
+    """
+    A subclass of the :class:`Person` class for observers. Fewer attributes
+    are made available for observers in the replay file.
+
+    All Observers are human.
+    """
     def __init__(self, pid, name):
         super(Observer,self).__init__(pid, name)
         self.is_observer = True
         self.is_human = True
 
 class Player(Person):
+    """
+    A subclass of the :class:`Person` class for players.
+    """
 
     URL_TEMPLATE = "http://%s.battle.net/sc2/en/profile/%s/%s/%s/"
 
+    #: A reference to the player's :class:`Team` object
+    team = None
+
     def __init__(self, pid, name):
         super(Player,self).__init__(pid, name)
         self.is_observer = False
-        # self.result = "Win","Loss","Unknown"
-        # self.team = Team()
-        # TODO: set default external interface variables?
 
     @property
     def url(self):
+        """The player's battle.net profile url"""
         return self.URL_TEMPLATE % (self.gateway, self.uid, self.subregion, self.name)
 
     def __str__(self):
         return "Player %s - %s (%s)" % (self.pid, self.name, self.play_race)
 
-    def __repr__(self):
-        return str(self)
-
     @property
     def result(self):
+        """The game result for this player"""
         return self.team.result
 
     def format(self, format_string):
-        return format_string.format(**self.__dict__)
+        return format_string.format(**self.__dict__)
+
+    def __repr__(self):
+        return str(self)