Metadata-Version: 2.4
Name: cobra-color
Version: 0.2.1
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow<11,>=9.0
Requires-Dist: numpy<2.0,>=1.21
Dynamic: license-file

<div align="center">

<h2 id="title">cobra-color</h2>

[![Build](https://github.com/tinchen777/cobra-color/actions/workflows/tests.yml/badge.svg)](https://github.com/tinchen777/cobra-color/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/cobra-color.svg)](https://pypi.org/project/cobra-color/)
![Python Versions](https://img.shields.io/pypi/pyversions/cobra-color.svg)
![License](https://img.shields.io/github/license/tinchen777/cobra-color.svg)
[![Pull Requests Welcome](https://img.shields.io/badge/pull%20requests-welcome-brightgreen.svg)](https://github.com/tinchen777/cobra-color/pulls)
![Github stars](https://img.shields.io/github/stars/tinchen777/cobra-color.svg)

</div>

## About

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

- Python: 3.9+
- Runtime deps: Pillow (>=9,<11), NumPy (>=1.21,<2)

## Features

- :rocket: Concise color/style names for terminal text.
- :rocket: Image rendering in multiple modes: ASCII, color, half-color, gray, half-gray.
- :rocket: Minimal dependencies and easy integration.

## Installation

Stable (once published):

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

## Quick Start

- Render a text in the terminal:

    ```python
    from cobra_color import ctext

    print(ctext("Hello World!", fg="r", styles=["bold"]))
    ```

- Render an image in the terminal:

    ```python
    from cobra_color.draw import fmt_image

    # ASCII art
    print(fmt_image("example.jpg", width=80, mode="ascii"))

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

- Render some text with fonts in the terminal:

    ```python
    from cobra_color.draw import fmt_font, FontName

    # Borderless grayscale font
    print(fmt_font("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
- Pillow >= 9.0, < 11
- 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
