Metadata-Version: 2.4
Name: eventure
Version: 0.2.0
Summary: A Python library providing a robust, type-safe event system for game development and simulation.
Author-email: Enrico Stara <enrico.stara@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Enrico Stara
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Eventure

A Python library providing a robust, type-safe event system for game development and simulation. Eventure offers event tracking, time-based event management, and a powerful event bus with wildcard subscription support.

## Features

- **Event Class**: Immutable events with tick, timestamp, type, and data attributes
- **EventLog**: Track, save, and replay sequences of events
- **EventBus**: Decouple event producers from consumers
- **Wildcard Subscriptions**: Subscribe to event patterns like `user.*` or global `*`
- **JSON Serialization**: Save and load events for persistence or network transmission
- **Type Safety**: Strong typing throughout the API
- **Zero Dependencies**: Pure Python implementation

## Installation

```bash
# Using pip
pip install eventure

# Using uv
uv add eventure
```

## Quick Start

```python
from eventure import EventBus, EventLog, Event

# Create an event log to track game state
event_log = EventLog()

# Create an event bus connected to the log
event_bus = EventBus(event_log)

# Subscribe to specific events
def handle_user_created(event):
    print(f"User created at tick {event.tick}: {event.data}")

unsubscribe = event_bus.subscribe("user.created", handle_user_created)

# Subscribe to all user events with wildcard
event_bus.subscribe("user.*", lambda event: print(f"User event: {event.type}"))

# Publish an event (automatically uses current tick from event_log)
event = event_bus.publish("user.created", {"id": 1, "name": "John"})

# Advance the game tick
event_log.advance_tick()

# Events can be serialized to JSON
json_str = event.to_json()
print(json_str)

# And deserialized back
reconstructed_event = Event.from_json(json_str)

# Save event history to file
event_log.save_to_file("game_events.json")

# Later, load event history
new_log = EventLog.load_from_file("game_events.json")

# Unsubscribe when done
unsubscribe()
```

## Event System Architecture

### Event

The `Event` class represents an immutable record of something that happened in your application:

```python
@dataclass
class Event:
    tick: int               # Game tick when event occurred
    timestamp: float        # UTC timestamp
    type: str               # Event type identifier
    data: Dict[str, Any]    # Event-specific data
```

### EventLog

The `EventLog` manages sequences of events and provides replay capability:

- Tracks current tick number
- Records events with timestamps
- Provides persistence through save/load methods

### EventBus

The `EventBus` handles event publishing and subscription:

- Supports specific event type subscriptions
- Supports wildcard subscriptions (`user.*`)
- Supports global subscriptions (`*`)
- Automatically assigns current tick from EventLog

## Development

```bash
# Clone the repository
git clone https://github.com/enricostara/eventure.git
cd eventure

# Install development dependencies
uv sync --all-extras

# Run tests
just test
```

## License

MIT License - see LICENSE file for details