Skip to content
lazy-cuh

Public API Reference

This page is a compact index of the documented public surface. The root package exports focused subpackages only; app-building primitives live under those subpackages by responsibility.

The export surfaces are snapshot-tested in tests/test_public_api.py; additions and removals should be intentional.

Root Package

Section titled “Root Package”

Import the package namespace and access focused subpackages:

import lazy_cuh as lc


item = lc.core.NavigableItem(id="one", label="first")
panel = lc.view.PanelSpec(id="main", index=1, tabs=(lc.view.TabSpec("main", "Main"),))

Core Models

Section titled “Core Models”
  • Items and options: NavigableItem, KeyValueItem, OptionItem, EditableOption, OptionEditRequest, OptionEditOutcome, OptionEditOutcomeKind, OptionSet, parse_bool, format_bool
  • Tree data: TreeItem, VisibleTreeItem, flatten_visible_tree, find_tree_item, set_tree_item_expanded, toggle_tree_item_expanded
  • Selection and notices: SelectionState, Notice, NoticeLevel
  • Events and commands: Event, ItemHighlighted, ItemSelected, ActionRequested, TabChanged, Command, GlobalCommand, ItemCommand, command_from_action

Input, Actions, And Hints

Section titled “Input, Actions, And Hints”
  • Action metadata: ActionBinding, ActionId, ActionMap, ActionDispatcher, ActionDispatchContext, ActionDispatchResult, ActionHandlerSpec
  • Hints: lc.hints.Hint, lc.hints.HintGroup, lc.hints.hints_from_actions, lc.hints.hint_groups_from_actions
  • Hint metadata: HintPlacement, HintVisibility, HintViewSpec
  • Key sequences: KeySequence, parse_key_sequence, KeyAlias, KeyAliasMap, KeyDisplayMap
  • Input resolution: InputResolver, InputResolution, InputResolutionKind
  • Binding registry: BindingRegistry, ScopedBinding, BindingContext, BindingCollision, BindingDiagnostic, BindingDiagnosticKind, BindingDiagnosticSeverity, CollisionPolicy, format_binding_diagnostics
  • Profiles and navigation: KeyHandlingProfile, CountPolicy, SIMPLE_KEYS, VIM_NAVIGATION_KEYS, ListNavigationState, NavigableKeymap, NavigableInputResolver, NavigationCommand, NavigationCommandKind, NavigableInput, NavigableIntent, ShellCommandState, ShellCommandKeymap, ShellCommand, default_shell_commands, is_count_key

Views And Layout

Section titled “Views And Layout”
  • Lists: ListViewModel, ListViewSpec
  • Trees: TreeViewModel, TreeViewSpec, TreeGuideStyle
  • Text: TextViewModel, TextViewSpec, TextContent
  • Shared view settings: ViewSettings
  • Panels and tabs: PanelSpec, PanelTitle, TabSpec, panel_title
  • Shell state: ShellState, ShellController, ShellKeyResult, FocusGraph, Direction, TabChange
  • Layout: LineNumberMode, LineNumberSpec, WrapMode, RenderedItem, RenderedLine, compose_row, render_item, render_line_number, line_number_for_index, line_number_width, next_line_number_mode
  • Viewport: ViewportMap, ItemLineRange, ScrollPolicy, ScrollState, clamp_line, effective_scroll_margin, half_page_step

Keybars, Modals, And Styles

