Commit 21524682 authored by Sandro Tosi's avatar Sandro Tosi

Imported Debian patch 0.6-1

Metadata-Version: 1.0
Metadata-Version: 1.1
Name: prettytable
Version: 0.5
Version: 0.6
Summary: A simple Python library for easily displaying tabular data in a visually appealing ASCII table format
Home-page: http://www.luke.maurits.id.au/software/prettytable
Home-page: http://code.google.com/p/prettytable
Author: Luke Maurits
Author-email: luke@maurits.id.au
License: http://www.luke.maurits.id.au/software/bsdlicense.txt
License: UNKNOWN
Description: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Text Processing
TUTORIAL ON HOW TO USE THE PRETTYTABLE 0.6 API
*** This tutorial is distributed with PrettyTable and is meant to serve
as a "quick start" guide for the lazy or impatient. It is not an
exhaustive description of the whole API, and it is not guaranteed to be
100% up to date. For more complete and update documentation, check the
PrettyTable wiki at http://code.google.com/p/prettytable/w/list ***
= Getting your data into (and out of) the table =
Let's suppose you have a shiny new PrettyTable:
from prettytable import PrettyTable
x = PrettyTable()
and you want to put some data into it. You have two (sane) options
== Row by row ==
You can add data one row at a time. To do this you need to set the field names
first using the `set_field_names` method, and then add the rows one at a time
using the `add_row` method:
x.set_field_names(["City name", "Area", "Population", "Annual Rainfall"])
x.add_row(["Adelaide",1295, 1158259, 600.5])
x.add_row(["Brisbane",5905, 1857594, 1146.4])
x.add_row(["Darwin", 112, 120900, 1714.7])
x.add_row(["Hobart", 1357, 205556, 619.5])
x.add_row(["Sydney", 2058, 4336374, 1214.8])
x.add_row(["Melbourne", 1566, 3806092, 646.9])
x.add_row(["Perth", 5386, 1554769, 869.4])
== Column by column ==
You can add data one column at a time as well. To do this you use the
`add_column` method, which takes two arguments - a string which is the name for
the field the column you are adding corresponds to, and a list or tuple which
contains the column data"
x.add_column("City name",
["Adelaide","Brisbane","Darwin","Hobart","Sydney","Melbourne","Perth"])
x.add_column("Area", [1295, 5905, 112, 1357, 2058, 1566, 5386])
x.add_column("Population", [1158259, 1857594, 120900, 205556, 4336374, 3806092,
1554769])
x.add_column("Annual Rainfall",[600.5, 1146.4, 1714.7, 619.5, 1214.8, 646.9,
869.4])
== Mixing and matching ==
If you really want to, you can even mix and match `add_row` and `add_column`
and build some of your table in one way and some of it in the other. There's a
unit test which makes sure that doing things this way will always work out
nicely as if you'd done it using just one of the two approaches. Tables built
this way are kind of confusing for other people to read, though, so don't do
this unless you have a good reason.
== Getting data out ==
There are three ways to get data out of a PrettyTable, in increasing order of
completeness:
* The `del_row` method takes an integer index of a single row to delete.
* The `clear_rows` method takes no arguments and deletes all the rows in the
table - but keeps the field names as they were so you that you can repopulate
it with the same kind of data.
* The `clear` method takes no arguments and deletes all rows and all field
names. It's not quite the same as creating a fresh table instance, though -
style related settings, discussed later, are maintained.
= Displaying your table in ASCII form =
PrettyTable's main goal is to let you print tables in an attractive ASCII form,
like this:
+-----------+------+------------+-----------------+
| City name | Area | Population | Annual Rainfall |
+-----------+------+------------+-----------------+
| Adelaide | 1295 | 1158259 | 600.5 |
| Brisbane | 5905 | 1857594 | 1146.4 |
| Darwin | 112 | 120900 | 1714.7 |
| Hobart | 1357 | 205556 | 619.5 |
| Melbourne | 1566 | 3806092 | 646.9 |
| Perth | 5386 | 1554769 | 869.4 |
| Sydney | 2058 | 4336374 | 1214.8 |
+-----------+------+------------+-----------------+
You can print tables like this to `stdout` or get string representations of
them.
== Printing ==
To print a table in ASCII form, you can just do this:
print x
in Python 2.x or:
print(x)
in Python 3.x.
The old x.printt() method from versions 0.5 and earlier has been removed. To
pass options changing the look of the table, use the get_string() method
documented below:
print x.get_string()
== Stringing ==
If you don't want to actually print your table in ASCII form but just get a
string containing what _would_ be printed if you use "print x", you can use
the `get_string` method:
mystring = x.get_string()
This string is guaranteed to look exactly the same as what would be printed by
doing "print x". You can now do all the usual things you can do with a
string, like write your table to a file or insert it into a GUI.
== Controlling which data gets displayed ==
If you like, you can restrict the output of `print x` or `x.get_string` to
only the fields or rows you like.
The `fields` argument to these methods takes a list of field names to be
printed:
print x.get_string(fields=["City name", "Population"])
gives:
+-----------+------------+
| City name | Population |
+-----------+------------+
| Adelaide | 1158259 |
| Brisbane | 1857594 |
| Darwin | 120900 |
| Hobart | 205556 |
| Melbourne | 3806092 |
| Perth | 1554769 |
| Sydney | 4336374 |
+-----------+------------+
The `start` and `end` arguments take the index of the first and last row to
print respectively. Note that the indexing works like Python list slicing - to
print the 2nd, 3rd and 4th rows of the table, set `start` to 1 (the first row
is row 0, so the second is row 1) and set `end` to 4 (the index of the 4th row,
plus 1):
print x.get_string(start=1,end=4)
prints:
+-----------+------+------------+-----------------+
| City name | Area | Population | Annual Rainfall |
+-----------+------+------------+-----------------+
| Brisbane | 5905 | 1857594 | 1146.4 |
| Darwin | 112 | 120900 | 1714.7 |
| Hobart | 1357 | 205556 | 619.5 |
+-----------+------+------------+-----------------+
== Changing the alignment of columns ==
By default, all columns in a table are centre aligned.
=== All columns at once ===
You can change the alignment of all the columns in a table at once by assigning
a one character string to the `align` attribute. The allowed strings are "l",
"r" and "c" for left, right and centre alignment, respectively:
x.align = "r"
print x
gives:
+-----------+------+------------+-----------------+
| City name | Area | Population | Annual Rainfall |
+-----------+------+------------+-----------------+
| Adelaide | 1295 | 1158259 | 600.5 |
| Brisbane | 5905 | 1857594 | 1146.4 |
| Darwin | 112 | 120900 | 1714.7 |
| Hobart | 1357 | 205556 | 619.5 |
| Melbourne | 1566 | 3806092 | 646.9 |
| Perth | 5386 | 1554769 | 869.4 |
| Sydney | 2058 | 4336374 | 1214.8 |
+-----------+------+------------+-----------------+
=== One column at a time ===
You can also change the alignment of individual columns based on the
corresponding field name by treating the `align` attribute as if it were a
dictionary.
x.align["City name"] = "l"
x.align["Area"] = "c"
x.align["Population"] = "r"
x.align["Annual Rainfall"] = "c"
print x
gives:
+-----------+------+------------+-----------------+
| City name | Area | Population | Annual Rainfall |
+-----------+------+------------+-----------------+
| Adelaide | 1295 | 1158259 | 600.5 |
| Brisbane | 5905 | 1857594 | 1146.4 |
| Darwin | 112 | 120900 | 1714.7 |
| Hobart | 1357 | 205556 | 619.5 |
| Melbourne | 1566 | 3806092 | 646.9 |
| Perth | 5386 | 1554769 | 869.4 |
| Sydney | 2058 | 4336374 | 1214.8 |
+-----------+------+------------+-----------------+
== Sorting your table by a field ==
You can make sure that your ASCII tables are produced with the data sorted by
one particular field by giving `get_string` a `sortby` keyword argument, which
must be a string containing the name of one field.
For example, to print the example table we built earlier of Australian capital
city data, so that the most populated city comes last, we can do this:
print x.get_string(sortby="Population")
to get
+-----------+------+------------+-----------------+
| City name | Area | Population | Annual Rainfall |
+-----------+------+------------+-----------------+
| Darwin | 112 | 120900 | 1714.7 |
| Hobart | 1357 | 205556 | 619.5 |
| Adelaide | 1295 | 1158259 | 600.5 |
| Perth | 5386 | 1554769 | 869.4 |
| Brisbane | 5905 | 1857594 | 1146.4 |
| Melbourne | 1566 | 3806092 | 646.9 |
| Sydney | 2058 | 4336374 | 1214.8 |
+-----------+------+------------+-----------------+
If we want the most populated city to come _first_, we can also give a
`reversesort=True` argument.
If you _always_ want your tables to be sorted in a certain way, you can make
the setting long term like this:
x.sortby = "Population"
print x
print x
print x
All three tables printed by this code will be sorted by population (you could
do `x.reversesort = True` as well, if you wanted). The behaviour will persist
until you turn it off:
x.sortby = None
If you want to specify a custom sorting function, you can use the `sort_key`
keyword argument. Pass this a function which accepts two lists of values
and returns a negative or positive value depending on whether the first list
should appeare before or after the second one. If your table has n columns,
each list will have n+1 elements. Each list corresponds to one row of the
table. The first element will be whatever data is in the relevant row, in
the column specified by the `sort_by` argument. The remaining n elements
are the data in each of the table's columns, in order, including a repeated
instance of the data in the `sort_by` column.
= Changing the appearance of your table - the easy way =
By default, PrettyTable produces ASCII tables that look like the ones used in
SQL database shells. But if can print them in a variety of other formats as
well. If the format you want to use is common, PrettyTable makes this very
easy for you to do using the `set_style` method. If you want to produce an
uncommon table, you'll have to do things slightly harder (see later).
== Setting a table style ==
You can set the style for your table using the `set_style` method before any
calls to `print` or `get_string`. Here's how to print a table in a format
which works nicely with Microsoft Word's "Convert to table" feature:
from prettytable import MSWORD_FRIENDLY
x.set_style(MSWORD_FRIENDLY)
print x
In addition to `MSWORD_FRIENDLY` there are currently two other in-built styles
you can use for your tables:
* `DEFAULT` - The default look, used to undo any style changes you may have
made
* `PLAIN_COLUMN` - A borderless style that works well with command line
programs for columnar data
Other styles are likely to appear in future releases.
= Changing the appearance of your table - the hard way =
If you want to display your table in a style other than one of the in-built
styles listed above, you'll have to set things up the hard way.
Don't worry, it's not really that hard!
== Style options ==
PrettyTable has a number of style options which control various aspects of how
tables are displayed. You have the freedom to set each of these options
individually to whatever you prefer. The `set_style` method just does this
automatically for you.
The options are these:
* `border` - A boolean option (must be `True` or `False`). Controls whether
or not a border is drawn around the table.
* `header` - A boolean option (must be `True` or `False`). Controls whether
or not the first row of the table is a header showing the names of all the
fields.
* `hrules` - Controls printing of horizontal rules after rows. Allowed
values: FRAME, ALL, NONE - note that these are variables defined inside the
`prettytable` module so make sure you import them or use `prettytable.FRAME`
etc.
* `int_format` - A string which controls the way integer data is printed.
This works like: print "%<int_format>d" % data
* `float_format` - A string which controls the way floating point data is
printed. This works like: print "%<int_format>f" % data
* `padding_width` - Number of spaces on either side of column data (only used
if left and right paddings are None).
* `left_padding_width` - Number of spaces on left hand side of column data.
* `right_padding_width` - Number of spaces on right hand side of column data.
* `vertical_char` - Single character string used to draw vertical lines.
Default is `|`.
* `horizontal_char` - Single character string used to draw horizontal lines.
Default is `-`.
* `junction_char` - Single character string used to draw line junctions.
Default is `+`.
You can set the style options to your own settings in two ways:
== Setting style options for the long term ==
If you want to print your table with a different style several times, you can
set your option for the "long term" just by changing the appropriate
attributes. If you never want your tables to have borders you can do this:
x.border = False
print x
print x
print x
Neither of the 3 tables printed by this will have borders, even if you do
things like add extra rows inbetween them. The lack of borders will last until
you do:
x.border = True
to turn them on again. This sort of long term setting is exactly how
`set_style` works. `set_style` just sets a bunch of attributes to pre-set
values for you.
Note that if you know what style options you want at the moment you are
creating your table, you can specify them using keyword arguments to the
constructor. For example, the following two code blocks are equivalent:
x = PrettyTable()
x.border = False
x.header = False
x.padding_width = 5
x = PrettyTable(border=False, header=False, padding_width=5)
== Changing style options just once ==
If you don't want to make long term style changes by changing an attribute like
in the previous section, you can make changes that last for just one
``get_string`` by giving those methods keyword arguments. To print two
"normal" tables with one borderless table between them, you could do this:
print x
print x.get_string(border=False)
print x
= Displaying your table in HTML form =
PrettyTable will also print your tables in HTML form, as `<table>`s. Just like
in ASCII form, you can actually print your table - just use `print_html()` - or
get a string representation - just use `get_html_string()`. HTML printing
supports the `fields`, `start`, `end`, `sortby` and `reversesort` arguments in
exactly the same way as ASCII printing.
== Styling HTML tables ==
By default, PrettyTable outputs HTML for "vanilla" tables. The HTML code is
quite simple. It looks like this:
<table border="1">
<tr>
<th>City name</th>
<th>Area</th>
<th>Population</th>
<th>Annual Rainfall</th>
</tr>
<tr>
<td>Adelaide</td>
<td>1295</td>
<td>1158259</td>
<td>600.5</td>
<tr>
<td>Brisbane</td>
<td>5905</td>
<td>1857594</td>
<td>1146.4</td>
...
...
...
</table>
If you like, you can ask PrettyTable to do its best to mimick the style options
that your table has set using inline CSS. This is done by giving a
`format=True` keyword argument to either the `print_html` or `get_html_string`
methods. Note that if you _always_ want to print formatted HTML you can do:
x.format = True
and the setting will persist until you turn it off.
Just like with ASCII tables, if you want to change the table's style for just
one `print_html` or one `get_html_string` you can pass those methods keyword
arguments - exactly like `print` and `get_string`.
== Setting HTML attributes ==
You can provide a dictionary of HTML attribute name/value pairs to the
`print_html` and `get_html_string` methods using the `attributes` keyword
argument. This lets you specify common HTML attributes like `name`, `id` and
`class` that can be used for linking to your tables or customising their
appearance using CSS. For example:
x.print_html(attributes={"name":"my_table", "class":"red_table"})
will print:
<table border="1" name="my_table" class="red_table">
<tr>
<th>City name</th>
<th>Area</th>
<th>Population</th>
<th>Annual Rainfall</th>
</tr>
...
...
...
</table>
= Miscellaneous things =
== Copying a table ==
You can call the `copy` method on a PrettyTable object without arguments to
return an identical independent copy of the table.
If you want a copy of a PrettyTable object with just a subset of the rows,
you can use list slicing notation:
new_table = old_table[0:5]
prettytable (0.6-1) unstable; urgency=low
* New upstream release
* debian/rules
- remove python3 transformation commands, available upstream now
- run tests at build time
* debian/copyright
- reorganize information
* Ship unittest in debian/, no longer available in upstream tarball
-- Sandro Tosi <morph@debian.org> Sun, 06 May 2012 11:06:13 +0200
prettytable (0.5-2) unstable; urgency=low
* debian/control
......
......@@ -2,9 +2,15 @@ Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: prettytable
Source: http://code.google.com/p/prettytable/
Files: *
Files: * debian/prettytable_test.py
Copyright: Copyright (c) 2009, Luke Maurits <luke@maurits.id.au>
License:
License: BSD
Files: debian/*
Copyright: Copyright (C) 2009-2012 Sandro Tosi <morph@debian.org>
License: BSD
License: BSD
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
.
......@@ -28,6 +34,3 @@ License:
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Files: debian/*
Copyright: Copyright (C) 2009-2012 Sandro Tosi <morph@debian.org>
License: same terms as upstream code
import unittest
import sys
sys.path.append("../src/")
from math import pi, e, sqrt
from prettytable import *
class BuildEquivelanceTest(unittest.TestCase):
"""Make sure that building a table row-by-row and column-by-column yield the same results"""
def setUp(self):
# Row by row...
self.row = PrettyTable()
self.row.field_names = ["City name", "Area", "Population", "Annual Rainfall"]
self.row.add_row(["Adelaide",1295, 1158259, 600.5])
self.row.add_row(["Brisbane",5905, 1857594, 1146.4])
self.row.add_row(["Darwin", 112, 120900, 1714.7])
self.row.add_row(["Hobart", 1357, 205556, 619.5])
self.row.add_row(["Sydney", 2058, 4336374, 1214.8])
self.row.add_row(["Melbourne", 1566, 3806092, 646.9])
self.row.add_row(["Perth", 5386, 1554769, 869.4])
# Column by column...
self.col = PrettyTable()
self.col.add_column("City name",["Adelaide","Brisbane","Darwin","Hobart","Sydney","Melbourne","Perth"])
self.col.add_column("Area", [1295, 5905, 112, 1357, 2058, 1566, 5386])
self.col.add_column("Population", [1158259, 1857594, 120900, 205556, 4336374, 3806092, 1554769])
self.col.add_column("Annual Rainfall",[600.5, 1146.4, 1714.7, 619.5, 1214.8, 646.9, 869.4])
# A mix of both!
self.mix = PrettyTable()
self.mix.field_names = ["City name", "Area"]
self.mix.add_row(["Adelaide",1295])
self.mix.add_row(["Brisbane",5905])
self.mix.add_row(["Darwin", 112])
self.mix.add_row(["Hobart", 1357])
self.mix.add_row(["Sydney", 2058])
self.mix.add_row(["Melbourne", 1566])
self.mix.add_row(["Perth", 5386])
self.mix.add_column("Population", [1158259, 1857594, 120900, 205556, 4336374, 3806092, 1554769])
self.mix.add_column("Annual Rainfall",[600.5, 1146.4, 1714.7, 619.5, 1214.8, 646.9, 869.4])
def testRowColEquivalenceASCII(self):
self.assertEqual(self.row.get_string(), self.col.get_string())
def testRowMixEquivalenceASCII(self):
self.assertEqual(self.row.get_string(), self.mix.get_string())
def testRowColEquivalenceHTML(self):
self.assertEqual(self.row.get_html_string(), self.col.get_html_string())
def testRowMixEquivalenceHTML(self):
self.assertEqual(self.row.get_html_string(), self.mix.get_html_string())
#class FieldnamelessTableTest(unittest.TestCase):
#
# """Make sure that building and stringing a table with no fieldnames works fine"""
#
# def setUp(self):
# self.x = PrettyTable()
# self.x.add_row(["Adelaide",1295, 1158259, 600.5])
# self.x.add_row(["Brisbane",5905, 1857594, 1146.4])
# self.x.add_row(["Darwin", 112, 120900, 1714.7])
# self.x.add_row(["Hobart", 1357, 205556, 619.5])
# self.x.add_row(["Sydney", 2058, 4336374, 1214.8])
# self.x.add_row(["Melbourne", 1566, 3806092, 646.9])
# self.x.add_row(["Perth", 5386, 1554769, 869.4])
#
# def testCanStringASCII(self):
# self.x.get_string()
#
# def testCanStringHTML(self):
# self.x.get_html_string()
#
# def testAddFieldnamesLater(self):
# self.x.field_names = ["City name", "Area", "Population", "Annual Rainfall"]
# self.x.get_string()
class CityDataTest(unittest.TestCase):
"""Just build the Australian capital city data example table."""
def setUp(self):
self.x = PrettyTable(["City name", "Area", "Population", "Annual Rainfall"])
self.x.add_row(["Adelaide",1295, 1158259, 600.5])
self.x.add_row(["Brisbane",5905, 1857594, 1146.4])
self.x.add_row(["Darwin", 112, 120900, 1714.7])
self.x.add_row(["Hobart", 1357, 205556, 619.5])
self.x.add_row(["Sydney", 2058, 4336374, 1214.8])
self.x.add_row(["Melbourne", 1566, 3806092, 646.9])
self.x.add_row(["Perth", 5386, 1554769, 869.4])
class OptionOverrideTests(CityDataTest):
"""Make sure all options are properly overwritten by printt."""
def testBorder(self):
default = self.x.get_string()
override = self.x.get_string(border=False)
self.assertTrue(default != override)
def testHeader(self):
default = self.x.get_string()
override = self.x.get_string(header=False)
self.assertTrue(default != override)
def testHrulesAll(self):
default = self.x.get_string()
override = self.x.get_string(hrules=ALL)
self.assertTrue(default != override)
def testHrulesNone(self):
default = self.x.get_string()
override = self.x.get_string(hrules=NONE)
self.assertTrue(default != override)
class BasicTests(CityDataTest):
"""Some very basic tests."""
def testNoBlankLines(self):
"""No table should ever have blank lines in it."""
string = self.x.get_string()
lines = string.split("\n")
self.assertTrue("" not in lines)
def testAllLengthsEqual(self):
"""All lines in a table should be of the same length."""
string = self.x.get_string()
lines = string.split("\n")
lengths = [len(line) for line in lines]
lengths = set(lengths)
self.assertEqual(len(lengths),1)
class NoBorderBasicTests(BasicTests):
"""Run the basic tests with border = False"""
def setUp(self):
BasicTests.setUp(self)
self.x.border = False
class NoHeaderBasicTests(BasicTests):
"""Run the basic tests with header = False"""
def setUp(self):
BasicTests.setUp(self)
self.x.header = False
class HrulesNoneBasicTests(BasicTests):
"""Run the basic tests with hrules = NONE"""
def setUp(self):
BasicTests.setUp(self)
self.x.hrules = NONE
class HrulesAllBasicTests(BasicTests):
"""Run the basic tests with hrules = ALL"""
def setUp(self):
BasicTests.setUp(self)
self.x.hrules = ALL
class PresetBasicTests(BasicTests):
"""Run the basic tests after using set_style"""
def setUp(self):
BasicTests.setUp(self)
self.x.set_style(MSWORD_FRIENDLY)
class SlicingTests(CityDataTest):
def setUp(self):
CityDataTest.setUp(self)
def testSliceFirstTwoRows(self):
y = self.x[0:2]
string = y.get_string()
assert len(string.split("\n")) == 6
assert "Adelaide" in string
assert "Brisbane" in string
assert "Melbourne" not in string
assert "Perth" not in string
def testSliceLastTwoRows(self):
y = self.x[-2:]
string = y.get_string()
assert len(string.split("\n")) == 6
assert "Adelaide" not in string
assert "Brisbane" not in string
assert "Melbourne" in string
assert "Perth" in string
class SortingTests(CityDataTest):
def setUp(self):
CityDataTest.setUp(self)
def testSortBy(self):
self.x.sortby = self.x.field_names[0]
old = self.x.get_string()
for field in self.x.field_names[1:]:
self.x.sortby = field
new = self.x.get_string()
assert new != old
def testReverseSort(self):
for field in self.x.field_names:
self.x.sortby = field
self.x.reversesort = False
forward = self.x.get_string()
self.x.reversesort = True
backward = self.x.get_string()
forward_lines = forward.split("\n")[2:] # Discard header lines
backward_lines = backward.split("\n")[2:]
backward_lines.reverse()
assert forward_lines == backward_lines
def testSortKey(self):
# Test sorting by length of city name
def key(vals):
vals[0] = len(vals[0])
return vals
self.x.sortby = "City name"
self.x.sort_key = key
assert self.x.get_string().strip() == """+-----------+------+------------+-----------------+
| City name | Area | Population | Annual Rainfall |
+-----------+------+------------+-----------------+
| Perth | 5386 | 1554769 | 869.4 |
| Darwin | 112 | 120900 | 1714.7 |
| Hobart | 1357 | 205556 | 619.5 |
| Sydney | 2058 | 4336374 | 1214.8 |
| Adelaide | 1295 | 1158259 | 600.5 |