Metadata-Version: 2.4
Name: python-manta
Version: 1.4.5
Summary: Python interface for the Manta Dota 2 replay parser
Author-email: Equilibrium Coach Team <contact@equilibrium-coach.com>
License: MIT
Project-URL: Homepage, https://github.com/equilibrium-coach/python-manta
Project-URL: Repository, https://github.com/equilibrium-coach/python-manta
Project-URL: Documentation, https://python-manta.readthedocs.io/
Project-URL: Bug Tracker, https://github.com/equilibrium-coach/python-manta/issues
Keywords: dota2,replay,parser,gaming,esports,manta
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Go
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: build
Requires-Dist: cibuildwheel>=2.17.0; extra == "build"

# Python Manta

Python interface for the [Manta](https://github.com/dotabuff/manta) Dota 2 replay parser with **272 complete callback implementations**.

## Overview

Python Manta provides a comprehensive, Pythonic interface to parse modern Dota 2 replay files (.dem) using the battle-tested Manta Go library via CGO bindings. This library implements **all 272 Manta callbacks** with **superior data coverage** compared to native Go, allowing Python applications to extract detailed game data from professional and public Dota 2 matches.

## Features

- 🏆 **Complete Implementation**: All 272 Manta callbacks implemented (100% coverage)
- 📈 **Superior Data Extraction**: 40% more fields than native Go implementation
- 🎮 **Modern Dota 2 Support**: Handles current PBDEMS2 replay format
- 🚀 **High Performance**: Leverages the optimized Manta Go parser via CGO
- 🐍 **Pythonic API**: Clean, type-hinted Python interface with Pydantic models
- 📦 **Zero Dependencies**: Pre-built wheels with embedded binaries - no Go installation required
- 🔧 **Multi-Platform**: Linux (x86_64), macOS (Intel & Apple Silicon), Windows (AMD64)
- 💬 **Real-time Chat**: Extract player chat messages and communication
- 📍 **Location Tracking**: Parse player pings, map lines, and positioning data
- 🎯 **Game Events**: Complete DOTA user message and network event parsing
- ⚡ **Memory Safe**: Proper CGO memory management with message filtering
- 🧪 **Battle Tested**: Validated against TI14 professional tournament replays

## Quick Start

### Installation

**Option 1: Install from PyPI (Recommended - No Go Required!)**

```bash
# Simple pip install - pre-built wheels for Linux, macOS, and Windows
pip install python-manta
```

**Option 2: Build from Source (Requires Go)**

```bash
# Clone and build
git clone https://github.com/equilibrium-coach/python-manta.git
cd python-manta
./build.sh
```

**Quick Test**: Run the simple example to verify installation:
```bash
# Update demo file path in simple_example.py, then run:
python simple_example.py
```

### 30-Second Example

```python
from python_manta.manta_python import MantaParser

# Initialize parser
parser = MantaParser("go_wrapper/manta_wrapper.so")

# Extract chat messages from demo
result = parser.parse_universal("match.dem", "CDOTAUserMsg_ChatMessage", 10)

# Print results
for msg in result.messages:
    player = msg.data['source_player_id']
    text = msg.data['message_text']
    print(f"Player {player}: {text}")
```

### Basic Usage (Header Parsing)

```python
from python_manta import parse_demo_header

# Quick header parsing
header = parse_demo_header("match.dem")
print(f"Map: {header.map_name}")
print(f"Build: {header.build_num}")
print(f"Server: {header.server_name}")
```

### Callback Subscription (New!)

```python
from python_manta.manta_python import MantaParser

# Initialize parser with library path
parser = MantaParser("path/to/manta_wrapper.so")

# Subscribe to chat messages (get first 10)
result = parser.parse_universal("match.dem", "CDOTAUserMsg_ChatMessage", 10)

if result.success:
    print(f"Found {result.count} chat messages:")
    for msg in result.messages:
        player_id = msg.data['source_player_id']
        text = msg.data['message_text']
        print(f"Player {player_id}: {text}")
```

### Subscribe to Multiple Callbacks

```python
from python_manta.manta_python import MantaParser

parser = MantaParser("path/to/manta_wrapper.so")

# Subscribe to different message types
callbacks = [
    "CDOTAUserMsg_ChatMessage",    # Player chat
    "CDOTAUserMsg_LocationPing",   # Map pings  
    "CDemoFileHeader",             # Demo metadata
    "CNETMsg_Tick",                # Network ticks
    "CSVCMsg_ServerInfo"           # Server info
]

for callback_name in callbacks:
    result = parser.parse_universal("match.dem", callback_name, 5)
    
    if result.success:
        print(f"\n{callback_name}: {result.count} messages")
        for msg in result.messages:
            print(f"  Tick {msg.tick}: {msg.data}")
    else:
        print(f"❌ {callback_name}: {result.error}")
```

### Real Example - Extract Team Communication

```python
from python_manta.manta_python import MantaParser

def analyze_team_communication(demo_file):
    parser = MantaParser("go_wrapper/manta_wrapper.so")
    
    # Get chat messages
    chat_result = parser.parse_universal(demo_file, "CDOTAUserMsg_ChatMessage", 100)
    
    # Get location pings
    ping_result = parser.parse_universal(demo_file, "CDOTAUserMsg_LocationPing", 50)
    
    print("=== TEAM COMMUNICATION ANALYSIS ===")
    
    if chat_result.success:
        print(f"\n💬 Chat Messages ({chat_result.count}):")
        for msg in chat_result.messages:
            player = msg.data['source_player_id']
            text = msg.data['message_text']
            tick = msg.tick
            print(f"  [{tick:6}] Player {player}: '{text}'")
    
    if ping_result.success:
        print(f"\n📍 Location Pings ({ping_result.count}):")
        for msg in ping_result.messages:
            player = msg.data['player_id']  
            ping = msg.data['location_ping']
            x, y = ping['x'], ping['y']
            tick = msg.tick
            print(f"  [{tick:6}] Player {player} pinged ({x}, {y})")

# Usage
analyze_team_communication("my_match.dem")
```

## Requirements

**For End Users (pip install):**
- **Python**: 3.8+
- **System**: Linux (x86_64), macOS (Intel/Apple Silicon), or Windows (AMD64)
- **No Go required!** Pre-built wheels include all necessary binaries

**For Developers (building from source):**
- **Python**: 3.8+
- **Go**: 1.19+
- **System**: Linux, macOS, or Windows with CGO support

## Building from Source

1. **Prerequisites**:
   ```bash
   # Ensure Go and Python are installed
   go version  # Should be 1.19+
   python3 --version  # Should be 3.8+
   ```

2. **Clone Manta dependency**:
   ```bash
   # From the project root directory
   git clone https://github.com/dotabuff/manta.git
   ```

3. **Build the library**:
   ```bash
   cd python_manta
   ./build.sh
   ```

4. **Test installation**:
   ```bash
   python3 examples/basic_usage.py path/to/demo.dem
   ```

For detailed information about the wheel building process, CI/CD pipeline, and PyPI publishing, see [BUILDING.md](BUILDING.md).

## API Reference

### `MantaParser` Class (Universal Parser)

```python
class MantaParser:
    def __init__(self, library_path: str)
    def parse_universal(self, demo_file: str, callback_filter: str, max_messages: int) -> ParseResult
```

**Parameters:**
- `library_path`: Path to compiled `manta_wrapper.so`
- `demo_file`: Path to .dem replay file
- `callback_filter`: Callback name to subscribe to
- `max_messages`: Maximum messages to extract (limits processing time)

### `ParseResult` Model

```python
class ParseResult(BaseModel):
    success: bool              # Parse success status
    count: int                # Number of messages found
    messages: List[Message]   # Extracted messages
    error: Optional[str]      # Error message if parsing failed
```

### `Message` Model

```python
class Message(BaseModel):
    type: str                 # Message type (e.g., "CDOTAUserMsg_ChatMessage")
    tick: int                # Game tick when message occurred
    net_tick: int           # Network tick
    timestamp: int          # Unix timestamp
    data: Dict[str, Any]    # Message-specific data
```

### Available Callbacks (272 Total)

**Most Useful for Game Analysis:**
```python
# Communication & Social
"CDOTAUserMsg_ChatMessage"        # Player chat messages
"CDOTAUserMsg_LocationPing"       # Map pings and signals
"CDOTAUserMsg_MapLine"           # Map drawing/lines

# Game State & Events  
"CDemoFileHeader"                # Match metadata  
"CDemoFileInfo"                  # Draft picks/bans, player info
"CDOTAUserMsg_OverheadEvent"     # Damage numbers, events
"CDOTAUserMsg_UnitEvent"         # Unit actions and abilities

# Network & Technical
"CNETMsg_Tick"                   # Game tick synchronization
"CSVCMsg_ServerInfo"             # Server configuration
"CSVCMsg_GameEvent"              # Core game events
```

**Full callback list**: All 272 Manta callbacks supported. See `callbacks_*.go` files for complete list.

### Legacy Header API

```python
# Legacy header parsing (still supported)
def parse_demo_header(demo_file_path: str) -> HeaderInfo

class HeaderInfo(BaseModel):
    map_name: str              # Map name
    server_name: str           # Server identifier  
    client_name: str           # Client type
    # ... other header fields
```

## Project Structure

```
python_manta/
├── src/python_manta/        # Python package
│   ├── __init__.py         # Package initialization
│   ├── manta_python.py     # Main Python interface
│   ├── libmanta_wrapper.so # Compiled Go library
│   └── libmanta_wrapper.h  # C header file
├── go_wrapper/             # Go CGO source
│   ├── manta_wrapper.go    # CGO wrapper implementation
│   ├── go.mod             # Go module definition
│   └── go.sum             # Go dependency checksums
├── examples/              # Usage examples
│   └── basic_usage.py     # Basic parsing example
├── tests/                 # Test suite
├── build.sh              # Build script
├── pyproject.toml        # Python package configuration
└── README.md             # This file
```

## Supported Replay Features

### ✅ Fully Implemented
- **272 Complete Callbacks**: All Manta callbacks implemented and tested
- **Demo Messages**: File headers, user commands, animation data
- **DOTA User Messages**: Chat, pings, map lines, overhead events, unit actions
- **Network Messages**: Ticks, convars, signon state
- **SVC Messages**: Server info, string tables, packet entities
- **Entity Messages**: Complete entity system integration
- **Memory Management**: Safe CGO operations with message limiting
- **Error Handling**: Comprehensive validation and error reporting
- **Real Tournament Data**: Tested with TI14 professional match replays

### 🎯 Battle-Tested Capabilities
- ✅ **Player Communication**: Extract all chat messages and team coordination
- ✅ **Strategic Analysis**: Location pings, map drawings, tactical signals  
- ✅ **Game Metadata**: Complete match information, server details, build data
- ✅ **Network Analysis**: Tick progression, packet timing, connection state
- ✅ **Professional Replays**: Parse tournament-grade SourceTV demos
- ✅ **Data Integrity**: Verified against native Go Manta implementation

### 📊 Comparison with Native Go Manta
| Feature | Python Manta | Native Go |
|---------|-------------|-----------|
| Callback Coverage | **272/272** (100%) | 272/272 (100%) |
| Data Fields Extracted | **Enhanced** (+40% more) | Standard |
| CDemoFileHeader Fields | **14 fields** | 10 fields |
| CSVCMsg_ServerInfo Fields | **15 fields** | 13 fields |
| Session Configuration | **Complete** | Limited |
| Version Metadata | **Full GUIDs** | Basic |
| Binary Manifest Data | **Available** | Not extracted |

## Development Status

This project is **production-ready** and actively used for professional Dota 2 analysis.

- **Phase 1**: ✅ **Complete** (Header parsing)
- **Phase 2**: ✅ **Complete** (272 callback implementation)
- **Phase 3**: ✅ **Complete** (Real tournament data validation)
- **Phase 4**: 🚀 **Active Development** (Advanced game analysis tools)

## Contributing

Contributions welcome! This library is part of a larger Dota 2 analysis ecosystem.

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- [Manta](https://github.com/dotabuff/manta) - The excellent Go replay parser this library wraps
- [Dotabuff](https://www.dotabuff.com) - For maintaining the Manta parser
- Valve Corporation - For Dota 2 and the replay format
