feat!: Added the ability to merge cells with Merge.LEFT

README.md

@@ -159,6 +159,40 @@ print(output)
 """
 ```
 
+### 🪄 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.

docs/source/api.rst

@@ -8,13 +8,20 @@ table2ascii
 
 .. autofunction:: table2ascii
 
-
 Alignment
 ~~~~~~~~~
 
 .. autoenum:: Alignment
     :members:
 
+.. _Merge:
+
+Merge
+~~~~~
+
+.. autoenum:: Merge
+    :members:
+
 PresetStyle
 ~~~~~~~~~~~
 
@@ -51,3 +58,10 @@ Exceptions
 .. autoexception:: table2ascii.exceptions.ColumnWidthTooSmallError
 
 .. autoexception:: table2ascii.exceptions.InvalidAlignmentError
+
+.. autoexception:: table2ascii.exceptions.TableStyleTooLongError
+
+Warnings
+~~~~~~~~
+
+.. autoclass:: table2ascii.exceptions.TableStyleTooShortWarning

docs/source/styles.rst

@@ -286,6 +286,29 @@ Preset styles
    ║ 2 ║ 30   40   35   30 ║
    ╚═══╩═══════════════════╝
 
+.. _PresetStyle.double_thin_box:
+
+`double_thin_box`
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: none
+
+   ╔═════╦═════╤═════╤═════╤═════╗
+   ║  #  ║  G  │  H  │  R  │  S  ║
+   ╠═════╬═════╪═════╪═════╪═════╣
+   ║  1  ║ 30  │ 40  │ 35  │ 30  ║
+   ╟─────╫─────┼─────┼─────┼─────╢
+   ║  2  ║ 30  │ 40  │ 35  │ 30  ║
+   ╠═════╬═════╪═════╪═════╪═════╣
+   ║ SUM ║ 130 │ 140 │ 135 │ 130 ║
+   ╚═════╩═════╧═════╧═════╧═════╝
+
+   ╔═══╦════╤════╤════╤════╗
+   ║ 1 ║ 30 │ 40 │ 35 │ 30 ║
+   ╟───╫────┼────┼────┼────╢
+   ║ 2 ║ 30 │ 40 │ 35 │ 30 ║
+   ╚═══╩════╧════╧════╧════╝
+
 .. _PresetStyle.double_thin_compact:
 
 `double_thin_compact`

docs/source/usage.rst

@@ -59,8 +59,8 @@ Set column widths and alignments
        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, 5, 5]
-       alignments=[Alignment.LEFT] + [Alignment.RIGHT] * 4, # First is left, remaining 4 are right
+       column_widths=[5, 5, 5, 5, 5],
+       alignments=[Alignment.LEFT] + [Alignment.RIGHT] * 4,
    )
 
    print(output)
@@ -84,7 +84,7 @@ Use a preset style
    output = table2ascii(
        header=["First", "Second", "Third", "Fourth"],
        body=[["10", "30", "40", "35"], ["20", "10", "20", "5"]],
-       column_widths=[10] * 4,
+       column_widths=[10, 10, 10, 10],
        style=PresetStyle.ascii_box
    )
 
@@ -130,7 +130,7 @@ Check :ref:`TableStyle` for more info.
    output = table2ascii(
        header=["First", "Second", "Third"],
        body=[["10", "30", "40"], ["20", "10", "20"], ["30", "20", "30"]],
-       style=my_style
+       style=my_style,
    )
 
    print(output)
@@ -143,4 +143,41 @@ Check :ref:`TableStyle` for more info.
    |  20   :   10   :  20   |
    |  30   :   20   :  30   |
    *-------'--------'-------*
-   """
+   """
+
+Merge adjacent cells
+~~~~~~~~~~~~~~~~~~~~
+
+Check :ref:`Merge` for more info.
+
+.. code:: 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 ║
+    ╚═════╩═════╧═══════╧═════╝
+    """

table2ascii/__init__.py

