Contents

Package ascii_graph

class ascii_graph.__init__.Pyasciigraph(line_length=79, min_graph_length=50, separator_length=2, graphsymbol=None, multivalue=True, human_readable=None)

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
  • 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)
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', 100, Cya),
           ('testval5', 50, Blu),
           ('testval6', [(100, Gre), (150, 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', 600),
        ('testval1', 500),
        ('testval2', 400),
        ('testval3', 400),
        ('testval4', 300),
        ('testval5', 200),
        ('testval6', 100),
        ('testval7', 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.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
    • reorganize –help to be more consistant 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

    • adding human readable flag (power of 1000 or 1024)
    • fixing multi values display alignment

  • 1.0.1

    • Light cleaning in source code
    • Test for python 3.4
    • Better documentation

  • 1.0.0

    • Remove sort capabilities
    • Add coloring capabilities (mono and multi color) (big thanks to David Whiteside)
    • Add some functions and constants to help color data
    • Adding possibility to change the symbol used for the graph bar
    • Better unit tests
    • Documentation improvement

  • 0.2.1

    • Small documentation improvement

  • 0.2.0

    • Fix number of encoding issues
    • Add a sort capability
    • Add unit tests
    • Add a command line utility (asciigraph)

  • 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

Travis CI Number of PyPI downloads PyPI version Join the chat at https://gitter.im/kakwa/py-ascii-graph https://coveralls.io/repos/kakwa/py-ascii-graph/badge.svg?branch=master Documentation Status
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 and a few tweaks
graph = Pyasciigraph(
    line_length=120,
    min_graph_length=50,
    separator_length=4,
    multivalue=False,
    human_readable='si',
    graphsymbol='*'
    )

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:10\nl2:100\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
   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)

See the examples/ directory for more examples.

Installation

$ pip install ascii_graph

or

$ easy_install ascii_graph

Indices and tables