Readme¶

Software Description¶

This script provides a very simple CLI based ping visualization script by utilizing either hipsterplot or gnuplot/asciiplotlib.

The hipsterplot backend is a very simple and lightweight backend, meant to allow easier install and wider operating system reach. However, it is nowhere near as easy to read & understand as the gnuplot/asciiplotlib backend. It is highly recommended you make use of that backend if you can.

Why should you use it?¶

The long and short is that pingstats provides a simple and stable method to visualize average ping over time from the command line. Aside from that, it provides the following features:

Provides a highly modular dynamic UI layout selector, allowing the user to modify the way the software presents data.
Provides a simple API for implementing unique and new UI behaviour
Automatically resizes and stays aware of viewport size
Stays under a megabyte of total size

Installation¶

To install the base package (and use the simple backend, hipsterplot), installation has been made easy via pip.

pip3 install pingstats

If however, you are using Linux and can install the gnuplot library, first obtain the binary from apt:

sudo apt-get install gnuplot

Note

The pingstats package will automatically use gnuplot if it is available.

Installing from source¶

Installing from source can be achieved relatively simply by first cloning the repository and moving into the subsequent directory:

git clone https://git.eclecticmedia.space/public/pingstats.git && cd pingstats

Note

To checkout the newest, experimental changes ensure you are on the master branch

Once the repository is cloned, you can run the setup.py script to install the local files:

python3 setup.py install

Usage¶

This software was implemented with simplicity in mind, and only provides one point of access:

pingstats google.ca

Command Line Arguments¶

The software also has a variety of command line arguments avaialable:

usage: pingstats [-h] [-l LAYOUT] [--list-widgets] [-V] address

positional arguments:
  address               The address to ping. This could be either a web
                        address (i.e, "google.ca") or an IP address.

optional arguments:
  -h, --help            show this help message and exit
  -l LAYOUT, --layout LAYOUT
                        Specify a UI layout by listing ui elements in a comma
                        separated list where
                        'realtimepane,progstatus,averagepane' displays the
                        default layout. See the docs for more information.
  --list-widgets        Output a list of available widgets for '-l'
  -V, --version         show program's version number and exit

Examples of software in use¶

In this image, we can see two separate outputs. The top display is a display of the most recent actual return times, whereas the bottom display is the average return time for each sequence.

This display automatically scales to whatever window you have open, adding more lines and columns as necessary.

Running the tests¶

To run the tests, clone the repository:

git clone https://git.eclecticmedia.space/public/pingstats.git

Then simply run:

python3 setup.py test

Contributing to the Project¶

Forking the project¶

To fork the project, first clone it from the official repository:

git clone git://git.eclecticmedia.space/public/pingstats.git

Then, create your own public repository and set the origin url to that repository:

git remote set-url origin *your repository*

Once we have set your remote to origin, we can tell git where the upstream is:

git remote add upstream git://git.eclecticmedia.space/public/pingstats.git

Note

The upstream should be the official repository.

Note

For more on the git native forking workflow, see the git forking tutorial

Our issue tracker¶

We use a [Google Group] hosted mailing list (pingstats@googlegroups.com) to track and recieve new patches and bug reports.