Updates the top level sc2reader interface to match the description in the Basic Usage section of the documentation

GraylinKim · GraylinKim · commit c1bbc5fc6033 · 2011-05-15T23:43:53.000-04:00
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -3,42 +3,56 @@
 sc2reader
 ==================
 
-Use Patterns
----------------
+Basic Usage
+-------------
 
-There are two primary usage patterns for sc2reader as illustrated below::
+The sc2reader package itself can be configured and used to read replay files
+right out of the box! This lightweight approach to usage provides sane default
+options so no configuration is necessary for most normal usage. Read accepts
+either a file or a directory and returns either a single replay or a list of
+replays as the result.
+
+::
 
     import sc2reader
     
-    #method 1
-    replay = sc2reader.read(file,options)
+    #default configuration provided
+    sc2reader.configure(**options)
+    replay = sc2reader.read(file)
+    
+If you prefer a class based approach or want to have several different
+configurations on hand try the above approach. Just initialize the SC2Reader
+with the desired options (sane defaults provided) and use it just like you
+would the package! To better reflect the structure of the source code, the rest
+of the documentation will use this class based approach.
+
+::
+
+    from sc2reader import SC2Reader
     
-    #method 2
-    reader = sc2reader.config(options)
+    #sane defaults provided
+    reader = SC2Reader(**options)
     replay = reader.read(file)
 
-Each time read is called on the sc2reader package, the options are used to
-configure the parsing and processors. For application where this repeated
-configuration is either too slow or harmful, ``config`` will pass back a
-pre-configured reader which can give a performance improvement.
+These two top level interfaces should remain fairly stable in the near to mid
+future.
 
-The replay object passed back contains all the game information in a densely
-linked object hierarchy described more fully in the :doc:`objects <objects>` page.
 
 Options
 -----------
 
-sc2reader behavior can be configured with a number of options which can either
+SC2Reader behavior can be configured with a number of options which can either
 be specified individually by keyword argument or packaged into a dictionary::
 
+    from sc2reader import config
+    
     options = dict(
             'processors': [PostProcessor],
-            'parse': sc2reader.FULL,
-            'debug':True,
+            'parse': config.PARTIAL,
+            'directory':'C:\Users\Me\Documents...',
         )
     
-    sc2reader.config(processors=[PostProcessor],parse=sc2reader.FULL)
-    sc2reader.config(options=options)
+    reader = SC2Reader(processors=[PostProcessor],parse=config.PARTIAL)
     sc2reader.config(**options)
     
 Options currently available are described below:
@@ -64,8 +78,15 @@ Options currently available are described below:
     Specifies the directory in which the files to be read reside (defaults to
     None). Does a basic `os.path.join` with the file names as passed in.
     
-.. option:: debug
+.. option:: parse
 
-    Turns on debugging features of sc2reader. See :doc:`debug`.
+    Three parse levels are provided in the ``sc2reader.config`` package:
+    
+    *   ``FULL`` parse will parse through all available files and produce the
+        most comprehensive replay object. 
+    *   ``PARTIAL`` parse will skip the game events file, resulting in loss of
+        detailed game information but with significant time savings.
+    *   ``CUSTOM`` parse allows a user with intimate knowledge of sc2reader to
+        hand build their own parse style.
     
     
diff --git a/sc2reader/__init__.py b/sc2reader/__init__.py
@@ -1,7 +1,8 @@
 import os
 
 from mpyq import MPQArchive
-from config import DefaultConfig
+import config
+from objects import Replay
 from utils import ReplayBuffer, LITTLE_ENDIAN
 
 def read_header(file):
@@ -22,42 +23,73 @@ def read_header(file):
     
     #return the release and frames information
     return data[1],data[3]
+
+class SC2Reader(object):
+
+    def __init__(self, parse=config.FULL, directory="", processors=[], debug=False, files=None):
+        #Check that arguments are consistent with expectations up front
+        #Easier to debug issues this way
+        if parse == config.FULL: 
+            files = config.FILES_FULL
+            processors = config.PROCESSORS_FULL + processors
+        elif parse == config.PARTIAL:
+            files = config.FILES_PARTIAL
+            processors = config.PROCESSORS_PARTIAL + processors
+        elif parse == config.CUSTOM:
+            if not files:
+                raise ValueError("Custom parsing requires specification the files arguments")
+        else:
+            raise ValueError("parse must be either FULL, PARTIAL, or CUSTOM")
+        
+        #Update the class configuration
+        self.__dict__.update(locals())
     
