Metadata-Version: 2.1
Name: table2ascii
Version: 1.0.4
Summary: Convert 2D Python lists into Unicode/ASCII tables
Author-email: Jonah Lawrence <jonah@freshidea.com>
License: MIT License
        
        Copyright (c) 2021 Jonah Lawrence
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: documentation, https://table2ascii.rtfd.io
Project-URL: issue-tracker, https://github.com/DenverCoder1/table2ascii/issues
Project-URL: repository, https://github.com/DenverCoder1/table2ascii
Keywords: table,ascii,unicode,formatter
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Topic :: Utilities
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Printing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: docs
Provides-Extra: dev
License-File: LICENSE

# table2ascii

[![build](https://img.shields.io/github/actions/workflow/status/DenverCoder1/table2ascii/python-test.yml?branch=main)](https://github.com/DenverCoder1/table2ascii/actions/workflows/python-app.yml)
[![version](https://img.shields.io/pypi/v/table2ascii)](https://pypi.org/project/table2ascii/)
[![downloads](https://static.pepy.tech/personalized-badge/table2ascii?period=total&left_color=grey&right_color=blue&left_text=downloads)](https://pepy.tech/project/table2ascii)
[![license](https://img.shields.io/pypi/l/table2ascii)](https://github.com/DenverCoder1/table2ascii/blob/main/LICENSE)
[![discord](https://img.shields.io/discord/819650821314052106?color=5865F2&logo=discord&logoColor=white "Dev Pro Tips Discussion & Support Server")](https://discord.gg/fPrdqh3Zfu)

An intuitive and type-safe library for converting 2D Python lists to fancy ASCII/Unicode tables

Documentation and examples are available at [table2ascii.rtfd.io](https://table2ascii.readthedocs.io/)

## 📥 Installation

`pip install -U table2ascii`

**Requirements:** `Python 3.7+`

## 🧑‍💻 Usage

### 🚀 Convert lists to ASCII tables

```py
from table2ascii import table2ascii

output = table2ascii(
    header=["#", "G", "H", "R", "S"],
    body=[["1", "30", "40", "35", "30"], ["2", "30", "40", "35", "30"]],
    footer=["SUM", "130", "140", "135", "130"],
)

print(output)

"""
╔═════════════════════════════╗
║  #     G     H     R     S  ║
╟─────────────────────────────╢
║  1    30    40    35    30  ║
║  2    30    40    35    30  ║
╟─────────────────────────────╢
║ SUM   130   140   135   130 ║
╚═════════════════════════════╝
"""
```

### 🏆 Set first or last column headings

```py
from table2ascii import table2ascii

output = table2ascii(
    body=[["Assignment", "30", "40", "35", "30"], ["Bonus", "10", "20", "5", "10"]],
    first_col_heading=True,
)

print(output)

"""
╔════════════╦═══════════════════╗
║ Assignment ║ 30   40   35   30 ║
║    Bonus   ║ 10   20    5   10 ║
╚════════════╩═══════════════════╝
"""
```

### 📰 Set column widths and alignments

```py
from table2ascii import table2ascii, Alignment

output = table2ascii(
    header=["#", "G", "H", "R", "S"],
    body=[["1", "30", "40", "35", "30"], ["2", "30", "40", "35", "30"]],
    first_col_heading=True,
    column_widths=[5, 5, 5, 5, 5],
    alignments=[Alignment.LEFT] + [Alignment.RIGHT] * 4,
)

print(output)

"""
╔═════╦═══════════════════════╗
║ #   ║   G     H     R     S ║
╟─────╫───────────────────────╢
║ 1   ║  30    40    35    30 ║
║ 2   ║  30    40    35    30 ║
╚═════╩═══════════════════════╝
"""
```

### 🎨 Use a preset style

See a list of 30+ preset styles [here](https://table2ascii.readthedocs.io/en/latest/styles.html).

```py
from table2ascii import table2ascii, Alignment, PresetStyle

output = table2ascii(
    header=["First", "Second", "Third", "Fourth"],
    body=[["10", "30", "40", "35"], ["20", "10", "20", "5"]],
    column_widths=[10, 10, 10, 10],
    style=PresetStyle.ascii_box
)

print(output)

"""
+----------+----------+----------+----------+
|  First   |  Second  |  Third   |  Fourth  |
+----------+----------+----------+----------+
|    10    |    30    |    40    |    35    |
+----------+----------+----------+----------+
|    20    |    10    |    20    |    5     |
+----------+----------+----------+----------+
"""

output = table2ascii(
    header=["First", "Second", "Third", "Fourth"],
    body=[["10", "30", "40", "35"], ["20", "10", "20", "5"]],
    style=PresetStyle.plain,
    cell_padding=0,
    alignments=[Alignment.LEFT] * 4,
)

print(output)

"""
First Second Third Fourth
10    30     40    35
20    10     20    5
"""
```

### 🎲 Define a custom style

Check [`TableStyle`](https://github.com/DenverCoder1/table2ascii/blob/main/table2ascii/table_style.py) for more info and [`PresetStyle`](https://github.com/DenverCoder1/table2ascii/blob/main/table2ascii/preset_style.py) for examples.

```py
from table2ascii import table2ascii, TableStyle

my_style = TableStyle.from_string("*-..*||:+-+:+     *''*")

output = table2ascii(
    header=["First", "Second", "Third"],
    body=[["10", "30", "40"], ["20", "10", "20"], ["30", "20", "30"]],
    style=my_style
)

print(output)

"""
*-------.--------.-------*
| First : Second : Third |
+-------:--------:-------+
|  10   :   30   :  40   |
|  20   :   10   :  20   |
|  30   :   20   :  30   |
*-------'--------'-------*
"""
```

### 🪄 Merge adjacent cells

```py
from table2ascii import table2ascii, Merge, PresetStyle

output = table2ascii(
    header=["#", "G", "Merge", Merge.LEFT, "S"],
    body=[
        [1, 5, 6, 200, Merge.LEFT],
        [2, "E", "Long cell", Merge.LEFT, Merge.LEFT],
        ["Bonus", Merge.LEFT, Merge.LEFT, "F", "G"],
    ],
    footer=["SUM", "100", "200", Merge.LEFT, "300"],
    style=PresetStyle.double_thin_box,
    first_col_heading=True,
)

print(output)

"""
╔═════╦═════╤═══════╤═════╗
║  #  ║  G  │ Merge │  S  ║
╠═════╬═════╪═══╤═══╧═════╣
║  1  ║  5  │ 6 │   200   ║
╟─────╫─────┼───┴─────────╢
║  2  ║  E  │  Long cell  ║
╟─────╨─────┴───┬───┬─────╢
║     Bonus     │ F │  G  ║
╠═════╦═════╤═══╧═══╪═════╣
║ SUM ║ 100 │  200  │ 300 ║
╚═════╩═════╧═══════╧═════╝
"""
```

## ⚙️ Options

All parameters are optional. At least one of `header`, `body`, and `footer` must be provided.

Refer to the [documentation](https://table2ascii.readthedocs.io/en/stable/api.html#table2ascii) for more information.

|       Option        |              Type              |        Default        |                                    Description                                    |
| :-----------------: | :----------------------------: | :-------------------: | :-------------------------------------------------------------------------------: |
|      `header`       |    `Sequence[SupportsStr]`     |        `None`         | First table row seperated by header row separator. Values should support `str()`  |
|       `body`        | `Sequence[Sequence[Sequence]]` |        `None`         | 2D List of rows for the main section of the table. Values should support `str()`  |
|      `footer`       |      `Sequence[Sequence]`      |        `None`         |  Last table row seperated by header row separator. Values should support `str()`  |
|   `column_widths`   |   `Sequence[Optional[int]]`    |  `None` (automatic)   |                List of column widths in characters for each column                |
|    `alignments`     |     `Sequence[Alignment]`      | `None` (all centered) | Column alignments<br/>(ex. `[Alignment.LEFT, Alignment.CENTER, Alignment.RIGHT]`) |
|       `style`       |          `TableStyle`          | `double_thin_compact` |                        Table style to use for the table\*                         |
| `first_col_heading` |             `bool`             |        `False`        |         Whether to add a heading column separator after the first column          |
| `last_col_heading`  |             `bool`             |        `False`        |         Whether to add a heading column separator before the last column          |
|   `cell_padding`    |             `int`              |          `1`          | The minimum number of spaces to add between the cell content and the cell border  |
|    `use_wcwidth`    |             `bool`             |        `True`         |   Whether to use [wcwidth][wcwidth] instead of `len()` to calculate cell width    |

[wcwidth]: https://pypi.org/project/wcwidth/

\*See a list of all preset styles [here](https://table2ascii.readthedocs.io/en/latest/styles.html).

See the [API Reference](https://table2ascii.readthedocs.io/en/latest/api.html) for more info.

## 👨‍🎨 Use cases

### 🗨️ Discord messages and embeds

-   Display tables nicely inside markdown code blocks on Discord
-   Useful for making Discord bots with [Discord.py](https://github.com/Rapptz/discord.py)

![image](https://user-images.githubusercontent.com/20955511/116203248-2973c600-a744-11eb-97d8-4b75ed2845c9.png)

### 💻 Terminal outputs

-   Tables display nicely whenever monospace fonts are fully supported
-   Tables make terminal outputs look more professional

![image](https://user-images.githubusercontent.com/20955511/207134452-a1eb1b9f-e63b-459b-8feb-fc6c234e902e.png)

## 🤗 Contributing

Contributions are welcome!

See [CONTRIBUTING.md](https://github.com/DenverCoder1/table2ascii/blob/main/CONTRIBUTING.md) for more details on how to get involved.
