Permalink
Browse files

Update the documentation for the release

  • Loading branch information...
1 parent 6aaec97 commit b71c25d1865a7e16c6d29cdd926721ae6b17a563 @GraylinKim committed Aug 21, 2012
View
28 docs/source/index.rst
@@ -6,23 +6,27 @@ Thanks for choosing sc2reader for your Starcraft analysis needs.
There is a pressing need in the SC2 community for better statistics, better
analytics, better tools for organizing and searching replays. Better websites
for sharing replays and hosting tournaments. These tools can't be created with
-out first being able to open up replay files and analyse the content within. That's why SC2Reader was built, to provide a solid foundation on which the next
+out first being able to open up replay files and analyse the content within.
+That's why SC2Reader was built, to provide a solid foundation on which the next
generation of tools and websites can be built and benefit the community.
So lets get you started right away! Through the linked tutorials and reference
pages below we'll get you started building your own tools and systems in no
-time. Any questions, suggestions, or concerns should be posted to the sc2reader `mailing list`_. You can also pop on to our #sc2reader, our `IRC channel`_ on Freenode if you want to chat or need some live support.
+time. Any questions, suggestions, or concerns should be posted to the sc2reader
+`mailing list`_. You can also pop on to our #sc2reader, our `IRC channel`_ on
+Freenode if you want to chat or need some live support.
.. _mailing list: http://groups.google.com/group/sc2reader
.. _IRC Channel: http://webchat.freenode.net/?channels=#sc2reader
+
Tutorials
---------------
The best way to learn how to pick sc2Reader up and get started is probably by example. With that in mind, we've written up a series of tutorials on getting various simple tasks done with sc2reader; hopefully they can serve as a quick on ramp for you.
* :doc:`tutorials/prettyprinter` (10-15 minutes)
-* :doc:`tutorials/actionlistener` (10-15 minutes)
+
Reference Pages
-----------------------
@@ -32,10 +36,10 @@ SC2 replays hold a ton of information. The following reference pages were put to
.. toctree::
sc2reader
- mainstructures
- supportstructures
- listeners
- processors
+ primaryresources
+ supportobjects
+ utilityclasses
+ plugins
.. toctree::
@@ -44,8 +48,8 @@ SC2 replays hold a ton of information. The following reference pages were put to
:glob:
sc2reader
- mainstructures
- supportstructures
- listeners
- processors
- tutorials/*
+ primaryresources
+ supportobjects
+ utilityclasses
+ plugins
+ tutorials/*
View
90 docs/source/mainstructures.rst
@@ -1,90 +0,0 @@
-.. currentmodule:: sc2reader.resources
-
-Main Structures
-======================
-
-The outline of the key structures in the replay object.
-
-
-Replay
---------------
-
-.. autoclass:: Replay
-
- .. autoattribute:: filename
- .. autoattribute:: frames
- .. autoattribute:: build
- .. autoattribute:: release_string
- .. autoattribute:: length
- .. autoattribute:: speed
- .. autoattribute:: type
- .. autoattribute:: category
- .. autoattribute:: is_ladder
- .. autoattribute:: is_private
- .. autoattribute:: map
- .. autoattribute:: gateway
- .. autoattribute:: events
- .. autoattribute:: results
- .. autoattribute:: teams
- .. autoattribute:: team
- .. autoattribute:: players
- .. autoattribute:: player
- .. autoattribute:: observers
- .. autoattribute:: people
- .. autoattribute:: person
- .. autoattribute:: humans
- .. autoattribute:: messages
- .. autoattribute:: recorder
- .. autoattribute:: winner
-
-
-.. currentmodule:: sc2reader.objects
-
-
-Team
-----------------
-
-.. autoclass:: Team
-
- .. autoattribute:: number
- .. autoattribute:: players
- .. autoattribute:: result
- .. autoattribute:: lineup
-
-
-Person
--------------
-
-.. autoclass:: Person
-
- .. autoattribute:: pid
- .. autoattribute:: name
- .. autoattribute:: is_observer
- .. autoattribute:: is_human
- .. autoattribute:: messages
- .. autoattribute:: events
- .. autoattribute:: recorder
-
-
-Observer
----------------
-
-.. autoclass:: Observer
-
-
-
-Player
-------------------
-
-.. autoclass:: Player
-
- .. autoattribute:: team
- .. autoattribute:: url
- .. autoattribute:: result
- .. autoattribute:: color
- .. autoattribute:: pick_race
- .. autoattribute:: play_race
- .. autoattribute:: difficulty
- .. autoattribute:: handicap
- .. autoattribute:: region
- .. autoattribute:: subregion
View
59 docs/source/plugins.rst
@@ -0,0 +1,59 @@
+Plugins
+=============
+
+A plugin is pretty much just a callable function or object that accepts a replay
+file as a single argument. sc2reader supports assignment of plugins to different
+resource types via the :meth:`SC2Factory.register_plugin` factory method.
+
+::
+
+ import sc2reader
+ from sc2reader.plugins.replay import APMTracker, SelectionTracker
+ sc2reader.register_plugin('Replay',APMTracker())
+ sc2reader.register_plugin('Replay',SelectionTracker())
+
+The order you register plugins is the order they are executed in so be careful to
+put register in the right order if you have dependencies between plugins.
+
+
+APMTracker
+----------------
+
+The APMTracker adds three simple fields based on a straight tally of non-camera
+player action events such as selections, abilities, and hotkeys.
+
+* ``player.aps`` = a dictionary of second => total actions in that second
+* ``player.apm`` = a dictionary of minute => total actions in that minute
+* ``player.avg_apm`` = Average APM as a float
+
+
+SelectionTracker
+--------------------
+
+The :class:`SelectionTracker` plugin simulates every person's selection at every
+frame in both the hotkey and active selection buffers. This selection information
+is stored in ``person.selection`` as a two dimensional array of lists.
+
+::
+
+ unit_list = replay.player[1].selection[frame][buffer]
+
+Where buffer is a hotkey 0-9 or 10 which represents the active selection.
+
+There are a number of known flaws with the current tracking algorithm and/or the
+source information on which it works:
+
+* Deaths are not recorded. A selected unit that dies will be deselected though.
+* Transformations are not recorded. A hotkey'd egg that hatches into 2 zerglings
+ will not register and the egg will stay hotkeyed until the hotkey is over
+ written. If the transformed unit is part of active selection the
+ selection/deslection is handled properly.
+
+To help expose these short comings a ``person.selection_errors`` tally is kept. An
+error is recorded every time a selection event instructs us to do something that
+would not be possible with what we believe to be the current selection. Such an
+event would mean that our tracker went wrong previously.
+
+Players that consistently use ``shift+ctrl+hotkey`` to add to hotkeys instead of
+resetting hotkeys with ``ctrl+hotkey`` create tons of issues for this tracker
+because selection changes in hotkeys are not recorded in the replay file.
View
37 docs/source/primaryresources.rst
@@ -0,0 +1,37 @@
+.. currentmodule:: sc2reader.resources
+
+Main Structures
+======================
+
+The outline of the key structures in the replay object.
+
+
+Replay
+--------------
+
+.. autoclass:: Replay
+ :members:
+
+Map
+------------
+
+.. autoclass:: Map
+ :members:
+
+Game Summary
+---------------
+
+.. autoclass:: GameSummary
+ :members:
+
+MapInfo
+---------------
+
+.. autoclass:: MapInfo
+ :members:
+
+MapHeader
+---------------
+
+.. autoclass:: MapHeader
+ :members:
View
6 docs/source/sc2reader.rst
@@ -1,9 +1,9 @@
-.. currentmodule:: sc2reader
+.. currentmodule:: sc2reader.factories
SC2Reader
======================
The replay factory
-.. autoclass:: SC2Reader
- :members: load_replay, load_replays, register_listener, configure, register_datapack, register_reader, reset
+.. autoclass:: SC2Factory
+ :members:
View
47 docs/source/supportobjects.rst
@@ -0,0 +1,47 @@
+.. currentmodule:: sc2reader.objects
+
+Support Structures
+=========================
+
+These dumb data structures help to give meaningful organization and structure to the information in their respective parent resources.
+
+
+Team
+----------------
+
+.. autoclass:: Team
+
+
+Person
+-------------
+
+.. autoclass:: Person
+ :members:
+
+
+Observer
+---------------
+
+.. autoclass:: Observer
+ :members:
+
+
+Player
+------------------
+
+.. autoclass:: Player
+ :members:
+
+
+PlayerSummary
+-----------------
+
+.. autoclass:: PlayerSummary
+ :members:
+
+Graph
+-----------
+
+.. autoclass:: Graph
+ :members:
+
View
29 docs/source/supportstructures.rst
@@ -1,29 +0,0 @@
-.. currentmodule:: sc2reader.utils
-
-Support Structures
-=========================
-
-
-Color
--------------
-
-.. autoclass:: Color
-
- .. autoattribute:: rgba
- .. autoattribute:: hex
-
-
-Length
--------------
-
-.. autoclass:: Length
-
- .. autoattribute:: hours
- .. autoattribute:: mins
- .. autoattribute:: secs
-
-
-PersonDict
----------------
-
-.. autoclass:: PersonDict
View
21 docs/source/tutorials/prettyprinter.rst
@@ -82,7 +82,7 @@ The replay object itself is a dumb data structure; there are no access methods o
>>> replay.teams
[<sc2reader.objects.Team object at 0x2b5e410>, <sc2reader.objects.Team object at 0x2b5e4d0>]
-Many of the replay attributes are nested data structures which are generally all pretty dumb as well. The idea being that you should be able to access almost anything with a mixture of indexes and dot notation. Clean and simple accessibility is one of the primary design goals for sc2reader.
+Many of the replay attributes are nested data structures which are generally all pretty dumb as well. The idea being that you should be able to access almost anything with a mixture of indexes and dot notation. Clean and simple accessibility is one of the primary design goals for sc2reader.
::
@@ -125,7 +125,7 @@ Similar formatting written in a more verbose and less pythonic way:
return output
Next we need to format the teams for display. The :class:`Team` and :class:`Player` data structures are pretty straightforward as well so we can apply a bit of string formatting and produce this:
-
+
::
def formatTeams(replay):
@@ -230,4 +230,19 @@ Recognizing that most users will only ever need one active configuration at a ti
followlinks=True
)
-An ideal prettyPrinter script would let the user configure these options as arguments using the argparse library. Such an expansion is beyond the scope of sc2reader though, so we'll leave it as an exercise to the reader.
+Many of your replay files might be custom games for which events cannot be parsed. Since the pretty printer doesn't use game event information in its output we can limit the parse level of the replay to stop after loading the basic details. This will make the pretty printer work for custom games as well.
+
+::
+
+ import sc2reader
+
+ sc2reader.load_replay(path, load_level=1)
+
+There are 4 available load levels:
+
+* 0: Parses the replay header for version, build, and length information
+* 1: Also parses the replay.details file for player, team, winner, map, and time information
+* 2: Also parses the replay.message.events file for chat messages and player pings.
+* 3: Also parses the replay.events file for game event information.
+
+So that's it! An ideal prettyPrinter script might let the user configure these options as arguments using the argparse library. Such an expansion is beyond the scope of sc2reader though, so we'll leave it that one to you.
View
41 docs/source/utilityclasses.rst
@@ -0,0 +1,41 @@
+.. currentmodule:: sc2reader.utils
+
+Utility Classes
+===================
+
+These classes are provided to make working with certain types of data a bit easier or more flexible in interpretation.
+
+
+Color
+-------------
+
+.. autoclass:: Color
+ :members:
+
+
+Length
+-------------
+
+.. autoclass:: Length
+ :members:
+
+
+PersonDict
+---------------
+
+.. autoclass:: PersonDict
+ :members:
+
+
+AttributeDict
+------------------
+
+.. autoclass:: AttributeDict
+ :members:
+
+
+ReplayBuffer
+-------------------
+
+.. autoclass:: ReplayBuffer
+ :members:
View
28 sc2reader/factories.py
@@ -22,23 +22,23 @@ class SC2Factory(object):
:class:`Replay` and :class:`Map` resources. These resources can be
loaded in both singular and plural contexts with:
- * :method:`load_replay` - :class:`Replay`
- * :method:`load_replays` - generator<:class:`Replay`>
- * :method:`load_map` - :class:`Map`
- * :method:`load_maps` - : generator<:class:`Map`>
+ * :meth:`load_replay` - :class:`Replay`
+ * :meth:`load_replays` - generator<:class:`Replay`>
+ * :meth:`load_map` - :class:`Map`
+ * :meth:`load_maps` - : generator<:class:`Map`>
The load behavior can be configured in three ways:
# Passing options to the factory constructor
- # Using the :method:`configure` method of a factory instance
+ # Using the :meth:`configure` method of a factory instance
# Passing overried options into the load method
- See the :method:`configure` method for more details on configuration
+ See the :meth:`configure` method for more details on configuration
options.
sc2reader comes with some post processing capabilities which, depending
on your needs, may be useful. You can register these plugins to the load
- process with the :method:`register_plugins` method.
+ process with the :meth:`register_plugins` method.
"""
_resource_name_map = dict(replay=Replay,map=Map)
@@ -62,45 +62,59 @@ def __init__(self, **options):
# Primary Interface
def load_replay(self, source, options=None, **new_options):
+ """Loads a single sc2replay file. Accepts file path, url, or file object."""
return self.load(Replay, source, options, **new_options)
def load_replays(self, sources, options=None, **new_options):
+ """Loads a collection of sc2replay files, returns a generator."""
return self.load_all(Replay, sources, options, extension='SC2Replay', **new_options)
def load_map(self, source, options=None, **new_options):
+ """Loads a single s2ma file. Accepts file path, url, or file object."""
return self.load(Map, source, options, **new_options)
def load_maps(self, sources, options=None, **new_options):
+ """Loads a collection of s2ma files, returns a generator."""
return self.load_all(Map, sources, options, extension='s2ma', **new_options)
def load_game_summary(self, source, options=None, **new_options):
+ """Loads a single s2gs file. Accepts file path, url, or file object."""
return self.load(GameSummary, source, options, **new_options)
def load_game_summaries(self, sources, options=None, **new_options):
+ """Loads a collection of s2gs files, returns a generator."""
return self.load_all(GameSummary, sources, options, extension='s2gs', **new_options)
def load_map_info(self, source, options=None, **new_options):
+ """Loads a single s2mi file. Accepts file path, url, or file object."""
return self.load(MapInfo, source, options, **new_options)
def load_map_infos(self, sources, options=None, **new_options):
+ """Loads a collection of s2mi files, returns a generator."""
return self.load_all(MapInfo, sources, options, extension='s2mi', **new_options)
def load_map_header(self, source, options=None, **new_options):
+ """Loads a single s2mh file. Accepts file path, url, or file object."""
return self.load(MapHeader, source, options, **new_options)
def load_map_headers(self, sources, options=None, **new_options):
+ """Loads a collection of s2mh files, returns a generator."""
return plugins_all(MapHeader, sources, options, extension='s2mh', **new_options)
def configure(self, cls=None, **options):
+ """ Configures the factory to use the supplied options. If cls is specified
+ the options will only be applied when loading that class"""
if isinstance(cls, basestring):
cls = self._resource_name_map.get[cls.lower()]
cls = cls or Resource
self.options[cls].update(options)
def reset(self):
+ "Resets the options to factory defaults"
self.options = defaultdict(dict)
def register_plugin(self, cls, plugin):
+ "Registers the given Plugin to be run on classes of the supplied name."
if isinstance(cls, basestring):
cls = self._resource_name_map.get(cls.lower(),Resource)
self.plugins.append((cls, plugin))
View
6 sc2reader/resources.py
@@ -615,6 +615,8 @@ def get_url(cls, gateway, map_hash):
class GameSummary(Resource):
+ """**Experimental**"""
+
base_url_template = 'http://{0}.depot.battle.net:1119/{1}.{2}'
url_template = 'http://{0}.depot.battle.net:1119/{1}.s2gs'
@@ -966,6 +968,8 @@ def __str__(self):
class MapInfo(Resource):
+ """**Experimental**"""
+
url_template = 'http://{0}.depot.battle.net:1119/{1}.s2mi'
#: Name of the Map
@@ -993,6 +997,8 @@ def __str__(self):
return self.map_name
class MapHeader(Resource):
+ """**Experimental**"""
+
base_url_template = 'http://{0}.depot.battle.net:1119/{1}.{2}'
url_template = 'http://{0}.depot.battle.net:1119/{1}.s2mh'
image_url_template = 'http://{0}.depot.battle.net:1119/{1}.s2mv'
View
41 sc2reader/utils.py
@@ -20,46 +20,9 @@
LITTLE_ENDIAN,BIG_ENDIAN = '<','>'
class ReplayBuffer(object):
- """ The ReplayBuffer is a wrapper over the cStringIO object and provides
+ """ The ReplayBuffer is a wrapper over the a StringIO object and provides
convenience functions for reading structured data from Starcraft II
- replay files. These convenience functions can be sorted into several
- different categories providing an interface as follows:
-
- Stream Manipulation::
- tell(self)
- skip(self, amount)
- reset(self)
- align(self)
- seek(self, position, mode=SEEK_CUR)
-
- Data Retrieval::
- read_variable_int(self)
- read_string(self,additional)
- read_timestamp(self)
- read_count(self)
- read_data_structure(self)
- read_object_type(self, read_modifier=False)
- read_object_id(self)
- read_coordinate(self)
- read_bitmask(self)
- read_range(self, start, end)
-
- Basic Reading::
- read_byte(self)
- read_int(self, endian=LITTLE_ENDIAN)
- read_short(self, endian=LITTLE_ENDIAN)
- read_chars(self,length)
- read_hex(self,length)
-
- Core Reading::
- shift(self,bits)
- read(bytes,bits)
-
- The ReplayBuffer additionally defines the following properties:
- left
- length
-
- All read_* functions throw EOFErrors
+ replay files.
"""
def __init__(self, source):

0 comments on commit b71c25d

Please sign in to comment.