Metadata-Version: 2.1
Name: pytput
Version: 0.3.0
Summary: Python3 API to format messages using colors and styles
Home-page: https://github.com/essembeh/pytput
Author: Sébastien MB
Author-email: seb@essembeh.org
License: Mozilla Public License Version 2.0
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
Requires-Dist: dataclasses ; python_version < "3.7"


![Github](https://img.shields.io/github/tag/essembeh/pytput.svg)
![PyPi](https://img.shields.io/pypi/v/pytput.svg)
![Python](https://img.shields.io/pypi/pyversions/pytput.svg)



# PyTput

> TL;DR: You can format your message with `{message:bold,underline,purple}`
> 
Simple executable and *Python3 API* to format messages using colors and styles from `tput`:
- `pytput` executable to be used in any *shell-like* script
- *Python3* module to format messages directly in any python application

![help](images/help.png)


# Install

Install via `pip`:

```sh
# Install pip for python3
$ sudo apt install python3 python3-pip python3-setuptools
# Install from PyPI
$ pip3 install --user pytput
# ... Or directly from the sources
$ pip3 install --user git+https://github.com/essembeh/pytput
```

To setup a development environment:

```sh
$ git clone https://github.com/essembeh/pytput
$ cd pytput
$ make venv
$ source venv/bin/activate
(venv) $ pip install -e .
```

# Usage

## Using *strcolor* instead of *str*

`strcolor` is a subclass of builtin `str` class to overide the default `str.format` method to use `TputFormatter`

```python
from pytput import strcolor
# Create a strcolor like a string 
a = strcolor("Hello")
# You can print it
print(a)
# You can append text
a += " {who:red,bold}"
print(a)
# When formatting, styles are applied
print(a.format(who="World"))
# And you can also use *constant* like {'today':bold} will be the string "today" with bold style applied
a += ", how are you {'today':green,underline}"
print(a.format(who="User"))
```
![strcolor](images/strcolor.png)

> Styles can be combined with `','` like `{message:underline,bold,yellow}`

> You can also reuse `string.Formatter` format specification like `{myint:05d,underline,bold,yellow}` or `{mystr:.10,underline,dim,red}`

> You can apply a style to constant strings with `{'today':bold}` or `{"today":bold}`

## Using a *TputFormatter* class

You can use the `TputFormatter` class to decorate variables with *styles*.

```python
from pytput import TputFormatter
tf = TputFormatter()
# Build a colored string and print it
print(tf.format("{'Hello':bg_yellow,bold} {who:cyan,underline}!", who="World"))
# You can combine multiple styles and common str.format spec
print(tf.format("{'Hello':.2,bg_yellow,underline} {myvalue:04d,cyan}!", myvalue=42))
```

![TputFormatter](images/formatter.png)

Here is the list of available styles

| Formatter keyword | tput command   |
| ----------------- | -------------- |
| *bold*            | `tput bold`    |
| *dim*             | `tput dim`     |
| *underline*       | `tput smul`    |
| *blink*           | `tput blink`   |
| *standout*        | `tput smso`    |
| *reverse*         | `tput rev`     |
| *reset*           | `tput sgr0`    |
| *black*           | `tput setaf 0` |
| *red*             | `tput setaf 1` |
| *green*           | `tput setaf 2` |
| *yellow*          | `tput setaf 3` |
| *blue*            | `tput setaf 4` |
| *purple*          | `tput setaf 5` |
| *cyan*            | `tput setaf 6` |
| *white*           | `tput setaf 7` |
| *bg_black*        | `tput setab 0` |
| *bg_red*          | `tput setab 1` |
| *bg_green*        | `tput setab 2` |
| *bg_yellow*       | `tput setab 3` |
| *bg_blue*         | `tput setab 4` |
| *bg_purple*       | `tput setab 5` |
| *bg_cyan*         | `tput setab 6` |
| *bg_white*        | `tput setab 7` |


## Directly use *Style*


```python
from pytput import Style
print(Style.RED.apply("Hello"), Style.GREEN.apply("World"))
```
![Style](images/style.png)


## Using *pytput* executable

*PyTput* comes with an handy executable to use colors and styles directly from the command line. This is usefull to customize messages in shell scripts for example.

```sh
$ pytput '{"Hello":red} {0:green}!' 'World'
$ pytput "{'This is':bold,red} {0:underline,dim,yellow} {1:bg_purple,yellow,bold}" "a message" "with styles ;)"
$ pytput "{0:red,bold,underline}" "Simple error message"
$ pytput "{'Another message':bg_purple,white,bold}"
```

![CLI](images/cli.png)

> See `pytput --help` for more details.

## Disabling *pytput*

By default, *pytput API* is disabled if `sys.stdout.isatty()` is `False`, so you won't write any color nor style if you pipe the output or redirect it in a file.

Using `pytput` executable, you can force colors and styles using the `--force` argument.

```sh
# You get colors by default
$ pytput '{0:red} {"World":green}!' 'Hello'
# Colors will be disabled
$ pytput '{0:red} {"World":green}!' 'Hello' | cat 
$ pytput '{0:red} {"World":green}!' 'Hello' > /tmp/pytput.txt
$ cat /tmp/pytput.txt
# Colors will be enabled
$ pytput --force '{0:red} {"World":green}!' 'Hello' | cat 
$ pytput --force '{0:red} {"World":green}!' 'Hello' > /tmp/pytput.txt
$ cat /tmp/pytput.txt
```

![force](images/force.png)

Using *pytput python3 API*, you can force styles and colors even if `sys.stdout` is not a TTY using `TputFormatter`:
```python
from pytput import TputFormatter, strcolor

# These lines won't have colors if you redirect stdout to a file
print(TputFormatter().format("{0:red} {'World':green}!", "Hello"))
print(strcolor("{0:red} {'World':green}!").format("Hello"))

# These line will have colors even if stdout is redirected 
print(TputFormatter(check_tty=False).format("{0:red} {'World':green}!", "Hello"))
print(strcolor("{0:red} {'World':green}!").format("Hello", check_tty=False))
```

You can totally disable `pytput` by setting `PYTPUT_DISABLE` variable in environment.
```sh
# Colors will be enabled
$ pytput '{0:red} {"World":green}!' 'Hello'
# Colors will be disabled
$ PYTPUT_DISABLE=1 pytput '{0:red} {"World":green}!' 'Hello'
```
![env](images/env.png)

> Note: When using *pytput API* (`strcolor`, `TputFormatter` ...), setting the environment variable `PYTPUT_DISABLE=1` will also disable all colors and styles.

