Metadata-Version: 2.4
Name: cobra-color
Version: 1.3.9
Summary: A Python library for enhanced terminal display.
Author-email: Zhen Tian <zhen.tian.cs@gmail.com>
Project-URL: Homepage, https://github.com/tinchen777/cobra-color.git
Project-URL: Repository, https://github.com/tinchen777/cobra-color.git
Project-URL: Issues, https://github.com/tinchen777/cobra-color.git/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: render
Requires-Dist: Pillow<11.0,>=9.0; extra == "render"
Requires-Dist: numpy<2.0,>=1.21; extra == "render"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

<div align="center">

<h2 id="title">🐱‍👤 cobra-color 🐱‍👤</h2>

[![PyPI version](https://img.shields.io/pypi/v/cobra-color.svg)](https://pypi.org/project/cobra-color/)
![Python](https://img.shields.io/pypi/pyversions/cobra-color?color=brightgreen)
[![codecov](https://codecov.io/gh/tinchen777/cobra-color/branch/main/graph/badge.svg)](https://codecov.io/gh/tinchen777/cobra-color)
![License](https://img.shields.io/github/license/tinchen777/cobra-color.svg)

[![Tests](https://github.com/tinchen777/cobra-color/actions/workflows/test.yml/badge.svg)](https://github.com/tinchen777/cobra-color/actions/workflows/test.yml)
![Github stars](https://img.shields.io/github/stars/tinchen777/cobra-color.svg)

<!-- [![Pull Requests Welcome](https://img.shields.io/badge/pull%20requests-welcome-brightgreen.svg)](https://github.com/tinchen777/cobra-color/pulls) -->

</div>

## About

A lightweight and easy-to-use Python library for enhanced terminal display: simple text color/style conventions and image-to-terminal rendering.

- Python: 3.9+

## Features

- 🚀 High compatibility with Python’s built-in `str` type.
- 🚀 Easy and intuitive creation of color strings.
- 🚀 Convert images to colored terminal output in a single step.

## Installation

### Install from PyPI

This installs the core package with minimal dependencies.

```bash
pip install cobra-color
```

### Install with Optional Dependencies

`cobra.render` module support.

```bash
pip install cobra-color[render]
```

## Quick Start

- Render a text in the terminal:

    ```python
    from cobra_color import cstr, safe_print

    c_text_1 = cstr("Hello World!", fg="r", styles=["bold"])
    # Print directly from the terminal
    print(c_text_1)

    c_text_2 = cstr("Hello World!", fg=(255, 255, 255), styles=["udl", "bold"])
    # Alternatively, you can use safe_print() to automatically support progress bar modes like tqdm and rich.
    safe_print(c_text_2)

    # Merge `c_text_1` and `c_text_2` while preserving their colors and style formatting.
    c_text_3 = c_text_1 + c_text_2

    # You can continue to use str's proprietary functions and keep the existing colors and styles.
    c_text_1.upper()
    ```

- Render an image in the terminal:

    ```python
    from cobra_color.render import imgfile_to_ansi, safe_print

    # ASCII art
    safe_print(imgfile_to_ansi("example.jpg", width=80, mode="ascii"))

    # Half-block color (recommended for truecolor terminals)
    imgfile_to_ansi("example.jpg", width=80, mode="half-color", display=True)
    ```

- Render some text with fonts in the terminal:

    ```python
    from cobra_color.draw import fonttext_to_ansi, FontName, safe_print

    # Borderless grayscale font
    safe_print(fonttext_to_ansi(
        "Hello World!",
        font=FontName.LLDISCO,
        mode="half-gray",
        trim_border=True
    ))
    ```

## Image Modes

- `ascii`: monochrome ASCII using a density charset.
- `color`: colorized character fill.
- `half-color`: half-block characters with color (higher density, good visual quality).
- `gray`: grayscale characters.
- `half-gray`: half-block grayscale.

Tip: For best results, use a TrueColor-capable terminal and a monospaced font.

## Requirements

- Python >= 3.9
- (Optional) `Pillow` >= 9.0, < 11.0
- (Optional) `NumPy` >= 1.21, < 2.0

## License

See LICENSE in the repository.

## Links

- [Homepage/Repo](https://github.com/tinchen777/cobra-color.git)
- [Issues](https://github.com/tinchen777/cobra-color.git/issues)
