How to Customize Column Separator Characters in Outfancy Tables

Outfancy allows you to customize the string that appears between columns by passing a separator argument to the Table.render method in outfancy/table.py.

The outfancy library provides flexible table formatting for terminal output. When rendering tables, you can control the visual delimiter between columns using the built-in separator parameter. This guide explains how to customize the separator characters in outfancy tables using the Table.render method and its validation logic.

Understanding the Separator Parameter

The primary mechanism for customizing column separators is the separator parameter in the Table.render method.

The Render Method Signature

In outfancy/table.py, the render method accepts a separator argument with the signature separator: str | None = None 【4†L52-L55】. When provided, this string is inserted between each column in the output row.

Default Fallback Behavior

If you omit the separator argument or pass None, the method defaults to a single blank space (' '). This default is also enforced by the Table.check_separator method when validation fails 【5†L31-L35】.

Validating Custom Separator Characters

Outfancy validates custom separators to ensure they render correctly within terminal boundaries.

The Table.check_separator method in outfancy/table.py performs two critical checks 【5†L31-L44】:

• The separator must be a string type.
• The printed length must not exceed the terminal width (screen_x).

If either check fails, the library silently falls back to a single space and logs an error. The printed length calculation uses widgets.printed_length to properly handle ANSI escape codes, ensuring colored separators are measured correctly.

Code Examples for Custom Separators

Here are practical implementations ranging from simple pipes to advanced styling.

Basic Pipe Separator

Use a simple pipe character to create a CSV-like visual output:

from outfancy.table import Table

tbl = Table()
data = [(1, "Alice", 23), (2, "Bob", 30)]

# Use a simple pipe character

print(tbl.render(data, separator="|"))

Visual Unicode Separators

Multi-character separators with box-drawing characters provide clearer visual separation:

# Multi-character separator with box-drawing characters

print(tbl.render(data, separator=" │ "))

ANSI Colored Separators

Embed color codes directly in the separator string. The widgets.printed_length function in outfancy/widgets.py strips these codes before validation:

# Green star separator using ANSI escape codes

print(tbl.render(data, separator="\x1b[32m★\x1b[0m"))

Handling Length Validation

If the separator exceeds the terminal width, check_separator automatically falls back to a single space:

# This 100-character separator exceeds typical terminal widths

long_sep = "—" * 100

# Automatically falls back to single space " " due to check_separator logic

print(tbl.render(data, separator=long_sep))

As implemented in outfancy/table.py, the check_separator method replaces overly long separators with a single space to prevent display corruption 【5†L31-L44】.

Reusable Custom Separator via Subclassing

For projects requiring consistent styling, subclass Table and store the separator as an instance attribute:

class FancyTable(Table):
    def __init__(self, sep=" | "):
        super().__init__()
        self._sep = sep
    
    def render(self, *args, **kwargs):
        # Inject preferred separator unless caller overrides it

        kwargs.setdefault("separator", self._sep)
        return super().render(*args, **kwargs)

# Create instance with custom default separator

fancy = FancyTable(sep=" ▸ ")
print(fancy.render(data))

Summary

• Pass a string to the separator argument of Table.render in outfancy/table.py to customize column delimiters.
• The default separator is a single space (' ') when the argument is omitted or invalid.
• Table.check_separator validates that the separator is a string and fits within the terminal width (screen_x).
• Invalid or overly long separators silently fall back to a single space with an error logged.
• For reusable styling, subclass Table and override render to inject your preferred separator automatically.

Frequently Asked Questions

What is the default column separator in outfancy?

According to the source code in outfancy/table.py, the default separator is a single blank space (' '). This value is used when you omit the separator argument or when Table.check_separator determines the provided value is invalid 【5†L31-L35】.

Can I use ANSI color codes or Unicode symbols as column separators?

Yes. The library supports ANSI escape codes and Unicode characters in the separator string. The widgets.printed_length helper strips color codes before measuring the separator's length against the terminal width, allowing colored separators like "\x1b[32m★\x1b[0m" to render correctly without triggering validation failures.

What happens if my custom separator is longer than the terminal width?

If the separator's printed length exceeds the terminal width (screen_x), the Table.check_separator method silently replaces it with a single space and logs an error 【5†L31-L44】. This safety mechanism prevents display corruption in narrow terminal windows.

How do I set a permanent custom separator for all tables in my project?

Subclass the Table class and store your preferred separator in an instance attribute. Override the render method to inject this separator via kwargs.setdefault("separator", self._sep) before calling super().render(). This approach ensures consistency across your application while still allowing per-call overrides.

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