phase-python 0.77.0__cp314-cp314-macosx_11_0_arm64.whl

phase/__init__.py

@@ -0,0 +1,19 @@
+"""Python bindings for the phase.rs Magic: The Gathering rules engine."""
+
+from phase._phase import (
+    ActionResult,
+    Engine,
+    Game,
+    GameAction,
+    build_oracle_face,
+    build_oracle_face_multi,
+)
+
+__all__ = [
+    "ActionResult",
+    "Engine",
+    "Game",
+    "GameAction",
+    "build_oracle_face",
+    "build_oracle_face_multi",
+]

phase/_phase.pyi

@@ -0,0 +1,207 @@
+"""
+Python bindings for the phase.rs Magic: The Gathering rules engine.
+"""
+
+from collections.abc import Sequence
+from os import PathLike
+from typing import Any, final
+
+@final
+class ActionResult:
+    """
+    Native result of applying one or more actions.
+    
+    Event and prompt values are converted only when their getters are read.
+    """
+    def __repr__(self, /) -> str: ...
+    @property
+    def events(self, /) -> Any:
+        """
+        Events emitted by the requested action and any fast-forwarded passes.
+        """
+    @property
+    def fast_forwarded(self, /) -> int:
+        """
+        Number of automatic `PassPriority` actions applied after the requested action.
+        """
+    @property
+    def log_entries(self, /) -> Any:
+        """
+        Game log entries emitted by the represented actions.
+        """
+    def to_dict(self, /) -> Any:
+        """
+        Convert to the engine's JSON-compatible result shape.
+        """
+    @property
+    def waiting_for(self, /) -> Any:
+        """
+        Prompt active after all actions represented by this result.
+        """
+
+@final
+class Engine:
+    """
+    Loaded card database used to create games.
+    """
+    def card_count(self, /) -> int:
+        """
+        Number of card faces in the loaded database.
+        """
+    @staticmethod
+    def from_json(json: str) -> Engine:
+        """
+        Load a `card-data.json` export from a JSON string.
+        """
+    @staticmethod
+    def from_path(path: str |PathLike[str]) -> Engine:
+        """
+        Load a `card-data.json` export from disk.
+        """
+    def load_game(self, /, state: Any) -> Game:
+        """
+        Resume a game from a previously exported state.
+        
+        `state` may be the dict returned by [`Game::state`], a JSON string of
+        that dict, or a WASM `TrustedGameStateEnvelope` (`{"state": ...}`).
+        """
+    def new_game(self, /, player: Any, opponent: Any, *, extra_players: Sequence[Any] |None = None, seed: int = 42, format: str = "Standard", format_config: Any |None = None, match_config: Any |None = None, first_player: int |None = None) -> Game:
+        """
+        Start a match and return a live [`Game`].
+        
+        `player` / `opponent` / `extra_players` may be a list of card names
+        (treated as the main deck) or a dict matching the engine `PlayerDeckList`
+        (`main_deck`, `sideboard`, `commander`, ...).
+        """
+
+@final
+class Game:
+    """
+    A started game: inspect legal actions, apply one, and read state.
+    """
+    def __repr__(self, /) -> str: ...
+    def actions(self, /) -> list[GameAction]:
+        """
+        Legal actions for the player currently expected to act.
+        
+        Returns [`GameAction`] objects. Pass one back to [`Game::apply`] with no
+        JSON conversion. Dicts in the tagged engine shape are still accepted.
+        """
+    def apply(self, /, actor: int, action: Any, *, fast_forward: bool = False) -> ActionResult:
+        """
+        Apply `action` as `actor` (seat index) and return the `ActionResult`.
+        
+        `action` should be a [`GameAction`] from [`Game::actions`]. A tagged
+        JSON dict is still accepted.
+        """
+    def battlefield(self, /) -> Any:
+        """
+        Objects currently on the battlefield.
+        """
+    def exile(self, /) -> Any:
+        """
+        Objects in exile.
+        """
+    def graveyard(self, /, seat: int) -> Any:
+        """
+        Objects in `seat`'s graveyard.
+        """
+    def hand(self, /, seat: int) -> Any:
+        """
+        Objects in `seat`'s hand.
+        """
+    def object(self, /, object_id: int) -> Any:
+        """
+        Look up one game object by its numeric object ID.
+        """
+    @property
+    def phase(self, /) -> str:
+        """
+        Current phase name.
+        """
+    def player(self, /, seat: int) -> Any:
+        """
+        Public player state for `seat`.
+        """
+    def priority_player(self, /) -> int:
+        """
+        Seat that currently holds priority, if any.
+        """
+    def stack(self, /) -> Any:
+        """
+        Current stack entries.
+        """
+    def state(self, /) -> Any:
+        """
+        Full persisted `GameState` as a Python dict (same serde shape as WASM export).
+        
+        Pass the result to [`Engine::load_game`] to resume from this snapshot.
+        """
+    @property
+    def turn(self, /) -> int:
+        """
+        Current turn number.
+        """
+    def waiting_for(self, /) -> Any:
+        """
+        Current `waiting_for` prompt.
+        """
+
+@final
+class GameAction:
+    """
+    An engine `GameAction`. Returned by [`Game::actions`] and accepted by [`Game::apply`].
+    
+    The Rust value is held natively — listing and applying actions does not
+    serialize through JSON. Use [`GameAction::to_dict`] only when you need the
+    tagged JSON shape.
+    """
+    @property
+    def __dict__(self, /) -> dict:
+        """
+        Flattened view of `kind` plus payload fields. Debuggers that inspect
+        `__dict__` use this instead of the native `EngineAction` layout.
+        """
+    def __dir__(self, /) -> list[str]: ...
+    def __eq__(self, other: object, /) -> bool: ...
+    def __getattr__(self, name: str, /) -> Any: ...
+    def __repr__(self, /) -> str: ...
+    @property
+    def data(self, /) -> Any:
+        """
+        Variant payload as a dict (or `None` for unit variants).
+        
+        Field names match the engine `GameAction` serde shape, so a `PlayLand`
+        action exposes `{"object_id": ..., "card_id": ...}`. The same keys are
+        also available as attributes (`action.object_id`) for debugger inspection.
+        """
+    @staticmethod
+    def from_dict(value: Any) -> GameAction:
+        """
+        Build from the tagged JSON dict (`{"type": "...", "data": ...}`).
+        """
+    @property
+    def kind(self, /) -> str:
+        """
+        Variant name, e.g. `"MulliganDecision"` or `"PassPriority"`.
+        """
+    def to_dict(self, /) -> Any:
+        """
+        Tagged JSON dict. Prefer passing this object to [`Game::apply`] instead.
+        """
+
+def build_oracle_face(mtgjson: Any, oracle_id: str |None) -> Any:
+    """
+    Build a `CardFace` from MTGJSON atomic card data.
+    
+    `mtgjson` should be a dict matching the engine `AtomicCard` shape
+    (`name`, `mana_cost`, `types`, `text`, `layout`, etc.).
+    `oracle_id` is an optional Scryfall oracle ID.
+    """
+
+def build_oracle_face_multi(mtgjson: Any, oracle_id: str |None) -> Any:
+    """
+    Build a `CardFace` for a multi-face card, skipping MTGJSON keywords.
+    
+    See [`build_oracle_face`] for parameter details.
+    """

