# ansiscape
[](https://circleci.com/gh/cariad/ansiscape/tree/main) [](https://codecov.io/gh/cariad/ansiscape) [](https://ansiscape.readthedocs.io/en/latest/?badge=latest)
`ansiscape` is a Python package and CLI tool for creating and interpreting ANSI escape codes.
- Support for **named**, **8-bit** and **24-bit colours**.
- Create formatted strings with **nested sequences** and **property reversions**.
- Convert embedded escape codes into **explanatory dictionaries**.
- Write sequences as **fully resolved strings** and **explanatory JSON**.
Full documentation is published at [ansiscape.readthedocs.io](https://ansiscape.readthedocs.io).
## Installation
`ansiscape` requires **Python 3.8 or later**.
```bash
pip install ansiscape
```
## Basic CLI usage
`ansiscape` on the command line will read from stdin and emit a JSON document describing the text and its escape codes.
For example:
```bash
ls --color | ansiscape
```
<!--dinject as=markdown host=shell range=start-->
```text
["ansiscape\nbuild.sh\ncoverage.xml\ndocs\nhtmlcov\nLICENSE\nlint.sh\nMANIFEST.in\nmkdocs.yml\nmypy.ini\nPipfile\nPipfile.lock\npyproject.toml\nREADME.md\nsetup.py\ntest-cli.sh\ntests\ntest.sh"]
```
<!--dinject range=end-->
Full documentation is published at [ansiscape.readthedocs.io](https://ansiscape.readthedocs.io).
## Basic Python usage
`ansiscape` provides a library of functions for formatting text.
For example, to make text bold:
```python
from ansiscape import heavy
print(heavy("Hello, world!"))
```
<!--dinject as=markdown host=shell range=start-->
```text
[1mHello, world.
## 👋 Hello!
**Hello!** I'm [Cariad Eccleston](https://cariad.io) and I'm an independent/freelance software engineer. If my work has value to you, please consider [sponsoring](https://github.com/sponsors/cariad/).
If you ever raise a bug, request a feature or ask a question then mention that you're a sponsor and I'll respond as a priority. Thank you!