Section titled “Keybars, Modals, And Styles”
  • Keybars: KeybarSpec, KeyHint, ContextualKeybar; domain helpers lc.keybar.from_actions, lc.keybar.render, lc.keybar.render_expanded, lc.keybar.render_help, lc.keybar.notice
  • Builders: lc.builders.actions.ActionScopeBuilder, lc.builders.shell.panel, lc.builders.shell.tab, lc.builders.shell.panel_widget, lc.builders.shell.content, lc.builders.shell.runtime_spec, lc.builders.actions.bind, lc.builders.actions.action_map, lc.builders.actions.registry, lc.builders.actions.scoped, lc.builders.actions.shell, lc.builders.actions.tabs, lc.builders.options.OptionsSpec, lc.builders.options.declare, lc.builders.options.field, lc.builders.options.text, lc.builders.options.integer, lc.builders.options.boolean, lc.builders.options.choice, lc.builders.options.set, lc.builders.options.edit_modal, lc.builders.options.edit_modal_for_item, lc.builders.options.apply_edit_result, lc.builders.options.view_model, lc.builders.options.refresh_view_model
  • Composition: lc.composition.shell.declare, lc.composition.shell.panel, lc.composition.shell.tab, lc.composition.shell.KeyScope, lc.composition.shell.navigation, lc.composition.shell.edge, lc.composition.shell.connect, lc.composition.shell.opposite_direction, lc.composition.shell.binding, lc.composition.shell.focus_binding, lc.composition.shell.move_binding, lc.composition.shell.panel_focus_bindings, lc.composition.shell.directional_focus_bindings, lc.composition.shell.select_tab_binding, lc.composition.shell.cycle_tab_binding, lc.composition.shell.cycle_line_numbers_binding, lc.composition.shell.focus, lc.composition.shell.move, lc.composition.shell.select_tab, lc.composition.shell.cycle_tab, lc.composition.shell.cycle_line_numbers, lc.composition.shell.ShellSpec, lc.composition.shell.ShellPanel, lc.composition.shell.ShellTab, lc.composition.shell.ShellNavigation, lc.composition.shell.ShellBinding, lc.composition.shell.ShellAction, lc.composition.shell.ShellActionKind, lc.composition.shell.ShellRuntimeSpec, ShellRuntimeSpec.compose, ShellRuntimeSpec.textual_bindings, ShellRuntimeSpec.validate_bindings, lc.composition.shell.default_textual_action_name, lc.composition.shell.runtime_from_spec, lc.composition.shell.textual_bindings_from_spec, lc.composition.shell.runtime, lc.composition.shell.textual_bindings, lc.composition.shell.dispatch_key
  • Modals: InputModalSpec, ConfirmModalSpec, InfoModalSpec, ModalState, ModalResult, ModalKind, ModalSpec, ModalContent, ModalLayoutSpec, InputParser, InputValidator, InputParseErrorFormatter
  • Presets: lc.presets.keys.leader, lc.presets.keys.display, lc.presets.keys.vim_directions, lc.presets.keys.arrow_directions, lc.presets.keys.movement_directions, lc.presets.navigation.ItemNavigationPreset, lc.presets.navigation.TreeActionKeymap, lc.presets.navigation.item, lc.presets.navigation.item_keymap, lc.presets.navigation.move_hint, lc.presets.navigation.select_hint, lc.presets.navigation.keybar_hints, lc.presets.navigation.lazygit, lc.presets.navigation.lazygit_keymap, lc.presets.navigation.lazy_vim, lc.presets.navigation.lazy_vim_keymap, lc.presets.navigation.tree_action_keymap, lc.presets.navigation.tree_action_hints, lc.presets.shell.bindings, lc.presets.shell.lazygit, lc.presets.shell.lazyvim
  • Styles: LAZY_CUH_CSS, Palette, StyleRole

Focused Subpackages

Section titled “Focused Subpackages”

Use focused subpackages when working on one layer of the framework or when a downstream app wants narrower imports.

| Package | Responsibility | | --- | --- | | lazy_cuh.core | Plain item, option, tree, event, command, notice, and selection models | | lazy_cuh.composition | Higher-level helpers that assemble primitives, builders, app content, shell declarations, and widgets | | lazy_cuh.hints | Neutral projection from action metadata into user-facing key hints and help groups | | lazy_cuh.inputs | Actions, key sequences, binding registry, input resolution, and navigation profiles | | lazy_cuh.keybar | Keybar models, contextual keybars, and keybar renderers | | lazy_cuh.layout | Item-to-line rendering, wrapping, line numbers, and row composition | | lazy_cuh.modals | Pure modal specs, layout policy, results, and state transitions | | lazy_cuh.presets | Opinionated key, theme, and shell defaults | | lazy_cuh.styles | Palette roles and default Textual CSS | | lazy_cuh.view | List, tree, text, panel, tab, and shell view models | | lazy_cuh.viewport | Visual-line mapping and scroll policy helpers | | lazy_cuh.widgets | Textual adapter widgets and widget messages |

Textual Widgets

Section titled “Textual Widgets”

Textual adapters live under lazy_cuh.widgets:

  • Widgets: ListViewWidget, TreeViewWidget, TextViewWidget, KeybarWidget, ModalWidget
  • Shell/modal adapters: ShellViewAdapter, ShellRuntime, ModalHost
  • Adapter specs: PanelWidgetSpec, ContentWidgetSpec, ContentKind
  • Messages and actions: ItemHighlightedMessage, ItemSelectedMessage, ItemActionMessage, ModalResultMessage, NavigableAction
  • Widget configuration/helpers: NavigableKeymap, render_model_lines, render_tree_lines, render_text_lines

Use widget imports only at the Textual boundary. Keep app state and user intentions in pure models, action maps, and commands.

App Composition

Section titled “App Composition”

lazy_cuh.composition.app is the first app-level composition layer above lazy_cuh.composition.shell. It can declare a shell and content together, or attach content slots to an existing shell without moving widget factory concerns into ShellSpec.

  • Models: AppSpec, ContentSlot
  • Shell helper: shell
  • Content helpers: declare, slot, list, tree, text, options
  • Typing helpers: ShellActionsFactory, WidgetFactory

Use this layer when app content needs to declare panel/tab ownership, widget ids, content kind, and focus behavior in one place. Keep using lazy_cuh.composition.shell directly when lower-level shell wiring is more appropriate.

AppSpec also carries optional ViewSettings defaults. Use lc.composition.app.shell(..., view=...) for app-wide presentation defaults and panel(..., view=...), tab(..., view=...), or content-slot view= for narrower overrides.

Use lc.builders.view.relative_lines(), absolute_lines(), no_line_numbers(), or settings(...) for concise view settings. Use lc.view.ViewSettings directly when a caller needs the explicit model object.

Section titled “Related Guides”