### Install sc2reader from Source (PyPI)

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Installs sc2reader from a downloaded source archive. Useful for installing specific versions or when direct PyPI installation is not feasible.

```bash
wget http://pypi.python.org/packages/source/s/sc2reader/sc2reader-x.x.x.tar.gz
tar -xzf sc2reader-x.x.x.tar.gz
cd sc2reader-x.x.x
pip install .
```

--------------------------------

### Plugin Setup and Cleanup Handlers

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/creatingagameengineplugin.md

Plugins can implement handleInitGame and handleEndGame methods to perform setup before replay processing and cleanup or post-processing after all events have been handled.

```python
# handleInitGame - is called prior to processing a new replay to provide
# an opportunity for the plugin to clear internal state and set up any
# replay state necessary.
handleInitGame

# handleEndGame - is called after all events have been processed and
# can be used to perform post processing on aggregated data or clean up
# intermediate data caches.
handleEndGame
```

--------------------------------

### Basic Script Setup

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Sets up a Python script to accept a replay file path from the command line.

```python
import sys

def main():
    path = sys.argv[1]

if __name__ == '__main__':
    main()
```

--------------------------------

### Install and Run Linting Tools

Source: https://github.com/ggtracker/sc2reader/blob/upstream/STYLE_GUIDE.rst

Install the required linting tools and run them to check code quality. Ensure your code adheres to these standards before committing.

```bash
pip install black codespell ruff
codespell -L queenland,uint
ruff .
black . --check
```

--------------------------------

### Install sc2reader from Source (Github)

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Installs sc2reader from a tarball downloaded from GitHub. This method is an alternative to pip installation from the repository.

```bash
wget -O sc2reader-upstream.tar.gz https://github.com/ggtracker/sc2reader/tarball/upstream
tar -xzf sc2reader-upstream.tar.gz
cd sc2reader-upstream
pip install .
```

--------------------------------

### Example Plugin Registration and Event Order

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/creatingagameengineplugin.md

Demonstrates how multiple plugins with different event handlers are registered and how the Game Engine calls them for a specific event type, respecting registration order and handler specificity.

```python
class Plugin1():
    def handleAbilityEvent(self, event, replay):
        pass

class Plugin2():
    def handleEvent(self, event, replay):
        pass

    def handleTargetAbilityEvent(self, event, replay):
        pass

sc2reader.engine.register_plugin(Plugin1())
sc2reader.engine.register_plugin(Plugin2())
```

```python
Plugin1.handleAbilityEvent(event, replay)
Plugin2.handleEvent(event, replay)
Plugin2.handleTargetAbilityEvent(event, replay)
```

--------------------------------

### Install sc2reader from PyPI

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Installs the stable version of sc2reader using pip. This is the recommended method for most users.

```bash
python3 -m pip install sc2reader
```

--------------------------------

### Install sc2reader from Github

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Installs the latest development version of sc2reader directly from its GitHub repository using pip. This provides the most up-to-date code.

```bash
pip install -e git+git://github.com/ggtracker/sc2reader#egg=sc2reader
```

--------------------------------

### Install for Development

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Installs sc2reader in 'develop' mode from a local Git clone. This links the installed package to your local code, allowing immediate use of local edits.

```bash
git clone https://github.com/ggtracker/sc2reader.git
cd sc2reader
pip install -e .
```

--------------------------------

### Install and Run Black Formatter

Source: https://github.com/ggtracker/sc2reader/blob/upstream/CONTRIBUTING.md

Install the Black code formatter and apply it to the current directory. This tool helps maintain consistent Python code style.

```bash
pip install black
black .
```

--------------------------------

### Run All Tests with Pytest

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Execute all tests using pytest. Ensure pytest is installed via pip.

```bash
pytest
```

--------------------------------

### Plugin Message Passing with Yield

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/creatingagameengineplugin.md

Event handlers can yield new events to inject them into the event stream, enabling message passing between plugins. This example shows how to yield an ExpansionEvent.

```python
def handleUnitDoneEvent(self, event, replay):
        if event.unit.name == 'Nexus':
                yield ExpansionEvent(event.frame, event.unit)
        ...
```

--------------------------------

### Configure and Load Replay with Default Factory

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/conceptsinsc2reader.md

Demonstrates how to configure the default sc2reader factory and load a replay file. Ensure the replay file path is correct.