@@ -3,15 +3,17 @@
 """
 
 from .alignment import Alignment
+from .merge import Merge
 from .preset_style import PresetStyle
 from .table_style import TableStyle
 from .table_to_ascii import table2ascii
 
 __version__ = "1.0.0"
 
 __all__ = [
-    "table2ascii",
     "Alignment",
-    "TableStyle",
+    "Merge",
     "PresetStyle",
+    "TableStyle",
+    "table2ascii",
 ]

table2ascii/exceptions.py

@@ -189,3 +189,54 @@ def _message(self):
             f"Invalid alignment: {self.alignment!r} is not a valid alignment. "
             f"Valid alignments are: {', '.join(a.__repr__() for a in Alignment)}"
         )
+
+
+class TableStyleTooLongError(Table2AsciiError, ValueError):
+    """Exception raised when the number of characters passed in the string
+    for creating the table style exceeds the number of parameters that the
+    table style accepts
+
+    This class is a subclass of :class:`Table2AsciiError` and :class:`ValueError`.
+
+    Attributes:
+        string (str): The string that caused the error
+        max_characters (int): The maximum number of characters that are allowed
+    """
+
+    def __init__(self, string: str, max_characters: int):
+        self.string = string
+        self.max_characters = max_characters
+        super().__init__(self._message())
+
+    def _message(self):
+        return (
+            f"Too many characters for table style: {len(self.string)} characters "
+            f"found, but the maximum number of characters allowed is {self.max_characters}."
+        )
+
+
+class TableStyleTooShortWarning(UserWarning):
+    """Warning raised when the number of characters passed in the string
+    for creating the table style is fewer than the number of parameters
+    that the table style accepts
+
+    This class is a subclass of :class:`UserWarning`.
+
+    It can be silenced using :func:`warnings.filterwarnings`.
+
+    Attributes:
+        string (str): The string that caused the warning
+        max_characters (int): The number of characters that :class:`TableStyle` accepts
+    """
+
+    def __init__(self, string: str, max_characters: int):
+        self.string = string
+        self.max_characters = max_characters
+        super().__init__(self._message())
+
+    def _message(self):
+        return (
+            f"Too few characters for table style: {len(self.string)} characters "
+            f"found, but table styles can accept {self.max_characters} characters. "
+            f"Missing characters will be replaced with spaces."
+        )

table2ascii/merge.py

@@ -0,0 +1,43 @@
+from enum import Enum
+
+
+class Merge(Enum):
+    """Enum for merging table cells
+
+    Using :attr:`Merge.LEFT` in a table cell will merge the cell it is used in
+    with the cell to its left.
+
+    In the case that the contents of the merged cell are longer than the
+    combined widths of the unmerged cells in the rows above and below,
+    the merged cell will be wrapped onto multiple lines. The ``column_widths``
+    option can be used to control the widths of the unmerged cells.
+
+    Example::
+
+        from table2ascii import table2ascii, Merge, PresetStyle
+
+        table2ascii(
+            header=["Name", "Price", "Category", "Stock"],
+            body=[["Milk", "$2.99", "N/A", Merge.LEFT]],
+            footer=["Description", "Milk is a nutritious beverage", Merge.LEFT, Merge.LEFT],
+            style=PresetStyle.double_box,
+        )
+
+        \"\"\"
+        ╔═════════════╦═══════╦══════════╦═══════╗
+        ║    Name     ║ Price ║ Category ║ Stock ║
+        ╠═════════════╬═══════╬══════════╩═══════╣
+        ║    Milk     ║ $2.99 ║       N/A        ║
+        ╠═════════════╬═══════╩══════════════════╣
+        ║ Description ║   Milk is a nutritious   ║
+        ║             ║         beverage         ║
+        ╚═════════════╩══════════════════════════╝
+        \"\"\"
+
+    .. versionadded:: 1.0.0
+    """
+
+    LEFT = 0
+
+    def __str__(self):
+        return ""

table2ascii/preset_style.py

@@ -16,33 +16,34 @@ class PresetStyle:
         )
     """
 
