Contents¶

Package ascii_graph¶

class ascii_graph.__init__.Pyasciigraph(line_length=79, min_graph_length=50, separator_length=2, force_max_value=None, graphsymbol=None, multivalue=True, human_readable=None, float_format=u'{0:.0f}', titlebar=u'#')¶

Constructor of Pyasciigraph

Parameters:

line_length (int) – the max number of char on a line if any line cannot be shorter, it will go over this limit. Default: 79
min_graph_length (int) – the min number of char used by the graph itself. Default: 50
force_max_value – if provided, force a max value in order to graph each line with respect to it (only taking the actual max value if it is greater).
separator_length (int) – the length of field separator. Default: 2
graphsymbol (str or unicode (length one)) – the symbol used for the graph bar. Default: ‘█’
multivalue (boolean) – displays all the values if multivalued when True. displays only the max value if False Default: True
human_readable (string (si, cs, none)) –
trigger human readable display (K, G, etc) Default: None (raw value display)
- ’si’ for power of 1000
- ’cs’ for power of 1024
- any other value for raw value display)
float_format – formatting of the float value Default: ‘{0:.0f}’ (convert to integers). expample: ‘{:,.2f}’ (2 decimals, ‘.’ to separate decimal and int, ‘,’ every three power of tens).
titlebar (string) – sets the character(s) for the horizontal title bar Default: ‘#’

Type:

force_max_value: int

graph(label=None, data=[])¶

function generating the graph

Parameters:	label (string) – the label of the graph data (iterable) – the data (list of tuple (info, value)) info must be “castable” to a unicode string value must be an int or a float
Return type:	a list of strings (each lines of the graph)

Package ascii_graph.colordata¶

ascii_graph.colordata.hcolor(data, thresholds)¶

Multicolor a graph according to thresholds

Parameters:	data (list of tuples (info, value)) – the data thresholds (dict) – dict of thresholds, format {<threshold>: <color>,}
Returns:	the colored graph
Return type:	list of arrays

ascii_graph.colordata.vcolor(data, pattern)¶

Color a graph line by line

Parameters:	data (list of tuples (info, value)) – the data pattern (list of 'colors' (str)) – list of colors, this list defines the pattern to color each line of the graph.
Returns:	the colored graph
Return type:	list of arrays (<info>, <value>, <color>)

Package ascii_graph.colors¶

List of colors available in ascii_graph.colors¶

# Text Reset
RCol = '\33[0m'

# Regular
Bla = '\33[0;30m'
Red = '\33[0;31m'
Gre = '\33[0;32m'
Yel = '\33[0;33m'
Blu = '\33[0;34m'
Pur = '\33[0;35m'
Cya = '\33[0;36m'
Whi = '\33[0;37m'

# Bold
BBla = '\33[1;30m'
BRed = '\33[1;31m'
BGre = '\33[1;32m'
BYel = '\33[1;33m'
BBlu = '\33[1;34m'
BPur = '\33[1;35m'
BCya = '\33[1;36m'
BWhi = '\33[1;37m'

# Underline
UBla = '\33[4;30m'
URed = '\33[4;31m'
UGre = '\33[4;32m'
UYel = '\33[4;33m'
UBlu = '\33[4;34m'
UPur = '\33[4;35m'
UCya = '\33[4;36m'
UWhi = '\33[4;37m'

# High Intensity
IBla = '\33[0;90m'
IRed = '\33[0;91m'
IGre = '\33[0;92m'
IYel = '\33[0;93m'
IBlu = '\33[0;94m'
IPur = '\33[0;95m'
ICya = '\33[0;96m'
IWhi = '\33[0;97m'

# BoldHigh Intens
BIBla = '\33[1;90m'
BIRed = '\33[1;91m'
BIGre = '\33[1;92m'
BIYel = '\33[1;93m'
BIBlu = '\33[1;94m'
BIPur = '\33[1;95m'
BICya = '\33[1;96m'
BIWhi = '\33[1;97m'

# Background
On_Bla = '\33[40m'
On_Red = '\33[41m'
On_Gre = '\33[42m'
On_Yel = '\33[43m'
On_Blu = '\33[44m'
On_Pur = '\33[45m'
On_Cya = '\33[46m'
On_Whi = '\33[47m'

# High Intensity Backgrounds
On_IBla = '\33[0;100m'
On_IRed = '\33[0;101m'
On_IGre = '\33[0;102m'
On_IYel = '\33[0;103m'
On_IBlu = '\33[0;104m'
On_IPur = '\33[0;105m'
On_ICya = '\33[0;106m'
On_IWhi = '\33[0;107m'

