Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/delestro/outputformat

Python library to decorate and beautify strings
https://github.com/delestro/outputformat

Last synced: 3 months ago
JSON representation

Python library to decorate and beautify strings

Awesome Lists containing this project

README

        

# outputformat
Python library to decorate and beautify your standard output ๐Ÿ’–

![ouf_image_example](https://felipedelestro.files.wordpress.com/2021/12/ouf_intro.png)

## Installation
To get the latest version, simply use pip:

``` Python
pip install outputformat
```
There are **no dependencies**.

`Python>=3.6` is needed, as it uses f strings.

## Basic usage

It is recommended to use `ouf` as shortcut for `outputformat`:

``` Python
import outputformat as ouf
```

Main functions are:
* `ouf.boxtitle`
* `ouf.linetitle`
* `ouf.bigtitle`
* `ouf.showlist`
* `ouf.bar`
* `ouf.barlist`

By default, functions `print` the result. You have the alternative to return a `string` instead, by passing the argument `return_str=True` (nothing will be printed in this case).

## Showing titles
To decorate titles with a box around it, use `ouf.boxtitle`:
```Python
ouf.boxtitle("Long title in a box")
```
```
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Long title in a box โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
```

Boxes can have different styles:
``` Python
ouf.boxtitle("Box with 'line' style", style="line")
ouf.boxtitle("Box with 'double' style", style="double")
ouf.boxtitle("Box with 'dashes' style", style="dashes")
```
```
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Box with 'line' style โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
โ•‘ Box with 'double' style โ•‘
โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
โ•ญโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•ฎ
โ”Š Box with 'dashes' style โ”Š
โ•ฐโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•Œโ•ฏ
```

Or you can pass any character and it will be used for the decoration:
``` Python
ouf.boxtitle("Box with custom character as style", style="รธ")
```
```
รธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธ
รธ Box with custom character as style รธ
รธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธรธ
```

With all the same options as for `boxtitle`, you can use `linetitle` for a simple line underneath your text:
```
ouf.linetitle("Long title with 'double' underline", style="double")
```
```
Long title with 'double' underline
โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
```

### Big title
It is possible to use ASCII art to generate big titles:
``` Python
outputstring = ouf.bigtitle("Here's a big title!")
```
```
โ–ˆ โ–ˆ โ–ˆโ–€โ–€ โ–ˆโ–€โ–ˆ โ–ˆโ–€โ–€ โ–€ โ–ˆโ–€ โ–„โ–€โ–ˆ โ–ˆโ–„โ–„ โ–ˆ โ–ˆโ–€โ–€ โ–€โ–ˆโ–€ โ–ˆ โ–€โ–ˆโ–€ โ–ˆ โ–ˆโ–€โ–€ โ–ˆ
โ–ˆโ–€โ–ˆ โ–ˆโ–ˆโ–„ โ–ˆโ–€โ–„ โ–ˆโ–ˆโ–„ โ–„โ–ˆ โ–ˆโ–€โ–ˆ โ–ˆโ–„โ–ˆ โ–ˆ โ–ˆโ–„โ–ˆ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–„โ–„ โ–ˆโ–ˆโ–„ โ–„
```

Currently, only one font is available, and the supported characters are: `"0123456789abcdefghijklmnopqrstuvwxyz_-!.' "`

(You can get them by using `ouf.fonts.suported_chars`)

## Showing lists

You can simply show a list using bullet points:
``` Python
data = ["Item A", "Item B", "Item C", "Item D"]
ouf.showlist(data)
```
```
โ€ข Item A
โ€ข Item B
โ€ข Item C
โ€ข Item D
```

And also there's an option to add a title to your list:
``` Python
data = ["Item A", "Item B", "Item C", "Item D"]
ouf.showlist(data, title="List of items")
```
```
List of items
โ€ข Item A
โ€ข Item B
โ€ข Item C
โ€ข Item D
```

Different styles are available, as `bullet`, `line`, `box` and `ordinal`
``` Python
data = ["Item A", "Item B", "Item C", "Item D"]

ouf.showlist(data, style="line", title="Style line")
ouf.showlist(data, style="box", title="Style box")
ouf.showlist(data, style="ordinal", title="Style ordinal")
```
```
Style line
โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
โ”œ Item A
โ”œ Item B
โ”œ Item C
โ•ฐ Item D

โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚ Style box โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ
โ”œ Item A
โ”œ Item B
โ”œ Item C
โ•ฐ Item D

Style ordinal
1. Item A
2. Item B
3. Item C
4. Item D
```

Or pass any string to be used as marker
``` Python
data = ["Item A", "Item B", "Item C", "Item D"]
ouf.showlist(data, style="~>", title="Custom style list")
```
```
Custom style list
~> Item A
~> Item B
~> Item C
~> Item D
```

## Showing bars

You can create a simple horizontal bar using `ouf.bar`
The first parameter (`value`) is the filled amount, the second (`maxvalue`) is the maximum amount

``` Python
ouf.bar(35, 50)
```
```
โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 35/50 ( 70.00%)

```
Note that there's some **integer rounding** needed to create the bar, so the size is not precise, more like a ballpark visualisation.

The size of the bar (in characters) is defined by `length`
``` Python
ouf.bar(35, 50, length=10)
ouf.bar(35, 50, length=50)
```
```
โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘ 35/50 ( 70.00%)
โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 35/50 ( 70.00%)
```

Different styles are available, as well as the option to have a title before the bar:
``` Python
ouf.bar(35, 50, style="block", length=15, title="Block style", title_pad=15)
ouf.bar(35, 50, style="battery", length=15,title="Battery style", title_pad=15)
ouf.bar(35, 50, style="bar", length=15, title="Bar style", title_pad=15)
ouf.bar(35, 50, style="circle", length=15, title="Circle style", title_pad=15)
```
```
Block style....: โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–“โ–‘โ–‘โ–‘โ–‘โ–‘ 35/50 ( 70.00%)

Battery style..: โ”ซโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โ”ฃ 35/50 ( 70.00%)

Bar style......: [โ– โ– โ– โ– โ– โ– โ– โ– โ– โ–  ] 35/50 ( 70.00%)

Circle style...: โ—โ—โ—โ—โ—โ—โ—โ—โ—โ—โ—‹โ—‹โ—‹โ—‹โ—‹ 35/50 ( 70.00%)
```

There's also a star emoji style, that works better with small values for `length` and using `show_percentage=False` and `show_values=False`

``` Python
ouf.bar(60, 100, style="star", length=5, title="Item A", show_percentage=False, show_values=False)
ouf.bar(20, 100, style="star", length=5, title="Item B", show_percentage=False, show_values=False)
ouf.bar(90, 100, style="star", length=5, title="Item C", show_percentage=False, show_values=False)
```
```
Item A: โญโญโญ
Item B: โญ
Item C: โญโญโญโญ
```
### Custom bars

A totally custom style for the bar can be created, passing a list of characters as `style`
``` Python
ouf.bar(35, 50, style=["(", "X", "-", ")"], title="Custom style")
```
```
Custom style: (XXXXXXXXXXXXXXXXXXXXXX----------) 35/50 ( 70.00%)

```

Or you can pass just a simple character, and it will be used for a basic bar:
``` Python
ouf.bar(35, 50, style="$", title="Custom style")
```
```
Custom style: [$$$$$$$$$$$$$$$$$$$$$$ ] 35/50 ( 70.00%)
```

### Multiple bars from list
It is possible to use `ouf.barlist` and pass directly a list of `values` with the correspondent list of `titles`

``` Python
values = [6, 3, 13, 8]
titles = ["var", "long var name", "medium var", "one more"]
ouf.barlist(values, titles, maxvalue=15, style="bar")
```
```
var..........: [โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ–  ] 6/15 ( 40.00%)
long var name: [โ– โ– โ– โ– โ– โ–  ] 3/15 ( 20.00%)
medium var...: [โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ–  ] 13/15 ( 86.67%)
one more.....: [โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ– โ–  ] 8/15 ( 53.33%)
```
The same parameters from `ouf.bar` can be used. Only one `maxvalue` is used for all the lists

## Show emoji
Some shortcuts for the unicode values of common emoji are available
``` Python
print(ouf.emoji.heart, ouf.emoji.thumbs_up)
```
```
๐Ÿ’– ๐Ÿ‘
```

Current shortcuts are the following:
```
crazy.............:๐Ÿคช
sad...............:๐Ÿ˜ฅ
circle_red........:๐Ÿ”ด
circle_orange.....:๐ŸŸ 
circle_yellow.....:๐ŸŸก
circle_green......:๐ŸŸข
circle_white......:โšช
circle_black......:โšซ
star..............:โญ
heart.............:๐Ÿ’–
thumbs_up.........:๐Ÿ‘
check.............:โœ…
clap..............:๐Ÿ‘
bomb..............:๐Ÿ’ฃ
```