# cli_tools_by_oleksa

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-orange.svg)](https://pypi.org/project/cli_tools_by_oleksa/)

Lightweight helper toolkit for building small CLI (command-line) applications in Python.

The library simplifies common CLI tasks such as:
- handling user input,
- validation and conversion,
- safe execution and retry loops,
- formatted console output.

It is ideal for educational scripts, training exercises, small utilities, and simple CLI apps where readability and robustness matter more than complex frameworks.

---

## ✨ Features

- **safe_run** — context manager for safe execution with optional debug output  
- **try_until_ok** — repeat an operation until success, catching specified exceptions  
- **valid_input** — flexible input validation (regex + custom validator + conversion)  
- **choose_from_list** — select an item from a list by number or text  
- **parse_list** — split text into a list and optionally convert elements  
- **🖨print_iterable / print_zipped_iterable** — neat console formatting of lists or zipped items  
- **safe_int / safe_float** — convert strings to numbers safely without raising exceptions  
- **Predefined regex patterns** — integers, floats, dates, usernames, emails, multi-item lists, etc.  
- **Validator factories** — range checks, list membership, numerical comparisons (>, >=, <, <=)

Zero external dependencies — just Python 3.10+.

---

## 📦 Installation
Stable:
```bash
pip install --upgrade cli_tools_by_oleksa
```
Test:
```bash
pip install --upgrade --index-url https://test.pypi.org/simple/ cli_tools_by_oleksa
```

---

## 🛠️ Usage Example
```Python
from cli_tools import (safe_run, try_until_ok, valid_input,
                       choose_from_list, print_iterable,
                       print_zipped_iterable, print_header)
from cli_tools.validators import is_in_range

with safe_run(debug=True, exit_on_error=False):
    print_header(' Some example ')
    name = valid_input("Enter your name: ", converter= lambda x: x.strip().capitalize())
    print(f"Hello, {name}!")
    age = try_until_ok(
        valid_input,
        prompt="Enter your age: ",
        validator=is_in_range(1, 100),
        converter=int,
        on_exception="Be serious :)"
    )

    options = ["A", "B", "C"]
    print_iterable(options, item_pattern='{}', join_by=' | ', start='[ ', end=' ]')
    option = choose_from_list(options, by_number=False, prompt='Choose: ')

    data = {
        'name': name,
        'age': age,
        'option': option,
    }

    print_zipped_iterable(data.items(), '| {: <10}|{: >10} |',
                          join_by='\n'+'—'*25+'\n', start='_'*25+'\n', end='\n'+'‾'*25)
```

Output:
```commandline
~~~~~~~~~~~~~~
 Some example 
~~~~~~~~~~~~~~
Enter your name:    oLeKSa
Hello, Oleksa!
Enter your age: 1000
Be serious :)
Enter your age: 19
[ A | B | C ]
Choose: D
Incorrect option!
Choose: A
_________________________
| name      |    Oleksa |
—————————————————————————
| age       |        19 |
—————————————————————————
| option    |         A |
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾

Process finished with exit code 0
```