Metadata-Version: 2.1
Name: Coquille
Version: 0.1.4
Summary: Coquille is a library that wraps terminal escape sequences as convenient functions.
Author: Qexat
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: coverage ; extra == 'dev'

# Coquille

Coquille (IPA: `/kɔ.kij/`, english: 'shell' or 'typo') is a library that wraps terminal escape sequences to easily apply them to a stream.

## Notes

Requires Python 3.9 or higher.

This library attempts to cover as many escape sequences as possible ; but it is not an exhaustive list, some might be missing. Also, you might find that few have no effect on your terminal emulator.

This library is based on the following resources:

- The Wikipedia page: <https://en.m.wikipedia.org/wiki/ANSI_escape_code>
- Some Microsoft documentation about console virtual terminal sequences: <https://learn.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences>

## Install

### Normal installation

```sh
pip install coquille
```

### Dev installation

```sh
pip install coquille[dev]
```

This allows you to run the tests:

```sh
coverage run -m pytest
```

Then check the coverage:

```sh
coverage report -m
```

## Examples

Even though the examples are mostly showcasing [SGR escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) (because they are pretty visible), Coquille can do more! See the [documentation](#documentation).

### Coquille context manager

```py
from coquille import Coquille
from coquille.sequences import bold, fg_magenta, italic

print("Hello World!")

# By default, the coquille wraps the standard output
with Coquille.new(fg_magenta, italic) as coquille:
    print("Hello World, but in magenta and italic!")
    coquille.apply(bold)
    print("Now, with a touch of bold :D")

print("Oh, we are back to normal now...")
```

![screenshot.png](https://raw.githubusercontent.com/qexat/Coquille/main/examples/coquille_context/screenshot.png)

Source code: [examples/coquille_context/](https://github.com/qexat/Coquille/blob/main/examples/coquille_context/__main__.py)

### Coquille.write()

```py
from coquille import Coquille
from coquille.sequences import bold, fg_blue, fg_magenta, italic

print("Hello World!")

Coquille.write("Hello World, but in magenta and italic!", fg_magenta, italic)

with open("examples/coquille_write/output.txt", "w") as my_file:
    Coquille.write("A pretty Hello World in a file!", fg_blue, bold, file=my_file)

```

![screenshot.png](https://raw.githubusercontent.com/qexat/Coquille/main/examples/coquille_write/screenshot.png)

Source code: [examples/coquille_write/](https://github.com/qexat/Coquille/blob/main/examples/coquille_write/__main__.py)

## Documentation

Coming soon! 🚧
