Modules

pingstats.__init__

Example Usage:

>>> import pingstats
>>> pings = pingstats.Pings('google.ca')
>>> for ping in pings:
...     pingstats.plot_pings(pings.realtime_data)
# HIPSTERPLOT OUTPUT
...     print(ping)
# The most recent return time in milliseconds

class pingstats.Pings(address, realtime_data=[], average_data=[], realtime_data_length=20, average_data_length=200)

Main logic object for obtaining ping data.

Example Usage:

>>> from pingstats import Pings
>>> pings = Pings('127.0.0.1')
>>> for this_time in pings:
...     print(pings.realtime_data)
...     print(pings.average_data)
...     print(pings.current_line)
...     print(this_time)  # current ping's realtime data in milliseconds

__init__(address, realtime_data=[], average_data=[], realtime_data_length=20, average_data_length=200)

Instantiates data used during the ping retrieval process.

Address:The address to send ICMP ECHO requests to. Realtime_data:A python list object to continue to append data to. Average_data:A python list object to continue to append data to. Realtime_data_length:  The maximum size of the realtime_data list Average_data_length:  The maximum size of the average_data list

pingstats.get_pings(address)

Yields the last set of realtime and average data points, according to user specified maximum.

Address:The address to send ICMP ECHO requests to.

pingstats.plot_pings(pings, columns=70, rows=15)

Provides high level bindings to hipsterplot.plot for use with pingstats.get_pings().

Pings:A list object containing ping return times as float values, normally from pingstats.get_pings() Columns:The number of columns to draw for the plot Rows:The number of rows to draw for the plot

pingstats.ui

Outlines UI behaviour.

UI is presented by outputting the same number of columns and rows as the connected tty.

The UI is constructed of several pingstats.ui.PingsWidget derivative classes. Each of these classes outputs different types of information to the display. Each type of derivative class has similar output:

Where objects with the following in their names have the listed effect:

• Status
  • A single line display of simple information. For example, the number of packets being displayed for a given measure (pingstats.ui.RealtimeStatus or pingstats.ui.AverageStatusc) or a simple display of ping target and program version.
• Plot
  • A plot based on hipsterplot plotting functionality. Each plot displays particular information (pingstats.ui.RealtimePlot displays a plot of realtime ping data, pingstats.ui.AveragePlot displays a plot of the average of those realtime data points.
• Pane
  • Some combination of Status and Plot widgets.

The pingstats.ui.Runner class provides functionality for dynamically executing the UI. For example, given the command line argument -l realtimepane,progstatus,averagepane produces the default display of the software.

—

Base Widgets

class pingstats.ui.Widget(columns, rows)

Base class for all UI elements. Defines columns and rows.

__init__(columns, rows)

Instantiates self.columns and self.rows

Columns:The total number of columns available for display. Rows:The total number of rows available for display.

class pingstats.ui.PingWidget(columns, rows, pings_object)

Adds realtime and average data objects to self

__init__(columns, rows, pings_object)

Instantiate self.columns, self.rows, self.realtime_data, self.average_data

Columns:The total number of columns available for display. Rows:The total number of rows available for display. Pings_object:An instance of pingstats.Pings()

Status Widgets

class pingstats.ui.RawStatus(*args)

Displays the current data line from the original call to ping.

Example output:

>>> -----------64 bytes from 127.0.0.1: icmp_seq=1 ttl=128 time=0.115 ms------------

class pingstats.ui.AverageStatus(*args)

Displays information about average data, and if the connection was dropped.

Example output:

>>> "Displaying the average of 12 total packets from 127.0.0.1"
                             - OR -
>>> "Connection dropped!"

class pingstats.ui.DroppedStatus(*args)

Displays how many packets have been dropped if any, otherwise the program name.

Example Output:

>>> -----------64 bytes from 127.0.0.1: icmp_seq=1 ttl=128 time=0.115 ms------------

• or -

>>> -----------64 bytes from 127.0.0.1: icmp_seq=1 ttl=128 time=0.115 ms------------

class pingstats.ui.ProgStatus(*args)

Displays Program information, and a separator bar.

Example output:

>>> "pingstats V0.9 ------------------------ ping data from 127.0.0.1

class pingstats.ui.RealtimeStatus(*args)

Displays information about real-time data, and packets dropped.

Example output:

>>> "Displaying 12 packets from 127.0.0.1"
                             - OR -
>>> "3 packets dropped of 12"

Plot Widgets

class pingstats.ui.AveragePlot(*args)

Displays average data on a plot.

class pingstats.ui.RealtimePlot(*args)

Displays real-time data on a plot.

Pane Widgets

class pingstats.ui.AveragePane(columns, rows, pings)

Displays average data on a plot, along with the output of pingstats.ui.AverageStatus().

class pingstats.ui.RealtimePane(columns, rows, pings)

Displays real-time data on a plot, along with the output of pingstats.ui.RealtimeStatus().

Creating your own Widget

To create your own widget, simply inherit from the topmost relevant widget class, override the init class, and then define your output to the stdout. For example:

from pingstats.ui import Runner, PingWidget  # Import resources


class MyStatus(PingWidget):  # Define our widget
    def __init__(self, *args):  # Overide init, collecting any args
        super(MyStatus, self).__init__(*args)  # Pass args to the original function
        print('hello world')  # Perform output


if __name__ == '__main__':
    # instantiate runner, pass a list containing our Widget and the equivalent of sys.argv
    runner = Runner([MyStatus], ['-l', 'droppedstatus,mystatus,realtimestatus', 'google.ca'])
    runner()  # Run logic loop

Warning

Arguments are passed to the widget classes internally. You can mirror the arguments of the parent class init function, or pass *args

Note

The runner class uses the name of the widget to determine how much space each should take on screen, where status widgets take one line and plot/pane widgets take n lines. Therefore, you should specify what kind of widget it is in the object name.

User Configuration

Provides ease of use configuration capabilities to the project.

Parses files with arguments for the project split line by line, such that:

-l droppedstatus,averagepane,rawstatus

Would be appended onto the end of sys.argv.

Warning

The config files do not accept the setting of targets

For *Nix users, the project searches for configuration files under the following paths:

~/.pingstats.rc

For NT users, the project searches for configuration files under the following paths:

%LOCALAPPDATA%\Pingstats\pingstats.rc