Metadata-Version: 2.4
Name: Ter-FX
Version: 1.1.0
Summary: A modern Python terminal utility library with text effects, loading animations, spinners, progress bars, and interactive input.
Author-email: Faizan-ur-Rahim <terfx.dev@gmail.com>
License-Expression: MIT
Keywords: terminal,cli,console,python,effects,loading,spinner,progress
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Dynamic: license-file

# ✨ Ter-FX 2.0.0

> **Build beautiful terminal applications with ease.**

Ter-FX is a lightweight, beginner-friendly Python package for building modern terminal applications. Whether you're creating shell emulators, installers, command-line tools, automation scripts, or games, Ter-FX provides colorful output, logging, terminal effects, system utilities, and command decorators to make development simple.

---

# Features

- 🎨 ANSI color support
- 🖨️ Colored terminal printing
- ⌨️ Interactive input
- 🔢 Number input validation
- 🔒 Hidden password input
- 📍 Centered text
- ⌛ Typewriter effect
- 🌀 Animated spinners
- 📊 Progress bars
- ⏳ Loading screens
- 📝 Logging utilities
- 💻 Built-in system utilities
- 🧩 Command decorator
- ⚡ Lightweight
- 🐍 Pure Python

---

# Installation

```bash
pip install ter-fx
```

---

# Quick Start

```python
from terfx import console

console.printin("Hello, World!", "green")
```

Output

```text
Hello, World!
```

---

# Importing

Import everything:

```python
from terfx import *
```

Or import only what you need:

```python
from terfx import console, log, sys, cmd
```

---

# Console

## Print Text

```python
console.printin("Hello!", "green")
```

---

## Typewriter Effect

```python
console.printout(
    "Welcome to Ter-FX!",
    "cyan",
    speed=0.03
)
```

---

## User Input

```python
name = console.input(
    "Enter your name: ",
    "yellow"
)
```

---

## Number Input

```python
age = console.numinput(
    "Enter your age: "
)
```

Supports both integers and decimal numbers.

---

## Password Input

```python
password = console.passinput(
    "Password: "
)
```

---

## Center Text

```python
console.printcenter(
    "Welcome!",
    "magenta"
)
```

---

# Effects

## Spinner

```python
console.spinner(
    "Loading",
    3,
    "cyan"
)
```

---

## Loading Screen

```python
console.loadscr(
    "Installing",
    5,
    "green"
)
```

---

## Progress Bar

```python
for i in range(101):
    console.progress(i, 100)
```

---

# Log

## Info

```python
log.info("Connecting...")
```

---

## Success

```python
log.success("Connected!")
```

---

## Warning

```python
log.warning("Low memory!")
```

---

## Error

```python
log.error("Connection failed!")
```

---

## Debug

```python
log.debug("Variable x = 42")
```

---

# Sys

The new **sys** module provides simple wrappers around common operating system tasks.

## Run Commands

```python
sys.cmd("ipconfig")
```

Capture command output:

```python
output = sys.cmd(
    "ipconfig",
    capture=True
)

print(output)
```

---

## Clear Terminal

```python
sys.clear()
```

---

## Current Directory

```python
print(sys.cwd())
```

---

## Change Directory

```python
sys.chdir("Documents")
```

---

## List Files

```python
print(sys.listdir())
```

---

## Check if a File Exists

```python
if sys.exists("hello.txt"):
    log.success("File found!")
```

---

## Create a Folder

```python
sys.mkdir("Projects")
```

---

## Rename

```python
sys.rename(
    "old.txt",
    "new.txt"
)
```

---

## Copy

```python
sys.copy(
    "main.py",
    "backup.py"
)
```

---

## Move

```python
sys.move(
    "backup.py",
    "Archive/"
)
```

---

# Command Decorator

Ter-FX includes the `@cmd` decorator for creating clean command handlers.

```python
from terfx import cmd

@cmd
def hello(parts):
    print(parts[0])
    print(parts[1])
    print(parts.rest)

hello(["hello", "world"])
```

Output

```text
hello
world
['world']
```

The decorator automatically converts the argument list into a `Part` object.

`Part` provides:

| Property | Description |
|----------|-------------|
| `parts[0]` | First argument |
| `parts[1]` | Second argument |
| `parts.count` | Number of arguments |
| `parts.rest` | Remaining arguments |
| `len(parts)` | Number of arguments |

Example:

```python
@cmd
def install(parts):

    if parts.count < 2:
        log.error("No package supplied.")
        return

    package = parts[1]

    if package == "dir":
        log.success("Installing directory package...")
```

---

# Available Colors

```
black
red
green
yellow
blue
magenta
cyan
white
```

Example

```python
console.printin(
    "Blue Text",
    "blue"
)
```

---

# Complete Example

```python
from terfx import *

console.printcenter(
    "Ter-FX 2.0 Demo",
    "cyan"
)

name = console.input(
    "Enter your name: ",
    "green"
)

console.printout(
    f"Welcome {name}!",
    "yellow"
)

console.spinner(
    "Loading",
    2
)

for i in range(101):
    console.progress(i, 100)

sys.clear()

log.success("Finished!")
```

---

# Requirements

- Python **3.9+**
- Windows
- Linux
- macOS

---

# Roadmap

Planned features:

- Tables
- Boxes
- Menus
- Terminal UI Widgets
- RGB Colors
- Cursor Control
- Text Styling
- Better CLI Framework
- More Decorators
- File Utilities
- Networking Utilities

---

# Contributing

Contributions are welcome!

You can help by:

- Reporting bugs
- Suggesting new features
- Improving documentation
- Optimizing performance
- Creating examples

---

# License

This project is licensed under the MIT License.

---

# Author

**Faizan-ur-Rahim**

Created with ❤️ using Python.