Examples¶

Simple¶

from ascii_graph import Pyasciigraph

test = [('long_label', 423), ('sl', 1234), ('line3', 531),
    ('line4', 200), ('line5', 834)]

graph = Pyasciigraph()

# Simpler example
for line in graph.graph('test 1', test):
    print(line)

# Take also anything castable to utf-8
test = [(1, 423), (2, 1234), (3, 531), ('line4', 200), ('line5', 834)]
for line in graph.graph('test 2', test):
    print(line)

# Example of sort
test.sort(reverse=False, key=lambda tup: tup[1] )
for line in graph.graph('test 2', test):
    print(line)

# Example of reverse sort
test.sort(reverse=True, key=lambda tup: tup[1] )
for line in graph.graph('test 2', test):
    print(line)

print('')
# No label
for line in graph.graph(data=test):
    print(line)

# Different separator length
graph = Pyasciigraph(separator_length=4)
for line in graph.graph(data=test):
    print(line)

Color¶

#!/bin/env python2

from ascii_graph import Pyasciigraph
from ascii_graph.colors import *

# Simple coloring
test = [('testval0', 600),
        ('testval1', 500, Pur),
        ('testval2', 400, Red),
        ('testval3', 400, Red),
        ('testval4', 300, Gre),
        ('testval5', 200, Yel),
        ('testval6', 100, Cya),
        ('testval7', 50,  Blu) ]

graph = Pyasciigraph()
for line in graph.graph('test graph', test):
    print(line)


# Bold and underline
test = [('testval0', 142),
        ('testval1', 204, BPur),
        ('testval2', 501, URed),
        ('testval3', 103, IRed),
        ('testval4',  29, BIGre),
        ('testval5',  19, UYel),
        ('testval6',  99, ICya),
        ('testval7', 404, BBlu)]
graph = Pyasciigraph()
for line in graph.graph('test graph', test):
    print(line)


# Coloring data according to a pattern (one color each line)
from ascii_graph.colordata import vcolor

test = [('testval0', 600),
        ('testval1', 500),
        ('testval2', 400),
        ('testval3', 400),
        ('testval4', 300),
        ('testval5', 200),
        ('testval6', 100),
        ('testval7', 50 )]

pattern = [Gre, Yel, Red]

data = vcolor(test, pattern)
for line in graph.graph('vcolor test', data):
    print(line)

exit(0)

Multicolor¶

#!/bin/env python2

from ascii_graph import Pyasciigraph
from ascii_graph.colors import *

test = [('testval0', 600),
           ('testval1', 400, Red),
           ('testval2', [(600, Gre), (500, Blu)]),
           ('testval3', [(200, Yel), (100,)]),
           ('testval4', -170, Cya),
           ('testval5', 50, Blu),
           ('testval6', [(-300, Gre), (-230, Red)]),
           ('testval7', [(-100, Gre), (-230, Red), (200, Yel), (600, Blu)])]

# Multicolor with all the values displayed
graph = Pyasciigraph(separator_length=4)
for line in graph.graph('test graph', test):
    print(line)

# Multicolor with only the max value displayed
graph = Pyasciigraph(separator_length=4, multivalue=False)
for line in graph.graph('test graph mono value', test):
    print(line)

# Coloring data according to thresholds
from ascii_graph.colordata import hcolor

test = [('testval0 (\033[92m+\033[0m)', 600),
        ('testval1 (\033[91m-\033[0m)', 500),
        ('testval2 (\033[92m+\033[0m)', -400),
        ('testval3 (\033[92m+\033[0m)', 400),
        ('testval4 (\033[92m+\033[0m)', 300),
        ('testval5 (\033[91m-\033[0m)', 200),
        ('testval6 (\033[92m+\033[0m)', 100),
        ('testval7 (\033[92m+\033[0m)', 50 )]

thresholds = {
  51:  Gre,
  100: Blu,
  350: Yel,
  500: Red,
}

data = hcolor(test, thresholds)
for line in graph.graph('hcolor test', data):
    print(line)

exit(0)

Human Readable¶

#!/bin/env python2

from ascii_graph import Pyasciigraph
from ascii_graph.colors import *

test = [('testval0', 123456),
           ('testval1', 918829, Red),
           ('testval2', [(600192, Gre), (500203, Blu)]),
           ('testval3', [(2, Yel), (10,)]),
           ('testval4', 10, Cya),
           ('testval5', 50, Blu),
           ('testval6', [(1001233, Gre), (150000, Red), (100000, Yel), (60, Blu)])]

