Metadata-Version: 2.4
Name: tui_utilities
Version: 1.9.6
Summary: Personal-use console utilities library
Author-email: Guido Iván Gross <grossguidoivan@gmail.com>
License: MIT License
        
        Copyright (c) 2.026 Guido Iván Gross
        
        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.
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=12.4.4
Requires-Dist: readchar>=4.0.0
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# **TUI Utilities**

Personal-use console utilities library providing styled terminal interaction, structured menus, robust input validation, formatting helpers, and Spanish-oriented user experience.

---

## **Purpose**

**This library is designed for console-based applications that need:**

- Clean TUI
- Structured Spanish-language user interaction
- Robust validation
- Consistent formatting

---

## **Requirements**

### **Dependencies**

**Standard library modules are used where possible; only external dependencies are listed:**

- rich (12.4.4 or higher)
- readchar (4.0.0 or higher)
- requests (2.25.0 or higher)

### **Python version**

Python (3.9 or higher)

### **Operating System**

**Any of the following:**

- Windows (10 or higher)
- Linux (any modern Linux distribution compatible with Python 3.9)
- MacOS (10.9 or higher)
  
### **Google Colaboratory support**

This library is fully compatible with Google Colaboratory.

---

## **Features**

### **Console Utilities (console)**

**Styled terminal interaction built on rich:**

- **print():** styled print function built on rich, supporting text styles, alignment, padding, and per-segment styling.
- **input():** styled input function built on rich, supporting text styles and automatically trimming whitespaces.
- **clear_console():** clears the terminal screen.
- **wait_for_key():** pauses execution until the user presses a key.

### **Structure Utilities (structure)**

**Tools for building structures in console applications:**

- **header():** prints a styled header, consisting of a title and a separator.
- **menu():** creates interactive selection menus with header and automatic selection validation.
- **confirmation_menu():** creates a confirmation dialog with custom message and options.
- **confirm_exit():** creates a confirmation dialog that exits the program safely (uses confirmation_menu()).
- **table():** creates personalized tables with easy introduction of fully-styled columns and rows.
- **separator():** prints a fully-personalized visual separator line.
- **error_message():** displays formatted error information including:
    - Custom message
    - Exception details
    - Full traceback

### **Input Validation (validation)**

**Interactive validation utilities for user input:**

- **check_if_list_is_empty():** checks if a list is empty and displays an error screen if it is.
- **validate_option():** validates user selection from a dictionary of options.
- **validate_string():** ensures non-empty string input.
- **validate_integer():** validates integers (uses Continental European numeric format) with optional range validation through an advanced syntax (syntax example: "(-infinity; 0] | 5 | [10; infinity)").
- **validate_double():** validates decimal numbers (uses Continental European numeric format) with support for fractions and mathematical constants ("pi", "e", "tau", "phi") and optional range validation through an advanced syntax (syntax example: "(-infinity; 0,1] | 1/3 | [pi; infinity)").
- **validate_datetime():** validates date and time input (uses Day–Month–Year date format with 24-hour time) with selectable year, time and second inclusion.
- **validate_id():** validates Argentinian national ID numbers.
- **validate_cellphone_number():** validates cellphone numbers (uses Argentinian format).
- **validate_email():** validates e-mail addresses using an official TLDs list (from IANA's website) or syntax fallback (in case of not having an internet connection or a locally imported list of TLDs).

### **Formatting Helpers (format)**

**Utilities for applying consistent formatting:**

- **decimal_format():** applies Continental European numeric formatting.
- **datetime_format():** formats datetime objects (uses Day–Month–Year date format with 24-hour time) with automatic or custom year, time and second inclusion.
- **id_format():** formats Argentinian national ID numbers.
- **cellphone_number_format():** formats cellphone numbers (uses Argentinian format).

### **System Utilities (system)**

**Helpers for interacting with the operating system console environment:**

- **set_window_title():** sets the console window title.
- **maximize_window():** maximizes the console window.
- **set_locale():** configures the process locale for number, date, and cultural formatting.
- **get_resources_path():** returns the absolute path to the resources directory, regardless of whether the program is running as a script in an IDE or as an executable.

---

## **Installation**

pip install tui_utilities

---

## **Update**

pip install -U tui_utilities
