diff options
author | kxxoling <kxxoling@gmail.com> | 2015-07-25 20:56:34 +0800 |
---|---|---|
committer | kxxoling <kxxoling@gmail.com> | 2015-07-25 20:58:54 +0800 |
commit | c401f910f05882ddb761707fb257a04b6be0bdc4 (patch) | |
tree | 46d81cdf125bd351c134c6207c3398db46a1b60e | |
parent | d1b50cfb7db88183953f7397c62aca1a6fe72348 (diff) | |
download | python-prettytable-ptable-c401f910f05882ddb761707fb257a04b6be0bdc4.tar.gz |
Reorganoze project documentation
-rw-r--r-- | README.rst | 617 |
1 files changed, 41 insertions, 576 deletions
@@ -1,6 +1,6 @@ -=============== -PTable Tutorial -=============== +============ +About PTable +============ PTable is a simple Python library designed to make it quick and easy to represent tabular data in visually appealing ASCII tables, originally @@ -18,608 +18,73 @@ forked from `PrettyTable <https://code.google.com/p/prettytable/>`_ . :target: https://pypi.python.org/pypi/PTable/ :alt: Downloads -**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** +Installation +============ -Links -===== +As PTable is a fork of PrettyTable, and compatible to all its APIs, +so PTable is usage is the same as PrettyTable, and the installation +would cover on the original PrettyTable. -* `Source Code (GitHub) <https://github.com/kxxoling/PrettyTable>`_ -* `PyPI <https://pypi.python.org/pypi/ptabl://pypi.python.org/pypi/ptable>`_ -* `RTFD <https://ptable.readthedocs.org>`_ +As always, you can install PTable in 3 ways. +Via pip(recommend):: -Getting your data into (and out of) the table -============================================= + pip install PTable -Let's suppose you have a shiny new PrettyTable: +Via easy_install:: -:: + easy_install PTable - from prettytable import PrettyTable - x = PrettyTable() - -and you want to put some data into it. You have a few options. - -Row by row ----------- - -You can add data one row at a time. To do this you can set the field -names first using the ``field_names`` attribute, and then add the rows -one at a time using the ``add_row`` method: - -:: - - x.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. - -Importing data from a CSV file ------------------------------- - -If you have your table data in a comma separated values file (.csv), you -can read this data into a PrettyTable like this: - -:: - - from prettytable import from_csv - fp = open("myfile.csv", "r") - mytable = from_csv(fp) - fp.close() - -Importing data from a database cursor -------------------------------------- - -If you have your table data in a database which you can access using a -library which confirms to the Python DB-API (e.g. an SQLite database -accessible using the sqlite module), then you can build a PrettyTable -using a cursor object, like this: - -:: - - import sqlite3 - from prettytable import from_cursor - - connection = sqlite3.connect("mydb.db") - cursor = connection.cursor() - cursor.execute("SELECT field1, field2, field3 FROM my_table") - mytable = from_cursor(cursor) - -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 +From source:: -in Python 2.x or: + python setup.py install -:: - print(x) +Quick start +=========== -in Python 3.x. +PTable supports two kinds of usage: -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: +As a library +------------ -:: +PTable library API is almost as PrettyTable, you can import the same API from +``prettytable`` library: - print x.get_string() +.. code-block:: python -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 -~~~~~~~~~~~~~~~~~~~~ + from prettytable import PrettyTable + x = PrettyTable() -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. +A better hosted document is hosted on `ReadTheDocument <http://ptable.readthedocs.org/?`_ . -:: - x.align["City name"] = "l" - x.align["Area"] = "c" - x.align["Population"] = "r" - x.align["Annual Rainfall"] = "c" - print x +As command-line tool +-------------------- -gives: +This is an original function of PTable, can be used as ``ptable`` command: -:: +.. code-block:: shell - +-----------+------+------------+-----------------+ - | 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. + ptable --csv somefile.csv -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: +or a unix style pipe: -:: +.. code-block:: shell - print x.get_string(sortby="Population") + cat somefile.csv | ptable -to get +Will both print a ASCII table in terminal. -:: - +-----------+------+------------+-----------------+ - | 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, HEADER, ALL, NONE - note that these are - variables defined > > inside the ``prettytable`` module so make sure - you import them or use > > ``prettytable.FRAME`` etc. -- ``vrules`` - Controls printing of vertical rules between columns. - Allowed > > values: FRAME, ALL, NONE. -- ``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: - -:: +Relative links +============== - 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> - <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 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. +* `Source Code (GitHub) <https://github.com/kxxoling/PrettyTable>`__ +* `RTFD <https://ptable.readthedocs.org>`__ +* `PyPI <https://pypi.python.org/pypi/ptabl://pypi.python.org/pypi/ptable>`__ +* `PrettyTable <https://code.google.com/p/prettytable/>`_ -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] |