Skip to content

Views

Add a view mixin to auto-render command results and expose matching CLI options.

from clak import ListViewMixin, Parser

class App(ListViewMixin, Parser):
    class Meta:
        view_cli_options = True  # or False, or ("columns", "add_index")

    def cli_run(self, **_):
        return [{"name": "ada", "role": "admin"}]

See the Views guide for usage, options, and override rules.

clak.comp.views

View mixins for automatic CLI rendering and view options.

Option layers (mirror ClakView hierarchy):

  1. ClakViewOptMixin — generic (no CLI flags)
  2. TableViewOptMixin — table (Show/List): width, format, columns, sort_columns, sort_mode, wrap, add_index
  3. ListViewMixin — list-only: expand_keys
  4. TextLayoutOptMixin — text wrap: line_length
  5. TextViewOptMixin — text (Markdown/Rst): format (view / raw) plus line_length
  6. PprintViewMixin / RawViewMixin — line_length only
  7. DataViewMixin — structured dump: format, compact, color, anchors
  8. CompositeViewMixin — table opts + expand_keys + format_scope + line_length (return a CompositeView; no auto cli_view)

Example:

class App(ListViewMixin, Parser):
    class Meta:
        view_cli_options = True  # or False, or ("columns", "add_index")
        view_columns = ("name", "role")
        view_column_names = ("name", "role", "city")
        view_sort_columns = 1
        view_format = "view"
        view_width = "terminal"
        view_wrap = "last"

    def cli_run(self, **_):
        return [{"name": "a"}, {"name": "b"}]

ClakViewOptMixin

Bases: _ViewMixinBase

Layer 1: generic ClakView (no CLI flags).

TableViewOptMixin

Bases: ClakViewOptMixin

Layer 2: table view options shared by Show and List.

TextLayoutOptMixin

Bases: ClakViewOptMixin

Text wrap options shared by Raw, Pprint, Markdown, Rst, and Composite.

TextViewOptMixin

Bases: TextLayoutOptMixin

Layer 2: text view options shared by Markdown and Rst.

ShowViewMixin

Bases: TableViewOptMixin

Auto-render command results with :class:~clak.views.ShowView.

Adds --columns, --add-index / --no-add-index, --format, --sort-columns, --sort-mode, --width, and --wrap. Configure exposed flags with Meta.view_cli_options.

ListViewMixin

Bases: TableViewOptMixin

Auto-render command results with :class:~clak.views.ListView.

Adds --columns, --add-index / --no-add-index, --expand-keys / --no-expand-keys, --format, --sort-columns, --sort-mode, --width, and --wrap. Configure exposed flags with Meta.view_cli_options.

PprintViewMixin

Bases: TextLayoutOptMixin

Auto-render command results with :class:~clak.views.PprintView.

Adds --line-length. Configure exposed flags with Meta.view_cli_options.

DataViewMixin

Bases: _ViewMixinBase

Auto-render command results with :class:~clak.views.DataView.

Adds --format (json / yaml), --compact / --no-compact, --color / --no-color, and --anchors / --no-anchors. Syntax theme: Meta.view_syntax_theme or CLAK_SYNTAX_THEME, else ansi_dark. Configure exposed flags with Meta.view_cli_options.

RawViewMixin

Bases: TextLayoutOptMixin

Auto-render command results with :class:~clak.views.RawView.

Adds --line-length. Configure exposed flags with Meta.view_cli_options.

MarkdownViewMixin

Bases: TextViewOptMixin

Auto-render command results with :class:~clak.views.MarkdownView.

Adds --format (view / raw) and --line-length. Syntax theme: Meta.view_syntax_theme or CLAK_SYNTAX_THEME, else ansi_dark. Configure exposed flags with Meta.view_cli_options.

RstViewMixin

Bases: TextViewOptMixin

Auto-render command results with :class:~clak.views.RstView.

Adds --format (view / raw) and --line-length. Configure exposed flags with Meta.view_cli_options.

CompositeViewMixin

Bases: TextLayoutOptMixin, TableViewOptMixin

CLI flags for multi-section :class:~clak.views.CompositeView output.

Adds table options, --expand-keys, --format-scope, --width, and --line-length. Does not set Meta.cli_view: return a CompositeView(...) from cli_run. Table flags apply to the primary section only. --line-length applies to text/pprint sections only. --expand-keys is for a ListView primary; hide it with Meta.view_cli_options when the primary is ShowView. --format is table-scoped (view / yaml / json / csv); markdown source is in --format-scope all envelopes, not --format raw.

clak.views

View classes for command line output formatting.

Classes:

Name Description
ClakView

