randpal 0.2__tar.gz → 0.4__tar.gz

{randpal-0.2 → randpal-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: randpal
-Version: 0.2
+Version: 0.4
 Summary: Your friendly random pal - at your random service.
 Project-URL: Repository, https://github.com/soucelover/randpal.git
 Project-URL: Issues, https://github.com/soucelover/randpal/issues

{randpal-0.2 → randpal-0.4}/pyproject.toml

@@ -112,6 +112,9 @@ runtime-evaluated-base-classes = [
 ]
 runtime-evaluated-decorators = ["invoke.tasks.task"]
 
+[tool.ruff.lint.flake8-builtins]
+ignorelist = ["help"]
+
 # ================
 # Pyright Settings
 # ================

randpal-0.4/src/randpal/__init__.py

@@ -0,0 +1,26 @@
+from importlib import metadata
+
+from .rng import (
+    FloatGenerator,
+    IntegerGenerator,
+    PythonRandom,
+    RandomProvider,
+    SecretsRandom,
+    SequencesGenerator,
+)
+
+__all__ = [
+    "FloatGenerator",
+    "IntegerGenerator",
+    "PythonRandom",
+    "RandomProvider",
+    "SecretsRandom",
+    "SequencesGenerator",
+    "__version__",
+]
+PACKAGE_NAME = "randpal"
+
+try:
+    __version__ = metadata.version(PACKAGE_NAME)
+except metadata.PackageNotFoundError:
+    __version__ = "0.1.dev1+UNKNOWN"

randpal-0.4/src/randpal/__main__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from randpal.cli import cli
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

randpal-0.4/src/randpal/cli/__init__.py

@@ -0,0 +1,3 @@
+from .parser import cli, setup_parser
+
+__all__ = ["cli", "setup_parser"]

randpal-0.4/src/randpal/cli/base.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from argparse import Namespace
+from collections.abc import Callable
+from typing import Literal, TypeAlias
+
+from randpal.rng import PythonRandom, SecretsRandom
+
+CommandFunction: TypeAlias = Callable[[Namespace], None]
+GeneratorCommandFunction: TypeAlias = Callable[
+    ["GeneratorCommandArgs", "RandomGeneratorFactory"], None
+]
+ProviderCode: TypeAlias = Literal["python", "secrets"]
+
+
+class RandomGeneratorFactory:
+    def create_python_rng(self) -> PythonRandom:
+        return PythonRandom()
+
+    def create_secrets_rng(self) -> SecretsRandom:
+        return SecretsRandom()
+
+    def create_rng(self, code: ProviderCode) -> PythonRandom | SecretsRandom:
+        match code:
+            case "python":
+                return self.create_python_rng()
+            case "secrets":
+                return self.create_secrets_rng()
+
+
+class GeneratorCommandArgs(Namespace):
+    provider: ProviderCode

randpal-0.4/src/randpal/cli/commands.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from randpal.rng import IntegerGenerator, SequencesGenerator
+
+    from .base import GeneratorCommandArgs, RandomGeneratorFactory
+
+
+VERBOSE_MODE = True
+
+
+def command_int(
+    args: GeneratorCommandArgs, factory: RandomGeneratorFactory
+) -> None:
+    generator: IntegerGenerator = factory.create_rng(args.provider)
+    number = generator.randint(args.a, args.b)
+
+    match args.output_format:
+        case "concise":
+            print(number)  # noqa: T201
+        case "verbose":
+            print(f"And so, the random number is... {number}!", end="\n\n")  # noqa: T201
+        case _:
+            raise NotImplementedError
+
+
+def command_pick(
+    args: GeneratorCommandArgs, factory: RandomGeneratorFactory
+) -> None:
+    generator: SequencesGenerator = factory.create_rng(args.provider)
+    item = generator.choice(args.items)
+
+    match args.output_format:
+        case "concise":
+            print(item)  # noqa: T201
+        case "verbose":
+            print(  # noqa: T201
+                f'The barrel with cards was shaken and a card with "{item}" '
+                "written on it has fallen out.",
+                end="\n\n",
+            )
+        case _:
+            raise NotImplementedError

randpal-0.4/src/randpal/cli/parser.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import inspect
+from argparse import ArgumentParser, RawDescriptionHelpFormatter
+from typing import TYPE_CHECKING
+
+import randpal
+
+from .base import GeneratorCommandArgs, RandomGeneratorFactory
+from .commands import command_int, command_pick
+
+if TYPE_CHECKING:
+    from argparse import (
+        _SubParsersAction,  # pyright: ignore[reportPrivateUsage]
+    )
+    from collections.abc import Sequence
+
+    from .base import CommandFunction, GeneratorCommandFunction
+
+
+def get_docs_header(obj: object) -> tuple[str, str] | tuple[None, None]:
+    """Get header of object's docstring.
+
+    Args:
+        obj: Source of docstring.
+
+    Returns:
+        The first line of the dosctring and an original docstring itself.
+    """
+    docs = inspect.getdoc(obj)
+
+    if docs is None:
+        return None, None
+
+    header, _, _body = docs.partition("\n")
+    return header, docs
+
+
+def add_command(  # noqa: PLR0913
+    commands: _SubParsersAction[ArgumentParser],
+    name: str,
+    function: CommandFunction,
+    *,
+    help: str | None = None,
+    epilog: str | None = None,
+    aliases: Sequence[str] = (),
+) -> ArgumentParser:
+    """Register a single command in `SubParsersAction`.
+
+    Args:
+        commands: `ArgumentParser`'s action representing commands
+        name: Name for the command.
+        function: Function implementing command and containing its docstrings.
+        aliases: Optional list of aliases for the command.
+
+    Returns:
+        A newly created parser of the command.
+    """
+    header, docs = get_docs_header(function)
+
+    if help is None:
+        help = header
+
+    parser = commands.add_parser(
+        name,
+        help=help,
+        description=docs,
+        epilog=epilog,
+        aliases=aliases,
+        formatter_class=RawDescriptionHelpFormatter,
+    )
+    parser.set_defaults(command=function)
+    return parser
+
+
+def add_generator_command(  # noqa: PLR0913
+    commands: _SubParsersAction[ArgumentParser],
+    name: str,
+    function: GeneratorCommandFunction,
+    *,
+    providers: Sequence[str] | None = ("python", "secrets"),
+    output_formats: Sequence[str] | None = ("verbose", "concise"),
+    help: str | None = None,
+    epilog: str | None = None,
+    aliases: Sequence[str] = (),
+) -> ArgumentParser:
+    def wrapper(args: GeneratorCommandArgs) -> None:
+        factory = RandomGeneratorFactory()
+
+        return function(args, factory)
+
+    parser = add_command(
+        commands,
+        name,
+        wrapper,  # type: ignore [reportArgumentType]
+        help=help,
+        epilog=epilog,
+        aliases=aliases,
+    )
+
+    if providers:
+        parser.add_argument(
+            "--provider",
+            default=providers[0],
+            choices=providers,
+            help="Provider chosen as a source of entropy "
+            "for random generation.",
+        )
+
+    if output_formats:
+        parser.add_argument(
+            "--output-format",
+            "--format",
+            default=output_formats[0],
+            choices=output_formats,
+            help="Output format for the generation results.",
+            dest="output_format",
+        )
+
+    return parser
+
+
+def register_commands(parser: ArgumentParser) -> None:
+    commands = parser.add_subparsers(required=True)
+
+    com_int = add_generator_command(commands, "int", command_int)
+    com_int.add_argument("a", type=int)
+    com_int.add_argument("b", type=int)
+
+    com_choose = add_generator_command(commands, "pick", command_pick)
+    com_choose.add_argument("items", nargs="+", metavar="item")
+
+
+def setup_parser() -> ArgumentParser:
+    parser = ArgumentParser(formatter_class=RawDescriptionHelpFormatter)
+
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"randpal {randpal.__version__}",
+    )
+
+    register_commands(parser)
+
+    return parser
+
+
+def cli(args: list[str] | None = None) -> None:
+    parser = setup_parser()
+
+    parsed = parser.parse_args(args)
+    parsed.command(parsed)