-    thin = TableStyle.from_string("┌─┬─┐││ ├─┼─┤├─┼─┤└┴─┘")
-    thin_box = TableStyle.from_string("┌─┬┬┐│││├─┼┼┤├─┼┼┤└┴┴┘")
-    thin_rounded = TableStyle.from_string("╭─┬─╮││ ├─┼─┤├─┼─┤╰┴─╯")
-    thin_compact = TableStyle.from_string("┌─┬─┐││ ├─┼─┤     └┴─┘")
-    thin_compact_rounded = TableStyle.from_string("╭─┬─╮││ ├─┼─┤     ╰┴─╯")
-    thin_thick = TableStyle.from_string("┌─┬─┐││ ┝━┿━┥├─┼─┤└┴─┘")
-    thin_thick_rounded = TableStyle.from_string("╭─┬─╮││ ┝━┿━┥├─┼─┤╰┴─╯")
-    thin_double = TableStyle.from_string("┌─┬─┐││ ╞═╪═╡├─┼─┤└┴─┘")
-    thin_double_rounded = TableStyle.from_string("╭─┬─╮││ ╞═╪═╡├─┼─┤╰┴─╯")
-    thick = TableStyle.from_string("┏━┳━┓┃┃ ┣━╋━┫┣━╋━┫┗┻━┛")
-    thick_box = TableStyle.from_string("┏━┳┳┓┃┃┃┣━╋╋┫┣━╋╋┫┗┻┻┛")
-    thick_compact = TableStyle.from_string("┏━┳━┓┃┃ ┣━╋━┫     ┗┻━┛")
-    double = TableStyle.from_string("╔═╦═╗║║ ╠═╬═╣╠═╬═╣╚╩═╝")
-    double_box = TableStyle.from_string("╔═╦╦╗║║║╠═╬╬╣╠═╬╬╣╚╩╩╝")
-    double_compact = TableStyle.from_string("╔═╦═╗║║ ╠═╬═╣     ╚╩═╝")
-    double_thin_compact = TableStyle.from_string("╔═╦═╗║║ ╟─╫─╢     ╚╩═╝")
-    minimalist = TableStyle.from_string(" ───  │  ━━━  ───  ── ")
-    borderless = TableStyle.from_string("      ┃  ━            ")
-    simple = TableStyle.from_string(" ═    ║  ═            ")
-    ascii = TableStyle.from_string("+-+-+|| +-+-++-+-+++-+")
-    ascii_box = TableStyle.from_string("+-+++|||+-++++-+++++++")
-    ascii_compact = TableStyle.from_string("+-+-+|| +-+-+     ++-+")
-    ascii_double = TableStyle.from_string("+-+-+|| +=+=++-+-+++-+")
-    ascii_minimalist = TableStyle.from_string(" ---  |  ===  ---  -- ")
-    ascii_borderless = TableStyle.from_string("      |  -            ")
-    ascii_simple = TableStyle.from_string(" =    |  =            ")
-    ascii_rounded = TableStyle.from_string(r"/===\|| |=|=||-|-|\|=/")
-    ascii_rounded_box = TableStyle.from_string(r"/===\||||=||||-|||\||/")
-    markdown = TableStyle.from_string("     ||||-|||         ")
-    plain = TableStyle.from_string("                      ").set(left_and_right_edge="")
+    thin = TableStyle.from_string("┌─┬─┐││ ├─┼─┤├─┼─┤└┴─┘────┬┴┬┴")
+    thin_box = TableStyle.from_string("┌─┬┬┐│││├─┼┼┤├─┼┼┤└┴┴┘┬┴┬┴┬┴┬┴")
+    thin_rounded = TableStyle.from_string("╭─┬─╮││ ├─┼─┤├─┼─┤╰┴─╯────┬┴┬┴")
+    thin_compact = TableStyle.from_string("┌─┬─┐││ ├─┼─┤     └┴─┘  ──  ┬┴")
+    thin_compact_rounded = TableStyle.from_string("╭─┬─╮││ ├─┼─┤     ╰┴─╯  ──  ┬┴")
+    thin_thick = TableStyle.from_string("┌─┬─┐││ ┝━┿━┥├─┼─┤└┴─┘──━━┬┴┯┷")
+    thin_thick_rounded = TableStyle.from_string("╭─┬─╮││ ┝━┿━┥├─┼─┤╰┴─╯──━━┬┴┯┷")
+    thin_double = TableStyle.from_string("┌─┬─┐││ ╞═╪═╡├─┼─┤└┴─┘──══┬┴╤╧")
+    thin_double_rounded = TableStyle.from_string("╭─┬─╮││ ╞═╪═╡├─┼─┤╰┴─╯──══┬┴╤╧")
+    thick = TableStyle.from_string("┏━┳━┓┃┃ ┣━╋━┫┣━╋━┫┗┻━┛━━━━┳┻┳┻")
+    thick_box = TableStyle.from_string("┏━┳┳┓┃┃┃┣━╋╋┫┣━╋╋┫┗┻┻┛┳┻┳┻┳┻┳┻")
+    thick_compact = TableStyle.from_string("┏━┳━┓┃┃ ┣━╋━┫     ┗┻━┛  ━━  ┳┻")
+    double = TableStyle.from_string("╔═╦═╗║║ ╠═╬═╣╠═╬═╣╚╩═╝════╦╩╦╩")
+    double_box = TableStyle.from_string("╔═╦╦╗║║║╠═╬╬╣╠═╬╬╣╚╩╩╝╦╩╦╩╦╩╦╩")
+    double_compact = TableStyle.from_string("╔═╦═╗║║ ╠═╬═╣     ╚╩═╝  ══  ╦╩")
+    double_thin_box = TableStyle.from_string("╔═╦╤╗║║│╠═╬╪╣╟─╫┼╢╚╩╧╝┬┴╤╧╥╨╦╩")
+    double_thin_compact = TableStyle.from_string("╔═╦═╗║║ ╟─╫─╢     ╚╩═╝  ──  ╥╨")
+    minimalist = TableStyle.from_string(" ───  │  ━━━  ───  ── ──━━┬┴┯┷")
+    borderless = TableStyle.from_string("      ┃  ━              ━━  ━━")
+    simple = TableStyle.from_string(" ═    ║  ═              ══  ╦╩")
+    ascii = TableStyle.from_string("+-+-+|| +-+-++-+-+++-+----++++")
+    ascii_box = TableStyle.from_string("+-+++|||+-++++-+++++++++++++++")
+    ascii_compact = TableStyle.from_string("+-+-+|| +-+-+     ++-+  --  --")
+    ascii_double = TableStyle.from_string("+-+-+|| +=+=++-+-+++-+--==--==")
+    ascii_minimalist = TableStyle.from_string(" ---  |  ===  ---  -- --==--==")
+    ascii_borderless = TableStyle.from_string("      |  -              --  --")
+    ascii_simple = TableStyle.from_string(" =    |  =              ==  ==")
+    ascii_rounded = TableStyle.from_string(r"/===\|| |=|=||-|-|\|=/--==--==")
+    ascii_rounded_box = TableStyle.from_string(r"/===\||||=||||-|||\||/--==--==")
+    markdown = TableStyle.from_string("     ||||-|||           --  --")
+    plain = TableStyle.from_string(" " * 30).set(left_and_right_edge="")