-def read(location,config=DefaultConfig()):
-    if not os.path.exists(location):
-        raise ValueError("Location must exist")
-    
-    if os.path.isdir(location):
-        replays = list()
-        for location in os.list_files(location):
-            replays.extend(read(location,config))
-        return replays
-    else:
-        return read_file(location,config)
-    
-def read_file(filename,config=DefaultConfig()):
-    if(os.path.splitext(filename)[1].lower() != '.sc2replay'):
-        raise TypeError("Target file must of the SC2Replay file extension")
-    
-    with open(filename) as replay_file:
-        release,frames = read_header(replay_file)
-        replay = config.ReplayClass(filename,release,frames)
-        archive = MPQArchive(filename,listfile=False)
+    def read(self, location):
+        #account for the directory option
+        location = os.path.join(self.directory,location)
         
-        #Extract and Parse the relevant files
-        for file,readers in config.readers.iteritems():
-            for reader in readers:
-                if reader.reads(replay.build):
-                    reader.read(ReplayBuffer(archive.read_file(file)),replay)
-                    break
-            else:
-                raise NotYetImplementedError("No parser was found that accepted the replay file;check configuration")
-
-        #Do cleanup and post processing
-        for processor in config.processors:
-            replay = processor.process(replay)
+        if not os.path.exists(location):
+            raise ValueError("Location must exist")
+        
+        #If its a directory, read each subfile/directory and combine the lists
+        if os.path.isdir(location):
+            return sum(map(self.read, os.list_files(location)),[])
             
-        return replay
+        #The primary replay reading routine
+        else:
+            if(os.path.splitext(location)[1].lower() != '.sc2replay'):
+                raise TypeError("Target file must of the SC2Replay file extension")
+        
+            with open(location) as replay_file:
+                #Use the MPQ Header information to initialize the replay
+                release,frames = read_header(replay_file)
+                replay = Replay(location,release,frames)
+                archive = MPQArchive(location,listfile=False)
+                
+                #Extract and Parse the relevant files based on parse level
+                for file,readers in config.READERS.iteritems():
+                    if file in self.files:
+                        for reader in readers:
+                            if reader.reads(replay.build):
+                                reader.read(ReplayBuffer(archive.read_file(file)),replay)
+                                break
+                        else:
+                            raise NotYetImplementedError("No parser was found that accepted the replay file;check configuration")
+                
+                #Do cleanup and post processing
+                for processor in self.processors:
+                    replay = processor.process(replay)
+                
+                return replay
+                
+#Prepare the lightweight interface
+__defaultSC2Reader = SC2Reader()
+
+def configure(parse=config.FULL, directory=None, processors=[], debug=False, files=None):
+    __defaultSC2Reader.__dict__.update(locals())
+
+def read(location):
+    return __defaultSC2Reader.read(location)
         
-__all__ = [DefaultConfig,read,read_file]
-__version__ = "0.1.0"
+__all__ = [read,config,SC2Reader]
+__version__ = "0.3.0"
diff --git a/sc2reader/config.py b/sc2reader/config.py
@@ -10,7 +10,7 @@
 from sc2reader.processors import *
 from sc2reader.readers import *
 from sc2reader.utils import key_in_bases
-
+"""
 #####################################################
 # Metaclass used to help enforce the usage contract
 #####################################################
@@ -90,3 +90,37 @@ class IntegrationConfig(Config):
         ])
         
     processors = []
+"""
+    
+FULL = 1
+PARTIAL = 2
+CUSTOM = 3
+
+FILES_FULL = ['replay.initData','replay.details','replay.attributes.events','replay.message.events','replay.game.events']
+FILES_PARTIAL = ['replay.initData','replay.details','replay.attributes.events','replay.message.events']
+
+PROCESSORS_FULL = [
+            PeopleProcessor(),
+            AttributeProcessor(),
+            TeamsProcessor(),
+            MessageProcessor(),
+            RecorderProcessor(),
+            EventProcessor(),
+            ApmProcessor(),
+            ResultsProcessor()
+        ]
+        
+PROCESSORS_PARTIAL = [
+            PeopleProcessor(),
+            AttributeProcessor(),
+            TeamsProcessor(),
+            MessageProcessor(),
+            RecorderProcessor(),
+        ]
+READERS = OrderedDict([
+        ('replay.initData', [ReplayInitDataReader()]),
+        ('replay.details', [ReplayDetailsReader()]),
+        ('replay.attributes.events', [AttributeEventsReader_17326(), AttributeEventsReader()]),
+        ('replay.message.events', [MessageEventsReader()]),
+        ('replay.game.events', [GameEventsReader()]),
+    ])
