pyvgc 0.0.1__tar.gz

pyvgc-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2026 Voozde
+
+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.
+
+- This license is currently under review and is a basic template

pyvgc-0.0.1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: pyvgc
+Version: 0.0.1
+Summary: A Pokémon Champions data science package.
+Author: Voozde
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PYVGC
+
+PYVGC is a Python package for basic Pokémon Champions-based data science.
+It is currently meant for Python 3.9 and newer, without runtime dependencies.
+
+Regulations scope legal Pokémon, moves,items, and learnsets, while named `BattleLogic` instances preserve historical and future rule sets. 
+
+Both `Cartridge-Champions-Release-2026` and `Simulator-Champions-Release-2026` are available. Regulation snapshots default to Cartridge rules and can be loaded with `platform="Simulator"` for simulator rules.
+
+All current development is meant for early implementation. Until 0.1 this package is on alpha development.
+
+Version 0.0.1 provides:
+
+- Level-50 Pokémon loading from the bundled roster;
+- Stat training, natures, and stat stages;
+- Pokémon battle type and held-item accessors (no in-battle functionality);
+- normal and critical damage rolls;
+- move, learnset, and Pokémon-for-move lookups;
+- Bundled battle-item reference data with effect descriptions crawled from
+  [Serebii's ItemDex](https://www.serebii.net/itemdex/).
+
+Item effects and regulation item membership are descriptive data only; item
+mechanics are not implemented in damage calculations. Teams, weather, terrain,
+and KO-target searches are not part of this MVP. Regulation snapshots and the
+single-ability query are available as data utilities; they do not affect
+damage calculations.
+
+The package is maintained by Voozde.
+
+AI DISCLAIMER
+
+Current development is assisted by the VSCode Copilot Plugin, which settled on Gpt-5.6-Luna

pyvgc-0.0.1/README.md

@@ -0,0 +1,32 @@
+# PYVGC
+
+PYVGC is a Python package for basic Pokémon Champions-based data science.
+It is currently meant for Python 3.9 and newer, without runtime dependencies.
+
+Regulations scope legal Pokémon, moves,items, and learnsets, while named `BattleLogic` instances preserve historical and future rule sets. 
+
+Both `Cartridge-Champions-Release-2026` and `Simulator-Champions-Release-2026` are available. Regulation snapshots default to Cartridge rules and can be loaded with `platform="Simulator"` for simulator rules.
+
+All current development is meant for early implementation. Until 0.1 this package is on alpha development.
+
+Version 0.0.1 provides:
+
+- Level-50 Pokémon loading from the bundled roster;
+- Stat training, natures, and stat stages;
+- Pokémon battle type and held-item accessors (no in-battle functionality);
+- normal and critical damage rolls;
+- move, learnset, and Pokémon-for-move lookups;
+- Bundled battle-item reference data with effect descriptions crawled from
+  [Serebii's ItemDex](https://www.serebii.net/itemdex/).
+
+Item effects and regulation item membership are descriptive data only; item
+mechanics are not implemented in damage calculations. Teams, weather, terrain,
+and KO-target searches are not part of this MVP. Regulation snapshots and the
+single-ability query are available as data utilities; they do not affect
+damage calculations.
+
+The package is maintained by Voozde.
+
+AI DISCLAIMER
+
+Current development is assisted by the VSCode Copilot Plugin, which settled on Gpt-5.6-Luna

pyvgc-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyvgc"
+version = "0.0.1"
+description = "A Pokémon Champions data science package."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Voozde"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = []
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pyvgc = [
+    "data/*.csv",
+    "data/regulations/*/*.csv",
+]
+

pyvgc-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyvgc-0.0.1/src/pyvgc/__init__.py

@@ -0,0 +1,45 @@
+"""Public API for the pyvgc package."""
+
+from .battle_logic import (
+    BattleLogic,
+    CARTRIDGE_CHAMPIONS_RELEASE_2026,
+    SIMULATOR_CHAMPIONS_RELEASE_2026,
+    get_battle_logic,
+)
+from .damage import calculate_damage, damage_rolls
+from .items import Item, get_item
+from .moves import (
+    Move,
+    get_move,
+    moves_for_pokemon,
+    pokemon_for_move,
+)
+from .pokemon import Pokemon
+from .regulations import load_regulation
+from .utils import (
+    pokemon_with_ability,
+    pokemon_with_single_ability,
+    regulation_description,
+    signature_moves,
+)
+
+__all__ = [
+    "BattleLogic",
+    "CARTRIDGE_CHAMPIONS_RELEASE_2026",
+    "SIMULATOR_CHAMPIONS_RELEASE_2026",
+    "calculate_damage",
+    "damage_rolls",
+    "get_battle_logic",
+    "get_item",
+    "get_move",
+    "Item",
+    "Move",
+    "moves_for_pokemon",
+    "Pokemon",
+    "pokemon_with_ability",
+    "pokemon_with_single_ability",
+    "pokemon_for_move",
+    "regulation_description",
+    "load_regulation",
+    "signature_moves",
+]

pyvgc-0.0.1/src/pyvgc/battle_logic.py

@@ -0,0 +1,135 @@
+"""Named battle-rule configurations used by regulations."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass, field, replace
+from fractions import Fraction
+from importlib import resources
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Mapping, Optional
+
+from .constants import (
+    BASE_HP_INCREASE,
+    BASE_STAT_INCREASE,
+    CRITICAL_MULTIPLIER,
+    DAMAGE_DIVISOR,
+    DAMAGE_LEVEL_DIVISOR,
+    LEVEL_DOUBLES,
+    MAX_TOTAL_TRAINING,
+    MAX_TRAINING_PER_STAT,
+    MAX_STAT_STAGE,
+    MIN_STAT_STAGE,
+    RANDOM_PERCENTAGES,
+    STAB_MULTIPLIER,
+    STAT_STAGE_MULTIPLIERS,
+    TYPES,
+)
+
+if TYPE_CHECKING:
+    from .damage import DamageRolls
+    from .pokemon import Pokemon
+
+
+@dataclass(frozen=True)
+class BattleLogic:
+    """Immutable rules and constants for one game-logic version."""
+
+    name: str
+    level: int = LEVEL_DOUBLES
+    base_hp_increase: int = BASE_HP_INCREASE
+    base_stat_increase: int = BASE_STAT_INCREASE
+    max_training_per_stat: int = MAX_TRAINING_PER_STAT
+    max_total_training: int = MAX_TOTAL_TRAINING
+    min_stat_stage: int = MIN_STAT_STAGE
+    max_stat_stage: int = MAX_STAT_STAGE
+    stat_stage_multipliers: Mapping[int, tuple[int, int]] = field(
+        default_factory=lambda: MappingProxyType(dict(STAT_STAGE_MULTIPLIERS))
+    )
+    damage_level_divisor: int = DAMAGE_LEVEL_DIVISOR
+    damage_divisor: int = DAMAGE_DIVISOR
+    random_percentages: range = RANDOM_PERCENTAGES
+    stab_multiplier: Fraction = STAB_MULTIPLIER
+    critical_multiplier: Fraction = CRITICAL_MULTIPLIER
+    type_chart: Optional[Mapping[str, Mapping[str, Fraction]]] = None
+
+    def with_type_chart(
+        self, type_chart: Mapping[str, Mapping[str, Fraction]]
+    ) -> "BattleLogic":
+        """Return this logic with an immutable type chart."""
+        immutable_chart = MappingProxyType({
+            attack: MappingProxyType(dict(defending))
+            for attack, defending in type_chart.items()
+        })
+        return replace(self, type_chart=immutable_chart)
+
+    def calculate_damage(
+        self,
+        attacker: "Pokemon",
+        defender: "Pokemon",
+        power: int,
+        move_type: str,
+        *,
+        special: bool = False,
+        percentage: bool = True,
+    ) -> "DamageRolls":
+        """Calculate damage using this battle logic and two Pokémon.
+
+        Both Pokémon must use this exact logic instance. This makes the
+        selected rule set explicit at the calculation call site.
+        """
+        from .damage import calculate_damage
+
+        if attacker.battle_logic is not self or defender.battle_logic is not self:
+            raise ValueError(
+                "attacker and defender must use this battle logic"
+            )
+        return calculate_damage(
+            attacker,
+            defender,
+            power,
+            move_type,
+            special=special,
+            percentage=percentage,
+        )
+
+
+def _load_type_chart() -> Mapping[str, Mapping[str, Fraction]]:
+    """Load the initial packaged type chart used by current battle logic."""
+    path = resources.files("pyvgc.data").joinpath("initial_type_chart.csv")
+    with path.open(newline="", encoding="utf-8") as file:
+        return MappingProxyType({
+            row["AttackingType"]: MappingProxyType({
+                defending: Fraction(row[defending]) for defending in TYPES
+            })
+            for row in csv.DictReader(file)
+        })
+
+
+CARTRIDGE_CHAMPIONS_RELEASE_2026 = BattleLogic(
+    name="Cartridge-Champions-Release-2026",
+    type_chart=_load_type_chart(),
+)
+
+SIMULATOR_CHAMPIONS_RELEASE_2026 = replace(
+    CARTRIDGE_CHAMPIONS_RELEASE_2026,
+    name="Simulator-Champions-Release-2026",
+)
+
+BATTLE_LOGICS = MappingProxyType(
+    {
+        "Cartridge-Champions-Release-2026": CARTRIDGE_CHAMPIONS_RELEASE_2026,
+        "Simulator-Champions-Release-2026": SIMULATOR_CHAMPIONS_RELEASE_2026,
+    }
+)
+
+
+def get_battle_logic(name: str) -> BattleLogic:
+    """Return a registered battle logic by case-insensitive name."""
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("battle logic name must be a non-empty string")
+    key = name.strip().casefold()
+    for logic_name, logic in BATTLE_LOGICS.items():
+        if logic_name.casefold() == key:
+            return logic
+    raise KeyError(f"Unknown battle logic: {name!r}")

pyvgc-0.0.1/src/pyvgc/constants.py

@@ -0,0 +1,53 @@
+"""Shared constants and packaged data paths for pyvgc."""
+
+from fractions import Fraction
+
+LEVEL_DOUBLES = 50
+
+BASE_HP_INCREASE = 75
+BASE_STAT_INCREASE = 20
+
+MAX_TRAINING_PER_STAT = 32
+MAX_TOTAL_TRAINING = 66
+MIN_STAT_STAGE = -6
+MAX_STAT_STAGE = 6
+
+STAT_STAGE_MULTIPLIERS = {
+    stage: (2 + stage, 2) if stage >= 0 else (2, 2 - stage)
+    for stage in range(MIN_STAT_STAGE, MAX_STAT_STAGE + 1)
+}
+DAMAGE_LEVEL_DIVISOR = 5
+DAMAGE_DIVISOR = 50
+
+RANDOM_PERCENTAGES = range(85, 101)
+STAB_MULTIPLIER = Fraction(3, 2)
+CRITICAL_MULTIPLIER = Fraction(3, 2)
+STAT_NAMES = (
+    "hp", "attack", "defense", "special_attack", "special_defense", "speed"
+)
+TYPES = frozenset((
+    "Normal", "Fire", "Water", "Electric", "Grass", "Ice", "Fighting",
+    "Poison", "Ground", "Flying", "Psychic", "Bug", "Rock", "Ghost",
+    "Dragon", "Dark", "Steel", "Fairy",
+))
+
+ALWAYS_HIT_VALUE = "always-hit"
+
+NATURES = {
+    "Hardy": ("attack", "attack"), "Lonely": ("attack", "defense"),
+    "Brave": ("attack", "speed"), "Adamant": ("attack", "special_attack"),
+    "Naughty": ("attack", "special_defense"),
+    "Bold": ("defense", "attack"), "Docile": ("defense", "defense"),
+    "Impish": ("defense", "special_attack"), "Lax": ("defense", "special_defense"),
+    "Relaxed": ("defense", "speed"),
+    "Modest": ("special_attack", "attack"), "Mild": ("special_attack", "defense"),
+    "Bashful": ("special_attack", "special_attack"),
+    "Rash": ("special_attack", "special_defense"), "Quiet": ("special_attack", "speed"),
+    "Calm": ("special_defense", "attack"), "Gentle": ("special_defense", "defense"),
+    "Careful": ("special_defense", "special_attack"),
+    "Quirky": ("special_defense", "special_defense"),
+    "Sassy": ("special_defense", "speed"),
+    "Timid": ("speed", "attack"), "Hasty": ("speed", "defense"),
+    "Jolly": ("speed", "special_attack"), "Naive": ("speed", "special_defense"),
+    "Serious": ("speed", "speed"),
+}

pyvgc-0.0.1/src/pyvgc/damage.py

@@ -0,0 +1,183 @@
+"""Pokémon Champions damage calculation for level-50 Pokémon."""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from typing import TYPE_CHECKING, Iterable, TypedDict
+
+from .battle_logic import BattleLogic, CARTRIDGE_CHAMPIONS_RELEASE_2026
+from .constants import TYPES
+
+if TYPE_CHECKING:
+    from .pokemon import Pokemon
+
+
+class DamageRolls(TypedDict, total=False):
+    """Mapping returned by damage calculations."""
+
+    normal: list[int]
+    critical: list[int]
+    normal_percentage: list[float]
+    critical_percentage: list[float]
+
+
+def _normalize_type(type_name: str) -> str:
+    """Validate and canonicalize one Pokémon type name."""
+    if not isinstance(type_name, str):
+        raise ValueError(f"type names must be strings, got {type(type_name).__name__}")
+    normalized = type_name.strip().title()
+    if normalized not in TYPES:
+        raise ValueError(f"unknown Pokémon type: {type_name!r}")
+    return normalized
+
+
+def _type_multiplier_for_types(
+    move_type: str, defender_types: tuple[str, ...], logic: BattleLogic
+) -> Fraction:
+    """Return effectiveness for already-normalized defender types."""
+    if logic.type_chart is None:
+        raise ValueError(f"battle logic {logic.name!r} has no type chart")
+    multiplier = Fraction(1)
+    for defender_type in defender_types:
+        multiplier *= logic.type_chart[move_type][defender_type]
+    return multiplier
+
+
+def _type_multiplier(
+    move_type: str, defender_types: Iterable[str], logic: BattleLogic
+) -> Fraction:
+    """Normalize types and return their combined effectiveness multiplier."""
+    normalized_move = _normalize_type(move_type)
+    normalized_defenders = tuple(
+        _normalize_type(defender_type) for defender_type in defender_types
+    )
+    return _type_multiplier_for_types(
+        normalized_move, normalized_defenders, logic
+    )
+
+
+def damage_rolls(
+    power: int,
+    attack: int,
+    defense: int,
+    move_type: str,
+    attacker_types: Iterable[str],
+    defender_types: Iterable[str],
+    *,
+    logic: BattleLogic = CARTRIDGE_CHAMPIONS_RELEASE_2026,
+) -> DamageRolls:
+    """Return all 16 normal and 16 critical damage rolls.
+
+    ``attack`` and ``defense`` are the already-calculated battle stats.
+    Damage is floored at every formula step, as in the games. Critical hits
+    use the selected logic's critical multiplier and ignore the relevant stat
+    stages.
+    """
+    if not all(
+        type(value) is int and value > 0
+        for value in (power, attack, defense)
+    ):
+        raise ValueError("power, attack, and defense must be positive integers")
+    move_type = _normalize_type(move_type)
+    attacker_types = tuple(
+        _normalize_type(type_name) for type_name in attacker_types
+    )
+    defender_types = tuple(
+        _normalize_type(type_name) for type_name in defender_types
+    )
+    if not attacker_types or not defender_types:
+        raise ValueError("attacker_types and defender_types must not be empty")
+    if len(attacker_types) > 2 or len(defender_types) > 2:
+        raise ValueError("a Pokémon can have at most two types")
+    stab = logic.stab_multiplier if move_type in attacker_types else Fraction(1)
+    effectiveness = _type_multiplier(move_type, defender_types, logic)
+
+    # (((((2L/5)+2) * Power * A / D) / 50) + 2), with integer floors.
+    base = (
+        (
+            (2 * logic.level // logic.damage_level_divisor + 2)
+            * power
+            * attack
+            // defense
+        )
+        // logic.damage_divisor
+    ) + 2
+
+    def rolls(critical: bool) -> list[int]:
+        """Calculate all 16 random outcomes for one hit category."""
+        result: list[int] = []
+        critical_damage = int(base * logic.critical_multiplier) if critical else base
+        for random_percent in logic.random_percentages:
+            fixed = critical_damage * random_percent // 100
+            fixed = int(fixed * stab)
+            fixed = int(fixed * effectiveness)
+            result.append(fixed)
+        return result
+
+    return {"normal": rolls(False), "critical": rolls(True)}
+
+
+def calculate_damage(
+    attacker: "Pokemon",
+    defender: "Pokemon",
+    power: int,
+    move_type: str,
+    *,
+    special: bool = False,
+    percentage: bool = True,
+) -> DamageRolls:
+    """Calculate damage rolls using two Pokémon and their current battle state.
+
+    The Pokémon models provide state only. This function owns the damage
+    calculation, including critical-hit stat-stage handling and percentages.
+    """
+    from .pokemon import Pokemon
+
+    if not isinstance(attacker, Pokemon) or not isinstance(defender, Pokemon):
+        raise TypeError("attacker and defender must be Pokemon instances")
+    if attacker.battle_logic != defender.battle_logic:
+        raise ValueError("attacker and defender must use the same battle logic")
+
+    attack_stat = "special_attack" if special else "attack"
+    defense_stat = "special_defense" if special else "defense"
+    attack = getattr(attacker, attack_stat)
+    defense = getattr(defender, defense_stat)
+    rolls = damage_rolls(
+        power,
+        attack,
+        defense,
+        move_type,
+        attacker.types,
+        defender.types,
+        logic=attacker.battle_logic,
+    )
+    critical_attack = (
+        attacker._pre_stage_stats[attack_stat]
+        if attacker._stat_stages.get(attack_stat, 0) < 0
+        else attack
+    )
+    critical_defense = (
+        defender._pre_stage_stats[defense_stat]
+        if defender._stat_stages.get(defense_stat, 0) > 0
+        else defense
+    )
+    if critical_attack != attack or critical_defense != defense:
+        rolls["critical"] = damage_rolls(
+            power,
+            critical_attack,
+            critical_defense,
+            move_type,
+            attacker.types,
+            defender.types,
+            logic=attacker.battle_logic,
+        )["critical"]
+    if percentage:
+        rolls["normal_percentage"] = [
+            round(damage / defender.hp * 100, 2)
+            for damage in rolls["normal"]
+        ]
+        rolls["critical_percentage"] = [
+            round(damage / defender.hp * 100, 2)
+            for damage in rolls["critical"]
+        ]
+    return rolls

pyvgc-0.0.1/src/pyvgc/data/__init__.py

@@ -0,0 +1 @@
+"""Bundled data files for pyvgc."""