Improved option management, add hook management

[tony]

OptionsMixin, HooksMixin, and SparseArray

Extracted from #513

Warning

APIs below are subject to change (both params, return types, and structures)

Summary

This PR introduces a comprehensive refactor of tmux option and hook management
through new mixin classes (OptionsMixin, HooksMixin) and a SparseArray
data structure for handling tmux's indexed arrays.

Key additions:

• OptionsMixin - Unified option management across Server, Session, Window,
  and Pane
• HooksMixin - Hook management with bulk operations API
• SparseArray - Data structure for tmux's sparse indexed arrays
  (e.g., command-alias[0], command-alias[99])

Changes

New internal: SparseArray

A dict-based data structure that preserves sparse indices while maintaining
list-like behavior:

>>> from libtmux._internal.sparse_array import SparseArray
>>> arr: SparseArray[str] = SparseArray()
>>> arr.add(0, "first")
>>> arr.add(99, "ninety-ninth")
>>> arr[0]
'first'
>>> arr[99]
'ninety-ninth'
>>> list(arr.iter_values())
['first', 'ninety-ninth']

This is essential for handling tmux options like command-alias[0],
command-alias[5], terminal-features[0], etc.

New internal: OptionsMixin

Unified option management across all tmux objects (Server, Session, Window,
Pane).

High-level API:

• show_options() - Returns structured data with SparseArray preservation

  >>> server.show_options()
  {'command-alias': {'split-pane': 'split-window', ...}}

• show_option(option) - Returns a single option value

  >>> server.show_option('command-alias')
  {'split-pane': 'split-window', 'splitp': 'split-window', ...}
  
  >>> server.show_option('buffer-limit')
  50

• set_option(option, value, **kwargs) - Set an option with full flag support

• unset_option(option) - Unset/remove an option

Low-level API:

• _show_options() - Map of options split by key with raw values
• _show_options_raw() - Raw stdout from tmux show-options
• _show_option() - Single option raw value
• _show_option_raw() - Raw stdout from tmux show-option [option]

Backward compatibility:

• The legacy g parameter is still accepted but deprecated in favor of global_
• Using g will emit a DeprecationWarning

New internal: HooksMixin

Hook management for tmux 3.0+ with full support for indexed hooks.

Basic operations:

• set_hook(hook, value) - Set a hook
• show_hook(hook) - Get current hook value (returns SparseArray for indexed
  hooks)
• show_hooks() - Get all hooks
• unset_hook(hook) - Remove a hook
• run_hook(hook) - Run a hook immediately (useful for testing)

Bulk operations:

• set_hooks(hook, values) - Set multiple hooks at once

  >>> session.set_hooks('session-renamed', {
  ...     0: 'display-message "hook 0"',
  ...     1: 'display-message "hook 1"',
  ...     5: 'run-shell "echo hook 5"',
  ... })

Working with indexed hooks:

>>> session.set_hook('session-renamed[0]', 'display-message "test"')
>>> session.set_hook('session-renamed[5]', 'display-message "test2"')

# show_hook returns SparseArray for indexed hooks
>>> hooks = session.show_hook('session-renamed')
>>> isinstance(hooks, SparseArray)
True
>>> sorted(hooks.keys())
[0, 5]
>>> hooks[0]
'display-message "test"'

New features

set_option() params

Param	Flag	Description
_format	-F	Expand format strings
unset	-u	Unset the option
global_	-g	Set as global option
unset_panes	-U	Also unset in other panes
prevent_overwrite	-o	Don't overwrite if exists
suppress_warnings	-q	Suppress warnings
append	-a	Append to existing value

show_option() / show_options() params

• scope - Specify option scope (Server, Session, Window, Pane)
• global_ - Show global options
• include_inherited - Include inherited options (with * suffix in tmux)
• include_hooks - Include hooks in output

Breaking changes

Deprecations

• Window.set_window_option() deprecated in favor of Window.set_option()
• Window.show_window_option() deprecated in favor of Window.show_option()
• Window.show_window_options() deprecated in favor of Window.show_options()
• g parameter deprecated in favor of global_ (emits DeprecationWarning)

New constants

• OptionScope enum: Server, Session, Window, Pane
• OPTION_SCOPE_FLAG_MAP - Maps scope to tmux flags (-s, -w, -p)
• HOOK_SCOPE_FLAG_MAP - Maps scope to hook flags

tmux Version Compatibility

Feature	Minimum tmux
All options/hooks features	3.2+
Window/Pane hooks (-w, -p)	3.2+
client-active, window-resized hooks	3.3+
pane-title-changed hook	3.5+

Testing

• Added comprehensive test grids for options (tests/test_options.py)
• Added comprehensive test grids for hooks (tests/test_hooks.py)
• Tests cover all option scopes, types (int, bool, str, style, choice), and
  tmux versions
• Added test for g parameter deprecation warning
• Added tests for SparseArray utility class

Files Changed

New Files

File	Description
src/libtmux/options.py	OptionsMixin class (1,256 lines)
src/libtmux/hooks.py	HooksMixin class (525 lines)
src/libtmux/_internal/sparse_array.py	SparseArray data structure
src/libtmux/_internal/constants.py	Options/Hooks dataclasses
tests/test_options.py	Comprehensive option tests (1,496 lines)
tests/test_hooks.py	Comprehensive hook tests (1,119 lines)
tests/test/test_sparse_array.py	SparseArray tests
docs/api/options.md	Options API documentation
docs/api/hooks.md	Hooks API documentation
docs/internals/sparse_array.md	SparseArray documentation
docs/internals/constants.md	Internal constants documentation

Modified Files

File	Changes
src/libtmux/constants.py	Added OptionScope, scope flag maps
src/libtmux/common.py	Added CmdMixin, CmdProtocol
src/libtmux/server.py	Uses OptionsMixin, HooksMixin
src/libtmux/session.py	Uses OptionsMixin, HooksMixin
src/libtmux/window.py	Uses OptionsMixin, HooksMixin, deprecated methods
src/libtmux/pane.py	Uses OptionsMixin, HooksMixin
CHANGES	Release notes for 0.50.0
tests/test_window.py	Updated for new API
tests/test_session.py	Updated for new API
tests/legacy_api/test_window.py	Legacy API tests
tests/legacy_api/test_session.py	Legacy API tests

[codecov]

Codecov Report

❌ Patch coverage is 39.73799% with 414 lines in your changes missing coverage. Please review.
✅ Project coverage is 43.99%. Comparing base (309c27f) to head (d24226e).
⚠️ Report is 120 commits behind head on master.

Files with missing lines	Patch %	Lines
src/libtmux/_internal/constants.py	5.53%	237 Missing and 2 partials ⚠️
src/libtmux/options.py	67.65%	65 Missing and 22 partials ⚠️
src/libtmux/hooks.py	50.39%	41 Missing and 22 partials ⚠️
src/libtmux/_internal/sparse_array.py	53.84%	6 Missing ⚠️
src/libtmux/window.py	50.00%	6 Missing ⚠️
src/libtmux/server.py	0.00%	5 Missing ⚠️
src/libtmux/pane.py	0.00%	3 Missing ⚠️
src/libtmux/session.py	0.00%	3 Missing ⚠️
src/libtmux/common.py	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #516      +/-   ##
==========================================
- Coverage   46.77%   43.99%   -2.79%     
==========================================
  Files          18       22       +4     
  Lines        1708     2305     +597     
  Branches      277      362      +85     
==========================================
+ Hits          799     1014     +215     
- Misses        799     1145     +346     
- Partials      110      146      +36     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.