randpal-0.4/src/randpal/rng/__init__.py

@@ -0,0 +1,17 @@
+from .base import (
+    FloatGenerator,
+    IntegerGenerator,
+    RandomProvider,
+    SequencesGenerator,
+)
+from .python import PythonRandom
+from .secrets import SecretsRandom
+
+__all__ = [
+    "FloatGenerator",
+    "IntegerGenerator",
+    "PythonRandom",
+    "RandomProvider",
+    "SecretsRandom",
+    "SequencesGenerator",
+]

randpal-0.4/src/randpal/rng/base.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import operator
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Protocol, SupportsIndex, TypeVar, overload
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "FloatGenerator",
+    "IntegerGenerator",
+    "RandomProvider",
+    "SequencesGenerator",
+]
+
+
+_T = TypeVar("_T")
+
+
+class RandomProvider(Protocol):
+    @abstractmethod
+    def randbytes(self, n: int) -> bytes:
+        raise NotImplementedError
+
+    # NOTE: It's possible to implement random buffering in future
+    def randbits(self, k: int) -> int:
+        n = (k + 7) // 8
+        value = int.from_bytes(self.randbytes(n), "big")
+        return value >> (n * 8 - k)
+
+    def _randbelow(self, n: int) -> int:
+        if n <= 0:
+            msg = "Empty range -- no values to choose from"
+            raise ValueError(msg)
+
+        k = n.bit_length()
+        randbits = self.randbits
+        r = randbits(k)
+
+        while r >= n:
+            r = randbits(k)
+
+        return r
+
+
+class IntegerGenerator(RandomProvider, Protocol):
+    @overload
+    def randrange(self, stop: SupportsIndex, /) -> int: ...
+    @overload
+    def randrange(
+        self, start: SupportsIndex, stop: SupportsIndex, /
+    ) -> int: ...
+    @overload
+    def randrange(
+        self, start: SupportsIndex, stop: SupportsIndex, step: SupportsIndex, /
+    ) -> int: ...
+
+    def randrange(
+        self,
+        start: SupportsIndex,
+        stop: SupportsIndex | None = None,
+        step: SupportsIndex = 1,
+        /,
+    ) -> int:
+        try:
+            istart = operator.index(start)  # Validate start
+        except TypeError as exc:
+            tname = type(start).__name__
+            msg = f"Arg 1 of type {tname} couldn't be interpreted as integer"
+            raise TypeError(msg) from exc
+
+        # Fast path: [0; start)
+        if stop is None:
+            if step != 1:
+                msg = "Step was provided without a non-None stop argument"
+                raise TypeError(msg)
+
+            return self._randbelow(istart)
+
+        try:
+            istop = operator.index(stop)  # Validate stop
+        except TypeError as exc:
+            tname = type(stop).__name__
+            msg = f"Arg 2 of type {tname} couldn't be interpreted as integer"
+            raise TypeError(msg) from exc
+
+        try:
+            istep = operator.index(step)  # Validate stop
+        except TypeError as exc:
+            tname = type(step).__name__
+            msg = f"Arg 3 of type {tname} couldn't be interpreted as integer"
+            raise TypeError(msg) from exc
+
+        width = istop - istart
+
+        # Fast path: [start; stop)
+        if istep == 1:
+            return istart + self._randbelow(width)
+
+        if istep == 0:
+            msg = "Zero step was provided"
+            raise ValueError(msg)
+
+        # Divide width and round in direction from zero
+        n = (width + istep + 1 - (istep > 0) * 2) // istep
+
+        return istart + istep * self._randbelow(n)
+
+    def randint(self, a: SupportsIndex, b: SupportsIndex) -> int:
+        try:
+            ia = operator.index(a)  # Validate a
+        except TypeError as exc:
+            tname = type(a).__name__
+            msg = f"Arg 1 of type {tname} couldn't be interpreted as integer"
+            raise TypeError(msg) from exc
+
+        try:
+            ib = operator.index(b)  # Validate b
+        except TypeError as exc:
+            tname = type(b).__name__
+            msg = f"Arg 2 of type {tname} couldn't be interpreted as integer"
+            raise TypeError(msg) from exc
+
+        width = ib - ia
+        return ia + self._randbelow(width + 1)
+
+    def randbool(self) -> bool:
+        return bool(self.randbits(1))
+
+
+class FloatGenerator(Protocol):
+    def uniform(self, a: float, b: float) -> float:
+        raise NotImplementedError
+
+    def chance(self, probability: float) -> bool:
+        raise NotImplementedError
+
+
+class SequencesGenerator(RandomProvider, Protocol):
+    def choice(self, seq: Sequence[_T]) -> _T:
+        return seq[self._randbelow(len(seq))]