# Multicolor with all the values displayed
graph = Pyasciigraph(separator_length=4, human_readable='cs')
for line in graph.graph('test graph', test):
    print(line)

# Multicolor with only the max value displayed
graph = Pyasciigraph(separator_length=4, multivalue=False, human_readable='cs')
for line in graph.graph('test graph mono value', test):
    print(line)

# Coloring data according to thresholds
from ascii_graph.colordata import hcolor

test = [('testval0', 6003),
        ('testval1', 900),
        ('testval2', 4920),
        ('testval3', 400),
        ('testval4', 30),
        ('testval5', 200),
        ('testval6', 1025),
        ('testval7', 5023 )]

thresholds = {
  51:  Gre,
  100: Blu,
  350: Yel,
  500: Red,
}

data = hcolor(test, thresholds)
for line in graph.graph('hcolor test', data):
    print(line)

exit(0)

Shell Scripts¶

#!/bin/sh

# It's a small example of asciigraph usage
# It just displays the load

tput clear
old_width=`tput cols`


# Get number of cores (empiricaly I always try to have load < number of cores)
max=`grep -c processor /proc/cpuinfo`
# Calculate the first threshold (until this threshold, graph is green)
t1=`awk "BEGIN {print $max * 3 / 4}"`
# Calculate the second threshold.
# Between t1 and t2, graph is yellow. 
# After t2, graph is red.
t2=`awk "BEGIN {print $max * 4 / 4}"`

while true
do
    # Get the load
    load_15=`uptime|sed "s/.*:\ //"|cut -d ',' -f 3`
    load_1=`uptime|sed "s/.*:\ //"|cut -d ',' -f 1`
    load_5=`uptime|sed "s/.*:\ //"|cut -d ',' -f 2`

    # Get the width of the term
    width=`tput cols`
    if [ $width -ne $old_width ]
    then
        tput clear
    fi
    old_width=$width

    printf "\
load threshold:$max\n\
load last minute:$load_1\n\
load last 5 minutes:$load_5\n\
load last 15 minutes:$load_15\n" | \
    asciigraph -w $width -l 'loadtop' -c -t $t1 -T $t2

    #refresh every 1 second
    tput cup 0 0
    sleep 1
done

#!/bin/sh

width=`tput cols`

# simple example to graph the du command output

# run du -> refomart a little with awk -> give it to asciigraph
du -d 1 $@ | head -n -1 |\
    awk '{s = ""; for (i = 2; i <= NF; i++) s = s $i " "; printf "%s:%s\n", s, $1 * 1024;}' | \
    asciigraph -l 'Disk Usage' -H -s dec -c -w $width

ChangeLogs¶

1.5.0
- Add possibility to change the titlebar character (thanks to Denis Khoshaba)
1.4.3
- Fix loading of license and long description (it was systematically fallbacking to default values with python2.7)
1.4.2
- Fix setup.py to handle encoding properly, and fallback to safe values in errors (license and long description)
1.4.1
- Fix length computation with string containing ANSI control characters
1.4.0
- Add –force-max-value (-x) option to command line tool to set max value. (Thanks to GerritRV)
- Add handling for negative values
1.3.0
- Add force_max_value optional parameter (permits to force a given scale) (Thanks to Yuly Tenorio)
1.2.0
- Add float formatting (float_format parameter in constructor, -F switch in CLI) (thanks to interrogator)
1.1.4
- Fix DivisionByZero in case all values are 0
1.1.3
- Fix typo in long option name for human readable mode in cli tool
- Improve –help to be more consistent in cli tool
1.1.2
- Fix bad format/empty dataset in asciigraph command line tool
1.1.1
- Fix auto-threshold calculation in asciigraph command line tool
1.1.0
- Add human readable flag (power of 1000 or 1024)
- Fix multi values display alignment
1.0.1
- Add testing on python 3.4
- Improve source code readability
- Improve documentation
1.0.0
- Add coloring capabilities (mono and multi color) (big thanks to David Whiteside)
- Add some functions and constants to help color data
- Add possibility to change the symbol used for the graph bar
- Improve unit tests
- Improve documentation
- Remove sort capabilities
0.2.1
- Improve documentation
0.2.0
- Add a sort capability
- Add unit tests
- Add a command line utility (asciigraph)
- Fix number of encoding issues
0.1.0
- Initial packaging, initial documentation and overall cleaning (big thanks to James Pearson (xiongchiamiov))

py-ascii-graph¶

A simple python lib to print data as ascii histograms

https://coveralls.io/repos/kakwa/py-ascii-graph/badge.svg?branch=master

