CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-mdutils

A comprehensive Python library for programmatically creating and manipulating Markdown files with support for headers, tables, lists, images, links, and text formatting.

80

1.90x
Overview
Eval results
Files

tables.mddocs/

Tables

Flexible table creation from flat lists or 2D arrays with customizable alignment, supporting various data input formats and styling options. MDUtils provides comprehensive table creation capabilities with automatic formatting, alignment controls, and positioning options.

Capabilities

Basic Table Creation

Create tables from flat lists with specified dimensions and alignment options.

class MdUtils:
    def new_table(self, columns: int, rows: int, text: List[str], text_align: Optional[Union[str, list]] = "center", marker: str = "") -> str:
        """
        Create a table from a flat list of strings.

        Parameters:
        - columns (int): Number of columns in the table
        - rows (int): Number of rows in the table  
        - text (List[str]): Flat list of cell contents (columns × rows elements)
        - text_align (str or list, optional): Alignment ('left', 'center', 'right') for all columns or per-column list
        - marker (str, optional): Marker for positioning table at specific location

        Returns:
        str: Formatted markdown table
        """

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='basic_table_example')

# Simple 2x3 table (2 columns, 3 rows)
table_data = [
    'Name', 'Age',           # Header row
    'Alice', '25',           # Row 1
    'Bob', '30'              # Row 2
]
md.new_table(columns=2, rows=3, text=table_data)

# Table with custom alignment
product_data = [
    'Product', 'Price', 'Stock',     # Headers
    'Laptop', '$999', '15',          # Row 1
    'Mouse', '$25', '50',            # Row 2
    'Keyboard', '$75', '30'          # Row 3
]
md.new_table(columns=3, rows=4, text=product_data, text_align='left')

# Table with per-column alignment
mixed_align_data = [
    'Item', 'Quantity', 'Total',
    'Books', '10', '$150.00',
    'Pens', '25', '$12.50'
]
# Left align first column, center second, right align third
alignments = ['left', 'center', 'right']
md.new_table(columns=3, rows=3, text=mixed_align_data, text_align=alignments)

Array-Based Table Creation

Create tables from 2D arrays for more intuitive data structure handling.

class MdUtils:
    def new_table_array(self, data: List[List[str]], text_align: Optional[Union[str, list]] = None, marker: str = "") -> str:
        """
        Create a table from a 2D array structure.

        Parameters:
        - data (List[List[str]]): 2D array where each inner list represents a table row
        - text_align (str or list, optional): Alignment specification
        - marker (str, optional): Marker for positioning table at specific location

        Returns:
        str: Formatted markdown table
        """

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='array_table_example')

# 2D array approach - more intuitive
table_data = [
    ['Language', 'Year', 'Creator'],         # Header row
    ['Python', '1991', 'Guido van Rossum'],  # Row 1
    ['JavaScript', '1995', 'Brendan Eich'],  # Row 2
    ['Go', '2009', 'Google']                 # Row 3
]
md.new_table_array(data=table_data, text_align='center')

# Financial data table with right alignment for numbers
financial_data = [
    ['Quarter', 'Revenue', 'Profit', 'Growth'],
    ['Q1 2023', '$1,200,000', '$150,000', '12%'],
    ['Q2 2023', '$1,350,000', '$180,000', '15%'],
    ['Q3 2023', '$1,500,000', '$225,000', '18%']
]
# Left align quarter, right align numbers
alignments = ['left', 'right', 'right', 'right']
md.new_table_array(data=financial_data, text_align=alignments)

Table Tool Classes

Direct access to table creation tools for advanced table manipulation and custom formatting.

class Table:
    def __init__(self):
        """Initialize a table creation tool."""

    def create_table(self, columns: int, rows: int, text: List[str], text_align: Optional[Union[str, list]] = None) -> str:
        """
        Create table from flat list with specified dimensions.

        Parameters:
        - columns (int): Number of columns
        - rows (int): Number of rows
        - text (List[str]): Flat list of cell contents
        - text_align (str or list, optional): Alignment specification

        Returns:
        str: Formatted markdown table
        """

    def create_table_array(self, data: List[List[str]], text_align: Optional[Union[str, list]] = None) -> str:
        """
        Create table from 2D array structure.

        Parameters:
        - data (List[List[str]]): 2D array of table data
        - text_align (str or list, optional): Alignment specification

        Returns:
        str: Formatted markdown table
        """

    @staticmethod
    def _align(columns: int, text_align: Optional[Union[str, Iterable]] = None) -> str:
        """
        Generate alignment row for markdown table.

        Parameters:
        - columns (int): Number of columns
        - text_align (str or iterable, optional): Alignment specification

        Returns:
        str: Markdown table alignment row
        """

    # Properties
    rows: int     # Number of rows in the table
    columns: int  # Number of columns in the table

Usage Example:

from mdutils import MdUtils
from mdutils.tools import Table

md = MdUtils(file_name='table_tools_example')

# Using Table class directly
table_tool = Table()

# Create table using tool methods
data = ['Header 1', 'Header 2', 'Value 1', 'Value 2']
table_content = table_tool.create_table(columns=2, rows=2, text=data, text_align='center')
md.write(table_content)

# Create table from array
array_data = [
    ['Feature', 'Status'],
    ['Authentication', 'Complete'],
    ['Database', 'In Progress'],
    ['UI', 'Planning']
]
array_table = table_tool.create_table_array(data=array_data, text_align=['left', 'center'])
md.write(array_table)

