pyDeciders 0.1.0__py3-none-any.whl

pyDeciders/__init__.py

@@ -0,0 +1,7 @@
+from pyDeciders.coin import flip_coin
+from pyDeciders.dice import roll_dice
+from pyDeciders.eight_ball import magic_8_ball
+from pyDeciders.pick import pick_one
+from pyDeciders.wheel import spin_wheel
+
+__all__ = ["flip_coin", "magic_8_ball", "pick_one", "roll_dice", "spin_wheel"]

pyDeciders/animation.py

@@ -0,0 +1,95 @@
+"""Small terminal animations for the decisions command.
+
+Only the command line tool uses this module. The library functions never
+print or animate, so they stay safe to call from other programs.
+
+The result is always decided before the animation starts. The animation only
+shows random "in progress" frames, so it never changes the answer, and the
+same --seed gives the same answer with or without it.
+"""
+
+import random
+import time
+
+from rich.console import Console
+from rich.live import Live
+from rich.text import Text
+
+FRAME_COUNT = 12
+
+FIRST_DELAY = 0.04
+DELAY_STEP = 0.012
+
+COIN_SPIN = ("( H )", "( | )", "( T )", "( | )")
+BALL_SHAKE = ("shaking the ball", "shaking the ball.", "shaking the ball..", "shaking the ball...")
+
+
+def should_animate(no_animation, stream):
+    """Decide whether to animate.
+
+    Animations are off when the user passed --no-animation, or when the output
+    is not a terminal (for example when it is piped into a file or another
+    program), so scripts only ever see the final answer.
+    """
+    if no_animation:
+        return False
+    isatty = getattr(stream, "isatty", None)
+    if isatty is None:
+        return False
+    return bool(isatty())
+
+
+def build_frames(command, args, rng=None, count=FRAME_COUNT):
+    """Return the list of in-progress frames to show for a command.
+
+    The frames are just for show. They come from their own random generator,
+    so they never use up the numbers that decide the real result.
+    """
+    if rng is None:
+        rng = random.Random()
+
+    if command == "dice":
+        return [
+            " ".join(f"[{rng.randint(1, args.sides)}]" for _ in range(args.n))
+            for _ in range(count)
+        ]
+    if command == "coin":
+        # each coin starts at a different point in the spin
+        starts = [rng.randrange(len(COIN_SPIN)) for _ in range(args.times)]
+        return [
+            " ".join(COIN_SPIN[(start + i) % len(COIN_SPIN)] for start in starts)
+            for i in range(count)
+        ]
+    if command in ("wheel", "pick"):
+        # move through the options in order, like a pointer going round
+        start = rng.randrange(len(args.options))
+        return [
+            f"> {args.options[(start + i) % len(args.options)]} <"
+            for i in range(count)
+        ]
+    if command == "8ball":
+        return [BALL_SHAKE[i % len(BALL_SHAKE)] for i in range(count)]
+    raise ValueError(f"no animation for command {command!r}")
+
+
+def frame_delays(count=FRAME_COUNT):
+    """How long to show each frame, in seconds, getting slower towards the end."""
+    return [FIRST_DELAY + DELAY_STEP * i for i in range(count)]
+
+
+def animate(command, args, console=None, sleep=time.sleep):
+    """Play the animation for a command, then clear it from the screen.
+
+    The caller prints the final answer afterwards. console and sleep can be
+    replaced in tests so nothing is drawn and nothing waits.
+    """
+    if console is None:
+        console = Console()
+    frames = build_frames(command, args)
+    delays = frame_delays(len(frames))
+
+    # transient=True removes the animation once it ends, leaving only the answer
+    with Live(console=console, transient=True, auto_refresh=False) as live:
+        for frame, delay in zip(frames, delays):
+            live.update(Text(frame, style="bold cyan"), refresh=True)
+            sleep(delay)

pyDeciders/cli.py