```python
sc2reader.configure(debug=True)
replay = sc2reader.load_replay('my_replay.SC2Replay')
```

--------------------------------

### Set Up Local Cache Directory for Tests

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Create a local directory for caching to speed up repeated test runs. This prevents long fetch times from battle.net.

```bash
mkdir cache
```

--------------------------------

### Loading a Replay with SC2Factory

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Demonstrates how to use SC2Factory to load a replay file into a Replay object.

```python
from sc2reader.factories import SC2Factory

def main():
    path = sys.argv[1]
    sc2 = SC2Factory()
    replay = sc2.load_replay(path)
```

--------------------------------

### Register Plugin and Run Game Engine

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/conceptsinsc2reader.md

Shows how to register a custom plugin with the sc2reader GameEngine and then run the engine on a replay. Ensure the plugin class is defined and the replay object is loaded.

```python
sc2reader.engine.register_plugin(MyPlugin())
sc2reader.engine.run(replay)
```

--------------------------------

### Load Multiple Replays

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/gettingstarted.md

Loads all replays from a specified directory. Returns a replay generator.

```python
replays = sc2reader.load_replays('path/to/replay/directory')
```

--------------------------------

### Registering APMTracker and SelectionTracker Plugins

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/plugins.md

Demonstrates how to register custom plugins with the sc2reader game engine. Ensure plugins are registered in the correct order if dependencies exist.

```python
import sc2reader
from sc2reader.engine.plugins import APMTracker, SelectionTracker
sc2reader.engine.register_plugin(APMTracker())
sc2reader.engine.register_plugin(SelectionTracker())
```

--------------------------------

### Loading a Replay with Default Factory

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

A shorthand method for loading a replay using the default sc2reader factory.

```python
import sc2reader

def main():
    path = sys.argv[1]
    replay = sc2reader.load_replay(path)
```

--------------------------------

### Load a Replay

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/gettingstarted.md

Loads a single replay file with all data. Use `load_map=true` to also load the corresponding map file.

```python
import sc2reader
replay = sc2reader.load_replay('MyReplay', load_map=true)
```

--------------------------------

### Load Replay with Limited Parse Level

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Loads a replay file with a specified `load_level`. Setting `load_level=1` parses basic header and detail information, which is sufficient for the pretty printer and allows processing custom game replays that may not have full event data.

```python
import sc2reader

sc2reader.load_replay(path, load_level=1)

```

--------------------------------

### Run a Specific Test with Local Cache

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Execute a single test case by specifying its path and name, utilizing the local cache directory.

```bash
SC2READER_CACHE_DIR=./cache pytest test_replays/test_replays.py::TestReplays::test_38749
```

--------------------------------

### Formatting Replay Header with String Formatting

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Uses Python's string formatting to create a formatted header for the replay output, leveraging the replay object's attributes.

```python
def formatReplay(replay):
    return """

{filename}
--------------------------------------------
SC2 Version {release_string}
{category} Game, {start_time}
{type} on {map_name}
Length: {game_length}

""".format(**replay.__dict__)
```

--------------------------------

### Registering a Plugin with sc2reader

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/creatingagameengineplugin.md

To use a custom plugin, register an instance of the plugin class with the sc2reader game engine using the register_plugin function. Ensure plugins are registered in the correct order if dependencies exist.

```python
sc2reader.engine.register_plugin(MyPlugin())
```

--------------------------------

### Register Plugins

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/gettingstarted.md

Registers custom plugins with the SC2Reader engine. Ensure plugins are imported before registration.

```python
from sc2reader.engine.plugins import SelectionTracker, APMTracker
sc2reader.engine.register_plugin(SelectionTracker())
sc2reader.engine.register_plugin(APMTracker())
```

--------------------------------

### Standard File Header

Source: https://github.com/ggtracker/sc2reader/blob/upstream/STYLE_GUIDE.rst

All files must begin with this specific header, including encoding declaration and necessary future imports. This ensures compatibility and proper module behavior.

```python
# -*- coding: utf-8 -*-
#
# Optional Documentation on the module
#
from __future__ import absolute_import, print_function, unicode_literals, division
```

--------------------------------

### Configure SC2Factory Options

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Customizes the SC2Factory instance with specific options like directory, exclusion lists, and symlink following. The `configure()` method can be used to modify an existing factory instance.

