Improve reference docs for resources/objects.

Author: GraylinKim

sc2reader/objects.py

@@ -116,6 +116,9 @@ class Person(object):
     #: Really just a shortcut for isinstance(obj, Observer).
     is_observer = bool()
 
+    #: A flag indicating if the person is a human or computer
+    is_human = bool()
+
     #: A list of :class:`ChatEvent` objects representing all of the chat
     #: messages the person sent during the game
     messages = list()
@@ -130,13 +133,17 @@ class Person(object):
     #: A flag indicating if the person is a computer or human
     is_human = bool()
 
+    #: The player's region.
+    region = str()
+
     def __init__(self, pid, name):
         self.pid = pid
         self.name = name
-        self.is_observer = None
+        self.is_observer = bool()
         self.messages = list()
         self.events = list()
         self.is_human = bool()
+        self.region = str()
         self.recorder = False # Actual recorder will be determined using the replay.message.events file
 
 class Observer(Person):
@@ -146,6 +153,7 @@ class Observer(Person):
 
     All Observers are human.
     """
+
     def __init__(self, pid, name):
         super(Observer,self).__init__(pid, name)
         self.is_observer = True
@@ -179,12 +187,13 @@ class Player(Person):
     #: The player's handicap as set prior to game start, ranges from 50-100
     handicap = int()
 
-    #: The player's region
-    region = str()
-
     #: The subregion with in the player's region
     subregion = int()
 
+    #: The player's bnet uid for his region/subregion.
+    #: Used to construct the bnet profile url.
+    uid = int()
+
     def __init__(self, pid, name):
         super(Player,self).__init__(pid, name)
         self.is_observer = False
@@ -199,43 +208,15 @@ def __str__(self):
 
     @property
     def result(self):
-        """The game result for this player"""
-        return self.team.result
+        """The game result for this player: Win, Loss, Unknown"""
+        return self.team.result if self.team else "Unknown"
 
     def format(self, format_string):
         return format_string.format(**self.__dict__)
 
     def __repr__(self):
         return str(self)
 
-class Graph():
-    """
-    A class to represent a graph on the score screen
-    """
-    #: Times in seconds on the x-axis of the graph
-    times = list()
-
-    #: Values on the y-axis of the graph
-    values = list()
-
-    def __init__(self, x, y, xy_list=None):
-        self.times = list()
-        self.values = list()
-
-        if xy_list:
-            for x, y in xy_list:
-                self.times.append(x)
-                self.values.append(y)
-        else:
-            self.times = x
-            self.values = y
-
-    def as_points(self):
-        """ Get the graph as a list of (x, y) tuples """
-        return zip(self.times, self.values)
-
-    def __str__(self):
-        return "Graph with {0} values".format(len(self.times))
 
 class PlayerSummary():
     """
@@ -257,7 +238,7 @@ class PlayerSummary():
 
     #: The index of the player in the game
     pid = int()
-    
+
     #: The index of the players team in the game
     teamid = int()
 
@@ -278,13 +259,13 @@ class PlayerSummary():
 
     #: unknown1
     unknown1 = int()
-    
+
     #: unknown2
     unknown2 = dict()
 
     #: :class:`Graph` of player army values over time (seconds)
     army_graph = None
-    
+
     #: :class:`Graph` of player income over time (seconds)
     income_graph = None
 
@@ -294,17 +275,46 @@ class PlayerSummary():
     def __init__(self, pid):
         unknown2 = dict()
         stats = dict()
-        
+
         self.pid = pid
-        
+
     def __str__(self):
         if not self.is_ai:
             return '{} - {} - {}/{}/'.format(self.teamid, self.race, self.subregion, self.bnetid)
         else:
-            return '{} - {} - AI'.format(self.teamid, self.race) 
-        
+            return '{} - {} - AI'.format(self.teamid, self.race)
+
     def get_stats(self):
         s = ''
         for k in self.stats:
             s += '{}: {}\n'.format(self.stats_pretty_names[k], self.stats[k])
         return s.strip()
+
+# TODO: Are there libraries with classes like this in them
+class Graph():
+    """A class to represent a graph on the score screen."""
+
+    #: Times in seconds on the x-axis of the graph
+    times = list()
+
+    #: Values on the y-axis of the graph
+    values = list()
+
+    def __init__(self, x, y, xy_list=None):
+        self.times = list()
+        self.values = list()
+
+        if xy_list:
+            for x, y in xy_list:
+                self.times.append(x)
+                self.values.append(y)
+        else:
+            self.times = x
+            self.values = y
+
+    def as_points(self):
+        """ Get the graph as a list of (x, y) tuples """
+        return zip(self.times, self.values)
+
+    def __str__(self):
+        return "Graph with {0} values".format(len(self.times))

sc2reader/resources.py

@@ -30,6 +30,11 @@ def __init__(self, file_object, filename=None, **options):
 
 class Replay(Resource):
 
+    #: A nested dictionary of player => { attr_name : attr_value } for
+    #: known attributes. Player 16 represents the global context and
+    #: contains attributes like game speed.
+    attributes = defaultdict(dict)
+
     #: Fully qualified filename of the replay file represented.
     filename = str()
 
@@ -42,10 +47,10 @@ class Replay(Resource):
     #: The full version release string as seen on Battle.net
     release_string = str()
 
