Adding upstream version 3.1.0.upstream/3.1.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

19 files changed, 470 insertions, 0 deletions

diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
new file mode 100644
index 0000000..f78ddc4
--- /dev/null
+++ b/docs/_templates/layout.html
@@ -0,0 +1,6 @@
+{# From https://github.com/snide/sphinx_rtd_theme/issues/166 #}
+
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ['_static/pygments.css'] %}
diff --git a/docs/asciitable.png b/docs/asciitable.png
new file mode 100644
index 0000000..97ae271
--- /dev/null
+++ b/docs/asciitable.png
diff --git a/docs/asciitable.rst b/docs/asciitable.rst
new file mode 100644
index 0000000..d5120f3
--- /dev/null
+++ b/docs/asciitable.rst
@@ -0,0 +1,16 @@
+.. _asciitable:
+
+==========
+AsciiTable
+==========
+
+AsciiTable is the simplest table. It uses ``+``, ``|``, and ``-`` characters to build the borders.
+
+.. image:: asciitable.png
+    :target: _images/asciitable.png
+
+API
+===
+
+.. autoclass:: terminaltables.AsciiTable
+    :members: column_max_width, column_widths, ok, table_width, table
diff --git a/docs/changelog.rst b/docs/changelog.rst
new file mode 100644
index 0000000..0b9ff7b
--- /dev/null
+++ b/docs/changelog.rst
@@ -0,0 +1,5 @@
+.. _changelog:
+
+.. include:: ../README.rst
+    :start-after: changelog-section-start
+    :end-before: changelog-section-end
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..fb33f09
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,53 @@
+"""Sphinx configuration file."""
+
+import os
+import sys
+import time
+
+
+# General configuration.
+sys.path.append(os.path.realpath(os.path.join(os.path.dirname(__file__), '..')))
+author = '@Robpol86'
+copyright = '{}, {}'.format(time.strftime('%Y'), author)
+master_doc = 'index'
+project = __import__('setup').NAME
+pygments_style = 'friendly'
+release = version = __import__('setup').VERSION
+templates_path = ['_templates']
+extensions = list()
+
+
+# Options for HTML output.
+html_context = dict(
+    conf_py_path='/docs/',
+    display_github=True,
+    github_repo=os.environ.get('TRAVIS_REPO_SLUG', '/' + project).split('/', 1)[1],
+    github_user=os.environ.get('TRAVIS_REPO_SLUG', 'robpol86/').split('/', 1)[0],
+    github_version=os.environ.get('TRAVIS_BRANCH', 'master'),
+    source_suffix='.rst',
+)
+html_copy_source = False
+html_favicon = 'favicon.ico'
+html_theme = 'sphinx_rtd_theme'
+html_title = project
+
+
+# autodoc
+extensions.append('sphinx.ext.autodoc')
+
+
+# extlinks.
+extensions.append('sphinx.ext.extlinks')
+extlinks = {'github': ('https://github.com/robpol86/{0}/blob/v{1}/%s'.format(project, version), '')}
+
+
+# google analytics
+extensions.append('sphinxcontrib.googleanalytics')
+googleanalytics_id = 'UA-82627369-1'
+
+
+# SCVersioning.
+scv_banner_greatest_tag = True
+scv_grm_exclude = ('.gitignore', '.nojekyll', 'README.rst')
+scv_show_banner = True
+scv_sort = ('semver', 'time')
diff --git a/docs/doubletable.png b/docs/doubletable.png
new file mode 100644
index 0000000..ce532a1
--- /dev/null
+++ b/docs/doubletable.png
diff --git a/docs/doubletable.rst b/docs/doubletable.rst
new file mode 100644
index 0000000..da322ab
--- /dev/null
+++ b/docs/doubletable.rst
@@ -0,0 +1,33 @@
+.. _doubletable:
+
+===========
+DoubleTable
+===========
+
+DoubleTable uses `box drawing characters`_ for table borders. On Windows terminaltables uses `code page 437`_
+characters. However there is no equivalent character set for POSIX (Linux/OS X). Python automatically converts CP437
+double-line box characters to Unicode and displays that instead.
+
+.. image:: doubletable.png
+    :target: _images/doubletable.png
+
+Gaps on Windows 10
+==================
+
+Like SingleTable the console on Windows 10 changed the default font face to ``Consolas``. This new font seems to show
+gaps between lines. Switching the font back to ``Lucida Console`` eliminates the gaps.
+
+Gaps on POSIX
+=============
+
+There is no easy trick for POSIX like there is on Windows. I can't seem to find out how to force terminals to eliminate
+gaps vertically between Unicode characters.
+
+API
+===
+
+.. autoclass:: terminaltables.DoubleTable
+    :members: column_max_width, column_widths, ok, table_width, table
+
+.. _box drawing characters: https://en.wikipedia.org/wiki/Box-drawing_character
+.. _code page 437: https://en.wikipedia.org/wiki/Code_page_437
diff --git a/docs/examples.png b/docs/examples.png
new file mode 100644
index 0000000..62a623c
--- /dev/null
+++ b/docs/examples.png
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 0000000..8cf8947
--- /dev/null
+++ b/docs/favicon.ico
diff --git a/docs/githubtable.png b/docs/githubtable.png
new file mode 100644
index 0000000..0b2a6a3
--- /dev/null
+++ b/docs/githubtable.png
diff --git a/docs/githubtable.rst b/docs/githubtable.rst
new file mode 100644
index 0000000..ba53218
--- /dev/null
+++ b/docs/githubtable.rst
@@ -0,0 +1,27 @@
+.. _githubtable:
+
+===========================
+GithubFlavoredMarkdownTable
+===========================
+
+GithubFlavoredMarkdownTable was initially implemented bcho_. It produces a `GitHub Flavored Markdown`_ formatted table.
+
+Because there are no outer table borders:
+
+* Table titles are ignored.
+* Border display toggles are also ignored.
+
+.. image:: githubtable.png
+    :target: _images/githubtable.png
+
+.. image:: githubtable_rendered.png
+    :target: _images/githubtable_rendered.png
+
+API
+===
+
+.. autoclass:: terminaltables.GithubFlavoredMarkdownTable
+    :members: column_max_width, column_widths, ok, table_width, table
+
+.. _bcho: https://github.com/Robpol86/terminaltables/pull/12
+.. _GitHub Flavored Markdown: https://help.github.com/categories/writing-on-github
diff --git a/docs/githubtable_rendered.png b/docs/githubtable_rendered.png
new file mode 100644
index 0000000..319bbcb
--- /dev/null
+++ b/docs/githubtable_rendered.png
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..002ca17
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,77 @@
+========================
+terminaltables |version|
+========================
+
+Easily draw tables in terminal/console applications from a list of lists of strings. As easy as:
+
+.. code-block:: pycon
+
+    >>> from terminaltables import AsciiTable
+    >>> table_data = [
+    ... ['Heading1', 'Heading2'],
+    ... ['row1 column1', 'row1 column2'],
+    ... ['row2 column1', 'row2 column2'],
+    ... ['row3 column1', 'row3 column2'],
+    ... ]
+    >>> table = AsciiTable(table_data)
+    >>> print table.table
+    +--------------+--------------+
+    | Heading1     | Heading2     |
+    +--------------+--------------+
+    | row1 column1 | row1 column2 |
+    | row2 column1 | row2 column2 |
+    | row3 column1 | row3 column2 |
+    +--------------+--------------+
+
+.. figure:: examples.png
+    :target: _images/examples.png
+
+    Windows 10, Windows XP, and OS X are also supported. View source: :github:`example1.py`, :github:`example2.py`,
+    :github:`example3.py`
+
+Features
+========
+
+* Multi-line rows: add newlines to table cells and terminatables will handle the rest.
+* Table titles: show a title embedded in the top border of the table.
+* POSIX: Python 2.6, 2.7, PyPy, PyPy3, 3.3, 3.4, and 3.5 supported on Linux and OS X.
+* Windows: Python 2.7, 3.3, 3.4, and 3.5 supported on Windows XP through 10.
+* CJK: Wide Chinese/Japanese/Korean characters displayed correctly.
+* RTL: Arabic and Hebrew characters aligned correctly.
+* Alignment/Justification: Align individual columns left, center, or right.
+* Colored text: colorclass_, colorama_, termcolor_, or just plain `ANSI escape codes`_.
+
+Project Links
+=============
+
+* Documentation: https://robpol86.github.io/terminaltables
+* Source code: https://github.com/Robpol86/terminaltables
+* PyPI homepage: https://pypi.python.org/pypi/terminaltables
+
+.. toctree::
+    :maxdepth: 2
+    :caption: General
+
+    install
+    quickstart
+    settings
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Table Styles
+
+    asciitable
+    singletable
+    doubletable
+    githubtable
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Appendix
+
+    changelog
+
+.. _colorclass: https://github.com/Robpol86/colorclass
+.. _colorama: https://github.com/tartley/colorama
+.. _termcolor: https://pypi.python.org/pypi/termcolor
+.. _ANSI escape codes: http://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/x329.html
diff --git a/docs/install.rst b/docs/install.rst
new file mode 100644
index 0000000..ea0bfae
--- /dev/null
+++ b/docs/install.rst
@@ -0,0 +1,38 @@
+.. _install:
+
+============
+Installation
+============
+
+Getting started is pretty simple. The first step is to install the library.
+
+Pip Install
+===========
+
+The easiest way to get terminaltables is to use `pip <https://pip.pypa.io>`_. Simply run this command.
+
+.. code-block:: bash
+
+    pip install terminaltables
+
+Latest from GitHub
+==================
+
+You can also elect to install the latest bleeding-edge version by using pip to install directly from the GitHub
+repository.
+
+.. code-block:: bash
+
+    pip install git+https://github.com/Robpol86/terminaltables.git
+
+Clone and Install
+=================
+
+Lastly you can also just clone the repo and install from it. Usually you only need to do this if you plan on
+`contributing <https://github.com/Robpol86/terminaltables/blob/master/CONTRIBUTING.md>`_ to the project.
+
+.. code-block:: bash
+
+    git clone https://github.com/Robpol86/terminaltables.git
+    cd terminaltables
+    python setup.py install
diff --git a/docs/key.enc b/docs/key.enc
new file mode 100644
index 0000000..f485db2
--- /dev/null
+++ b/docs/key.enc
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
new file mode 100644
index 0000000..83e9ee8
--- /dev/null
+++ b/docs/quickstart.rst
@@ -0,0 +1,110 @@
+.. _quickstart:
+
+==========
+Quickstart
+==========
+
+This section will go over the basics of terminaltables.
+
+Make sure that you've already :ref:`installed <install>` it.
+
+Table with Default Settings
+===========================
+
+Let's begin by importing AsciiTable, which just uses ``+``, ``-``, and ``|`` characters.
+
+.. code-block:: pycon
+
+    >>> from terminaltables import AsciiTable
+
+Now let's define the table data in a variable called ``data``. We'll do it the long way by creating an empty list
+representing the entire table. Then we'll add rows one by one. Each row is a list representing table cells.
+
+.. code-block:: pycon
+
+    >>> data = []
+    >>> data.append(['Row one column one', 'Row one column two'])
+    >>> data.append(['Row two column one', 'Row two column two'])
+    >>> data.append(['Row three column one', 'Row three column two'])
+
+Next we can use AsciiTable to format the table properly and then we can just print it. ``table.table`` gives you just
+one long string with newline characters so you can easily print it.
+
+.. code-block:: pycon
+
+    >>> table = AsciiTable(data)
+    >>> print table.table
+    +----------------------+----------------------+
+    | Row one column one   | Row one column two   |
+    +----------------------+----------------------+
+    | Row two column one   | Row two column two   |
+    | Row three column one | Row three column two |
+    +----------------------+----------------------+
+
+By default the first row of the table is considered the heading. This can be turned off.
+
+Changing Table Settings
+=======================
+
+There are more options available to change how your tables are formatted. Say your table doesn't really have a heading
+row; all rows are just data.
+
+.. code-block:: pycon
+
+    >>> table.inner_heading_row_border = False
+    >>> print table.table
+    +----------------------+----------------------+
+    | Row one column one   | Row one column two   |
+    | Row two column one   | Row two column two   |
+    | Row three column one | Row three column two |
+    +----------------------+----------------------+
+
+Now you want to add a title to the table:
+
+.. code-block:: pycon
+
+    >>> table.title = 'My Table'
+    >>> print table.table
+    +My Table--------------+----------------------+
+    | Row one column one   | Row one column two   |
+    | Row two column one   | Row two column two   |
+    | Row three column one | Row three column two |
+    +----------------------+----------------------+
+
+Maybe you want lines in between all rows:
+
+.. code-block:: pycon
+
+    >>> table.inner_row_border = True
+    >>> print table.table
+    +My Table--------------+----------------------+
+    | Row one column one   | Row one column two   |
+    +----------------------+----------------------+
+    | Row two column one   | Row two column two   |
+    +----------------------+----------------------+
+    | Row three column one | Row three column two |
+    +----------------------+----------------------+
+
+There are many more settings available. You can find out more by reading the :ref:`settings` section. Each table style
+pretty much shares the same settings but there are a few minor exceptions. Refer to each table style's documentation on
+the sidebar.
+
+Other Table Styles
+==================
+
+Terminaltables comes with a few other table styles than just ``AsciiTable``. All table styles more or less have the same
+API.
+
+.. code-block:: pycon
+
+    >>> from terminaltables import SingleTable
+    >>> table = SingleTable(data)
+    >>> print table.table
+    ┌──────────────────────┬──────────────────────┐
+    │ Row one column one   │ Row one column two   │
+    ├──────────────────────┼──────────────────────┤
+    │ Row two column one   │ Row two column two   │
+    │ Row three column one │ Row three column two │
+    └──────────────────────┴──────────────────────┘
+
+You can find documentation for all table styles on the sidebar.
diff --git a/docs/settings.rst b/docs/settings.rst
new file mode 100644
index 0000000..c609d1f
--- /dev/null
+++ b/docs/settings.rst
@@ -0,0 +1,79 @@
+.. _settings:
+
+========
+Settings
+========
+
+All tables (except :ref:`githubtable`) have the same settings to change the way the table is displayed. These attributes
+are available after instantiation.
+
+.. py:attribute:: Table.table_data
+
+    The actual table data to render. This must be a list (or tuple) of lists of strings. The outer list holds the rows
+    and the inner lists holds the cells (aka columns in that row).
+
+    Example:
+
+    .. code-block:: python
+
+        table.table_data = [
+            ['Name', 'Color', 'Type'],
+            ['Avocado', 'green', 'nut'],
+            ['Tomato', 'red', 'fruit'],
+            ['Lettuce', 'green', 'vegetable'],
+        ]
+
+.. py:attribute:: Table.title
+
+    Optional title to show within the top border of the table. This is ignored if None or a blank string.
+
+.. py:attribute:: Table.inner_column_border
+
+    Toggles the column dividers. Set to **False** to disable these vertically dividing borders.
+
+.. py:attribute:: Table.inner_footing_row_border
+
+    Show a horizontal dividing border before the last row. If **True** this defines the last row as the table footer.
+
+.. py:attribute:: Table.inner_heading_row_border
+
+    Show a horizontal dividing border after the first row. If **False** this removes the border so the first row is no
+    longer considered a header row. It'll look just like any other row.
+
+.. py:attribute:: Table.inner_row_border
+
+    If **True** terminaltables will show dividing borders between every row.
+
+.. py:attribute:: Table.outer_border
+
+    Toggles the four outer borders. If **False** the top, left, right, and bottom borders will not be shown.
+
+.. py:attribute:: Table.justify_columns
+
+    Aligns text in entire columns. The keys in this dict are column integers (0 for the first column) and the values
+    are either 'left', 'right', or 'center'. Left is the default.
+
+    Example:
+
+    .. code-block:: pycon
+
+        >>> table.justify_columns[0] = 'right'  # Name column.
+        >>> table.justify_columns[1] = 'center'  # Color column.
+        >>> print table.table
+        +---------+-------+-----------+
+        |    Name | Color | Type      |
+        +---------+-------+-----------+
+        | Avocado | green | nut       |
+        |  Tomato |  red  | fruit     |
+        | Lettuce | green | vegetable |
+        +---------+-------+-----------+
+
+.. py:attribute:: Table.padding_left
+
+    Number of spaces to pad on the left side of every cell. Default is **1**. Padding adds spacing between the cell text
+    and the column border.
+
+.. py:attribute:: Table.padding_right
+
+    Number of spaces to pad on the right side of every cell. Default is **1**. Padding adds spacing between the cell
+    text and the column border.
diff --git a/docs/singletable.png b/docs/singletable.png
new file mode 100644
index 0000000..cc595ff
--- /dev/null
+++ b/docs/singletable.png
diff --git a/docs/singletable.rst b/docs/singletable.rst
new file mode 100644
index 0000000..9d6313b
--- /dev/null
+++ b/docs/singletable.rst
@@ -0,0 +1,26 @@
+.. _singletable:
+
+===========
+SingleTable
+===========
+
+SingleTable uses `box drawing characters`_ for table borders. On POSIX (Linux/OS X) terminaltables uses ``Esc ( 0``
+characters while on Windows it uses `code page 437`_ characters.
+
+.. image:: singletable.png
+    :target: _images/singletable.png
+
+Gaps on Windows 10
+==================
+
+Unfortunately the console on Windows 10 changed the default font face to ``Consolas``. This new font seems to show gaps
+between lines. Switching the font back to ``Lucida Console`` eliminates the gaps.
+
+API
+===
+
+.. autoclass:: terminaltables.SingleTable
+    :members: column_max_width, column_widths, ok, table_width, table
+
+.. _box drawing characters: https://en.wikipedia.org/wiki/Box-drawing_character
+.. _code page 437: https://en.wikipedia.org/wiki/Code_page_437