Skip to main content

Print tabular data in markdown format

Project description


Print tabular data in markdown format


Tested on Pythons above 3.6+. pip3 install table2md


from table2md import MarkdownTable

# All following examples print the following table onto stdout:
# | constant | value |
# |----------|-------|
# | e        | 2.71  |
# | pi       | 3.14  |
# | sqrt2    | 1.41  |

# With dictionaries
    {"constant": "e", "value": 2.71},
    {"constant": "pi", "value": 3.14},
    {"constant": "sqrt2", "value": 1.41},

# With 2D iterables
    ["constant", "value"],
    ["pi", 6.28],
    ["e", 2.71],
    ["sqrt2", 1.41],

# With named tuples
from typing import NamedTuple

class Constant(NamedTuple):
    constant: str
    value: float

    Constant("e", 2.71),
    Constant("pi", 3.14),
    Constant("sqrt2", 1.41),

MarkdownTable automatically coalesces all values into strings (with str(value)); with the exception of the MarkdownTable.from_dicts, where keys are assumed to be strings.

To use custom formatting, either coalesce values into strings on your own, use your own classes with custom __str__ methods, or use the special MarkdownTable.from_serializable constructor.

It takes an iterable of objects with _fields property and a serialize method. Example:

from table2md import MarkdownTable
from typing import NamedTuple
from datetime import datetime

# Named tuples already provide the _fields property,
# so we only need to implement the serialize method.
class TemperatureReadout(NamedTuple):
    tstamp: datetime
    value: float

    def serialize(self) -> tuple[str, str]:
        return self.tstamp.strftime("%Y-%m-%d %H:%M"), f"{self.value:.1f}"

    TemperatureReadout(datetime(2021, 11, 1, 10, 0, 0), 10.411),
    TemperatureReadout(datetime(2021, 11, 1, 12, 0, 0), 12.782),
    TemperatureReadout(datetime(2021, 11, 1, 14, 0, 0), 11.214),
# Output:
# |      tstamp      | value |
# |------------------|-------|
# | 2021-11-01 10:00 | 10.4  |
# | 2021-11-01 12:00 | 12.8  |
# | 2021-11-01 14:00 | 11.2  |



A class to represent tabular data

  • MarkdownTable(data: List[List[Str]]):
    Initializes a table from a 2D list of strings. 1st row is always the header row. See utility MarkdownTable.from_* helper classmethods. Provided lists are not copied!

  • markdown_table.__str__() -> str:
    Serializes the contained tabular data to a markdown table. First row is assumed to be the header row.

  • markdown_table.validate() -> None:
    Ensures the contained table is good-to-print - that is it has a header; and all rows with data have the same number of cells as the header.
    Raises a sub-class of InvalidData in case invalid state is detected.

  • markdown_table.print(end: str = "", file: SupportsWrite[str] = sys.stdout, flush: bool = False) -> None:
    Validates the table, and then prints it. 'end', 'file' and 'flush' arguments are passed through to the builtin print function.
    Pleas note that the serialized table already has a newline at the end, so end="\n" is not necessary.

  • markdown_table.display() -> None:
    Validates the table, then tries to pretty-print using IPython.display.display_markdown.

    If that is not available, the same as table.print()

  • MarkdownTable.from_2d_iterable(iters: Iterable[Iterable[Any]]) -> MarkdownTable:
    Initializes the table from a 2D iterable. Every cell is saved by calling str(cell). If provided with a 2D list, those lists are copied (this is different to the behavior from the constructor).

  • MarkdownTable.from_dicts(dicts: Iterable[Mapping[str, Any]]) -> MarkdownTable::
    Initializes the table from an iterable of dictionaries. Every value is saved by calling str(cell).
    Only keys from the first dictionary are used; that is any extra key in other dictionaries are ignored. However, if a following dict has a missing key, KeyError is thrown.

  • MarkdownTable.from_namedtuples(named_tuples: Iterable[_NamedTupleLike]) -> MarkdownTable:
    Initializes the table from an iterable of NamedTuples.
    Well, in reality those don't have to be NamedTuples per se; as longs at the objects have a _fields property and one can iterate over those objects this function works fine.
    First object's _fields property is the header row.
    If objects aren't of the same type, ensure all of them have the same amount of fields; otherwise an invalid table is created.

  • MarkdownTable.from_serializable(objects: Iterable[_Serializable]) -> MarkdownTable:
    This is an extension of from_namedtuples; but instead of iterating over those objects directly, obj.serialize() is used to get the string representations of the cells.
    So, as long as objects have the _fields property and a serialize() method; this method works fine.
    First object's _fields property is the header row.
    Ensure all object's serialize() method yield the same amount of cells, otherwise an invalid table is created.


  • InvalidData: Base exception fort use in table validation. Subclasses ValueError.

  • NoData: Exception used when a table has absolutely no data; not even a header row. Subclasses InvalidData.

  • MisalignedRows: Exception used when a table has rows with more/less cells than the header. Subclasses InvalidData.


  • SupportsWrite[str]: Anything with a write method accepting a string argument. Implemented by the _typeshed module.

  • _NamedTupleLike: Anything with a _fields property, which is an iterable of strings representing field names; that is itself iterable.

  • _Serializable: Anything with a _fields property, which is an iterable of strings representing field names; and with a serialize() -> Iterable[str] method which returns all the held field values as strings.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

table2md-1.1.0.tar.gz (7.1 kB view hashes)

Uploaded Source

Built Distribution

table2md-1.1.0-py3-none-any.whl (7.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page