-    #: The :class:`Length` of the replay as an alternative to :attr:`frames`
-    length = utils.Length()
+    #: A tuple of the individual pieces of the release string
+    versions = tuple()
 
-    #: The effective game speed when the game was played.
+    #: The game speed: Slower, Slow, Normal, Fast, Faster
     speed = str()
 
     #: The game type: 1v1, 2v2, 3v3, 4v4, FFA
@@ -60,9 +65,42 @@ class Replay(Resource):
     #: A flag for private non-ladder games
     is_private = bool()
 
+    #: The raw hash name of the s2ma resource as hosted on bnet depots
+    map_hash = str()
+
     #: The name of the map the game was played on
+    map_name = str()
+
+    #: A reference to the loaded :class:`Map` resource.
     map = None
 
+    #: The UTC time the game was ended as represented by the Windows OS
+    windows_timestamp = int()
+
+    #: The UTC time the game was ended as represented by the Unix OS
+    unix_timestamp = int()
+
+    #: The time zone adjustment for the location the replay was recorded at
+    time_zone= int()
+
+    #: Deprecated: See `end_time` below.
+    date = None
+
+    #: A datetime object representing the local time at the end of the game.
+    end_time = None
+
+    #: A datetime object representing the local time at the start of the game
+    start_time = None
+
+    #: Deprecated: See `game_length` below.
+    length = None
+
+    #: The :class:`Length` of the replay as an alternative to :attr:`frames`
+    game_length = None
+
+    #: The :class:`Length` of the replay in real time adjusted for the game speed
+    self.real_length = None
+
     #: The gateway the game was played on: us, eu, sea, etc
     gateway = str()
 
@@ -103,12 +141,27 @@ class Replay(Resource):
     #: A list of all the chat message events from the game
     messages = list()
 
+    #: A list of pings sent by all the different people in the game
+    pings = list()
+
+    #: A list of packets sent between the various game clients
+    packets = list()
+
     #: A reference to the :class:`Person` that recorded the game
     recorder = None
 
     #: If there is a valid winning team this will contain a :class:`Team` otherwise it will be :class:`None`
     winner = None
 
+    #: A dictionary mapping unit unique ids to their corresponding classes
+    objects = dict()
+
+    #: A sha256 hash uniquely representing the combination of people in the game.
+    #: Can be used in conjunction with date times to match different replays
+    #: of the game game.
+    people_hash = str()
+
+
     def __init__(self, replay_file, filename=None, load_level=4, **options):
         super(Replay, self).__init__(replay_file, filename, **options)
         self.datapack = None
@@ -123,23 +176,20 @@ def __init__(self, replay_file, filename=None, load_level=4, **options):
         self.is_ladder = False
         self.is_private = False
         self.map = ""
+        self.map_hash = ""
         self.gateway = ""
         self.events = list()
         self.events_by_type = defaultdict(list)
         self.results = dict()
-
         self.teams, self.team = list(), dict()
         self.players, self.player = list(), utils.PersonDict()
         self.observers = list() #Unordered list of Observer
-
         self.people, self.humans = list(), list() #Unordered list of Players+Observers
-
         self.person = utils.PersonDict() #Maps pid to Player/Observer
-        self.attributes = list()
+        self.attributes = defaultdict(dict)
         self.messages = list()
         self.recorder = None # Player object
         self.packets = list()
-
         self.objects = {}
 
         # Bootstrap the readers.
@@ -152,6 +202,7 @@ def __init__(self, replay_file, filename=None, load_level=4, **options):
 
         # Unpack the MPQ and read header data if requested
         if load_level >= 0:
+            # Set ('versions', 'frames', 'build', 'release_string', 'length')
             self.__dict__.update(utils.read_header(replay_file))
             self.archive = utils.open_archive(replay_file)
 
@@ -331,7 +382,7 @@ def load_players(self):
                 if obs_name in all_players: continue
 
                 observer = Observer(obs_index,obs_name)
-                observer.gateway = self.gateway
+                observer.region = default_region
                 self.observers.append(observer)
                 self.people.append(observer)
                 self.person[obs_index] = observer
@@ -372,6 +423,7 @@ def load_events(self):
 
         for event in self.events:
             event.load_context(self)
+            # TODO: Should this be documented or removed? I don't like it.
             self.events_by_type[event.name].append(event)
             if event.pid != 16:
                 self.person[event.pid].events.append(event)
@@ -462,6 +514,28 @@ def _read_data(self, data_file, reader):
 class Map(Resource):
     url_template = 'http://{0}.depot.battle.net:1119/{1}.s2ma'
 
+    #: The unique hash used to identify this map on bnet's depots.
+    hash = str()
+
+    #: The gateway this map was posted to.
+    #: Maps must be posted individually to each gateway.
+    gateway = str()
+
+    #: A URL reference to the location of this map on bnet's depots.
+    url = str()
+
+    #: The localized (only enUS supported right now) map name
+    name = str()
+
+    #: The map's author
+    author = str()
+
+    #: The map description as written by author
+    description = str()
+
+    #: A byte string representing the minimap in tga format.
+    minimap = str()
+
     def __init__(self, map_file, filename=None, gateway=None, map_hash=None, **options):
         super(Map, self).__init__(map_file, filename, **options)
         self.hash = map_hash