```python
from sc2reader.factories import SC2Factory

sc2 = SC2Factory(
    directory='~/Documents/Starcraft II/Multiplayer/Replays',
    exclude=['Customs','Pros'],
    followlinks=True
)

sc2.configure(depth=1)

```

--------------------------------

### Load Map File

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Loads a map file directly or alongside a replay. The `replay.load_map()` method can be called after loading a replay.

```python
replay = sc2reader.load_replay('MyReplay.SC2Replay', load_map=true)
replay.load_map()
```

```python
map = sc2reader.load_map('MyMap.SC2Map')
```

```python
map = sc2reader.load_maps('path/to/maps/directory')
```

--------------------------------

### Generate Build Data Script

Source: https://github.com/ggtracker/sc2reader/blob/upstream/sc2reader/data/HOWTO.md

Execute this Python script to generate updated data files for a new StarCraft II build version. Ensure you provide the correct expansion level, build version, balance data directory, and sc2reader project root.

```python
python3 sc2reader/generate_build_data.py LotV 53644 balance_data/ sc2reader/
```

--------------------------------

### List Game Events and Messages

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/faq.md

Iterate through all events in a replay to print their process ID, name, and timestamp. Ensure the replay file is loaded using sc2reader.load_replay.

```python
replay = sc2reader.load_replay('path/to/replay.SC2Replay')
for event in replay.events:
    print '{0} => {1}: {2}'.format(event.pid,event.name, event.time)
```

--------------------------------

### Accessing Replay Attributes

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Shows how to access various attributes of a loaded Replay object, such as filename, version, category, and game details.

```python
>>> replay.filename
'test_replays/1.4.0.19679/The Boneyard (10).SC2Replay'
>>> replay.release_string
'1.4.0.19679'
>>> replay.category
'Ladder'
>>> replay.end_time
datetime.datetime(2011, 9, 20, 21, 8, 8)
>>> replay.type
'2v2'
>>> replay.map_name
'The Boneyard'
>>> replay.game_length # string format is MM.SS
Length(0, 1032)
>>> replay.teams
[<sc2reader.objects.Team object at 0x2b5e410>, <sc2reader.objects.Team object at 0x2b5e4d0>]
```

--------------------------------

### Load Map File

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/gettingstarted.md

Loads a specific map file or all maps from a directory.

```python
map = sc2reader.load_map('MyMap.SC2Map')
```

```python
map = sc2reader.load_maps('path/to/maps/directory')
```

--------------------------------

### Load Multiple Replays

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Processes multiple replay files or directories by iterating through the results of `sc2reader.load_replays()`. This function is more versatile than `load_replay()` for handling collections of replays.

```python
def main():
    paths = sys.argv[1:]
    for replay in sc2reader.load_replays(paths):
        print formatReplay(replay)

```

--------------------------------

### Formatting Replay Header Verbose

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

An alternative, more verbose method for formatting the replay header using string concatenation.

```python
def formatReplay(replay):
    output  = replay.filename+'\n'
    output += "--------------------------------------------\n"
    output += "SC2 Version "+replay.release_string+'\n'
    output += replay.category+" Game, "+str(replay.start_time)+'\n'
    output += replay.type+" on "+replay.map_name+'\n'
    output += "Length: "+str(replay.game_length)
    return output
```

--------------------------------

### Configure Caching

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/gettingstarted.md

Sets environment variables for SC2Reader caching BEFORE importing the module. `SC2READER_CACHE_DIR` specifies the cache directory, and `SC2READER_CACHE_MAX_SIZE` sets the maximum number of entries for memory caching.

```python
import os
os.environ['SC2READER_CACHE_DIR'] = "path/to/local/cache"
os.environ['SC2READER_CACHE_MAX_SIZE'] = 100

# if you have imported sc2reader anywhere already this won't work
import sc2reader
```

--------------------------------

### Load Replay with Specific Load Levels

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/gettingstarted.md

Limits replay loading to improve performance. Higher `load_level` values include more data.

```python
# Release version and game length info. Nothing else
sc2reader.load_replay('MyReplay.SC2Replay', load_level=0)
```

```python
# Also loads game details: map, speed, time played, etc
sc2reader.load_replay('MyReplay.SC2Replay', load_level=1)
```

```python
# Also loads players and chat events:
sc2reader.load_replay('MyReplay.SC2Replay', load_level=2)
```

```python
# Also loads tracker events:
sc2reader.load_replay('MyReplay.SC2Replay', load_level=3)
```

