LumiToolsLib 1.3.3
Python utilities for dynamic strings, sandboxed files, and ANSI colors
Requires Python: >=3.8

# **LumiToolsLib**
*A Swiss Army knife for Python scripting and automation*

[![PyPI version](https://badge.fury.io/py/LumiToolsLib.svg)](https://pypi.org/project/LumiToolsLib/)

`LumiToolsLib` is a powerful utility library for Python that simplifies file operations, text manipulation, encoding, system tasks, and more, with built-in **sandbox mode** for safe testing.

---

## **Features**
* **File Operations** – Read, write, copy, grep, and manage files (with sandbox support).

* **Dynamic Strings** – `S()` and `M()` for runtime string interpolation.

* **Encoding/Decoding** – Secure `encode()`/`decode()` with shadow keys.

* **System Utilities** – Cross-platform notifications, clipboard access, and public IP fetching.

* **ANSI Styling** – RGB colors and text formatting for terminals.

* **Sandbox Mode** – Virtual filesystem for testing without touching real files.

* **Smart Functions** – Fuzzy matching, random generators, UUIDs, and more.

* **Temporary Values** - Allows for variables that expire after some time or uses.

---

## **Quick Start**

### **1. File Operations (Sandbox Supported)**
```python
from LumiToolsLib import *

# Write to a sandboxed file (doesn't touch disk)
debug.sandbox(True)  # Enable sandbox mode
rw_file("test.txt", "Hello, sandbox!")
print(file_exists("test.txt"))  # True (in sandbox)

# Real filesystem operations
debug.sandbox(False)
rw_file("real_file.txt", "This writes to disk.")
```

### **2. Dynamic Strings (`S` and `M` Classes)**
```python
user = "Alice"
id_num = 42

# S() updates dynamically
greeting = S("User {user} (ID: {id_num}) logged in at {timestamp()}")
m_greeting = M("User {user} (ID: [id_num]) logged in at {timestamp()}")
print(greeting)  # "User Alice (ID: 42) logged in at ..."
print(m_greeting)  # "User Alice (ID: 42) logged in at ..."

user = "Bob"
id_num = 31

print(greeting)  # Automatically updates to "User Bob (ID: 31)..."
print(m_greeting)  # Updates to "User Bob (ID: 42)..."
```

### **3. Encoding & Security**
```python
encoded = encode("Secret Message")
decoded = decode(encoded)
print(decoded.decode())
```

### **4. System Utilities**
```python
notify("Task Done", "Script completed successfully!")  # OS notification
clipboard_copy("Copy this to clipboard")
print(censor(get_public_ip(),'-'))  # "192.---.-.1" (censored)
```

### **5. Run the Full Demo**
```python
tech_demo()  # Showcases all features
```

## **API Highlights**

| Function | Description |
|----------|-------------|
| `rw_file()` | Read/write files (sandbox-aware). |
| `S("text {var}")` | Dynamic string (updates on variable changes). |
| `encode(data)` / `decode(data)` | Secure encoding with shadow keys. |
| `notify()` | Cross-platform system notifications. |
| `file_grep()` | Search files using regex. |
| `ansi()` | RGB terminal styling. |
| `debug.sandbox()` | Toggle sandbox mode. |
| `Temporary(content, delay, expiry, uses, permanent)` | Makes a variable that expires after a certain amount of time (if time is not 0), or after enough uses. |

## **DEBUG Features**
```debug.sandbox(True/False)  # Sets if you want to use sandbox or not.
debug.death(True/False)    # Enables/disables debug.death(), which raises an error on call. Good for testing error handling.
debug.status()             # Prints current sandbox and death state.
debug.peek_vars(dictionary, KeysToInspect=None) # Returns values from the dictionary. If KeysToInspect is not provided, returns all keys+values.
debug.safe_eval(expression, globals_=None, locals_=None) # Attempts to evaluate an expression safely with error-catching. Pass in globals()/locals() for scope control.
debug.trace(msg="Trace", pause=False, lines=2) # Prints a mini traceback (stack trace) up to `lines` frames, with a header. pause=True will halt execution until Enter is pressed.
debug.pause(msg="\nPaused. Press enter to continue code.") # Simple pause that waits for user input. Customize the message if you'd like.
debug.watch(var_name, scope, prefix="[WATCH]") # Prints the value of a variable from a provided `scope` (e.g., locals() or globals()). Helpful for real-time debug output.
```

## **Why Use ltools?**
- **Saves Time** – No reinventing the wheel for common tasks.
- **Safe Testing** – Sandbox mode prevents accidental file changes.
- **Cross-Platform** – Works on Windows, macOS, and Linux.
- **Batteries Included** – From clipboard ops to quantum random numbers.