From 41b9ce71dd80d0b5c89993e0c56f1e56c0fb876b Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Mon, 12 Jun 2023 11:06:20 -0500
Subject: [PATCH] pybricks.tools: add read_input_byte()

This adds stubs and docs for the new `pybricks.tools.read_input_byte()`
function.
---
 doc/main/tools/index.rst           |  5 +++++
 jedi/tests/test_complete_import.py |  1 +
 src/pybricks/tools.py              | 13 ++++++++++++-
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/doc/main/tools/index.rst b/doc/main/tools/index.rst
index 7172d2d..3e13747 100644
--- a/doc/main/tools/index.rst
+++ b/doc/main/tools/index.rst
@@ -22,6 +22,11 @@ Timing tools
 
     .. automethod:: pybricks.tools.StopWatch.reset
 
+Input tools
+-----------
+
+.. autofunction:: pybricks.tools.read_input_byte
+
 Linear algebra tools
 --------------------
 
diff --git a/jedi/tests/test_complete_import.py b/jedi/tests/test_complete_import.py
index d8eb85f..fb62d9e 100644
--- a/jedi/tests/test_complete_import.py
+++ b/jedi/tests/test_complete_import.py
@@ -158,6 +158,7 @@ def test_from_pybricks_tools_import():
         "cross",
         "DataLog",
         "Matrix",
+        "read_input_byte",
         "StopWatch",
         "vector",
         "wait",
diff --git a/src/pybricks/tools.py b/src/pybricks/tools.py
index 64f8bc7..6d81b0b 100644
--- a/src/pybricks/tools.py
+++ b/src/pybricks/tools.py
@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Sequence, Tuple, overload
+from typing import TYPE_CHECKING, Any, Optional, Sequence, Tuple, overload
 
 if TYPE_CHECKING:
     from .parameters import Number
@@ -222,6 +222,17 @@ def cross(a: Matrix, b: Matrix) -> Matrix:
     """
 
 
+def read_input_byte() -> Optional[int]:
+    """
+    read_input_byte() -> int | None
+
+    Reads one byte from standard input without blocking.
+
+    Returns:
+        The numeric value of the byte read or ``None`` if no data is available.
+    """
+
+
 # HACK: hide from jedi
 if TYPE_CHECKING:
     del Number