[people/ms/python-rrdtool.git] / README.md

python-rrdtool
==============

Python bindings for rrdtool with a native C extension and an object-oriented way to work with Round Robin Databases. As of version 0.1.1, Python 2 and 3 is supported.

The bindings are based on the code of the original Python 2 bindings for rrdtool by Hye-Shik Chang.

Installation
------------

In order to build the native C extension (which is an required step), you'll need librrd and its headers installed. Having rrdtool installed should be enough on most distributions.

**How to Install?**

1. Download a copy of the repository.
2. Run `python setup.py install` to build an install the native C extension as well as the RRD module.

Usage
-----

You can either use the low-level `rrdtool` module (which offers almost the same functions as the old Python 2 bindings for rrdtool provided), or the `RRDtool` module, which represents a object-oriented interface to rrdtool.

### Using the low-level `rrdtool` module

```python
import rrdtool

# Create Round Robin Database
rrdtool.create('test.rrd', '--start', 'now', '--step', '300', 'RRA:AVERAGE:0.5:1:1200', 'DS:temp:GAUGE:600:-273:5000')

# Feed updates to the RRD
rrdtool.update('test.rrd', 'N:32')
```

### Using the high-level `RRDtool` module

```python
import RRDtool

# Create a Round Robin Database
rrd = RRDtool.create('test.rrd', '--start', 'now', '--step', '300', 'RRA:AVERAGE:0.5:1:1200', 'DS:temp:GAUGE:600:-273:5000')

# Update the RRD
rrd.update([(None, 32)])

# Create a graph from it
rrd.graph('test.png', '--end', 'now', '--start', 'end-5minutes', '--width', '400', 'DEF:ds0a=test.rrd:temp:AVERAGE', 'LINE1:ds0a#0000FF:"temperature\l"')

# Same, but keep data in memory.
imgdata = rrd.graph(None, '--end', 'now', '--start', 'end-5minutes', '--width', '400', 'DEF:ds0a=test.rrd:temp:AVERAGE', 'LINE1:ds0a#0000FF:"temperature\l"')

# You can also use file-like objects
from io import BytesIO
rrd.graph(io, ...)
```

Changes
-------

## 0.1.1

*Released 2013-12-19*

* Added support for Python 2.7 (other 2.x versions might also work, but its not tested)
* Added dump command
* Fixed some issues regarding generating graphs with `graphv` on Python 3.3

*Please note:* The `graph` method in the object-oriented RRD class will now return a dict by default (as returned by graphv). Only if the `output_file` parameter is None, the actual graph image bytes are returned. Python 3.3 will return a bytes object whereas Python 2.x will return a str object.

## 0.1.0

*Released 2012-09-17*

* Initial release.
* Support for Python 3.x added
* Updated documentation strings (`__doc__`) for each of the rrdtool functions

Author
------

Christian Jurk <commx@commx.ws>

This binding was created because I am currently porting some existing Python 2 code to Python 3 and try to help the community by contributing a updated binding extension. Hope someone can benefit from it.

If you encounter any bugs (which I expected at time of writing this), please submit them in the issue tracker here on the project page on Github. Thank you.
Commit	Line	Data
225c0910 CJ	1	python-rrdtool
225c0910 CJ	2	==============
c639f664	3
225c0910	4	Python bindings for rrdtool with a native C extension and an object-oriented way to work with Round Robin Databases. As of version 0.1.1, Python 2 and 3 is supported.
b4570f2a CJ	5
	6	The bindings are based on the code of the original Python 2 bindings for rrdtool by Hye-Shik Chang.
	7
	8	Installation
	9	------------
	10
	11	In order to build the native C extension (which is an required step), you'll need librrd and its headers installed. Having rrdtool installed should be enough on most distributions.
	12
225c0910	13	How to Install?
b4570f2a CJ	14
	15	1. Download a copy of the repository.
	16	2. Run `python setup.py install` to build an install the native C extension as well as the RRD module.
	17
	18	Usage
	19	-----
	20
	21	You can either use the low-level `rrdtool` module (which offers almost the same functions as the old Python 2 bindings for rrdtool provided), or the `RRDtool` module, which represents a object-oriented interface to rrdtool.
	22
b4570f2a CJ	23	### Using the low-level `rrdtool` module
	24
	25	```python
	26	import rrdtool
	27
	28	# Create Round Robin Database
	29	rrdtool.create('test.rrd', '--start', 'now', '--step', '300', 'RRA:AVERAGE:0.5:1:1200', 'DS:temp:GAUGE:600:-273:5000')
	30
	31	# Feed updates to the RRD
	32	rrdtool.update('test.rrd', 'N:32')
	33	```
	34
	35	### Using the high-level `RRDtool` module
	36
	37	```python
	38	import RRDtool
	39
	40	# Create a Round Robin Database
	41	rrd = RRDtool.create('test.rrd', '--start', 'now', '--step', '300', 'RRA:AVERAGE:0.5:1:1200', 'DS:temp:GAUGE:600:-273:5000')
	42
	43	# Update the RRD
	44	rrd.update([(None, 32)])
	45
	46	# Create a graph from it
	47	rrd.graph('test.png', '--end', 'now', '--start', 'end-5minutes', '--width', '400', 'DEF:ds0a=test.rrd:temp:AVERAGE', 'LINE1:ds0a#0000FF:"temperature\l"')
	48
	49	# Same, but keep data in memory.
225c0910	50	imgdata = rrd.graph(None, '--end', 'now', '--start', 'end-5minutes', '--width', '400', 'DEF:ds0a=test.rrd:temp:AVERAGE', 'LINE1:ds0a#0000FF:"temperature\l"')
b4570f2a CJ	51
	52	# You can also use file-like objects
	53	from io import BytesIO
	54	rrd.graph(io, ...)
	55	```
	56
225c0910 CJ	57	Changes
	58	-------
	59
	60	## 0.1.1
	61
	62	Released 2013-12-19
	63
	64	* Added support for Python 2.7 (other 2.x versions might also work, but its not tested)
	65	* Added dump command
	66	* Fixed some issues regarding generating graphs with `graphv` on Python 3.3
	67
	68	Please note: The `graph` method in the object-oriented RRD class will now return a dict by default (as returned by graphv). Only if the `output_file` parameter is None, the actual graph image bytes are returned. Python 3.3 will return a bytes object whereas Python 2.x will return a str object.
	69
	70	## 0.1.0
	71
	72	Released 2012-09-17
	73
	74	* Initial release.
	75	* Support for Python 3.x added
	76	* Updated documentation strings (`__doc__`) for each of the rrdtool functions
	77
b4570f2a CJ	78	Author
	79	------
	80
	81	Christian Jurk <commx@commx.ws>
	82
	83	This binding was created because I am currently porting some existing Python 2 code to Python 3 and try to help the community by contributing a updated binding extension. Hope someone can benefit from it.
	84
	85	If you encounter any bugs (which I expected at time of writing this), please submit them in the issue tracker here on the project page on Github. Thank you.