Base view class for rendering command output
ShowView / ListView

Table-oriented views
PprintView / RawView / MarkdownView / RstView

Text views
DataView

Structured JSON / YAML dumps

Functions:

Name Description
pformat_truncated

Format data with width constraints

FeatureFullViewer = TableView module-attribute

OUTPUT_FORMATS = frozenset({'view', 'yaml', 'json', 'csv'}) module-attribute

TEXT_FORMATS = frozenset({'view', 'raw'}) module-attribute

DATA_FORMATS = frozenset({'json', 'yaml'}) module-attribute

FORMAT_SCOPES = frozenset({'first', 'all'}) module-attribute

WIDTH_MODES = frozenset({'content', 'fit', 'terminal'}) module-attribute

WRAP_MODES = frozenset({'last', 'all', 'first'}) module-attribute

DEFAULT_LINE_LENGTH = 120 module-attribute

ShowView

Bases: TableView

Render show data

render(*args, stdout=True, **kwargs)

Render data

ListView

Bases: TableView

Render list data

render(*args, stdout=True, **kwargs)

Render data

PprintView

Bases: ClakView

Render any payload with pprint

render(*args, stdout=True, **kwargs)

Render data

DataView

Bases: ClakView

Render any payload as structured JSON or YAML.

render(*args, stdout=True, **kwargs)

Render data

RawView

Bases: ClakView

Render payload as plain text

render(*args, stdout=True, **kwargs)

Render data

MarkdownView

Bases: ClakView

Render markdown text (or raw source with format=raw)

render(*args, stdout=True, **kwargs)

Render data

RstView

Bases: ClakView

Render reStructuredText (or raw source with format=raw)

render(*args, stdout=True, **kwargs)

Render data

CompositeView

Bases: ClakView

Render ordered sections (tables and/or text) as one CLI output.

Human view mode prints sections separated by a blank line and equalizes table outer widths. Machine formats honor format_scope:

  • first (default): export only the primary section
  • all: export a structured envelope of every section

render(*args, stdout=True, **kwargs)

Render composite sections

ClakView

Render command line output

TableView

Bases: ClakView

Table view base: shared settings for Show and List

merge_view_settings(existing=None, cli_settings=None)

Merge CLI view settings over existing view settings.

CLI values win. When CLI overrides a non-None existing value, log a warning.

parse_columns(value)

Parse a comma-separated --columns value into a list of keys/indexes.

Integer tokens use the same rules as --sort-columns: 1-based indexes (1=first), negatives from end (-1=last). Index 0 is rejected at resolve.

parse_sort_columns(value)

Parse --sort-columns: names, 1-based indexes (1=first), or negatives from end.

parse_wrap(value)

Parse --wrap: keyword last/all/first, or flexible column specs.

Keywords are recognized only when they are the entire value (case insensitive). Otherwise the value is a comma-separated column list (same rules as --columns). Listed columns expand or shrink to fit the terminal; other columns stay content-sized.

normalize_sort_columns(value)

Normalize Meta.view_sort_columns (string, int index, or sequence).

normalize_wrap(value)

Normalize Meta.view_wrap (keyword or flexible column specs).

normalize_wrap_min(value)

Normalize Meta.view_wrap_min: positive int or column-spec mapping.

normalize_sections(sections)

Normalize section specs to (name, ClakView, meta) triples.

format_show_payload(payload, fmt, columns=None, sort_columns=None, sort_mode='asc', add_index=True)

Render a single show payload as yaml, json, or csv.

Sort is applied before serialization (same column rules as the table path).

format_data_payload(payload, *, fmt=None, compact=False, anchors=True)

Serialize payload as JSON or YAML text (no color).

resolve_view_width(settings=None, *, width=None, term_width=None, stdout_tty=None)

Resolve effective table width mode and optional terminal budget.

Non-TTY stdout forces fit / terminal down to content (no wrap). Returns (effective_mode, term_budget_or_none).

resolve_line_length(settings=None, *, line_length=None, term_width=None, stdout_tty=None)

Resolve whether to wrap text and the column budget.

nowrap or non-TTY stdout: no wrap. terminal: wrap to term_width. A positive int N: wrap to min(term_width, N). Returns (wrap, budget_or_none).

resolve_data_format(fmt=None)

Resolve json / yaml; None / view means auto (yaml if available).

parse_line_length(value=None)

Parse a text line_length: positive int, terminal, or nowrap.

0 is rejected; use nowrap or terminal.

normalize_width_mode(mode=None)

Return a canonical table width mode (content / fit / terminal).

Accepts aliases min -> content and auto -> fit.