python-reckless 0.1.6__tar.gz

python_reckless-0.1.6/.gitignore

@@ -0,0 +1,5 @@
+*.DS_Store
+venv
+.python-version
+dist
+notes.txt

python_reckless-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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.

python_reckless-0.1.6/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: python-reckless
+Version: 0.1.6
+Summary: A lightweight Python wrapper for the Reckless UCI chess engine
+Project-URL: Homepage, https://github.com/DaveP80/python-reckless
+Project-URL: Repository, https://github.com/DaveP80/python-reckless
+Project-URL: Issues, https://github.com/DaveP80/python-reckless/issues
+Author-email: David Paquette <davidpaq1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chess,chess-engine,reckless,uci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Games/Entertainment :: Board Games
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-reckless
+
+A lightweight, dependency-free Python wrapper for the
+[Reckless](https://github.com/codedeliveryservice/Reckless) UCI chess engine.
+
+`python-reckless` does **not** bundle the engine. Reckless is a standalone
+compiled executable; this package launches it as a subprocess and speaks the
+UCI protocol to it. You supply the binary.
+
+## Installing the engine
+
+Download a prebuilt binary for your platform from the
+[Reckless releases page](https://github.com/codedeliveryservice/Reckless/releases),
+then make it discoverable in one of these ways:
+
+- Put it on your `PATH` as `reckless`, **or**
+- set the `RECKLESS_PATH` environment variable to its full path, **or**
+- pass the path directly: `Reckless(path="/path/to/reckless")`.
+
+## Installing this package
+
+```bash
+pip install python-reckless
+```
+
+The import name is `reckless` (the distribution name is `python-reckless`).
+
+## Usage
+
+```python
+from reckless import Reckless
+
+with Reckless() as engine:
+    engine.new_game()
+    engine.set_position(moves=["e2e4", "e7e5"])
+    best = engine.best_move(depth=12)
+    print("Reckless suggests:", best)
+```
+
+You can also search by time instead of depth:
+
+```python
+move = engine.best_move(movetime=1000)  # think for 1 second
+```
+## Development
+
+Make changes on a feature branch and put up to date `engine.py` files and other helper files in the `src` directory.
+
+## Note
+
+For a fully featured UCI client (analysis info, evaluations, multipv, async),
+consider the mature [`python-chess`](https://pypi.org/project/chess/) library,
+whose `chess.engine.SimpleEngine.popen_uci()` works with Reckless out of the
+box. This package is intentionally tiny and focused.
+
+## License
+
+MIT

python_reckless-0.1.6/README.md

@@ -0,0 +1,58 @@
+# python-reckless
+
+A lightweight, dependency-free Python wrapper for the
+[Reckless](https://github.com/codedeliveryservice/Reckless) UCI chess engine.
+
+`python-reckless` does **not** bundle the engine. Reckless is a standalone
+compiled executable; this package launches it as a subprocess and speaks the
+UCI protocol to it. You supply the binary.
+
+## Installing the engine
+
+Download a prebuilt binary for your platform from the
+[Reckless releases page](https://github.com/codedeliveryservice/Reckless/releases),
+then make it discoverable in one of these ways:
+
+- Put it on your `PATH` as `reckless`, **or**
+- set the `RECKLESS_PATH` environment variable to its full path, **or**
+- pass the path directly: `Reckless(path="/path/to/reckless")`.
+
+## Installing this package
+
+```bash
+pip install python-reckless
+```
+
+The import name is `reckless` (the distribution name is `python-reckless`).
+
+## Usage
+
+```python
+from reckless import Reckless
+
+with Reckless() as engine:
+    engine.new_game()
+    engine.set_position(moves=["e2e4", "e7e5"])
+    best = engine.best_move(depth=12)
+    print("Reckless suggests:", best)
+```
+
+You can also search by time instead of depth:
+
+```python
+move = engine.best_move(movetime=1000)  # think for 1 second
+```
+## Development
+
+Make changes on a feature branch and put up to date `engine.py` files and other helper files in the `src` directory.
+
+## Note
+
+For a fully featured UCI client (analysis info, evaluations, multipv, async),
+consider the mature [`python-chess`](https://pypi.org/project/chess/) library,
+whose `chess.engine.SimpleEngine.popen_uci()` works with Reckless out of the
+box. This package is intentionally tiny and focused.
+
+## License
+
+MIT

python_reckless-0.1.6/__init__.py

@@ -0,0 +1,6 @@
+"""python-reckless: a lightweight wrapper for the Reckless UCI chess engine."""
+
+from .engine import Reckless, RecklessError
+
+__version__ = "0.1.6"
+__all__ = ["Reckless", "RecklessError", "__version__"]

python_reckless-0.1.6/engine.py

@@ -0,0 +1,163 @@
+"""A minimal, dependency-free wrapper around the Reckless UCI chess engine.
+
+Reckless is a standalone compiled executable that speaks the Universal Chess
+Interface (UCI) protocol over stdin/stdout. This module launches that
+executable as a subprocess and exchanges UCI text commands with it.
+
+It does NOT bundle the engine binary. You must have `reckless` available:
+download a prebuilt binary from
+https://github.com/codedeliveryservice/Reckless/releases and either put it on
+your PATH, set the RECKLESS_PATH environment variable, or pass its path to
+``Reckless(path=...)``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import Iterable, Optional
+
+
+class RecklessError(RuntimeError):
+    """Raised when the engine cannot be found or behaves unexpectedly."""
+
+
+def _locate_engine(path: Optional[str]) -> str:
+    """Resolve the engine executable: explicit arg -> env var -> PATH."""
+    candidate = path or os.environ.get("RECKLESS_PATH") or shutil.which("reckless")
+    if not candidate:
+        raise RecklessError(
+            "Could not find the Reckless engine. Pass path=..., set the "
+            "RECKLESS_PATH environment variable, or put 'reckless' on your PATH. "
+            "Prebuilt binaries: "
+            "https://github.com/codedeliveryservice/Reckless/releases"
+        )
+    if not os.path.isfile(candidate) and not shutil.which(candidate):
+        raise RecklessError(f"Engine path does not point to a file: {candidate!r}")
+    return candidate
+
+
+class Reckless:
+    """A simple handle to a running Reckless engine process.
+
+    Example
+    -------
+    >>> with Reckless() as engine:
+    ...     move = engine.best_move(depth=12)
+    ...     print(move)
+    """
+
+    def __init__(self, path: Optional[str] = None, *, start: bool = True) -> None:
+        self.path = _locate_engine(path)
+        self._proc: Optional[subprocess.Popen] = None
+        if start:
+            self.start()
+
+    # -- process lifecycle -------------------------------------------------
+
+    def start(self) -> "Reckless":
+        if self._proc is not None:
+            return self
+        self._proc = subprocess.Popen(
+            [self.path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,  # line-buffered
+        )
+        self._handshake()
+        return self
+
+    def quit(self) -> None:
+        if self._proc is None:
+            return
+        try:
+            self._send("quit")
+            self._proc.wait(timeout=5)
+        except Exception:
+            self._proc.kill()
+        finally:
+            self._proc = None
+
+    def __enter__(self) -> "Reckless":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.quit()
+
+    # -- low-level UCI I/O -------------------------------------------------
+
+    def _send(self, command: str) -> None:
+        if self._proc is None or self._proc.stdin is None:
+            raise RecklessError("Engine is not running.")
+        self._proc.stdin.write(command + "\n")
+        self._proc.stdin.flush()
+
+    def _read_until(self, token: str) -> str:
+        """Read lines until one starts with `token`; return that line."""
+        if self._proc is None or self._proc.stdout is None:
+            raise RecklessError("Engine is not running.")
+        while True:
+            line = self._proc.stdout.readline()
+            if not line:
+                raise RecklessError("Engine closed the connection unexpectedly.")
+            if line.strip().startswith(token):
+                return line.strip()
+
+    def _handshake(self) -> None:
+        self._send("uci")
+        self._read_until("uciok")
+        self.is_ready()
+
+    # -- public commands ---------------------------------------------------
+
+    def is_ready(self) -> bool:
+        """Block until the engine reports it is ready."""
+        self._send("isready")
+        self._read_until("readyok")
+        return True
+
+    def new_game(self) -> None:
+        self._send("ucinewgame")
+        self.is_ready()
+
+    def set_position(
+        self,
+        fen: Optional[str] = None,
+        moves: Optional[Iterable[str]] = None,
+    ) -> None:
+        """Set the board. Defaults to the standard start position.
+
+        `moves` is a sequence of UCI moves (e.g. ["e2e4", "e7e5"]).
+        """
+        base = f"fen {fen}" if fen else "startpos"
+        move_str = ""
+        if moves:
+            move_str = " moves " + " ".join(moves)
+        self._send(f"position {base}{move_str}")
+
+    def best_move(
+        self,
+        *,
+        depth: Optional[int] = None,
+        movetime: Optional[int] = None,
+    ) -> str:
+        """Search the current position and return the best move (UCI string).
+
+        Provide either `depth` (plies) or `movetime` (milliseconds).
+        Defaults to depth 10 if neither is given.
+        """
+        if depth is None and movetime is None:
+            depth = 10
+        go = "go"
+        if depth is not None:
+            go += f" depth {depth}"
+        if movetime is not None:
+            go += f" movetime {movetime}"
+        self._send(go)
+        line = self._read_until("bestmove")
+        # Format: "bestmove e2e4 ponder e7e5"
+        parts = line.split()
+        return parts[1] if len(parts) > 1 else ""

python_reckless-0.1.6/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-reckless"
+version = "0.1.6"
+description = "A lightweight Python wrapper for the Reckless UCI chess engine"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "David Paquette", email = "davidpaq1@gmail.com" },
+]
+keywords = ["chess", "uci", "reckless", "chess-engine"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment :: Board Games",
+]
+dependencies = []  # zero runtime deps — we talk UCI ourselves
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/DaveP80/python-reckless"
+Repository = "https://github.com/DaveP80/python-reckless"
+Issues = "https://github.com/DaveP80/python-reckless/issues"
+
+# Distribution is "python-reckless"; the import package is "reckless".
+# This mirrors python-dateutil -> import dateutil.
+# IMPORTANT: this MUST point at where the package actually lives on disk.
+# Files are in src/reckless/, so the path is "src/reckless" (hatchling strips
+# the src/ prefix automatically, so it still imports as `reckless`).
+[tool.hatch.build.targets.wheel]
+packages = ["src/reckless"]

python_reckless-0.1.6/src/reckless/__init__.py

@@ -0,0 +1,6 @@
+"""python-reckless: a lightweight wrapper for the Reckless UCI chess engine."""
+
+from .engine import Reckless, RecklessError
+
+__version__ = "0.1.6"
+__all__ = ["Reckless", "RecklessError", "__version__"]

python_reckless-0.1.6/src/reckless/engine.py

@@ -0,0 +1,163 @@
+"""A minimal, dependency-free wrapper around the Reckless UCI chess engine.
+
+Reckless is a standalone compiled executable that speaks the Universal Chess
+Interface (UCI) protocol over stdin/stdout. This module launches that
+executable as a subprocess and exchanges UCI text commands with it.
+
+It does NOT bundle the engine binary. You must have `reckless` available:
+download a prebuilt binary from
+https://github.com/codedeliveryservice/Reckless/releases and either put it on
+your PATH, set the RECKLESS_PATH environment variable, or pass its path to
+``Reckless(path=...)``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import Iterable, Optional
+
+
+class RecklessError(RuntimeError):
+    """Raised when the engine cannot be found or behaves unexpectedly."""
+
+
+def _locate_engine(path: Optional[str]) -> str:
+    """Resolve the engine executable: explicit arg -> env var -> PATH."""
+    candidate = path or os.environ.get("RECKLESS_PATH") or shutil.which("reckless")
+    if not candidate:
+        raise RecklessError(
+            "Could not find the Reckless engine. Pass path=..., set the "
+            "RECKLESS_PATH environment variable, or put 'reckless' on your PATH. "
+            "Prebuilt binaries: "
+            "https://github.com/codedeliveryservice/Reckless/releases"
+        )
+    if not os.path.isfile(candidate) and not shutil.which(candidate):
+        raise RecklessError(f"Engine path does not point to a file: {candidate!r}")
+    return candidate
+
+
+class Reckless:
+    """A simple handle to a running Reckless engine process.
+
+    Example
+    -------
+    >>> with Reckless() as engine:
+    ...     move = engine.best_move(depth=12)
+    ...     print(move)
+    """
+
+    def __init__(self, path: Optional[str] = None, *, start: bool = True) -> None:
+        self.path = _locate_engine(path)
+        self._proc: Optional[subprocess.Popen] = None
+        if start:
+            self.start()
+
+    # -- process lifecycle -------------------------------------------------
+
+    def start(self) -> "Reckless":
+        if self._proc is not None:
+            return self
+        self._proc = subprocess.Popen(
+            [self.path],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,  # line-buffered
+        )
+        self._handshake()
+        return self
+
+    def quit(self) -> None:
+        if self._proc is None:
+            return
+        try:
+            self._send("quit")
+            self._proc.wait(timeout=5)
+        except Exception:
+            self._proc.kill()
+        finally:
+            self._proc = None
+
+    def __enter__(self) -> "Reckless":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.quit()
+
+    # -- low-level UCI I/O -------------------------------------------------
+
+    def _send(self, command: str) -> None:
+        if self._proc is None or self._proc.stdin is None:
+            raise RecklessError("Engine is not running.")
+        self._proc.stdin.write(command + "\n")
+        self._proc.stdin.flush()
+
+    def _read_until(self, token: str) -> str:
+        """Read lines until one starts with `token`; return that line."""
+        if self._proc is None or self._proc.stdout is None:
+            raise RecklessError("Engine is not running.")
+        while True:
+            line = self._proc.stdout.readline()
+            if not line:
+                raise RecklessError("Engine closed the connection unexpectedly.")
+            if line.strip().startswith(token):
+                return line.strip()
+
+    def _handshake(self) -> None:
+        self._send("uci")
+        self._read_until("uciok")
+        self.is_ready()
+
+    # -- public commands ---------------------------------------------------
+
+    def is_ready(self) -> bool:
+        """Block until the engine reports it is ready."""
+        self._send("isready")
+        self._read_until("readyok")
+        return True
+
+    def new_game(self) -> None:
+        self._send("ucinewgame")
+        self.is_ready()
+
+    def set_position(
+        self,
+        fen: Optional[str] = None,
+        moves: Optional[Iterable[str]] = None,
+    ) -> None:
+        """Set the board. Defaults to the standard start position.
+
+        `moves` is a sequence of UCI moves (e.g. ["e2e4", "e7e5"]).
+        """
+        base = f"fen {fen}" if fen else "startpos"
+        move_str = ""
+        if moves:
+            move_str = " moves " + " ".join(moves)
+        self._send(f"position {base}{move_str}")
+
+    def best_move(
+        self,
+        *,
+        depth: Optional[int] = None,
+        movetime: Optional[int] = None,
+    ) -> str:
+        """Search the current position and return the best move (UCI string).
+
+        Provide either `depth` (plies) or `movetime` (milliseconds).
+        Defaults to depth 10 if neither is given.
+        """
+        if depth is None and movetime is None:
+            depth = 10
+        go = "go"
+        if depth is not None:
+            go += f" depth {depth}"
+        if movetime is not None:
+            go += f" movetime {movetime}"
+        self._send(go)
+        line = self._read_until("bestmove")
+        # Format: "bestmove e2e4 ponder e7e5"
+        parts = line.split()
+        return parts[1] if len(parts) > 1 else ""

python_reckless-0.1.6/test_engine.py

@@ -0,0 +1,36 @@
+"""Tests for python-reckless.
+
+These tests need a real `reckless` binary to run the engine-dependent cases.
+If one isn't available they skip rather than fail, so the suite is green in CI
+even without the engine installed.
+"""
+
+import shutil
+
+import pytest
+
+from reckless import Reckless, RecklessError
+
+HAS_ENGINE = shutil.which("reckless") is not None
+needs_engine = pytest.mark.skipif(not HAS_ENGINE, reason="reckless not on PATH")
+
+
+def test_missing_engine_raises():
+    with pytest.raises(RecklessError):
+        Reckless(path="/definitely/not/a/real/engine", start=False)
+
+
+@needs_engine
+def test_handshake_and_ready():
+    with Reckless() as engine:
+        assert engine.is_ready() is True
+
+
+@needs_engine
+def test_best_move_from_start():
+    with Reckless() as engine:
+        engine.new_game()
+        engine.set_position()  # start position
+        move = engine.best_move(depth=8)
+        # A legal opening move is 4 chars of UCI, e.g. "e2e4".
+        assert len(move) >= 4