valanga 0.1.1__tar.gz → 0.1.2__tar.gz

{valanga-0.1.1/src/valanga.egg-info → valanga-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valanga
-Version: 0.1.1
+Version: 0.1.2
 Summary: Shared types and utilities for evalaution
 Requires-Python: >=3.13
 License-File: LICENSE

valanga-0.1.2/README.md

@@ -0,0 +1,43 @@
+# valanga
+
+![Python 3.13](https://img.shields.io/badge/python-3.13-blue?logo=python)
+[![Tests](https://github.com/victorgabillon/valanga/actions/workflows/ci.yaml/badge.svg?label=tests)](https://github.com/victorgabillon/valanga/actions/workflows/ci.yaml)
+[![License: GPL v3](https://img.shields.io/github/license/victorgabillon/valanga)](LICENSE)
+
+Shared Python types and lightweight utilities for describing turn-based games and their evaluations. The package exposes protocols for representing states, outcomes, and state representations that other libraries can build on.
+
+## Key concepts
+- **Game primitives**: `Color`, `BranchKey`, `State`, and related protocols describe whose turn it is, how to enumerate legal branches, and how to copy or advance a state. 【F:src/valanga/game.py†L14-L95】
+- **Evaluations**: `FloatyStateEvaluation` captures heuristic scores while `ForcedOutcome` records a definitive result plus the line of play that forces it. Both are grouped under `BoardEvaluation`. 【F:src/valanga/evaluations.py†L13-L43】
+- **Game termination**: `OverEvent` combines how a game ended with who won, backed by `HowOver` and `Winner` enums. Utility helpers like `is_over()` and `get_over_tag()` simplify downstream checks. 【F:src/valanga/over_event.py†L8-L115】
+- **State representations**: `ContentRepresentation` defines how to turn a `State` into evaluator input, and `RepresentationFactory` builds or updates those representations from states and modifications. 【F:src/valanga/represention_for_evaluation.py†L9-L22】【F:src/valanga/representation_factory.py†L7-L55】
+- **Progress reporting**: `PlayerProgressMessage` communicates per-player progress percentages during long-running work. 【F:src/valanga/progress_messsage.py†L9-L18】
+
+## Installation
+```bash
+pip install .
+```
+The project targets Python 3.13 and has no required runtime dependencies.
+
+## Quick start
+Below is a minimal example that marks a finished game and obtains an evaluation structure:
+```python
+from valanga import ForcedOutcome, OverEvent
+from valanga.over_event import HowOver, Winner
+
+# A checkmate where white wins.
+over_event = OverEvent(how_over=HowOver.WIN, who_is_winner=Winner.WHITE)
+
+# Record the forced outcome and the line of optimal moves that lead to it.
+forced = ForcedOutcome(outcome=over_event, line=["e2e4", "e7e5"])
+print(forced.outcome.get_over_tag())  # -> OverTags.TAG_WIN_WHITE
+```
+
+To wire in a custom state representation, supply callables to `RepresentationFactory` that know how to build representations from a `State` and its modifications.
+
+## Development
+Install the development dependencies and run the test suite:
+```bash
+pip install -e '.[dev]'
+pytest
+```

{valanga-0.1.1 → valanga-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "valanga"
-version = "0.1.1"
+version = "0.1.2"
 description = "Shared types and utilities for evalaution"
 requires-python = ">=3.13"
 dependencies = []

{valanga-0.1.1 → valanga-0.1.2}/src/valanga/game.py

@@ -16,7 +16,7 @@ type StateModifications = Annotated[
 type BranchKey = Annotated[Hashable, "A label or identifier for a branch in a tree"]
 
 
-T_co = TypeVar("T_co", bound=BranchKey, covariant=True)
+T_co = TypeVar("T_co", bound=BranchKey, covariant=True, default=BranchKey)
 
 
 class BranchKeyGeneratorP(Protocol[T_co]):

{valanga-0.1.1 → valanga-0.1.2/src/valanga.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valanga
-Version: 0.1.1
+Version: 0.1.2
 Summary: Shared types and utilities for evalaution
 Requires-Python: >=3.13
 License-File: LICENSE

{valanga-0.1.1 → valanga-0.1.2}/src/valanga.egg-info/SOURCES.txt

@@ -15,4 +15,6 @@ src/valanga.egg-info/SOURCES.txt
 src/valanga.egg-info/dependency_links.txt
 src/valanga.egg-info/requires.txt
 src/valanga.egg-info/top_level.txt
-tests/test_placeholder.py
+tests/test_over_event.py
+tests/test_placeholder.py
+tests/test_representation_factory.py

valanga-0.1.2/tests/test_over_event.py

@@ -0,0 +1,106 @@
+import pytest
+
+from valanga.game import Color
+from valanga.over_event import HowOver, OverEvent, OverTags, Winner
+
+
+@pytest.mark.parametrize(
+    "who, expected",
+    [
+        (Winner.WHITE, OverTags.TAG_WIN_WHITE),
+        (Winner.BLACK, OverTags.TAG_WIN_BLACK),
+    ],
+)
+def test_get_over_tag_win_outcomes(who, expected):
+    event = OverEvent(how_over=HowOver.WIN, who_is_winner=who)
+
+    assert event.get_over_tag() == expected
+    assert event.is_over() is True
+    assert event.is_win() is True
+    assert event.is_draw() is False
+
+
+@pytest.mark.parametrize("winner", [Winner.WHITE, Winner.BLACK])
+def test_is_winner_matches_color(winner):
+    event = OverEvent(how_over=HowOver.WIN, who_is_winner=winner)
+
+    assert event.is_winner(Color.WHITE) is (winner == Winner.WHITE)
+    assert event.is_winner(Color.BLACK) is (winner == Winner.BLACK)
+
+
+@pytest.mark.parametrize(
+    "how_over, winner, expected",
+    [
+        (HowOver.DRAW, Winner.NO_KNOWN_WINNER, OverTags.TAG_DRAW),
+        (HowOver.DO_NOT_KNOW_OVER, Winner.NO_KNOWN_WINNER, OverTags.TAG_DO_NOT_KNOW),
+    ],
+)
+def test_get_over_tag_draw_and_unknown(how_over, winner, expected):
+    event = OverEvent(how_over=how_over, who_is_winner=winner)
+
+    assert event.get_over_tag() == expected
+    assert event.is_over() is (how_over == HowOver.DRAW)
+    assert event.is_win() is False
+    assert event.is_draw() is (how_over == HowOver.DRAW)
+
+
+@pytest.mark.parametrize(
+    "how_over, who_is_winner",
+    [
+        (HowOver.WIN, Winner.NO_KNOWN_WINNER),
+        (HowOver.DRAW, Winner.WHITE),
+    ],
+)
+def test_post_init_validates_winner_configuration(how_over, who_is_winner):
+    with pytest.raises(AssertionError):
+        OverEvent(how_over=how_over, who_is_winner=who_is_winner)
+
+
+@pytest.mark.parametrize("player", [Color.WHITE, Color.BLACK])
+def test_is_winner_requires_win(player):
+    event = OverEvent(how_over=HowOver.DRAW, who_is_winner=Winner.NO_KNOWN_WINNER)
+
+    assert event.is_winner(player) is False
+
+
+@pytest.mark.parametrize(
+    "how_over, expected_exception",
+    [
+        (HowOver.WIN, ValueError),
+        (None, ValueError),
+    ],
+)
+def test_get_over_tag_invalid_configurations(how_over, expected_exception):
+    event = OverEvent(how_over=HowOver.WIN, who_is_winner=Winner.WHITE)
+    event.how_over = how_over  # mutate to bypass post-init validation
+    event.who_is_winner = Winner.NO_KNOWN_WINNER
+
+    with pytest.raises(expected_exception):
+        event.get_over_tag()
+
+
+@pytest.mark.parametrize(
+    "how_over, who_is_winner",
+    [
+        (HowOver.WIN, Winner.WHITE),
+        (HowOver.WIN, Winner.BLACK),
+    ],
+)
+def test_test_method_for_wins(how_over, who_is_winner):
+    event = OverEvent(how_over=how_over, who_is_winner=who_is_winner)
+
+    event.test()
+
+
+def test_test_method_invalid_draw_configuration():
+    event = OverEvent(how_over=HowOver.DRAW, who_is_winner=Winner.NO_KNOWN_WINNER)
+
+    with pytest.raises(AssertionError):
+        event.test()
+
+
+def test_bool_raises():
+    event = OverEvent()
+
+    with pytest.raises(ValueError):
+        bool(event)

valanga-0.1.2/tests/test_representation_factory.py

@@ -0,0 +1,70 @@
+from collections import Counter
+
+from valanga.representation_factory import RepresentationFactory
+
+
+class DummyRepresentation:
+    pass
+
+
+def test_create_from_transition_root_uses_full_creator():
+    calls = Counter()
+
+    def create_from_state(state):
+        calls["create_from_state"] += 1
+        return ("state", state)
+
+    factory = RepresentationFactory(
+        create_from_state=create_from_state, create_from_state_and_modifications=None
+    )
+
+    result = factory.create_from_transition(
+        state="root", previous_state_representation=None, modifications=None
+    )
+
+    assert result == ("state", "root")
+    assert calls["create_from_state"] == 1
+
+
+def test_create_from_transition_no_modifications_falls_back_to_state():
+    calls = Counter()
+
+    def create_from_state(state):
+        calls["create_from_state"] += 1
+        return ("state", state)
+
+    factory = RepresentationFactory(
+        create_from_state=create_from_state, create_from_state_and_modifications=None
+    )
+
+    result = factory.create_from_transition(
+        state="child",
+        previous_state_representation=DummyRepresentation(),
+        modifications=None,
+    )
+
+    assert result == ("state", "child")
+    assert calls["create_from_state"] == 1
+
+
+def test_create_from_transition_with_modifications():
+    calls = Counter()
+
+    def create_from_state_and_modifications(
+        state, state_modifications, previous_state_representation
+    ):
+        calls["create_from_state_and_modifications"] += 1
+        return (state, state_modifications, previous_state_representation)
+
+    factory = RepresentationFactory(
+        create_from_state=lambda state: ("unused", state),
+        create_from_state_and_modifications=create_from_state_and_modifications,
+    )
+
+    previous = DummyRepresentation()
+    result = factory.create_from_transition(
+        state="child", previous_state_representation=previous, modifications="delta"
+    )
+
+    assert result == ("child", "delta", previous)
+    assert calls["create_from_state_and_modifications"] == 1

valanga-0.1.1/README.md

@@ -1,2 +0,0 @@
-# valanga
-Common objects for evaluations