diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 00000000..22805d76 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,4 @@ +include COPYING +include CHANGELOG +include README +include prettytable_test.py diff --git a/README b/README new file mode 100644 index 00000000..c1d94c57 --- /dev/null +++ b/README @@ -0,0 +1,462 @@ +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 "%d" % data + * `float_format` - A string which controls the way floating point data is + printed. This works like: print "%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 ``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: + +
+ + + + + + + + + + + + + + + + + ... + ... + ... +
City nameAreaPopulationAnnual Rainfall
Adelaide12951158259600.5
Brisbane590518575941146.4
+ +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: + + + + + + + + + ... + ... + ... +
City nameAreaPopulationAnnual Rainfall
+ += 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] diff --git a/src/prettytable.py b/prettytable.py similarity index 99% rename from src/prettytable.py rename to prettytable.py index f421988b..e6794a55 100644 --- a/src/prettytable.py +++ b/prettytable.py @@ -83,7 +83,6 @@ def __init__(self, field_names=None, **kwargs): field_names - list or tuple of field names fields - list or tuple of field names to include in displays - caching - boolean value to turn string caching on/off start - index of first data row to include in output end - index of last data row to include in output PLUS ONE (list slice style) fields - names of fields (columns) to include @@ -114,7 +113,7 @@ def __init__(self, field_names=None, **kwargs): self._rows = [] # Options - self._options = "start end fields header border sortby reversesort sort_key attributes format hrules caching".split() + self._options = "start end fields header border sortby reversesort sort_key attributes format hrules".split() self._options.extend("int_format float_format padding_width left_padding_width right_padding_width".split()) self._options.extend("vertical_char horizontal_char junction_char".split()) for option in self._options: @@ -123,7 +122,6 @@ def __init__(self, field_names=None, **kwargs): else: kwargs[option] = None - self._caching = kwargs["caching"] or True self._start = kwargs["start"] or 0 self._end = kwargs["end"] or None @@ -206,7 +204,7 @@ def _validate_option(self, option, val): self._validate_hrules(option, val) elif option in ("fields"): self._validate_all_field_names(option, val) - elif option in ("header", "border", "caching", "reversesort"): + elif option in ("header", "border", "reversesort"): self._validate_true_or_false(option, val) elif option in ("int_format"): self._validate_int_format(option, val) diff --git a/src/prettytable_test.py b/prettytable_test.py similarity index 100% rename from src/prettytable_test.py rename to prettytable_test.py diff --git a/src/setup.py b/setup.py similarity index 87% rename from src/setup.py rename to setup.py index 458ab593..157b6202 100644 --- a/src/setup.py +++ b/setup.py @@ -13,9 +13,11 @@ 'License :: OSI Approved :: BSD License', 'Topic :: Text Processing' ], + license="BSD (3 clause)", description='A simple Python library for easily displaying tabular data in a visually appealing ASCII table format', author='Luke Maurits', author_email='luke@maurits.id.au', url='http://code.google.com/p/prettytable', - py_modules=['prettytable'] + py_modules=['prettytable'], + test_suite = "prettytable_test" )