@@ -0,0 +1,72 @@
+import argparse
+import sys
+
+from pyDeciders import flip_coin, magic_8_ball, pick_one, roll_dice, spin_wheel
+from pyDeciders.animation import animate, should_animate
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="decisions",
+        description="Roll dice, flip coins, and spin a wheel.",
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--seed", type=int, default=None)
+    common.add_argument(
+        "--no-animation",
+        action="store_true",
+        help="print the answer straight away, without the animation",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    dice = commands.add_parser("dice", parents=[common], help="roll dice")
+    dice.add_argument("-n", type=int, default=1)
+    dice.add_argument("--sides", type=int, default=6)
+    dice.set_defaults(run=lambda a: roll_dice(a.n, a.sides, a.seed))
+
+    coin = commands.add_parser("coin", parents=[common], help="flip a coin")
+    coin.add_argument("--times", type=int, default=1)
+    coin.add_argument("--bias", type=float, default=0.5)
+    coin.set_defaults(run=lambda a: flip_coin(a.times, a.bias, a.seed))
+
+    wheel = commands.add_parser("wheel", parents=[common], help="spin a wheel")
+    wheel.add_argument("options", nargs="+")
+    wheel.add_argument("--weights", type=float, nargs="+", default=None)
+    wheel.set_defaults(run=lambda a: spin_wheel(a.options, a.weights, a.seed))
+
+    pick = commands.add_parser("pick", parents=[common], help="pick one option")
+    pick.add_argument("options", nargs="+")
+    pick.set_defaults(run=lambda a: pick_one(a.options, a.seed))
+
+    ball = commands.add_parser("8ball", parents=[common], help="ask the magic 8 ball")
+    ball.add_argument("question")
+    ball.set_defaults(run=lambda a: magic_8_ball(a.question, a.seed))
+
+    return parser
+
+
+def print_result(result):
+    if isinstance(result, (list, tuple)):
+        print(" ".join(str(item) for item in result))
+    else:
+        print(result)
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        result = args.run(args)
+    except NotImplementedError:
+        print(f"decisions: {args.command} is not implemented yet", file=sys.stderr)
+        return 1
+    except ValueError as error:
+        print(f"decisions: {error}", file=sys.stderr)
+        return 1
+
+    if should_animate(args.no_animation, sys.stdout):
+        try:
+            animate(args.command, args)
+        except KeyboardInterrupt:
+            pass 
+    print_result(result)
+    return 0

pyDeciders/coin.py

@@ -0,0 +1,44 @@
+"""Coin flipping for the indecisive."""
+
+import random
+
+HEADS = "heads"
+TAILS = "tails"
+
+def flip_coin(times=1, bias=0.5, seed=None):
+    """Flipping a coin one or more times.
+
+    Args:
+        times: how many flips to make. Must be a whole number of at least 1.
+        bias: chance of landing heads, from 0.0 (always tails) to 1.0 (always heads).
+            The default of 0.5 is a fair coin.
+        seed: optional number that makes the result repeatable. The same seed
+            always gives the same flips.
+
+    Returns:
+        A list of "heads" / "tails" strings, one per flip.
+
+    Raises:
+        TypeError: if times is not an int, or bias is not a number.
+        ValueError: if times is less than 1, or bias is outside 0.0-1.0.
+    """
+    if isinstance(times, bool) or not isinstance(times, int):
+        raise TypeError("times must be a whole number")
+    if times < 1:
+        raise ValueError("times must be at least 1")
+    # checks for bool too as True == 1;
+    if isinstance(bias, bool) or not isinstance(bias, (int, float)):
+        raise TypeError("bias must be a number between 0 and 1")
+    if not 0 <= bias <= 1:
+        raise ValueError("bias must be between 0 and 1")
+
+    # a private random generator, so seeding here never affects other code
+    rng = random.Random(seed)
+
+    results = []
+    for _ in range(times):
+        if rng.random() < bias:
+            results.append(HEADS)
+        else:
+            results.append(TAILS)
+    return results

pyDeciders/dice.py

@@ -0,0 +1,40 @@
+"""Dice rolling for the indecisive."""
+
+import random
+
+
+def roll_dice(n=1, sides=6, seed=None):
+    """Roll one or more dice.
+
+    Args:
+        n: how many dice to roll. Must be a whole number of at least 1.
+        sides: how many sides each die has. Must be a whole number of at least 2.
+            The default of 6 is a regular die; use 20 for a D&D d20.
+        seed: optional number that makes the result repeatable. The same seed
+            always gives the same rolls.
+
+    Returns:
+        A list of ints, one per die, each between 1 and sides.
+
+    Raises:
+        TypeError: if n or sides is not a whole number.
+        ValueError: if n is less than 1, or sides is less than 2.
+    """
+    # bool is a subclass of int, so True would sneak through as 1
+    if isinstance(n, bool) or not isinstance(n, int):
+        raise TypeError("n must be a whole number")
+    if n < 1:
+        raise ValueError("n must be at least 1")
+
+    if isinstance(sides, bool) or not isinstance(sides, int):
+        raise TypeError("sides must be a whole number")
+    if sides < 2:
+        raise ValueError("a die needs at least 2 sides")
+
+    # a private random generator, so seeding here never affects other code
+    rng = random.Random(seed)
+
+    results = []
+    for _ in range(n):
+        results.append(rng.randint(1, sides))
+    return results

pyDeciders/eight_ball.py

@@ -0,0 +1,54 @@
+"""A fortune-telling ball for the indecisive."""
+
+import random
+
+POSITIVE = (
+    "Absolutely, go for it.",
+    "The stars say yes.",
+    "Without a shadow of a doubt.",
+    "Yes, and you knew that already.",
+    "Signs point to a cheerful yes.",
+)
+UNSURE = (
+    "Hmm, the ball is buffering. Ask again.",
+    "Too foggy to tell right now.",
+    "Ask me after a snack.",
+    "The answer is hiding. Try later.",
+    "Maybe. Maybe not. Maybe so.",
+)
+NEGATIVE = (
+    "Not a chance.",
+    "The stars say no.",
+    "I would not bet on it.",
+    "Nope, not today.",
+    "All signs point to no.",
+)
+
+ANSWERS = POSITIVE + UNSURE + NEGATIVE
+
+
+def magic_8_ball(question, seed=None):
+    """Ask the ball a yes-or-no question and get its answer.
+
+    Args:
+        question: the question to ask, e.g. "Should I order pizza?". Must be a
+            string with at least one non-space character.
+        seed: optional number that makes the result repeatable. The same seed
+            always gives the same answer.
+
+    Returns:
+        One answer string from ANSWERS.
+
+    Raises:
+        TypeError: if question is not a string.
+        ValueError: if question is empty or only whitespace.
+    """
+    if not isinstance(question, str):
+        raise TypeError("question must be a string")
+    if not question.strip():
+        raise ValueError("question must not be empty")
+
+    # a private random generator, so seeding here never affects other code
+    rng = random.Random(seed)
+
+    return rng.choice(ANSWERS)

pyDeciders/pick.py

@@ -0,0 +1,31 @@
+"""Picking one option for the indecisive."""
+
+import random
+
+
+def pick_one(options, seed=None):
+    """Pick one option at random, each with an equal chance.
+
+    Args:
+        options: a list or tuple of choices, e.g. ["pizza", "tacos", "sushi"].
+            Must contain at least one item.
+        seed: optional number that makes the result repeatable. The same seed
+            always gives the same pick.
+
+    Returns:
+        One item from options.
+
+    Raises:
+        TypeError: if options is not a list or tuple (a single string counts as
+            wrong, since it would pick one letter).
+        ValueError: if options is empty.
+    """
+    if not isinstance(options, (list, tuple)):
+        raise TypeError("options must be a list or tuple of choices")
+    if len(options) == 0:
+        raise ValueError("options must contain at least one choice")
+
+    # a private random generator, so seeding here never affects other code
+    rng = random.Random(seed)
+
+    return rng.choice(options)

pyDeciders/wheel.py

@@ -0,0 +1,25 @@
+import math
+import random
+
+
+def spin_wheel(options, weights=None, seed=None):
+    if not isinstance(options, (list, tuple)):
+        raise TypeError("options must be a list or tuple")
+    if not options:
+        raise ValueError("options must not be empty")
+
+    if weights is not None:
+        if not isinstance(weights, (list, tuple)):
+            raise TypeError("weights must be a list or tuple")
+        if len(weights) != len(options):
+            raise ValueError("weights must have one value per option")
+        for weight in weights:
+            if isinstance(weight, bool) or not isinstance(weight, (int, float)):
+                raise TypeError("each weight must be a number")
+            if not math.isfinite(weight) or weight < 0:
+                raise ValueError("each weight must be a real number and least 0")
+        if sum(weights) == 0:
+            raise ValueError("at least one weight must be above 0")
+
+    rng = random.Random(seed)
+    return rng.choices(options, weights=weights, k=1)[0]