Metadata-Version: 2.4
Name: outputdecorator
Version: 0.1.1
Summary: Library for decorating strings in CLI apps.
Author-email: Alexander Suvorov <aixandrolab@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/aixandrolab/outputdecorator
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Output Decorator <sup>v0.1.1</sup>

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/aixandrolab/outputdecorator)](https://github.com/aixandrolab/outputdecorator/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/outputdecorator?label=pypi%20downloads)](https://pypi.org/project/outputdecorator/)
![GitHub top language](https://img.shields.io/github/languages/top/aixandrolab/outputdecorator)
[![PyPI](https://img.shields.io/pypi/v/outputdecorator)](https://pypi.org/project/outputdecorator)
[![GitHub](https://img.shields.io/github/license/aixandrolab/outputdecorator)](https://github.com/aixandrolab/outputdecorator/blob/master/LICENSE)
[![PyPI - Format](https://img.shields.io/pypi/format/outputdecorator)](https://pypi.org/project/outputdecorator)

---

## ⚠️ Disclaimer

**By using this software, you agree to the full disclaimer terms.**

**Summary:** Software provided "AS IS" without warranty. You assume all risks.

**Full legal disclaimer:** See [DISCLAIMER.md](https://github.com/aixandrolab/outputdecorator/blob/master/DISCLAIMER.md)

---

## 📌 Overview

**Output Decorator** is a lightweight Python library designed to enhance CLI application output with professional text decoration. It automatically adapts to your terminal width and provides simple methods for creating visually appealing formatted output.

---

## ✨ Features

- 🖥️ **Terminal-aware** – Automatically detects and uses your terminal width
- 🎨 **Flexible decoration** – Customize border symbols for any style
- 📝 **Frame formatting** – Create framed text blocks with different top/bottom borders
- 🔧 **Simple API** – Clean, intuitive interface with minimal learning curve
- ⚡ **Lightweight** – No external dependencies beyond Python standard library

---

## 📦 Installation

```bash
pip install outputdecorator
```

---

## 🚀 Quick Start

```python
from output_decorator import StringDecorator

# Center text with automatic terminal width
StringDecorator.string_decorate(text='Python', symbol='*', print_flag=True)
# Output: ************************************ Python ***********************************

# Get decorated string without printing
decorated = StringDecorator.string_decorate(text='Python', symbol='*', print_flag=False)
print(decorated)  # Same output as above

# Create framed text with different border styles
frame = StringDecorator.framed_decorate(
    text='Python', 
    top_symbol='*', 
    bottom_symbol='-'
)
print(frame)
"""
******
Python
------
"""
```

---

## 📚 API Reference

### `StringDecorator.string_decorate(text='', symbol='*', print_flag=True)`

Creates a centered line of text padded with the specified symbol to fill the terminal width.

**Parameters:**
- `text` (str) – The text to decorate (default: empty string)
- `symbol` (str) – Character used for padding (default: '*')
- `print_flag` (bool) – If True, prints directly; if False, returns the string (default: True)

**Returns:** `str` or `None` – Decorated string if `print_flag=False`, otherwise `None`

### `StringDecorator.framed_decorate(text='', top_symbol='-', bottom_symbol='-')`

Creates a framed text block with separate top and bottom borders.

**Parameters:**
- `text` (str) – The text to frame (default: empty string)
- `top_symbol` (str) – Character for the top border (default: '-')
- `bottom_symbol` (str) – Character for the bottom border (default: '-')

**Returns:** `str` – Formatted string with top border, text, and bottom border

### `StringDecorator.term_width()`

Returns the current terminal width in columns.

**Returns:** `int` – Terminal width

---

## 💡 Use Cases

- **CLI tools** – Create visually distinct section headers
- **Logging** – Highlight important log entries
- **Reports** – Format console output for better readability
- **Installers/Setup scripts** – Create professional-looking progress indicators
- **Development tools** – Debug output with clear visual separation

---

## 🔍 Examples

### Creating a banner
```python
StringDecorator.string_decorate(text='WELCOME', symbol='=')
# =================================== WELCOME ====================================
```

### Empty line separator
```python
StringDecorator.string_decorate(symbol='-')
# --------------------------------------------------------------------------------
```

### Different frame styles
```python
# Warning box
print(StringDecorator.framed_decorate('⚠️  WARNING  ⚠️', top_symbol='!', bottom_symbol='!'))

# Success message
print(StringDecorator.framed_decorate('✓ Success!', top_symbol='=', bottom_symbol='='))
```

---

## 🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/aixandrolab/outputdecorator/issues).

---

## 📄 License

This project is licensed under the terms specified in the repository. See the [LICENSE](https://github.com/aixandrolab/outputdecorator/blob/master/LICENSE) file for details.

---

## 📞 Support

- **Documentation**: Check this README
- **Issues**: [GitHub Issues](https://github.com/aixandrolab/outputdecorator/issues)
- **PyPI**: [Package Page](https://pypi.org/project/outputdecorator/)

---

*Made with ❤️ for the Python CLI community*