# Access table properties
print(f"Table has {table_tool.rows} rows and {table_tool.columns} columns")

Advanced Table Positioning

Use markers to position tables at specific locations within the document.

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='positioned_tables')

# Create content structure
md.new_header(level=1, title='Data Analysis Report')
md.new_paragraph('This report contains several data tables.')

# Create marker for first table
md.new_header(level=2, title='Sales Data')
md.new_paragraph('The following table shows our sales performance:')
sales_marker = md.create_marker('sales_table')

md.new_header(level=2, title='User Statistics')  
md.new_paragraph('User engagement metrics are shown below:')
users_marker = md.create_marker('users_table')

# Create tables and place them at markers
sales_data = [
    'Month', 'Sales', 'Target',
    'January', '$45,000', '$40,000',
    'February', '$52,000', '$45,000',
    'March', '$48,000', '$50,000'
]
md.new_table(columns=3, rows=4, text=sales_data, 
           text_align=['left', 'right', 'right'], 
           marker=sales_marker)

users_data = [
    ['Metric', 'Value', 'Change'],
    ['Active Users', '12,500', '+5%'],
    ['New Signups', '850', '+12%'],
    ['Retention', '78%', '+2%']
]
md.new_table_array(data=users_data, 
                  text_align=['left', 'center', 'right'],
                  marker=users_marker)

Table Alignment Options

Comprehensive guide to table alignment specifications and their effects.

Alignment Values:

  • 'left' - Left-align column content
  • 'center' - Center-align column content
  • 'right' - Right-align column content

Alignment Specification Methods:

  1. Single string: Same alignment for all columns
  2. List of strings: Individual alignment per column
  3. None/default: Center alignment for all columns

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='alignment_examples')

# Same alignment for all columns
md.new_header(level=2, title='Left Aligned Table')
left_data = ['Name', 'City', 'Country', 'John', 'New York', 'USA', 'Jane', 'London', 'UK']
md.new_table(columns=3, rows=3, text=left_data, text_align='left')

# Individual column alignments
md.new_header(level=2, title='Mixed Alignment Table')
mixed_data = [
    ['Product', 'Price', 'Rating', 'Notes'],
    ['Laptop', '$999.99', '4.5/5', 'Excellent performance'],
    ['Mouse', '$29.99', '4.2/5', 'Good ergonomics'],  
    ['Monitor', '$299.99', '4.8/5', 'Great display quality']
]
# Left, right, center, left alignment
mixed_alignments = ['left', 'right', 'center', 'left']
md.new_table_array(data=mixed_data, text_align=mixed_alignments)

# Default center alignment (no text_align specified)
md.new_header(level=2, title='Default Center Aligned')
center_data = ['Feature', 'Available', 'SSL', 'Yes', 'Database', 'PostgreSQL']
md.new_table(columns=2, rows=3, text=center_data)

Complex Table Examples

Real-world examples demonstrating advanced table creation patterns and data presentation.

Usage Example:

from mdutils import MdUtils

md = MdUtils(file_name='complex_tables')

# Project status table with varied content
md.new_header(level=1, title='Project Dashboard')

project_status = [
    ['Project', 'Lead', 'Progress', 'Due Date', 'Status'],
    ['Website Redesign', 'Alice Johnson', '85%', '2023-12-15', '🟢 On Track'],
    ['Mobile App', 'Bob Smith', '60%', '2024-01-30', '🟡 At Risk'],
    ['API Integration', 'Carol Davis', '95%', '2023-11-20', '🟢 On Track'],
    ['Database Migration', 'David Wilson', '30%', '2024-02-15', '🔴 Behind']
]
alignments = ['left', 'left', 'center', 'center', 'center']
md.new_table_array(data=project_status, text_align=alignments)

# Financial summary with calculations
md.new_header(level=2, title='Quarterly Financial Summary')
financial_summary = [
    'Category', 'Q1', 'Q2', 'Q3', 'Total',
    'Revenue', '$125,000', '$138,000', '$142,000', '$405,000',
    'Expenses', '$95,000', '$102,000', '$108,000', '$305,000', 
    'Profit', '$30,000', '$36,000', '$34,000', '$100,000',
    'Margin', '24%', '26%', '24%', '25%'
]
financial_alignments = ['left', 'right', 'right', 'right', 'right']
md.new_table(columns=5, rows=5, text=financial_summary, text_align=financial_alignments)

# Technical specifications table
md.new_header(level=2, title='System Requirements')
tech_specs = [
    ['Component', 'Minimum', 'Recommended'],
    ['CPU', 'Intel i3 / AMD Ryzen 3', 'Intel i7 / AMD Ryzen 7'],
    ['RAM', '8 GB', '16 GB'],
    ['Storage', '256 GB SSD', '512 GB SSD'],
    ['GPU', 'Integrated', 'Dedicated 4GB+'],
    ['OS', 'Windows 10 / macOS 10.15', 'Windows 11 / macOS 12+']
]
tech_alignments = ['left', 'center', 'center']
md.new_table_array(data=tech_specs, text_align=tech_alignments)

Install with Tessl CLI

npx tessl i tessl/pypi-mdutils

docs

advanced.md

core-document.md

headers-toc.md

index.md

links-images.md

lists.md

tables.md

text-formatting.md

tile.json