Metadata-Version: 2.4
Name: colorprint-python
Version: 0.1.0
Summary: Simple colored terminal output for Python
Author: Misha
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# colorprint

A simple Python library for colored terminal output.

## Features

- Named colors
- HEX colors
- Short HEX colors
- `cprint()` function
- `@colored` decorator
- No external dependencies
- Python 3.10+

## Installation

Install the package from PyPI:

```bash
pip install colorprint
```

For development, clone the repository and install it in editable mode:

```bash
git clone https://github.com/your-username/colorprint.git
cd colorprint
python -m pip install -e .
```

## Usage

### Basic usage

Import `cprint`:

```python
from colorprint import cprint
```

Use a named color:

```python
cprint("Hello!", color="red")
cprint("Success!", color="green")
cprint("Warning!", color="yellow")
cprint("Information!", color="cyan")
```

You can also omit the `color` argument:

```python
cprint("Hello!")
```

## Supported colors

The following colors are available:

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

Example:

```python
cprint("Black", color="black")
cprint("Red", color="red")
cprint("Green", color="green")
cprint("Yellow", color="yellow")
cprint("Blue", color="blue")
cprint("Magenta", color="magenta")
cprint("Cyan", color="cyan")
cprint("White", color="white")
```

## HEX colors

`colorprint` supports custom HEX colors.

```python
cprint("Blue", color="#00aaff")
cprint("Purple", color="#a020f0")
cprint("Orange", color="#ff8800")
```

Short HEX notation is also supported:

```python
cprint("White", color="#fff")
cprint("Red", color="#f00")
cprint("Green", color="#0f0")
```

Both of these are equivalent:

```python
cprint("Hello", color="#fff")
cprint("Hello", color="#ffffff")
```

## Decorator

`colorprint` provides the `@colored` decorator.

Import it:

```python
from colorprint import colored
```

Use it with a function:

```python
@colored("green")
def hello():
    return "Hello, world!"

hello()
```

The decorator prints the return value using the selected color.

## Function arguments

The decorator works with functions that accept arguments:

```python
from colorprint import colored

@colored("cyan")
def add(a, b):
    return a + b

result = add(10, 20)

print(result)
```

Output:

```text
30
```

The result is still returned normally, so you can store it in a variable.

## HEX with decorator

HEX colors can also be used with the decorator:

```python
from colorprint import colored

@colored("#00aaff")
def message():
    return "Custom colored message"

message()
```

## Error handling

An unknown color raises `ValueError`:

```python
from colorprint import cprint

cprint("Hello", color="unknown")
```

Result:

```text
ValueError: Unknown color: unknown
```

An invalid HEX color also raises `ValueError`:

```python
cprint("Hello", color="#xyz")
```

## Example

A complete example:

```python
from colorprint import cprint, colored

cprint("Hello!", color="red")
cprint("Success!", color="green")
cprint("Warning!", color="yellow")
cprint("Custom color!", color="#00aaff")


@colored("cyan")
def hello():
    return "Hello from decorator!"


@colored("#a020f0")
def add(a, b):
    return a + b


hello()

result = add(10, 20)

print(f"Result: {result}")
```

## Project structure

```text
colorprint/
├── src/
│   └── colorprint/
│       ├── __init__.py
│       └── colors.py
├── tests/
│   └── colors_test.py
├── main.py
├── README.md
├── pyproject.toml
└── .gitignore
```

## Development

Create a virtual environment:

```bash
python -m venv .venv
```

Activate it on Linux/macOS:

```bash
source .venv/bin/activate
```

Install the package:

```bash
python -m pip install -e .
```

Install pytest:

```bash
python -m pip install pytest
```

Run tests:

```bash
python -m pytest
```

## Requirements

- Python 3.10 or newer
- No external runtime dependencies