phase/gen.py

@@ -0,0 +1,210 @@
+# simplified version of crates/engine/src/bin/oracle_gen.rs
+import argparse
+import gzip
+import json
+import os
+import urllib.request
+from collections import defaultdict
+
+from phase import build_oracle_face, build_oracle_face_multi
+
+INPUT_PATH = "AtomicCards.json.gz"
+OUTPUT_PATH = "card-data.json"
+SOURCE_URL = "https://mtgjson.com/api/v5/AtomicCards.json.gz"
+SET_SOURCE_URL = "https://mtgjson.com/api/v5/{set_name}.json.gz"
+
+MULTI_LAYOUTS = {
+    "split",
+    "flip",
+    "transform",
+    "meld",
+    "adventure",
+    "modal_dfc",
+    "prepare",
+    "aftermath",
+}
+
+
+def legality_score(card: dict) -> int:
+    return sum(1 for status in (card.get("legalities") or {}).values() if status.lower() == "legal")
+
+
+def make_entry(face: dict, layout=None, face_index=None) -> dict:
+    entry = dict(face)
+    if layout:
+        entry["layout"] = layout
+    if face_index is not None:
+        entry["face_index"] = face_index
+    return entry
+
+
+def insert_face(result: dict, entry: dict) -> None:
+    key = entry['name'].lower()
+    existing = result.get(key)
+    if existing is None:
+        result[key] = entry
+        return
+    # Standalone paper cards win over a multi-face back face of the same name.
+    if existing.get("layout") and not entry.get("layout"):
+        result[key] = entry
+
+
+def oracle_id(card: dict) -> str | None:
+    return (card.get("identifiers") or {}).get("scryfallOracleId")
+
+
+def load_json(path: str):
+    if path.endswith(".gz"):
+        with gzip.open(path, "rt", encoding="utf-8") as f:
+            return json.load(f)
+    with open(path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def dedupe_set_faces(cards: list) -> list:
+    unique = []
+    seen = set()
+    for card in cards:
+        key = (card.get("faceName") or card.get("name"), card.get("side"), oracle_id(card))
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(card)
+    unique.sort(key=lambda c: c.get("side") or "a")
+    return unique
+
+
+def groups_from_set_cards(cards: list):
+    by_name = defaultdict(list)
+    for card in cards:
+        if isinstance(card, dict) and card.get("name"):
+            by_name[card["name"]].append(card)
+    for name, group in by_name.items():
+        yield name, dedupe_set_faces(group)
+
+
+def load_card_groups(file_path: str):
+    root = load_json(file_path)
+    data = root.get("data", {})
+    if "cards" in data:
+        yield from groups_from_set_cards(data["cards"])
+    else:
+        for name, cards in data.items():
+            if isinstance(cards, list):
+                yield name, cards
+
+
+def process_group(cards: list, result: dict) -> None:
+    faces = [c for c in cards if isinstance(c, dict) and not c.get("isFunny")]
+    if not faces or len(faces) > 2:
+        return
+
+    if len(faces) == 1:
+        source = faces[0]
+        face = build_oracle_face(source, oracle_id(source))
+        insert_face(result, face)
+        return
+
+    if len(faces) == 2 and faces[1]['subtypes'] == ['Omen']:
+        # fix Omen -> adventure layout. in mtgjson data they have layout 'reversible_card'
+        layouts = {'adventure', }
+    else:
+        layouts = {f.get("layout", "normal") for f in faces}
+    if layouts <= MULTI_LAYOUTS:
+        oid = oracle_id(faces[0])
+        layout_str = 'adventure' if layouts == {'adventure', } else faces[0].get("layout")
+        face_a = build_oracle_face_multi(faces[0], oid)
+        face_b = build_oracle_face_multi(faces[1], oid)
+
+        for idx, face in enumerate([face_a, face_b]):
+            insert_face(
+                result,
+                make_entry(
+                    face,
+                    layout=layout_str,
+                    face_index=idx,
+                ),
+            )
+        return
+
+    if all(f.get("layout", "normal") not in MULTI_LAYOUTS for f in faces):
+        # name collisions
+        source = max(faces, key=legality_score)
+        face = build_oracle_face(source, oracle_id(source))
+        insert_face(result, face)
+
+
+def resolve_set_input(set_name: str) -> str:
+    for candidate in (f"{set_name}.json.gz", f"{set_name}.json"):
+        if os.path.exists(candidate):
+            return candidate
+    return f"{set_name}.json.gz"
+
+
+def ensure_source(file_path: str, source_url: str) -> None:
+    if os.path.exists(file_path):
+        return
+    print(f"Downloading {source_url} -> {file_path}")
+    tmp_path = file_path + ".tmp"
+    try:
+        urllib.request.urlretrieve(source_url, tmp_path)
+        os.replace(tmp_path, file_path)
+    except Exception:
+        if os.path.exists(tmp_path):
+            os.remove(tmp_path)
+        raise
+
+
+def process_cards(file_path: str, output_path: str) -> None:
+    print(f"Processing cards from: {file_path}")
+    result = {}
+    for name, cards in load_card_groups(file_path):
+        try:
+            process_group(cards, result)
+        except Exception as exc:
+            print(f"Skipping {name}: {exc}")
+            return
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(result, f, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+    print(f"Wrote {len(result)} faces to {output_path}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="phase-gen",
+        description="Generate card-data.json from MTGJSON AtomicCards or a single set.",
+    )
+    parser.add_argument(
+        "-i",
+        "--input",
+        default=None,
+        help="Path to AtomicCards.json.gz or a set JSON (downloaded from MTGJSON if missing)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default=OUTPUT_PATH,
+        help="Path to write card-data.json",
+    )
+    parser.add_argument(
+        "--set",
+        dest="set_name",
+        help="MTGJSON set code (e.g. HOB). Downloads https://mtgjson.com/api/v5/{SET}.json.gz "
+        "and reads cards from data.cards",
+    )
+    args = parser.parse_args(argv)
+    if args.set_name:
+        set_name = args.set_name.upper()
+        source_url = SET_SOURCE_URL.format(set_name=set_name)
+        input_path = args.input if args.input is not None else resolve_set_input(set_name)
+    else:
+        source_url = SOURCE_URL
+        input_path = args.input if args.input is not None else INPUT_PATH
+
+    ensure_source(input_path, source_url)
+    process_cards(input_path, args.output)
+
+
+if __name__ == "__main__":
+    main()

phase_python-0.77.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: phase-python
+Version: 0.77.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Games/Entertainment
+License-File: LICENSE
+Summary: Python bindings for the phase.rs Magic: The Gathering rules engine
+Keywords: mtg,magic-the-gathering,rules-engine
+Author-email: Boris Klyus <klyusba@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/klyusba/phase-python
+Project-URL: Repository, https://github.com/klyusba/phase-python
+
+# phase-rs
+
+Unofficial Python bindings for the [phase.rs](https://github.com/phase-rs/phase) Magic: The Gathering rules engine.
+
+```python
+from phase import Engine, Game, GameAction
+```
+
+Install from PyPI (prebuilt wheels; no Rust toolchain required):
+
+```bash
+pip install phase-python
+```
+
+The import name is `phase`. The distribution is `phase-rs` because `phase` is already taken on PyPI.
+
+## Card data
+
+The engine needs a `card-data.json` oracle export. After installing the package, generate one with:
+
+```bash
+phase-gen -o card-data.json
+```
+
+Or generate `card-data.json` for one set only:
+```bash
+phase-gen --set SET -o card-data.json
+```
+
+If `AtomicCards.json.gz` is missing, `phase-gen` downloads it from [MTGJSON](https://mtgjson.com). You can also pass an existing dump:
+
+```bash
+phase-gen -i AtomicCards.json.gz -o card-data.json
+```
+
+You can generate a `card-data.json` for single set with
+
+```bash
+phase-gen -i HOB.json -o card-data.json
+```
+
+A hosted snapshot is available at https://data.phase-rs.dev/card-data.json.
+
+## Quick start
+
+```python
+from phase import Engine
+
+engine = Engine.from_path("card-data.json")
+game = engine.new_game(
+    player=["Forest"] * 60,
+    opponent=["Forest"] * 60,
+    seed=42,
+    first_player=0,
+)
+
+actions = game.actions()
+result = game.apply(0, actions[0])
+```
+
+See [API.md](API.md) for the full Python API.
+
+## Develop from source
+
+Requires Rust (see `rust-toolchain.toml`) and Python 3.10+.
+
+```bash
+uv venv && source .venv/bin/activate
+uv pip install maturin
+maturin develop --generate-stubs
+```
+
+## License
+
+MIT
+

phase_python-0.77.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+phase/__init__.py,sha256=_Aur4XAH3a6L_RbTuKtkcX44P1t9msdeA1RtOVUEkMQ,347
+phase/_phase.cpython-314-darwin.so,sha256=YHDuAbEE-vOylLAseU6GK0BaqTFoqicM63M9lfYbLV8,62184064
+phase/_phase.pyi,sha256=tISdGY1kHfMJMFn5-c1qTseqS69Jhiy9VXm1xWyUcbE,6627
+phase/gen.py,sha256=EsBsge7WpVw96dI9Ax3Tvz2SOG8ZfD5uCuPPuK65hqk,6357
+phase/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+phase_python-0.77.0.dist-info/METADATA,sha256=RMacQU3JwVgLmbeBmRPxaQES-wojb-PbixwkFBymYwQ,2617
+phase_python-0.77.0.dist-info/WHEEL,sha256=wCw_9gE4rxFYW3BEzeT3cTNR34OBbxo66jwr_m338Mg,105
+phase_python-0.77.0.dist-info/entry_points.txt,sha256=cGDxKEmcSjzKFUeQBBgH2ZHsX1qvtZOYUfunWpOORdQ,43
+phase_python-0.77.0.dist-info/licenses/LICENSE,sha256=2AfuGGvse92w30YagK582bRaR63VGWsvqEJEgjZIM2U,1083
+phase_python-0.77.0.dist-info/sboms/phase.cyclonedx.json,sha256=8kGtcsPRguwEkTV4x35C2OXF4APTOxgmZIYAIEv_-YE,76367
+phase_python-0.77.0.dist-info/RECORD,,

phase_python-0.77.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp314-cp314-macosx_11_0_arm64

phase_python-0.77.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+phase-gen=phase.gen:main

phase_python-0.77.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 phase.rs contributors
+
+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.