Merge branch 'develop'

3 files changed, 70 insertions, 576 deletions

diff --git a/README.rst b/README.rst
index 6408e5e..f959050 100644
--- a/README.rst
+++ b/README.rst
@@ -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]
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/tests/__init__.py
diff --git a/tests/test_utils.py b/tests/test_utils.py
new file mode 100644
index 0000000..6ed710b
--- /dev/null
+++ b/tests/test_utils.py
@@ -0,0 +1,29 @@
+# -*- coding:utf-8 -*-
+from __future__ import unicode_literals
+import unittest
+
+from prettytable.prettytable import _char_block_width
+
+
+
+def _width_test_factory(width, words):
+    def _(self):
+        map(lambda x: self.assertEqual(width, _char_block_width(ord(x))),
+            list(words))
+    return _
+
+
+class CharBlockWidthTest(unittest.TestCase):
+    fixtures = {
+        'normal': (1, '12345qwerljk/.,WESD'),
+        'chs': (2, '石室诗士施氏嗜狮誓食十狮'),
+        'jp': (2, 'はじめまして'),
+        'hangul': (2, '우리글자언문청'),
+        'full_width_latin': (2, 'ＸＹＺ［＼］＾＿ｘｙｚ｛｜｝～｟'),
+        # 'cjk': (2, u''),
+    }
+
+    def test_fixtures(self):
+        for name in self.fixtures:
+            _width_test_factory(*self.fixtures[name])(self)
+