menataur 0.1.0__tar.gz

menataur-0.1.0/LICENSE

@@ -0,0 +1,41 @@
+Menataur (main)
+---------------------------------------------------------------------------------------------
+MIT License
+
+Copyright (c) 2026 Gratonic (https://github.com/Gratonic/Minotaur) and FailurePoint (https://github.com/FailurePoint)
+
+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.
+
+Colorama
+---------------------------------------------------------------------------------------------
+Copyright (c) 2010 Jonathan Hartley
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its contributors
+  may be used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

menataur-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: menataur
+Version: 0.1.0
+Summary: ...
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Dynamic: license-file

menataur-0.1.0/README.md

@@ -0,0 +1,242 @@
+# What is Menataur?
+
+Menataur is a menu interface builder module for Python3.10.x. It is super easy to use and makes
+constructing menu interfaces a breeze, turning hours, days, or even months of work into just a few minutes.
+
+# How do you construct an awesome menu interface with Menataur? Here's a tested example...
+
+```bash
+pip3 install menataur
+```
+
+```python
+import menataur
+
+# [=== Test Menu 1 ===] #
+
+# create Banner
+banner_1 = menataur.Banner()
+
+banner_1.title = r"""
+ _____          _                                   _       
+|_   _|        | |                                 | |      
+  | | _ __  ___| |_ _ __ _   _ _ __ ___   ___ _ __ | |_ ___ 
+  | || '_ \/ __| __| '__| | | | '_ ` _ \ / _ \ '_ \| __/ __|
+ _| || | | \__ \ |_| |  | |_| | | | | | |  __/ | | | |_\__ \
+ \___/_| |_|___/\__|_|   \__,_|_| |_| |_|\___|_| |_|\__|___/"""
+banner_1.title_colors = ["cyan", "yellow", "green", "magenta"]
+banner_1.title_bar = "_______________________________________________________________/"
+banner_1.title_bar_color = "blue"
+banner_1.program_name = "Menataur"
+banner_1.program_name_color = "blue"
+banner_1.program_version_number = 1.0 
+banner_1.program_version_number_color = "yellow"
+banner_1.operating_system_support_message = "This Program Supports Linux, MacOS, and Windows"
+banner_1.operating_system_support_message_color = "light_green"
+
+# create Options
+options_1 = menataur.Options()
+
+options_1.option_description_color = "blue"
+options_1.option_number_color = "yellow"
+options_1.option_name_color = "magenta"
+options_1.navigation_option_color = "gray"
+
+options_1.add_option("A string instrument is a musical instrument that produces sound through the vibration of strings", 1, "Stringed")
+options_1.add_option("A keyboard instrument is a musical instrument played using a keyboard, a row of levers pressed by the fingers", 2, "Keyboards")
+options_1.add_option("A percussion instrument is a musical instrument that makes sound by being struck or scraped by a beater", 3, "Percussion")
+
+# create Prompt
+prompt_1 = menataur.Prompt()
+
+prompt_1.prompt_message_color = "light_magenta"
+prompt_1.prompt_message = "Select An Option From The Menu [Ex: 3]: "
+
+# create Menu
+menu_1 = menataur.Menu()
+
+menu_1.name = "main_menu"
+menu_1.main_menu = True
+
+menu_1.add_banner(banner_1)
+menu_1.add_options(options_1)
+menu_1.add_prompt(prompt_1)
+
+# [=== Test Menu 2 ===] #
+
+# create Banner
+banner_2 = menataur.Banner()
+
+banner_2.title = r"""
+ _____ _        _                      _ 
+/  ___| |      (_)                    | |
+\ `--.| |_ _ __ _ _ __   __ _  ___  __| |
+ `--. \ __| '__| | '_ \ / _` |/ _ \/ _` |
+/\__/ / |_| |  | | | | | (_| |  __/ (_| |
+\____/ \__|_|  |_|_| |_|\__, |\___|\__,_|
+                         __/ |           
+                        |___/            """
+banner_2.title_colors = ["cyan", "yellow", "green", "magenta"]
+banner_2.title_bar = "_________________________________________________/"
+banner_2.title_bar_color = "blue"
+banner_2.program_name = "Stringed"
+banner_2.program_name_color = "blue"
+banner_2.program_version_number = 1.0 
+banner_2.program_version_number_color = "yellow"
+banner_2.operating_system_support_message = "This Program Supports Linux, MacOS, and Windows"
+banner_2.operating_system_support_message_color = "light_green"
+
+# create Options
+options_2 = menataur.Options()
+
+options_2.option_description_color = "blue"
+options_2.option_number_color = "yellow"
+options_2.option_name_color = "magenta"
+options_2.navigation_option_color = "gray"
+
+options_2.add_option("An string instrument played by strumming or plucking its strings", 1, "Guitar")
+options_2.add_option("A small, high-pitched string instrument usually played with a bow", 2, "Violin")
+options_2.add_option("A small, four-string instrument played by strumming or plucking", 3, "Ukulele")
+
+# create Prompt
+prompt_2 = menataur.Prompt()
+
+prompt_2.prompt_message_color = "light_magenta"
+prompt_2.prompt_message = "Select An Option From The Menu [Ex: 3]: "
+
+# create Menu
+menu_2 = menataur.Menu()
+
+menu_2.name = "stringed_menu"
+
+menu_2.add_banner(banner_2)
+menu_2.add_options(options_2)
+menu_2.add_prompt(prompt_2)
+
+menu_2.final_menu = True
+
+# [=== Test Menu 3 ===] #
+
+# create Banner
+banner_3 = menataur.Banner()
+
+banner_3.title = r"""
+ _   __           _                         _     
+| | / /          | |                       | |    
+| |/ /  ___ _   _| |__   ___   __ _ _ __ __| |___ 
+|    \ / _ \ | | | '_ \ / _ \ / _` | '__/ _` / __|
+| |\  \  __/ |_| | |_) | (_) | (_| | | | (_| \__ \
+\_| \_/\___|\__, |_.__/ \___/ \__,_|_|  \__,_|___/
+             __/ |                                
+            |___/                                 """
+banner_3.title_colors = ["cyan", "yellow", "green", "magenta"]
+banner_3.title_bar = "_________________________________________________/"
+banner_3.title_bar_color = "blue"
+banner_3.program_name = "Keyboards"
+banner_3.program_name_color = "blue"
+banner_3.program_version_number = 1.0 
+banner_3.program_version_number_color = "yellow"
+banner_3.operating_system_support_message = "This Program Supports Linux, MacOS, and Windows"
+banner_3.operating_system_support_message_color = "light_green"
+
+# create Options
+options_3 = menataur.Options()
+
+options_3.option_description_color = "blue"
+options_3.option_number_color = "yellow"
+options_3.option_name_color = "magenta"
+options_3.navigation_option_color = "gray"
+
+options_3.add_option("A keyboard instrument that makes sound when hammers strike its strings", 1, "Piano")
+options_3.add_option("A keyboard instrument that produces sound by sending air through pipes or electronic tone generators", 2, "Organ")
+options_3.add_option("A keyboard instrument that produces a delicate, bell-like sound when hammers strike metal bars", 3, "Celeste")
+
+# create Prompt
+prompt_3 = menataur.Prompt()
+
+prompt_3.prompt_message_color = "light_magenta"
+prompt_3.prompt_message = "Select An Option From The Menu [Ex: 3]: "
+
+# create Menu
+menu_3 = menataur.Menu()
+
+menu_3.name = "keyboards_menu"
+
+menu_3.add_banner(banner_3)
+menu_3.add_options(options_3)
+menu_3.add_prompt(prompt_3)
+
+menu_3.final_menu = True
+
+# [=== Test Menu 4 ===] #
+
+# create Banner
+banner_4 = menataur.Banner()
+
+banner_4.title = r"""
+______                           _             
+| ___ \                         (_)            
+| |_/ /__ _ __ ___ _   _ ___ ___ _  ___  _ __  
+|  __/ _ \ '__/ __| | | / __/ __| |/ _ \| '_ \ 
+| | |  __/ | | (__| |_| \__ \__ \ | (_) | | | |
+\_|  \___|_|  \___|\__,_|___/___/_|\___/|_| |_|"""
+banner_4.title_colors = ["cyan", "yellow", "green", "magenta"]
+banner_4.title_bar = "_________________________________________________/"
+banner_4.title_bar_color = "blue"
+banner_4.program_name = "Percussion"
+banner_4.program_name_color = "blue"
+banner_4.program_version_number = 1.0 
+banner_4.program_version_number_color = "yellow"
+banner_4.operating_system_support_message = "This Program Supports Linux, MacOS, and Windows"
+banner_4.operating_system_support_message_color = "light_green"
+
+# create Options
+options_4 = menataur.Options()
+
+options_4.option_description_color = "blue"
+options_4.option_number_color = "yellow"
+options_4.option_name_color = "magenta"
+options_4.navigation_option_color = "gray"
+
+options_4.add_option("A large drum that produces a deep, low sound when struck", 1, "Bass Drum")
+options_4.add_option("A metal percussion instrument that makes a bright crash or ringing sound when struck", 2, "Cymbal")
+options_4.add_option("Tall, single-headed hand drums played with the hands, often in pairs", 3, "Congas")
+
+# create Prompt
+prompt_4 = menataur.Prompt()
+
+prompt_4.prompt_message_color = "light_magenta"
+prompt_4.prompt_message = "Select An Option From The Menu [Ex: 3]: "
+
+# create Menu
+menu_4 = menataur.Menu()
+
+menu_4.name = "percussion_menu"
+
+menu_4.add_banner(banner_4)
+menu_4.add_options(options_4)
+menu_4.add_prompt(prompt_4)
+
+menu_4.final_menu = True
+
+# [=== Datamapping === ] #
+
+main_menu_datamap = {
+    1: menu_2,
+    2: menu_3,
+    3: menu_4
+}
+
+menu_1.datamap = main_menu_datamap
+
+# [=== Menataur (menu interface) ===] #
+
+# create a Menataur (menu interface)
+menu_interface = menataur.Menataur()
+
+# specify the start Menu
+menu_interface.start_menu = menu_1
+
+# run the Menataur (menu interface)
+user_choices = menu_interface.run()
+```

menataur-0.1.0/menataur.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: menataur
+Version: 0.1.0
+Summary: ...
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Dynamic: license-file

menataur-0.1.0/menataur.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+menataur.py
+pyproject.toml
+menataur.egg-info/PKG-INFO
+menataur.egg-info/SOURCES.txt
+menataur.egg-info/dependency_links.txt
+menataur.egg-info/requires.txt
+menataur.egg-info/top_level.txt

menataur-0.1.0/menataur.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

menataur-0.1.0/menataur.egg-info/requires.txt

@@ -0,0 +1 @@
+colorama>=0.4.6

menataur-0.1.0/menataur.egg-info/top_level.txt

@@ -0,0 +1 @@
+menataur

menataur-0.1.0/menataur.py

@@ -0,0 +1,683 @@
+r"""
+# :: Author Information and Program Details :: #
+
+File Name: menataur.py
+Author(s): Gratonic (https://github.com/Gratonic) and FailurePoint (https://github.com/FailurePoint)
+Language: Python 3.13.5
+Dependencie(s): colorama
+Last Modified: Septemeber 26, 2026
+
+# :: Description :: #
+
+This program was designed to make writing command-line menu interfaces easier. 
+It splits each menu into blocks represented by classes. These block classes are combined to create 
+a Menu instance, which can then be combined with other Menu instances within the Menataur class.
+The Menataur class organizes the menu components and uses a navigation algorithm to allow 
+users to move between them.
+
+note: 
+When reading the menu navigation algorithm code in this program (split between Menu and Menataur), think about a Binary Tree
+and it will begin to make a lot more sense. I believe this is the simplest way to make sb ense
+of the navigation algorithm.
+
+# :: Example Usage :: #
+
+# create the banner
+banner = Banner()
+
+banner.title = 
+___  ___                 _                   
+|  \/  |                | |                  
+| .  . | ___ _ __   __ _| |_ __ _ _   _ _ __ 
+| |\/| |/ _ \ '_ \ / _` | __/ _` | | | | '__|
+| |  | |  __/ | | | (_| | || (_| | |_| | |   
+\_|  |_/\___|_| |_|\__,_|\__\__,_|\__,_|_|   
+banner.title_colors = ["cyan", "yellow", "green", "magenta"]
+banner.title_bar = "_________________________________________________/"
+banner.title_bar_color = "blue"
+banner.program_name = "Menataur"
+banner.program_name_color = "blue"
+banner.program_version_number = 1.0 
+banner.program_version_number_color = "yellow"
+banner.operating_system_support_message = "This Program Supports Linux, MacOS, and Windows"
+banner.operating_system_support_message_color = "light_green"
+
+# create the options
+options = Options()
+
+options.option_description_color = "white"
+options.option_number_color = "light_yellow"
+options.option_name_color = "cyan"
+options.navigation_option_color = "light_red"
+
+options.add_option("View Profile", 1, "Profile")
+options.add_option("Settings", 2, "Settings")
+options.add_option("Help", 3, "Help")
+
+# create the prompt
+prompt = Prompt()
+
+prompt.prompt_message_color = "light_magenta"
+prompt.prompt_message = "Select an option: "
+
+# create and run the menu
+menu = Menu()
+
+menu.name = "main"
+menu.main_menu = True
+
+menu.add_banner(banner)
+menu.add_options(options)
+menu.add_prompt(prompt)
+
+menu.run()
+
+# you can only simply display it (excludes the input prompt)
+menu.display()
+"""
+
+# [=== Imports ===] #
+
+from colorama import Fore, Back
+from functools import partial
+import subprocess
+import random
+import sys
+
+# [=== Global Variables ===]
+
+# used to ensure the user does not give two or more Menu's the same name
+_used_menu_name: list[str] = list()
+
+# [=== Functions ===] #
+
+def clear_terminal():
+    # for Linux, MacOS, and Unix-Like operating systems
+    if sys.platform in ("linux", "darwin"):
+        subprocess.run("clear", shell=True)
+    else:
+        # for Windows and other obsolete operating systems
+        subprocess.run("cls", shell=True)
+
+def validate_foreground_color(fore_color: str) -> str:
+    foreground_colors = {
+        "blue": Fore.BLUE, "light_blue": Fore.LIGHTBLUE_EX, 
+        "cyan": Fore.CYAN, "light_cyan": Fore.LIGHTCYAN_EX,
+        "red": Fore.RED, "light_red": Fore.LIGHTRED_EX,
+        "green": Fore.GREEN, "light_green": Fore.LIGHTGREEN_EX, 
+        "yellow": Fore.YELLOW, "light_yellow": Fore.LIGHTYELLOW_EX,
+        "magenta": Fore.MAGENTA, "light_magenta": Fore.LIGHTMAGENTA_EX,
+        "black": Fore.BLACK, "white": Fore.WHITE, 
+        "gray": Fore.LIGHTBLACK_EX, "grey": Fore.LIGHTBLACK_EX
+    }
+
+    color = fore_color.lower()
+    if color in foreground_colors:
+        return foreground_colors[color]
+    else:
+        print(f"{Fore.RED}[!] Error: {Fore.YELLOW}{color}{Fore.RED} is not a valid/supported color in this program.{Fore.RESET}")
+        print(f"{Fore.GREEN}The following colors are supported:{Fore.RESET}")
+        for color_key in foreground_colors.keys():
+            if color_key != "gray" or color_key != "grey":
+                print(f"{Fore.BLUE}{color_key}{Fore.RESET}")
+            else:
+                print(f"{Fore.BLUE}gray/grey{Fore.RESET}")
+
+        exit(1)
+
+# note: although this function is currently not in use it may be later
+def validate_background_color(back_color: str) -> str:
+    background_colors = {
+        "blue": Back.BLUE, "light_blue": Back.LIGHTBLUE_EX, 
+        "cyan": Back.CYAN, "light_cyan": Back.LIGHTCYAN_EX,
+        "red": Back.RED, "light_red": Back.LIGHTRED_EX,
+        "green": Back.GREEN, "light_green": Back.LIGHTGREEN_EX, 
+        "yellow": Back.YELLOW, "light_yellow": Back.LIGHTYELLOW_EX,
+        "magenta": Back.MAGENTA, "light_magenta": Back.LIGHTMAGENTA_EX,
+        "black": Back.BLACK, "white": Back.WHITE, 
+        "gray": Back.LIGHTBLACK_EX, "grey": Back.LIGHTBLACK_EX
+    }
+
+    color = back_color.lower()
+    if color in background_colors:
+        return background_colors[color]
+    else:
+        print(f"{Fore.RED}[!] Error: {Fore.YELLOW}{color}{Fore.RED} is not a valid/supported color in this program.{Fore.RESET}")
+        print(f"{Fore.GREEN}The following colors are supported:{Fore.RESET}")
+        for color_key in background_colors.keys():
+            if color_key != "gray" or color_key != "grey":
+                print(f"{Fore.BLUE}{color_key}{Fore.RESET}")
+            else:
+                print(f"{Fore.BLUE}gray/grey{Fore.RESET}")
+
+        exit(1)
+
+"""
+note: 
+the reason for the complex approach in this function is to avoid large amounts of color repeats, 
+which was a major issue with a previous one-liner approach
+"""
+def paint_text(text: str, colors: list) -> str:
+    # avoids waisting compute time with an algorithm if there is only one color provided
+    if len(colors) == 1:
+        return f"{validate_foreground_color(colors[0])}{text}{Fore.RESET}"
+
+    # validates the colors and retrieves their actual color values
+    colors = [validate_foreground_color(fore_color=color) for color in colors]
+    # creates a list of every character in the given text
+    characters = list(text)
+    # keeps track of the colors list index numbers that can temporarily not be used
+    banned_indexes = set()
+
+    # len(colors) %2 == 0: even, else: odd 
+    if len(colors) % 2 == 0:
+        # needed colors list index(s)
+        middle_index = len(colors) // 2
+
+        # note: used to determine the random index number
+        low = middle_index
+        high = middle_index
+
+        for char in range(len(text)):
+            # avoids waisting compute time on non-printable characters (with the needed exceptions)
+            if characters[char] == " ":
+                continue
+            elif characters[char].isprintable() == True or characters[char] == "\\" or characters[char] == "\'" or characters[char] == '\"':
+                pass
+            else:
+                continue
+
+            # note: loops until a valid index number has been selected
+            while True:
+                selected_index = random.randint(low, high)
+
+                if selected_index not in banned_indexes:
+                    break
+
+            # add the color code for the current character
+            characters[char] = colors[selected_index] + characters[char]
+
+            if low != 0 and high != len(colors) - 1:
+                # ban the current low and high indexes temporarily
+                banned_indexes.add(low)
+                banned_indexes.add(high)
+
+                # fetch the new low and high indexes; note: center -> ends
+                low -= 1
+                high += 1
+            else:
+                # reset the low and high indexes values along with the banned_indexes set
+                low = middle_index
+                high = middle_index
+
+                banned_indexes = set()
+
+        # create the new text string
+        text = "".join(characters)
+
+        return f"{text}{Fore.RESET}"
+    else:
+        # needed colors list index(s)
+        middle_index = ((len(colors) - 1) // 2) + 1
+
+        # note: used to determine the random index number
+        low = 0
+        high = len(colors) - 1
+
+        for char in range(len(text)):
+            # avoids waisting compute time on non-printable characters (with the needed exceptions)
+            if characters[char] == " ":
+                continue
+            elif characters[char].isprintable() == True or characters[char] == "\\" or characters[char] == "\'" or characters[char] == '\"':
+                pass
+            else:
+                continue
+
+            # note: loops until a valid index number has been selected
+            while True:
+                selected_index = random.randint(low, high)
+
+                if selected_index not in banned_indexes:
+                    break
+
+            # add the color code for the current character
+            characters[char] = colors[selected_index] + characters[char]
+
+            if low == middle_index or high == middle_index:
+                # reset the low and high indexes values along with the banned_indexes set
+                low = 0
+                high = len(colors) - 1
+
+                banned_indexes = set()
+            else:
+                # ban the current low and high indexes temporarily
+                banned_indexes.add(low)
+                banned_indexes.add(high)
+
+                # fetch the new low and high indexes; note: ends -> center
+                low += 1
+                high -= 1
+
+        # create the new text string
+        text = "".join(characters)
+
+        return f"{text}{Fore.RESET}"
+
+def input_prompt(prompt_message) -> str:
+    try:
+        user_choice = input(prompt_message)
+
+        return user_choice
+    except KeyboardInterrupt:
+        print("\n")
+        exit(0)
+
+# [=== Classes ===] #
+
+class Banner:
+    def __init__(self):
+        # elements
+        self.title = str()
+        self.title_bar = str()
+        self.program_name = str()
+        self.program_version_number = float()
+        self.title_bar = str()
+        self.operating_system_support_message = "This Program Supports: Linux, MacOS, and Windows"
+
+        # element colors
+        self._title_colors: list[str] = list()
+        self._title_bar_color = str()
+        self._program_name_color = str()
+        self._program_version_number_color = str()
+        self._operating_system_support_message_color = str()
+
+    # --- getter/setter properties --- #
+
+    @property
+    def title_colors(self):
+        return self._title_colors
+    
+    @title_colors.setter
+    def title_colors(self, colors: list):
+        # note: the paint function will handle the color validation for the colors list
+        self._title_colors = colors
+
+    @property
+    def title_bar_color(self):
+        return self._title_bar_color
+
+    @title_bar_color.setter
+    def title_bar_color(self, color: str):
+        self._title_bar_color = validate_foreground_color(color)
+
+    @property
+    def program_name_color(self):
+        return self._program_name_color
+
+    @program_name_color.setter
+    def program_name_color(self, color: str):
+        self._program_name_color = validate_foreground_color(color)
+
+    @property
+    def program_version_number_color(self):
+        return self._program_version_number_color
+
+    @program_version_number_color.setter
+    def program_version_number_color(self, color: str):
+        self._program_version_number_color = validate_foreground_color(color)
+
+    @property
+    def operating_system_support_message_color(self):
+        return self._operating_system_support_message_color
+
+    @operating_system_support_message_color.setter
+    def operating_system_support_message_color(self, color: str):
+        self._operating_system_support_message_color = validate_foreground_color(color)
+
+class Options:
+    def __init__(self):
+        # elements #
+        self.options: dict[int, str] = dict()
+
+        # element colors
+        self._option_description_color = str()
+        self._option_number_color = str()
+        self._option_name_color = str()
+
+        self._navigation_option_color = Fore.LIGHTBLACK_EX
+
+    # --- getter/setter properties --- #
+
+    @property
+    def option_description_color(self):
+        return self._option_description_color
+
+    @option_description_color.setter
+    def option_description_color(self, color: str):
+        self._option_description_color = validate_foreground_color(color)
+
+    @property
+    def option_number_color(self):
+        return self._option_number_color
+
+    @option_number_color.setter
+    def option_number_color(self, color: str):
+        self._option_number_color = validate_foreground_color(color)
+
+    @property
+    def option_name_color(self):
+        return self._option_name_color
+
+    @option_name_color.setter
+    def option_name_color(self, color: str):
+        self._option_name_color = validate_foreground_color(color)
+
+    @property
+    def navigation_option_color(self):
+        return self._navigation_option_color
+
+    @navigation_option_color.setter
+    def navigation_option_color(self, color: str):
+        self._navigation_option_color = validate_foreground_color(color)
+
+    # --- methods ---  #
+
+    def add_option(self, option_description: str, option_number: int, option_name: str) -> None:
+        # validation
+        if option_number == 0:
+            print(f"{Fore.RED}[!] Error: The {Fore.YELLOW}option_number 0{Fore.RED} is reserved for the exit option (automatically included).{Fore.RESET}")
+            sys.exit(1)
+
+        if option_number < 0:
+            print(f"{Fore.RED}[!] Error: The chosen {Fore.YELLOW}option_number{Fore.RED} can not be negative.")
+        
+        if option_number in self.options.keys():
+            print(f"{Fore.RED}[!] Error: The {Fore.YELLOW}option_number {option_number}{Fore.RED} is already in use.{Fore.RESET}")
+
+        # construct and add the option to the options dictionary; note: color reset is handled when the element is added to a Menu
+        option = f"{self._option_description_color}{option_description}\n{self.option_number_color}{option_number}) {self._option_name_color}{option_name}"
+        
+        self.options[option_number] = option
+
+class Prompt:
+    def __int__(self):
+        # element(s)
+        self.prompt_message = "Choose An Option From The Menu [ex: 0]: "
+
+        # element color(s)
+        self._prompt_message_color = str()
+
+        # used to determine wether or not the user decided to color the prompt message using the module
+        # note: they may have chosen not to because they wanted to use multiple colors, so instead they added the color codes themself
+        self.prompt_colored = False
+
+    # --- getter/setter properties --- #
+
+    @property
+    def prompt_message_color(self):
+        return self._prompt_message_color
+
+    @prompt_message_color.setter
+    def prompt_message_color(self, color: str):
+        self._prompt_message_color = validate_foreground_color(color)
+
+        self.prompt_colored = True
+
+class Menu:
+    def __init__(self):
+        # note: these strings are formated to construct menu elements (in the technical sense they are the elements)
+        self._menu = str()
+        self._banner = "{title}\n{title_bar_color}{title_bar}\n{program_name_color}{program_name}{program_version_number_color}v{program_version_number}\n{operating_system_support_message_color}{operating_system_support_message}\n{reset}"
+        self._option = "{option}{reset}"
+
+        # this variable will a hold a callable address for the input_prompt() function loaded with its parameter already
+        self._prompt = None
+
+        # used to make it easier to sort through the final Menataur (menu interface) data
+        self._name = str()
+        # used to determine wether or not this is a/the main menu
+        self.main_menu = False
+        # used to determine wether or not this is the final menu in a menu path
+        self._final_menu = False
+        # used to store the option numbers for basic input validation in the run_menu method
+        self._option_numbers: set[int] = set()
+        # used to store the Option to Menu mappings - required if the user want's to use this Menu in a Menataur
+        self._datamap: dict[int, Menu | str] = dict()
+
+    # --- getter/setter properties --- #
+
+    @property
+    def name(self):
+        return self._name
+
+    @name.setter
+    def name(self, menu_name: str):
+        if menu_name in _used_menu_name:
+            print(f"{Fore.RED}[!] Error: Every Menu must be assigned a unique {Fore.YELLOW}name{Fore.RED}.{Fore.RESET}")
+            exit(1)
+        
+        _used_menu_name.append(menu_name)
+
+        self._name = menu_name
+
+    @property
+    def final_menu(self):
+        return self._final_menu
+
+    @final_menu.setter
+    def final_menu(self, value: bool):
+        if value == True:
+            # used to create a special data map for the final menu
+            _final_menu_datamap: dict[int, str] = dict()
+            # used to know when to stop looping; note: 1 is not subtracted for previous menu because of the way the range() function works
+            _last_option = max(self._option_numbers)
+
+            _final_menu_datamap[0] = "exit"
+
+            for opt in range(1, _last_option):
+                _final_menu_datamap[opt] = "final_menu"
+
+            _final_menu_datamap[_last_option] = "previous_menu"
+
+            self._datamap = _final_menu_datamap
+        
+        # set the _final_menu tracker variable to the user given bool (True or False)
+        self._final_menu = value
+
+    @property
+    def datamap(self):
+        return self._datamap
+
+    @datamap.setter
+    def datamap(self, map: dict):
+        # add the exit and previous menu (if applicable) options 
+        map[0] = "exit"
+
+        # ensure this is not a final menu because final Menus do not need a user configured datamap
+        if self.final_menu == True:
+            print(f"{Fore.RED}[!] Error: This is a {Fore.YELLOW}Final Menu{Fore.RED}, it should not have a datamap.{Fore.RESET}")
+            exit(1)
+
+        if self.main_menu != True:
+            map[max(self._option_numbers)] = "previous_menu"
+
+        self._datamap = map
+
+        # ensure the user has provided map keys that match the option numbers and store the map if so
+        if map.keys() != self._datamap.keys():
+            print(f"{Fore.RED}[!] Error: The {Fore.YELLOW}map keys{Fore.RED} do not match the {Fore.YELLOW}option numbers{Fore.RED}.{Fore.RESET}")
+            print(map.keys())
+            print(self._datamap.keys())
+            exit(1)
+
+    # --- methods ---  #
+
+    # formally adds an element to the menu
+    def _add_element(self, menu_element) -> None:
+        self._menu = self._menu + f"{menu_element}\n"
+
+    def add_banner(self, banner: Banner) -> None:
+        self._add_element(menu_element=self._banner.format(
+            title=paint_text(banner.title, banner.title_colors),
+            title_bar_color=banner.title_bar_color,
+            title_bar=banner.title_bar,
+            program_name_color=banner.program_name_color,
+            program_name=banner.program_name,
+            program_version_number_color=banner.program_version_number_color,
+            program_version_number=banner.program_version_number,
+            operating_system_support_message_color=banner.operating_system_support_message_color,
+            operating_system_support_message=banner.operating_system_support_message,
+            reset=Fore.RESET
+        ))
+
+    def add_options(self, options: Options) -> None:
+        # add the exit option
+        exit_option = f"{options.navigation_option_color}0) Exit"
+
+        self._add_element(self._option.format(
+            option=exit_option,
+            reset=Fore.RESET
+        ))
+
+        for option_key in options.options.keys():
+            self._add_element(self._option.format(
+                option=options.options[option_key],
+                reset=Fore.RESET
+            ))
+
+        # add the previous menu option if necessary
+        if self.main_menu != True:
+            previous_menu_option_number = list(options.options.keys())[-1] + 1
+            previous_menu_option = f"{options.navigation_option_color}{previous_menu_option_number}) Previous Menu"
+
+            self._add_element(self._option.format(
+                option=previous_menu_option,
+                reset=Fore.RESET
+            ))
+
+            # add the previous_menu_option with its respective option number to the options dictionary to keep a record of it
+            options.options[previous_menu_option_number] = previous_menu_option
+
+        # add the exit_option with it's respective option number to the options dictionary to keep a record of it
+        options.options[0] = exit_option
+
+        # store the option numbers to reference for basic input validation in the run_method function
+        self._option_numbers = options.options.keys()
+
+    def add_prompt(self, prompt: Prompt) -> None:
+        if prompt.prompt_colored == True:
+            prompt_message = f"{prompt.prompt_message_color}{prompt.prompt_message}{Fore.RESET}"
+        else:
+            # note: the Fore.RESET is added in case the user has forgotten to include the reset code (in the case that they manually added the color codes in their prompt_message)
+            prompt_message = f"{prompt.prompt_message}{Fore.RESET}"
+
+        # creates a callable function object with the parameter; think of it like a loaded gun ready to fire
+        self._prompt = partial(input_prompt, prompt_message)
+
+    def display(self) -> None:
+        print(self._menu)
+
+    def run(self) -> int:
+        print(self._menu)
+
+        if self.name == str():
+            print(f"{Fore.RED}[!] Error: Every Menu must be assigned a unique{Fore.YELLOW}name{Fore.RED}.")
+            exit(1)
+
+        while True:
+            user_choice = self._prompt()
+
+            try:
+                user_choice = int(user_choice)
+
+                if user_choice == 0:
+                    exit(0)
+
+                if user_choice in self._option_numbers:
+                    clear_terminal()
+
+                    return user_choice
+                else:
+                    print(f"{Fore.RED}Invalid Option!{Fore.RESET}")
+            except ValueError:
+                print(f"{Fore.RED}Invalid Option!{Fore.RESET}")
+            except Exception as e:
+                print(f"{Fore.RED}Invalid Option!{Fore.RESET}")
+
+class Menataur:
+    def __init__(self):
+        # stores the starting position of the Menataur (menu interface)
+        self._start_menu = None
+
+    @property
+    def start_menu(self):
+        return self._start_menu
+
+    @start_menu.setter
+    def start_menu(self, menu: Menu):
+        if menu.main_menu == True:
+            self._start_menu = menu
+        else:
+            print(f"{Fore.RED}[!] Error: The {Fore.YELLOW}start_menu{Fore.RED} must be a {Fore.YELLOW}main_menu{Fore.RED}.{Fore.RESET}")
+            print(f"{Fore.BLUE}[?] Help: If you would like to use this {Fore.YELLOW}menu{Fore.BLUE} as your start_menu, set {Fore.YELLOW}main_menu=True{Fore.BLUE}.{Fore.RESET}")
+            exit(1)
+
+    def run(self) -> list[int]:
+        # keeps track of the current menu (changed at the end of each loop depending on the user choice)
+        _current_menu = self._start_menu
+        # keeps track of the previous menu (becomes _current_menu after the _current_menu runs in each loop)
+        _previous_menu = None
+
+        """
+        note: 
+        This data format was chosen because it allows for easy access to the data
+        while still maintaing the orignal order the data was added. If just was used it would make
+        it hard for the user to sort through the data and if just a dictionary was used the .keys() and 
+        .values() sets would not retain the original order in which the data was addded. 
+        """
+        _user_choices: list[dict[str, int]] = list()
+
+        if self._start_menu == None:
+            print(f"{Fore.RED}[!] Error: You must set a {Fore.YELLOW}start_menu{Fore.RED}.{Fore.RESET}")
+
+        # note: think of a Binary Tree when thiking about how the menu navigation works
+        while _current_menu != "final_menu":
+            # fetch the current Menu's name
+            _current_menu_name = _current_menu.name
+            
+            # fetch the current Menu's datamap
+            _current_menu_datamap = _current_menu.datamap
+
+            # run the current menu and store the returned option number
+            _menu_output = _current_menu.run()
+
+            # use the _menu_output to determine what to do next; note: the datamap may provide another Menu or a Menu code
+            _next = _current_menu_datamap[_menu_output]
+
+            match _next:
+                case "final_menu":
+                    clear_terminal()
+
+                    _user_choice_map = {_current_menu_name: _menu_output}
+                    _user_choices.append(_user_choice_map)
+
+                    return _user_choices
+                case "previous_menu":
+                    clear_terminal()
+
+                    # the _current_menu was already stored as the _previous_menu, so nothing needs to be done
+                    continue
+                case _:
+                    clear_terminal()
+
+                    # set the previous_menu for the _next Menu's datamap
+                    _next.datamap[max(_next.datamap.keys())] = _current_menu
+
+                    # add the user's choice to the _user_choices_map
+                    _user_choice_map = {_current_menu_name: _menu_output}
+                    _user_choices.append(_user_choice_map)
+
+                    # set the _current_menu to the _next Menu so the _next Menu is called in the next loop
+                    _current_menu = _next
+
+                    continue

menataur-0.1.0/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "menataur"
+version = "0.1.0"
+description = "..."  # Add a short description
+requires-python = ">=3.10"
+dependencies = ["colorama>=0.4.6"]
+
+[tool.setuptools]
+py-modules = ["menataur"]

menataur-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+