randpal-0.4/src/randpal/rng/python.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import random
+
+from typing_extensions import override
+
+from .base import IntegerGenerator, RandomProvider, SequencesGenerator
+
+
+class PythonRandom(SequencesGenerator, IntegerGenerator, RandomProvider):
+    _generator: random.Random
+
+    def __init__(self, generator: random.Random | None = None) -> None:
+        if generator is None:
+            generator = random.Random()  # noqa: S311
+
+        self._generator = generator
+
+    @override
+    def randbytes(self, n: int) -> bytes:
+        return self._generator.randbytes(n)
+
+    @override
+    def randbits(self, k: int) -> int:
+        return self._generator.getrandbits(k)

randpal-0.4/src/randpal/rng/secrets.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import secrets
+
+from typing_extensions import override
+
+from .base import IntegerGenerator, RandomProvider, SequencesGenerator
+
+
+class SecretsRandom(SequencesGenerator, IntegerGenerator, RandomProvider):
+    _generator: secrets.SystemRandom
+
+    def __init__(self, generator: secrets.SystemRandom | None = None) -> None:
+        if generator is None:
+            generator = secrets.SystemRandom()
+
+        self._generator = generator
+
+    @override
+    def randbytes(self, n: int) -> bytes:
+        return self._generator.randbytes(n)
+
+    @override
+    def randbits(self, k: int) -> int:
+        return self._generator.getrandbits(k)

