How Outfancy Manages Column Suppression When Terminal Space Is Limited

Outfancy dynamically suppresses columns by evaluating a priority-ordered list against available terminal width, iteratively removing low-priority columns until all remaining columns exceed the minimum width threshold.

Outfancy, developed in the carlosplanchon/outfancy repository, implements an intelligent column suppression system that ensures tabular data remains readable even when terminal space is constrained. The library dynamically adjusts which columns to render based on the available horizontal space (screen_x), using a sophisticated three-part algorithm that balances data importance against physical display limitations.

The Three Pillars of Column Suppression

The column suppression mechanism in outfancy/table.py relies on three coordinated components working within the Table class:

• Priority list – An ordered list of column indices (ordered_priority_list) ranked from highest to lowest importance, created by check_priority_list at line 1068.
• Width threshold – The minimum usable width (self.show_width_threshold, default 5 characters) that prevents columns from rendering at unreadable sizes (line 58).
• Width allocation algorithm – The assign_column_width method (line 1095) that iteratively distributes available space and triggers column removal when constraints are violated.

Step-by-Step Column Suppression Workflow

When render() is called, Outfancy executes a precise sequence to determine which columns survive the width constraints.

Terminal Size Detection

The process begins by measuring available space. In render (lines 78-84), Outfancy calls shutil.get_terminal_size() to capture screen_x and screen_y, then applies a self.corrector offset (default -2) to account for terminal quirks and padding.

Priority List Construction

Before allocation begins, check_priority_list (lines 1050-1085) analyzes column types to build ordered_priority_list. The system automatically assigns priority based on detected data categories: id columns receive highest priority, followed by value, name, date, time, and finally desc (descriptive text) as lowest priority.

Iterative Width Allocation

The assign_column_width method (line 1095) orchestrates the suppression logic through the following steps:

1. Calculate medium width: The algorithm computes remaining_space = screen_x - len_separator * len_order, then derives medium_width = remaining_space / len_order via the inner get_medium_width function.

2. Detect space violations: If medium_width <= 0, the algorithm identifies the lowest-priority column via ordered_priority_list and removes it by compressing the list (lines 1228-1236). This functionality utilizes helper utilities from outfancy/widgets.py.

3. Initial width assignment: For each column, the system assigns width[column] = min(maximum[column], medium_width), where maximum represents the longest content per column. During this phase, columns with maximum < self.show_width_threshold are tracked in maxima_less_than_show_width_threshold (lines 1274-1280).

4. Sub-threshold detection: After the first pass, any column with assigned width below self.show_width_threshold that wasn't already flagged forces another iteration by setting not_finished = True (lines 1301-1308).

5. Final removal: When not_finished is true, the algorithm removes the column indexed by ordered_priority_list[len_order-1] from the order, maximum, and ordered_priority_list structures, then repeats the allocation loop (lines 1309-1324).

6. Render surviving columns: The resulting width dictionary and trimmed order list flow into generate_table_frames and generate_pre_table (lines 1049-1070), ensuring only columns meeting the width threshold appear in the final output.

Configuring Column Suppression Behavior

You can control how Outfancy handles constrained terminal space through several configuration options and runtime parameters.

Default Automatic Suppression

Outfancy automatically suppresses columns when terminal width is insufficient:

from outfancy import Table
from outfancy.example_dataset import dataset

t = Table()

# Simulate narrow terminal (40 characters)

output = t.render(dataset, screen_x=40)
print(output)

With a 40-character width, Outfancy drops the lowest-priority columns (typically descriptive text fields) to ensure the table fits within the constraints.

Adjusting the Width Threshold

Prevent columns from rendering at unreadable sizes by modifying show_width_threshold:

t = Table()
t.show_width_threshold = 10  # Columns narrower than 10 chars are suppressed

print(t.render(dataset, screen_x=70))

This configuration omits any column that would render narrower than 10 characters, regardless of available total space.

Custom Priority Lists

Override the automatic priority detection to protect specific columns:

t = Table()
t.set_check_data(False)  # Skip automatic data type detection

priority = [0, 2]  # Prioritize columns at indices 0 and 2

print(t.render(dataset, priority_list=priority, screen_x=30))

With this custom priority list, Outfancy attempts to render only columns 0 and 2. If 30 characters remains insufficient, the algorithm suppresses the lower-priority column (index 2) first while preserving index 0.

Summary

• Outfancy implements dynamic column suppression through the assign_column_width algorithm in outfancy/table.py.
• The system uses a priority-ordered list (ordered_priority_list) to determine which columns to remove first, with descriptive fields typically ranked lowest.
• A configurable width threshold (show_width_threshold, default 5 characters) prevents the display of unreadably narrow columns.
• The algorithm iteratively removes low-priority columns until remaining columns fit within the corrected terminal width (screen_x + self.corrector).
• Users can customize behavior through the priority_list parameter, show_width_threshold attribute, or corrector value.

Frequently Asked Questions

How does Outfancy decide which columns to hide first?

Outfancy hides columns based on the ordered_priority_list generated by check_priority_list. The system automatically prioritizes columns containing IDs and values over descriptive text, following the hierarchy: id > value > name > date > time > desc. You can override this by passing a custom priority_list to the render() method.

What is the minimum column width in Outfancy?

The default minimum width is 5 characters, defined by self.show_width_threshold in outfancy/table.py (line 58). Any column calculated to render narrower than this threshold is automatically suppressed, even if space technically exists. You can increase this value to prevent columns from displaying at unreadable sizes.

Can I force Outfancy to show specific columns regardless of terminal size?

While you cannot force display below the show_width_threshold safety limit, you can prioritize specific columns by passing a custom priority_list to render(). Place your critical column indices at the beginning of this list. Outfancy will suppress columns from the end of the list first, protecting your high-priority data until physical space is exhausted.

Where does the terminal width calculation happen?

Terminal width detection occurs in the render method of outfancy/table.py (lines 78-84). The code calls shutil.get_terminal_size() to obtain screen_x, then applies self.corrector (default -2) to account for terminal borders or scrollbars. You can also manually specify screen_x as a parameter to render() for testing or fixed-width outputs.

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