How to Configure Column Priority and Width for Tables in Outfancy

To configure column priority and width for tables in outfancy, pass the priority_list argument to Table.render() to control which columns hide first when space is tight, and use the width argument to set fixed character counts, force equal distribution, or rely on automatic allocation.

The outfancy library (carlosplanchon/outfancy) provides fine-grained control over terminal table layouts through its rendering API. When you configure column priority and width for tables in outfancy, you interact directly with the Table class in outfancy/table.py, specifically through the render, check_priority_list, and assign_column_width methods.

Understanding Column Priority in Outfancy

What Column Priority Controls

Column priority determines the survival order of columns when terminal width is insufficient. The priority_list is a list of column indices ordered from most important to least important. When the total table width exceeds available space, outfancy drops columns starting from the end of this list.

For a dataset with three columns (indices 0, 1, 2):

priority = [2, 0, 1]  # Column 2 (most important), Column 0, Column 1 (least important)

If the screen cannot accommodate all columns, Column 1 is omitted first.

The check_priority_list Implementation

The validation and reconstruction of priority lists occurs in Table.check_priority_list at approximately line 967 of outfancy/table.py. This method:

• Accepts the auto-detected data-type list from the dataset
• Validates the user-supplied priority_list for correct length and numeric entries
• Rebuilds a default priority order if the list is missing, incorrectly sized, or contains invalid data

The resulting ordered list drives the column-dropping logic during the rendering phase.

Configuring Column Widths

Explicit Width Lists

To enforce specific character widths, pass a list of integers to the width parameter in Table.render(). The order must match the priority-ordered columns, not the original data order.

import outfancy.table as ot

data = [
    (101, "Alice", "2024-01-01"),
    (102, "Bob", "2024-02-15")
]

# Priority: Date (2) most important, then ID (0), then Name (1)

priority = [2, 0, 1]

# Widths ordered by priority: Date=12, ID=4, Name=10

widths = [12, 4, 10]

tbl = ot.Table()
print(tbl.render(data, priority_list=priority, width=widths))

If the sum of explicit widths plus separator characters exceeds the terminal width (screen_x adjusted by the internal corrector value of -2), outfancy falls back to automatic allocation.

Equal Width Distribution

Force uniform column widths by setting width=False:

print(tbl.render(data, width=False))  # Each visible column receives identical space

This triggers the equal-distribution logic in Table.assign_column_width (around line 1092), which divides available terminal width evenly among visible columns.

Automatic Width Allocation

When width is omitted (None), assign_column_width computes optimal widths based on:

• Content metrics: The longest printed content per column
• Terminal constraints: Current screen width via shutil.get_terminal_size()
• Priority weighting: Higher-priority columns receive the minimum of their content width and available space; remaining space is distributed to lower-priority columns
• Visibility threshold: self.show_width_threshold (default 5) determines the minimum width for a column to remain visible; columns below this threshold are hidden

This automatic mode ensures readable layouts across varying terminal sizes without manual calculation.

Practical Usage Examples

Full Customization with Priority and Width

import outfancy.table as ot

dataset = [
    (101, "Alice", "2024-01-01", 3.14),
    (102, "Bob", "2024-02-15", 2.71),
    (103, "Charlie", "2024-03-30", 1.62)
]

# Keep numeric value (3) most important, then date (2), then ID (0), hide name (1) if needed

priority = [3, 2, 0, 1]

# Widths ordered by priority: Value=6, Date=12, ID=4, Name=10

widths = [6, 12, 4, 10]

tbl = ot.Table()
print(tbl.render(dataset, priority_list=priority, width=widths))

Equal Widths with Custom Priority

import outfancy.table as ot

tbl = ot.Table()
print(tbl.render(
    dataset,
    priority_list=[2, 0, 1, 3],  # date > ID > name > value

    width=False                  # equal distribution across visible columns

))

On a 40-character terminal, the value column (lowest priority) disappears automatically, and the remaining three columns share equal space.

Dynamic Widths on Narrow Terminals

import outfancy.table as ot
import shutil

tbl = ot.Table()

# Force 50-character width simulation

print(tbl.render(
    dataset,
    screen_x=50,                 # constrain terminal width

    priority_list=[0, 1, 2, 3]   # natural column order

))

Outfancy computes widths fitting within 50 characters, truncating or hiding columns based on show_width_threshold and the priority list.

Key Source Files and Methods

File	Relevant Symbol(s)	Description
outfancy/table.py	Table.render (≈ L250)	Public entry point accepting priority_list and width parameters.
outfancy/table.py	Table.check_priority_list (≈ L967)	Validates and rebuilds priority lists, ensuring correct ordering from most to least important.
outfancy/table.py	Table.assign_column_width (≈ L1092)	Calculates per-column widths, handles equal distribution, and enforces show_width_threshold.
outfancy/widgets.py	printed_length, compress_list	Utility functions supporting width calculations and content measurement.

These components implement the rendering pipeline that powers outfancy’s table formatting. By passing the appropriate arguments to Table.render, you control which columns survive screen-size constraints and how much horizontal space each column occupies.

Summary

• Column priority determines survival order when space is tight. Pass a list of indices to priority_list in Table.render(), ordered from most to least important.
• Column width accepts explicit character counts (list of integers), equal distribution (width=False), or automatic calculation (omit parameter).
• Core implementation resides in outfancy/table.py: check_priority_list (≈ L967) handles priority validation, while assign_column_width (≈ L1092) manages width allocation.
• Visibility thresholds default to 5 characters (show_width_threshold), and a -2 character margin (corrector) prevents line wrapping.

Frequently Asked Questions

What happens if my priority list has the wrong number of elements?

Outfancy’s check_priority_list method detects size mismatches and automatically rebuilds a valid priority list based on detected data types. While the table renders successfully, your custom ordering is discarded if the list length does not match the column count or contains invalid entries.

Can I force a specific column to always remain visible regardless of terminal width?

There is no explicit "pin" feature, but you can achieve this by placing the column’s index at the start of the priority_list (most important) and ensuring the show_width_threshold (default 5) remains low. The column only disappears if fewer than 5 characters can be allocated.

Why do my fixed widths seem to be ignored on narrow terminals?

If the sum of your explicit widths plus separator characters exceeds the available terminal width (screen_x adjusted by the internal corrector value of -2), assign_column_width falls back to automatic allocation. To enforce fixed widths, ensure the total fits within the terminal or increase available space.

How does outfancy determine which columns are high priority by default?

When priority_list is omitted, check_priority_list auto-detects column types (such as id, name, date) and builds an internal priority order. This heuristic keeps identifier and date columns visible longer than descriptive text columns when horizontal space becomes constrained.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}