sc2nachos 0.1.0__py3-none-any.whl

sc2nachos/__about__.py

@@ -0,0 +1,2 @@
+# Written by hatch-vcs from the git tag at build time; not tracked.
+__version__ = "0.1.0"

sc2nachos/__init__.py

@@ -0,0 +1,57 @@
+"""NachOS — an event-driven StarCraft II bot API for Python.
+
+A bot makes one `Api`, subscribes handlers to the events a game hands out with `Api.on`, and plays through a runner:
+`run_local` against the built-in computer, or `run_from_command_line` for the ladder and local games alike. Each turn
+it reads its units from `Api.units` and orders them through `Api.orders`.
+
+The [README](https://github.com/maxnus/NachOS#readme) says how to get started and lists the guides.
+"""
+
+from sc2nachos.__about__ import __version__
+from sc2nachos._shared.errors import NachOSError
+from sc2nachos.api import Api, FogOnError, NoEnemyError, NotPlayingError
+from sc2nachos.gamedata import Cost, Resources
+from sc2nachos.gamemap import Expansion, StartLocation
+from sc2nachos.gametime import GameTime
+from sc2nachos.geometry import Circle, Footprint, Point, Rectangle
+from sc2nachos.ids import AbilityId, BuffId, UnitTypeId, UpgradeId
+from sc2nachos.match import AIBuild, Computer, Difficulty, Race, Result
+from sc2nachos.run import run_from_command_line, run_ladder, run_local, run_recording, run_replay
+from sc2nachos.units import OwnUnit, Unit, UnitDict, Units, UnitType
+
+__all__ = [
+    "AIBuild",
+    "AbilityId",
+    "Api",
+    "BuffId",
+    "Circle",
+    "Computer",
+    "Cost",
+    "Difficulty",
+    "Expansion",
+    "FogOnError",
+    "Footprint",
+    "GameTime",
+    "NachOSError",
+    "NoEnemyError",
+    "NotPlayingError",
+    "OwnUnit",
+    "Point",
+    "Race",
+    "Rectangle",
+    "Resources",
+    "Result",
+    "StartLocation",
+    "Unit",
+    "UnitDict",
+    "UnitType",
+    "UnitTypeId",
+    "Units",
+    "UpgradeId",
+    "__version__",
+    "run_from_command_line",
+    "run_ladder",
+    "run_local",
+    "run_recording",
+    "run_replay",
+]

sc2nachos/_shared/__init__.py

@@ -0,0 +1,4 @@
+"""What NachOS's own modules share: the base of its errors, its enums' base, argument checks and rounding.
+
+It imports nothing else of NachOS, so that any module can import it.
+"""

sc2nachos/_shared/checks.py

@@ -0,0 +1,18 @@
+"""Checks that the arguments of several modules share."""
+
+from numbers import Integral
+from pathlib import Path
+
+
+def is_whole_number(value: object) -> bool:
+    """Whether `value` is a whole number, and not a `bool`."""
+    return isinstance(value, Integral) and not isinstance(value, bool)
+
+
+def check_file_to_write(path: Path, purpose: str) -> None:
+    """Raise `FileNotFoundError` if `path` is in no folder that exists, and `IsADirectoryError` if it is a folder. Each
+    message ends with `purpose`, what the file is for: "record into"."""
+    if not path.parent.is_dir():
+        raise FileNotFoundError(f"there is no folder {path.parent} to {purpose}")
+    if path.is_dir():
+        raise IsADirectoryError(f"{path} is a folder, not a file to {purpose}")

sc2nachos/_shared/errors.py

@@ -0,0 +1,10 @@
+"""The base of the exceptions the library raises for its own failures, and the errors more than one package raises."""
+
+
+class NachOSError(Exception):
+    """A failure of the library's own. Misuse, such as a bad argument, raises a built-in instead."""
+
+
+class NotReportedError(NachOSError, LookupError):
+    """The game has not reported what was asked: a field of a unit it has never shown visible, or which start location
+    the enemy took on a map with more than two."""

sc2nachos/_shared/readable_int_enum.py

@@ -0,0 +1,53 @@
+"""Base class for the package's enums."""
+
+from enum import IntEnum
+from typing import Self, cast
+
+from sc2nachos._shared.errors import NachOSError
+
+
+class UnknownValueError(NachOSError, ValueError):
+    """The game reported a value the enum has no member for."""
+
+    def __init__(self, enum: "type[ReadableIntEnum]", value: int) -> None:
+        super().__init__(f"{enum.__name__} has no member for {value}")
+        self.enum = enum
+        self.value = value
+
+
+class ReadableIntEnum(IntEnum):
+    """An `IntEnum` that prints as its name, not its value, and reads values the game reports.
+
+    An explicit format spec still formats the integer.
+    """
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__}.{self.name}"
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__}.{self.name}: {self.value}>"
+
+    def __format__(self, format_spec: str) -> str:
+        if format_spec:
+            return int.__format__(int(self), format_spec)
+        return str(self)
+
+    @classmethod
+    def read(cls, value: int) -> Self:
+        """The member for `value`. Raises `UnknownValueError` if the enum has none."""
+        # The enum's own value-to-member map: under half the time of calling the enum.
+        if (member := cls._value2member_map_.get(value)) is None:
+            raise cls._unknown(value)
+        return cast("Self", member)
+
+    @classmethod
+    def get(cls, value: int) -> Self | None:
+        """The member for `value`, or `None` if `value` is zero or the enum has no member for it."""
+        if not value:
+            return None
+        return cast("Self | None", cls._value2member_map_.get(value))
+
+    @classmethod
+    def _unknown(cls, value: int) -> UnknownValueError:
+        """The error `read` raises. An enum overrides it to say where the value should have come from."""
+        return UnknownValueError(cls, value)

sc2nachos/_shared/rounding.py

@@ -0,0 +1,11 @@
+"""Rounding that several modules share."""
+
+import math
+
+
+def rounded_half_up(value: float) -> int:
+    """`value` rounded to the nearest integer, a tie up, toward the larger one, where Python's `round` takes the even
+    one. Raises `OverflowError` for an infinity and `ValueError` for a NaN, as `math.floor` does."""
+    # Not `math.floor(value + 0.5)`: the addition itself rounds, taking 0.49999999999999994 to 1.0.
+    floored = math.floor(value)
+    return floored + (value - floored >= 0.5)

sc2nachos/api/__init__.py

@@ -0,0 +1,10 @@
+"""Everything a bot talks to."""
+
+from sc2nachos.api._api import Api, FogOnError, NoEnemyError, NotPlayingError
+
+__all__ = [
+    "Api",
+    "FogOnError",
+    "NoEnemyError",
+    "NotPlayingError",
+]