add @terminal_required

CHANGELOG.md

@@ -5,6 +5,7 @@
 + Add RNG/random selection overloads such as `luck()`, `rng_overload()`
 + Add 7 new throwable exceptions
 + Add color utilities: `chalk` module
++ Add `.terminal` module, to ease TUI development.
 
 ## 0.6.1
 

src/suou/exceptions.py

@@ -86,13 +86,18 @@ class Fahrenheit451Error(PoliticalError):
     Base class for thought crimes related to arts (e.g. writing, visual arts, music)
     """
 
+    # Werkzeug
+    code = 451
+
 class FuckAroundFindOutError(PoliticalError):
     """
     Raised when there is no actual grounds to raise an exception, but you did something in the past to deserve this outcome.
 
-    Ideal for permanent service bans or something.
+    Ideal for permanent service bans or similar.
     """
 
 __all__ = (
-    'MissingConfigError', 'MissingConfigWarning', 'LexError', 'InconsistencyError', 'NotFoundError'
+    'MissingConfigError', 'MissingConfigWarning', 'LexError', 'InconsistencyError', 'NotFoundError',
+    'TerminalRequiredError', 'PoliticalError', 'PoliticalWarning', 'Fahrenheit451Error', 'FuckAroundFindOutError',
+    'BrokenStringsError', 'BadLuckError'
 )

src/suou/terminal.py

@@ -0,0 +1,37 @@
+"""
+Utilities for console I/O and text user interfaces (TUI)
+
+---
+
+Copyright (c) 2025 Sakuragasaki46.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+See LICENSE for the specific language governing permissions and
+limitations under the License.
+
+This software is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+"""
+
+
+from __future__ import annotations
+from functools import wraps
+import sys
+from suou.exceptions import TerminalRequiredError
+
+
+def terminal_required(func):
+    """
+    Requires the decorated callable to be fully connected to a terminal.
+
+    NEW 0.7.0
+    """
+    @wraps(func)
+    def wrapper(*a, **ka):
+        if not (sys.stdin.isatty() and sys.stdout.isatty() and sys.stderr.isatty()):
+            raise TerminalRequiredError('this program must be run from a terminal')
+        return func(*a, **ka)
+    return wrapper
+
+__all__ = ('terminal_required',)