# How to Configure Column Priority and Width for Tables in Outfancy

> Learn to configure column priority and width for tables in Outfancy using priority_list and width arguments to control column hiding and size for optimal table display.

- Repository: [Carlos A. Planchón/outfancy](https://github.com/carlosplanchon/outfancy)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/carlosplanchon/outfancy/blob/main/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):

```python
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`](https://github.com/carlosplanchon/outfancy/blob/main/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.

```python
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`:

```python
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

```python
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

```python
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

```python
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`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py) | `Table.render` (≈ L250) | Public entry point accepting `priority_list` and `width` parameters. |
| [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py) | `Table.check_priority_list` (≈ L967) | Validates and rebuilds priority lists, ensuring correct ordering from most to least important. |
| [`outfancy/table.py`](https://github.com/carlosplanchon/outfancy/blob/main/outfancy/table.py) | `Table.assign_column_width` (≈ L1092) | Calculates per-column widths, handles equal distribution, and enforces `show_width_threshold`. |
| [`outfancy/widgets.py`](https://github.com/carlosplanchon/outfancy/blob/main/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`](https://github.com/carlosplanchon/outfancy/blob/main/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.