Git:	Github
PyPI:	Package
Doc:	Documentation
License:	MIT
Author:	Pierre-Francois Carpentier - copyright 2014

License¶

py-ascii-graph is released under the MIT License.

Description¶

py-ascii-graph is a simple python library to build ascii histograms. Just give it a label and a list of tuples (description, value) and it will automaticaly creates a nice histogram, with all the stuff aligned and fitting in a fixed width line (if possible).

py-ascii-graph although comes with a command line utility.

Examples¶

Library¶

Simple example:

from ascii_graph import Pyasciigraph

test = [('long_label', 423), ('sl', 1234), ('line3', 531),
    ('line4', 200), ('line5', 834)]

graph = Pyasciigraph()
for line in  graph.graph('test print', test):
    print(line)

Result:

test print
###############################################################################
████████████████████                                            423  long_label
█████████████████████████████████████████████████████████████  1234  sl
██████████████████████████                                      531  line3
█████████                                                       200  line4
█████████████████████████████████████████                       834  line5

Complex examples (colors, different spacing, no label…):

from ascii_graph import Pyasciigraph
from ascii_graph.colors import *
from ascii_graph.colordata import vcolor
from ascii_graph.colordata import hcolor

test = [('long_label', 423), ('sl', 1234), ('line3', 531),
    ('line4', 200), ('line5', 834)]

# One color per line
print('Color example:')
pattern = [Gre, Yel, Red]
data = vcolor(test, pattern)

graph = Pyasciigraph()
for line in graph.graph('vcolor test', data):
    print(line)

# Multicolor on one line
print('\nMultiColor example:')

# Color lines according to Thresholds
thresholds = {
  51:  Gre, 100: Blu, 350: Yel, 500: Red,
}
data = hcolor(test, thresholds)

# graph with colors, power of 1000, different graph symbol,
# float formatting and a few tweaks
graph = Pyasciigraph(
    line_length=120,
    min_graph_length=50,
    separator_length=4,
    multivalue=False,
    human_readable='si',
    graphsymbol='*',
    float_format='{0:,.2f}',
    force_max_value=2000,
    )

for line in graph.graph(label=None, data=data):
    print(line)

Command Line Utility¶

command line:

$ asciigraph -h
Usage: asciigraph [-l <label>] [-f file] [-s inc|dec] \
   [-c] [-t <first color threshold> [-T <second color threshold>] \
   [-w <number of char>] [-m <min len of char>] [-H] [-M cs|si]

examples:
   printf 'label1:10\nlabel2:100\n' | asciigraph -l 'my graph'
   printf 'label1:1000\nlabel2:20000\n' | asciigraph -l 'my graph' -H -M 'si'
   printf 'l1:100\nl2:1200.42\n' > ./mf; asciigraph -l 'my graph' -f ./mf
   asciigraph -l 'my graph' -f mf -s inc
   asciigraph -l 'my graph' -f mf -s dec -w 60 -m 10
   asciigraph -l 'my graph' -f mf -c -F '{0:,.2f}'
   asciigraph -l 'my graph' -f mf -c -t 5 -T 50


Options:
  -h, --help            show this help message and exit
  -f FILE, --file=FILE  import data from FILE (one data per line,
                        format: <label>:<value>)
  -s SORT, --sort=SORT  sort type: inc (increasing) or dec (decreasing)
  -l LAB, --label=LAB   label of the graph
  -w WIDTH, --width=WIDTH
                        width of the graph
  -m LEN, --min_graph=LEN
                        minimum length of the graph bar
  -c, --color           Color the graph
  -t TC1, --threshold-1=TC1
                        first color threshold, only make sense if --color is
                        passed
  -T TC2, --threshold-2=TC2
                        second color threshold, only make sense if --color is
                        passed
  -H, --human-readable  enable human readable mode (K, M, G, etc)
  -M HR_MODE, --human-readable-mode=HR_MODE
                        Human readable mode ('cs' -> power of 1024 or 'si' ->
                        power of 1000, default: cs)
  -F FORMAT, --float-format=FORMAT
                        float formatting, ex: {0:,.2f}

See the examples/ directory for more examples.

Installation¶

$ pip install ascii_graph

or

$ easy_install ascii_graph

Contents¶

Package ascii_graph¶

Package ascii_graph.colordata¶

Package ascii_graph.colors¶

List of colors available in ascii_graph.colors¶

Examples¶

Simple¶

Color¶

Multicolor¶

Human Readable¶

Shell Scripts¶

ChangeLogs¶

py-ascii-graph¶

License¶

Description¶

Examples¶

Library¶

Command Line Utility¶

Installation¶

Indices and tables¶