```python
# Also loads game events:
sc2reader.load_replay('MyReplay.SC2Replay', load_level=4)
```

--------------------------------

### Accessing Nested Replay Data

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Demonstrates accessing nested data structures within the Replay object, like player colors and profile URLs.

```python
>>> replay.teams[0].players[0].color.hex
'B4141E'
>>> replay.player.name('Remedy').url
'https://starcraft2.com/en-us/profile/1/1/2198663'
```

--------------------------------

### Configure Default Factory

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Configures the default SC2Reader factory globally. This allows setting options such as the replay directory, exclusion patterns, recursion depth, and symlink following for all subsequent replay loading operations.

```python
import sc2reader

sc2reader.configure(
    directory='~/Documents/Starcraft II/Multiplayer/Replays',
    exclude=['Customs','Pros'],
    depth=1,
    followlinks=True
)

```

--------------------------------

### Formatting Team and Player Information

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Formats the team and player information for display, including player race and name.

```python
def formatTeams(replay):
    teams = list()
    for team in replay.teams:
        players = list()
        for player in team:
            players.append("({0}) {1}".format(player.pick_race[0], player.name))
        formattedPlayers = '\n         '.join(players)
        teams.append("Team {0}:  {1}".format(team.number, formattedPlayers))
    return '\n\n'.join(teams)
```

--------------------------------

### Format Replay Data

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/tutorials/prettyprinter.md

Formats replay data into a human-readable string, including game version, map, players, and teams. Requires helper functions `formatTeams` and `formatReplay`.

```python
import sys

import sc2reader

def formatTeams(replay):
    teams = list()
    for team in replay.teams:
        players = list()
        for player in team:
            players.append("({0}) {1}".format(player.pick_race[0], player.name))
        formattedPlayers = '\n         '.join(players)
        teams.append("Team {0}:  {1}".format(team.number, formattedPlayers))
    return '\n\n'.join(teams)

def formatReplay(replay):
    return """
{filename}
--------------------------------------------
SC2 Version {release_string}
{category} Game, {start_time}
{type} on {map_name}
Length: {game_length}

{formattedTeams}
 "".format(formattedTeams=formatTeams(replay), **replay.__dict__)


def main():
    path = sys.argv[1]
    replay = sc2reader.load_replay(path)
    print formatReplay(replay)

if __name__ == '__main__':
    main()

```

--------------------------------

### Plugin Early Exit with PluginExit

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/creatingagameengineplugin.md

Plugins can stop processing a replay by yielding a PluginExit event. The GameEngine intercepts this, removes the plugin, and makes the exit code and details available.

```python
def handleEvent(self, event, replay):
        if len(replay.tracker_events) == 0:
                yield PluginExit(self, code=0, details=dict(msg="tracker events required"))
                return
        ...
```

```python
def handleAbilityEvent(self, event, replay):
        try:
                possibly_throwing_error()
        catch Error as e:
                logger.error(e)
                yield PluginExit(self, code=0, details=dict(msg="Unexpected exception"))
                return
```

```python
code, details = replay.plugins['MyPlugin']
```

--------------------------------

### Plugin Event Handling Methods

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/articles/creatingagameengineplugin.md

Plugins can handle specific events using methods named after the event, or more general events by handling parent classes. Matching handlers are called in order of plugin registration.

```python
def handleEventName(self, event, replay)
```

--------------------------------

### Accessing Player Selection Data

Source: https://github.com/ggtracker/sc2reader/blob/upstream/docs/source/plugins.md

Shows how to access a player's active selection data using the SelectionTracker plugin. This attribute reflects the selection state at the time of the event within a plugin.

```python
active_selection = event.player.selection[10]
```

--------------------------------

### Stop on First Failure

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Configure pytest to halt execution immediately after the first test failure occurs using the -x flag.

```bash
pytest -x
```

--------------------------------

### Run Tests with Local Cache Directory

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Run pytest tests while specifying a local cache directory using the SC2READER_CACHE_DIR environment variable.

```bash
SC2READER_CACHE_DIR=./cache pytest
```

--------------------------------

### Display Slowest Tests

Source: https://github.com/ggtracker/sc2reader/blob/upstream/README.rst

Identify the 10 slowest tests to help pinpoint performance issues by using the --durations=10 flag with pytest.

```bash
pytest --durations=10
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.