Metadata-Version: 1.1
Name: monotable
Version: 1.0.2
Summary: ASCII table with per column format specs, multi-line content, plug-in format functions, column width control.
Home-page: https://github.com/tmarktaylor/monotable
Author: Mark Taylor
Author-email: mark66547ta2@gmail.com
License: Apache 2.0
Description: .. |apache| image:: https://img.shields.io/pypi/l/monotable.svg
           :target: http://www.apache.org/licenses/LICENSE-2.0
           :alt: License: Apache 2.0
        
        .. |py_versions| image::
            https://img.shields.io/pypi/pyversions/monotable.svg
            :target: https://pypi.python.org/pypi/monotable
            :alt: Python versions supported
        
        |apache| |py_versions|
        
        .. This file is used by Sphinx and for the setup.py long_description.
        .. The examples are doctested by Sphinx.
        .. The doctest directives here are replaced when setup.py creates
        .. the setup() argument long_description.
        
        .. _Format Specification Mini-Language:
           https://docs.python.org
           /3/library/string.html#format-specification-mini-language
        .. _Format String Syntax:
           https://docs.python.org/3/library/string.html#format-string-syntax
        .. _Template Strings:
           https://docs.python.org/3/library/string.html#template-strings
        .. _Printf Style:
           https://docs.python.org
           /3/library/stdtypes.html#printf-style-string-formatting
        .. _Apache 2.0:
           http://www.apache.org/licenses/LICENSE-2.0
        .. _Documentation:
           https://monotable.readthedocs.io/en/latest//index.html
        .. _More Examples:
           https://monotable.readthedocs.io/en/latest/more_examples.html
        .. _Read the Docs:
           https://readthedocs.org
        .. _Repository:
           https://github.com/tmarktaylor/monotable
        .. _Issue Tracker:
           https://github.com/tmarktaylor/monotable/issues
        .. _Python Package Index/monotable:
           https://pypi.python.org/pypi/monotable
        .. _Master branch build status, coverage, testing:
           https://github.com/tmarktaylor/monotable/blob/master/README.md
        
        Introduction
        ============
        
        monotable is a Python library that generates an ASCII table from
        tabular data that looks *pretty* when printed in a monospaced font.
        
        monotable eliminates the need to pre-format
        your data objects before generating the table.
        
        monotable will do the formatting for you using your format function
        or one of its own general purpose format functions; on a per column basis.
        
        monotable handles multi-line content.
        
        monotable is *thoroughly* documented and tested.
        
        First Example
        -------------
        
        .. code:: python
        
            import monotable
            headings = ['int', 'percent']
            formats = [',', '.1%']
            t1 = monotable.MonoTable(headings, formats)
            cells = [[123456789, 0.33], [2345678, 0.995]]
            print(t1.table(cells,
                           title='=Comma and percent formats.'))
        
        .. code::
        
             Comma and percent
                  formats.
            --------------------
                    int  percent
            --------------------
            123,456,789    33.0%
              2,345,678    99.5%
            --------------------
        
        - The built-in function **format(value, format_spec)** is used by default
          for each column.
        - The string in the list **formats** is passed as format_spec for the column.
        - To write a format_spec, consult Python's
          `Format Specification Mini-Language`_.
        
        Installation
        ------------
        
        ::
        
            pip install monotable
        
        
        Links to License, Docs, Repos, Issues, PYPI page
        ------------------------------------------------
        - License: `Apache 2.0`_
        - Full `Documentation`_ on `Read the Docs`_
        - `Repository`_
        - `Issue Tracker`_
        - `Python Package Index/monotable`_
        - `Master branch build status, coverage, testing`_
        
        Description
        -----------
        
        You can specify the format spec and the format function on a per column
        basis as needed.
        
        These format functions are available:
        
           - The default is built-in function **format**\ (value, format_spec).
           - An unlimited number of user defined plug-in format functions.
           - An adapter to standard library string.format().
           - An adapter to pass a mapping to string.format().
           - An adapter to percent operator % formatting.
           - An adapter to standard library Template.substitute().
        
        When custom formatting code is needed for an object type,
        put it in a plug-in format function and reuse it in other tables that
        process the same type.
        
        monotable supports multi-line content in headings, formatted cells,
        and titles.
        
        monotable can limit column width on a per column basis and
        truncates or wraps the text to fit.  Maximum cell height
        is configurable.  A more marker is placed to show where text was omitted.
        
        monotable auto-aligns each column.  Auto-alignment is overridden by
        using one of ``'<'``, ``'^'``, ``'>'`` prefixes
        on a heading string, format string, or title.
        
        monotable does not do the following:
        
            - Produce terminal graphics characters.  Try PYPI terminaltables.
            - Produce markup source text.  Try PYPI tabulate instead.
            - Handle CJK wide characters.
            - Handle ANSI escape terminal color sequences. Try PYPI terminaltables.
        
        However, monotable does make the output of its formatting and
        alignment engine available in list form.  Please look for the function
        **MonoTable.row_strings()** in the API documentation.
        
        More features are described in the documentation section
        'Full List of Features'.
        
        .. Reserved for recognizing contributors
        .. Contributors
        .. ============
        
        Recent Changes
        ==============
        1.0.2 - 2017-04-06
        
        - Bug fix, incorrect cell auto-alignment when mixed types in a column.
        - Bug fix, format_none_as cell ignoring column format string's align_spec.
        - Remove and re-add files to git index so stored with LFs.
        - Add complexity inspections to CI.
        - Refactor 2 functions to reduce McCabe complexity.
        - Code inspection fixes.  Docs and comments fixed.
        
        1.0.1 - 2017-03-26
        
        - MANIFEST.in and doc fixes.
        
        1.0.0 - 2017-03-25
        
        - Initial upload.
        
        
        
        Examples
        ========
        
        Per column formatting with format spec
        --------------------------------------
        
        In the example below formats is a list of format strings, one for each column.
        Format strings are assigned to columns from left to right.
        
        .. code:: python
        
            import datetime
            import monotable
        
            d = datetime.datetime(2016, 9, 16)
        
            headings = ['precision\n1', 'precision\n3', 'default', '9/16/16']
            formats = ['.1f', '.3f', '', 'week-%U-day-%j']
            t2 = monotable.MonoTable(headings, formats)
        
            cells = [[1.23456789,   1.23456789,   1.23456789, d],
                     [999.87654321, 999.87654321, 999.87654321, None]]
        
            print(t2.table(cells, title='Different float precisions.'))
        
        .. code::
        
                       Different float precisions.
            -------------------------------------------------
            precision  precision
                    1          3     default  9/16/16
            -------------------------------------------------
                  1.2      1.235    1.234568  week-37-day-260
                999.9    999.877  999.876543
            -------------------------------------------------
        
        - For type float, when the format_spec is empty, a default format_spec
          of ``'.6f'`` is used.  This is configurable.
        - Auto-alignment is right justifying a cell that is an instance of
          numbers.Number.
        - Auto alignment aligns the heading the same way as the alignment of
          the cell in the first row of the column.
        - The title is centered by default.
        
        
        Selecting keys from a dictionary
        --------------------------------
        
        This example uses monotable's extended format string notation to set
        the format function of the second column. A format string has the form:
        
            ``[align_spec][option_spec][format_spec]``
        
        align_spec is one of the characters '<', '^', '>' to override auto-alignment.
        align_spec is not used in this example.
        
        option_spec is one or more monotable options enclosed by ``'('``
        and ``')'`` separated by ``';'``.  In the second column the option_spec
        is ``(mformat)``.
        mformat selects the function **monotable.plugin.mformat()**
        as the format function.
        The API section MonoTable.__init__() in the docs describes the other options.
        
        .. code:: python
        
            import monotable
        
            headings = ['int', 'Formatted by mformat()']
            formats = ['',
                '(mformat)name= {name}\nage= {age:.1f}\ncolor= {favorite_color}']
            t3 = monotable.MonoTable(headings, formats)
        
            cells = [[2345, dict(name='Row Zero',
                                 age=888.000,
                                 favorite_color='blue')],
        
                     [6789, dict(name='Row One',
                                 age=999.111,
                                 favorite_color='No! Red!')]]
        
            print(t3.bordered_table(cells, title='mformat() Formatting.'))
        
        .. code::
        
                  mformat() Formatting.
            +------+------------------------+
            |  int | Formatted by mformat() |
            +======+========================+
            | 2345 | name= Row Zero         |
            |      | age= 888.0             |
            |      | color= blue            |
            +------+------------------------+
            | 6789 | name= Row One          |
            |      | age= 999.1             |
            |      | color= No! Red!        |
            +------+------------------------+
        
        - Note the age fixed precision formatting.  This is not possible with
          template substitution provided by option tformat.
        - Format a bordered table by calling **bordered_table()**
          instead of **table()**.
        - This example also shows formatted cells with newlines.
        
        
        User defined format function
        ----------------------------
        
        Set a user defined format function for the 3rd column.
        
        The user defined function is plugged in to the table by overriding the
        MonoTable class variable **format_func_map** with a dictionary that contains
        the name of the function as the key and function object as the value.
        
        The keys in **format_func_map** become option names that can be specified
        in the option_spec.
        
        .. code:: python
        
            import monotable
        
            # User defined format function.
            def fulfill_menu_request(value, spec):
                _, _ = value, spec          # avoid unused variable nag
                return 'Spam!'              # ignore both args
        
            # Configure MonoTable subclass with the dictionary
            # of user defined format functions.
            class FormatFuncsMonoTable(monotable.MonoTable):
                format_func_map = {'fulfill_menu_request': fulfill_menu_request}
        
            headings = ['Id Number', 'Duties', 'Meal\nPreference']
            formats = ['', '', '(fulfill_menu_request)']
            t4 = FormatFuncsMonoTable(headings, formats)
        
            cells = [[1, 'President and CEO', 'steak'],
                     [2, 'Raise capital', 'eggs'],
                     [3, 'Oversee day to day operations', 'toast']]
        
            print(t4.table(cells, title='>User defined format function.'))
        
        .. code::
        
                                   User defined format function.
            ----------------------------------------------------
                                                      Meal
            Id Number  Duties                         Preference
            ----------------------------------------------------
                    1  President and CEO              Spam!
                    2  Raise capital                  Spam!
                    3  Oversee day to day operations  Spam!
            ----------------------------------------------------
        
        - The user defined format function **fulfill_menu_request()**
          ignores the arguments and returns the string 'Spam!'.
        - Keys in the dictionary **my_format_func_map** become option names
          that can be used in an option_spec.
        - The dictionary is configured into a MonoTable subclass called
          FormatFuncsMonoTable by overriding the class variable **format_func_map**.
        - Alternatively, you can override on an instance by assignment
          like this:
        
        .. code:: python
        
          t4 = monotable.MonoTable(headings, formats)
          t4.format_func_map = {'fulfill_menu_request': fulfill_menu_request}
        
        - The Duties column auto-aligns to the left since the cells
          are strings.
        - The headings auto-align to the alignment of the cell in the first row.
        - The title starts with an ``'>'`` align_spec_char which right aligns
          the title over the table.
        
        .. admonition:: More ...
        
           If you are not already there, please continue reading
           `More Examples`_ in the `Documentation`_ on `Read the Docs`_.
Keywords: ascii table pretty
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