randpal-0.2/src/randpal/__init__.py

@@ -1,9 +0,0 @@
-from importlib import metadata
-
-__all__ = ["__version__"]
-PACKAGE_NAME = "randpal"
-
-try:
-    __version__ = metadata.version(PACKAGE_NAME)
-except metadata.PackageNotFoundError:
-    __version__ = "0.1.dev1+UNKNOWN"

randpal-0.2/src/randpal/__main__.py

@@ -1,43 +0,0 @@
-import argparse
-import random
-
-VERBOSE_MODE = True
-
-
-def command_int(args: argparse.Namespace) -> None:
-    if VERBOSE_MODE:
-        print("Random number is ", end="")  # noqa: T201
-
-    print(random.randint(args.a, args.b), end="\n\n")  # noqa: S311, T201
-
-
-def command_choose(args: argparse.Namespace) -> None:
-    if VERBOSE_MODE:
-        print("Random chosen item is ", end="")  # noqa: T201
-
-    print(random.choice(args.item), end="\n\n")  # noqa: S311, T201
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser()
-    commands = parser.add_subparsers(required=True)
-
-    com_int = commands.add_parser("int")
-    com_int.add_argument("a", type=int)
-    com_int.add_argument("b", type=int)
-    com_int.set_defaults(command=command_int)
-
-    com_choose = commands.add_parser("choose")
-    com_choose.add_argument("item", nargs="+")
-    com_choose.set_defaults(command=command_choose)
-
-    return parser.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    args.command(args)
-
-
-if __name__ == "__main__":
-    main()