tony mentioned this pull request

Closed

tony mentioned this pull request

Open

why: Document new OptionsMixin and HooksMixin features for 0.50.x release.
what:
- Add breaking changes for renamed Window option methods
- Document OptionsMixin with set_option, show_option, show_options, unset_option
- Document HooksMixin with set_hook, show_hook, unset_hook, set_hooks
- Document new Window.set_option() arguments

why: Deprecated method should guide users to public API, not private
what:
- Update docstring to reference show_option() instead of _show_option()
- Change method call from _show_option() to show_option()
- Aligns with show_window_options() which correctly uses show_options()

why: The g parameter was accepted but silently ignored, breaking
backward compatibility for callers using the legacy API
what:
- Forward g parameter to _show_option() via global_ or g
- Ensures show_option("foo", g=True) works as expected

why: The g parameter should emit DeprecationWarning like set_option() does
what:
- Add deprecation warning when g parameter is used
- Follow same pattern as set_option() (lines 669-671)
- Ensures backward compatibility while guiding users to global_

why: Deprecation warnings should use proper DeprecationWarning category
to be properly filtered by Python's warning system
what:
- Update all 4 instances of g deprecation warning to use category=DeprecationWarning
- Affects set_option, _show_options_raw, _show_option_raw, show_option

why: Verify that show_option() emits DeprecationWarning when deprecated g
parameter is used
what:
- Add test_show_option_g_parameter_emits_deprecation_warning test
- Ensures backward compatibility warning is properly raised

why: The global_ parameter was accepted but not forwarded, preventing
users from querying server-wide hooks with -g flag
what:
- Forward global_=global_ when calling _show_hook()

why: CHANGES documented bulk hook APIs that don't exist in HooksMixin
what:
- Remove get_hook_indices, get_hook_values, append_hook, clear_hook
- These methods were documented but never implemented
- Keep only the implemented methods: set_hook, show_hook, show_hooks,
  unset_hook, run_hook, set_hooks

why: Server.set_hook() was broken - HOOK_SCOPE_FLAG_MAP[Server] was ""
which added an empty string argument to tmux commands. Server/global
hooks require -g flag per tmux documentation.
what:
- Change OptionScope.Server from "" to "-g" in HOOK_SCOPE_FLAG_MAP
- Fixes Server.set_hook(), Server.show_hooks(), Server.run_hook()

why: Control-mode hooks like %output, %window-add have % prefix that
Hooks.from_stdout() strips when creating attributes, but show_hook()
didn't strip it before lookup, causing all %-prefixed hooks to return
None.
what:
- Add lstrip("%") before replace("-", "_") in show_hook() attribute lookup

why: The g parameter was silently ignored in set_hook(), breaking
backward compatibility. Code calling set_hook(..., g=True) would not
get global behavior.
what:
- Add DeprecationWarning when g parameter is used
- Forward g value to global_ for backward compatibility
- Matches pattern used in OptionsMixin.set_option()

why: Hooks set globally (with global_=True) could not be run via
run_hook() because it had no way to pass -g flag to tmux.
what:
- Add global_: bool | None = None parameter to run_hook()
- Add -g flag handling when global_ is True

why: The SparseArray-specific branch at lines 248-251 was unreachable
dead code. Since SparseArray inherits from dict, isinstance(value, dict)
returns True and the dict branch handles it correctly first.
what:
- Remove unreachable SparseArray branch that contained buggy logic
- Add comment explaining dict branch handles SparseArray too

why: tmux set-hook does not accept -F flag (only set-option does).
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove _format parameter from set_hook() signature
- Remove _format flag handling code

why: tmux set-hook does not accept -o flag (only set-option does).
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove prevent_overwrite parameter from set_hook() signature
- Remove prevent_overwrite flag handling code

why: tmux set-hook does not accept -q flag (only set-option does).
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove ignore_errors parameter from set_hook() signature
- Remove ignore_errors flag handling code

why: tmux set-hook (used with -u for unset) does not accept -q flag.
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove ignore_errors parameter from unset_hook() signature
- Remove ignore_errors flag handling code

why: tmux show-hooks does not accept -q flag.
     Verified against ~/study/c/tmux/cmd-show-options.c:67 which shows
     show-hooks accepts "gpt:w" only.
what:
- Remove ignore_errors parameter from show_hooks() signature
- Remove ignore_errors flag handling code
- Remove ignore_errors from docstring parameters

…rameter
why: tmux show-hooks does not accept -q flag.
     Verified against ~/study/c/tmux/cmd-show-options.c:67 which shows
     show-hooks accepts "gpt:w" only.
what:
- Remove ignore_errors parameter from _show_hook() signature
- Remove ignore_errors parameter from show_hook() signature
- Remove ignore_errors flag handling code
- Remove ignore_errors from _show_hook() call in show_hook()

why: Verify show_option correctly handles bracketed array indices like
'status-format[0]'. Currently returns None instead of the value.
what:
- Add ShowOptionIndexedTestCase NamedTuple with test_id pattern
- Add parametrized test_show_option_indexed_array test
- Test verifies indexed query returns value, base name returns SparseArray
- Test follows TDD RED phase (currently failing as expected)

why: Querying 'status-format[0]' returned None because explode_arrays()
transforms the key to 'status-format', losing the original indexed key.
what:
- Parse raw output first before exploding arrays
- Direct lookup for indexed queries (key with brackets found in raw dict)
- For base name queries, continue with explode_arrays transformation
- Avoids duplicating regex parsing logic already in explode_arrays()

…test
why: The test `test_deprecated_window_methods_emit_warning[show_window_option_global]`
triggered two warnings: the expected one (Window method deprecated) and an unexpected
secondary one (g argument deprecated). The secondary warning leaked to pytest output.
what:
- Add @pytest.mark.filterwarnings to ignore "g argument is deprecated" warning
- Test still validates the primary deprecation warning via pytest.warns()

why: Per tmux.1, terminal-overrides entries are colon-separated strings where
the first part is a terminal pattern and remaining parts are individual
features. The previous code used `split(":", maxsplit=1)` which collapsed all
features after the pattern into a single key.
what:
- Split on all colons, not just the first
- Iterate over each feature part individually
- Add parametrized tests for multi-feature entries

why: When calling show_hook("session-renamed[0]"), the code attempted to find
an attribute named "session_renamed[0]" on the Hooks dataclass, which doesn't
exist. Per tmux.1, hooks are array options that can be queried by index.
what:
- Extract index from bracketed suffix before attribute lookup
- Return specific indexed value from SparseArray when present
- Add parametrized tests for indexed hook lookups

why: tmux appends "*" to option names that are inherited from parent scopes
(e.g., "visual-activity*" when the value comes from global scope). The
lookup code was checking for the exact option name, missing inherited values.
what:
- Check for both exact key and key with "*" suffix in raw output lookup
- Check for inherited marker in exploded output lookup as well
- Fix test to properly capture inherited value before set/unset cycle

why: When tmux outputs inherited array options with -A flag (e.g.,
"status-format[0]*"), the asterisk was being stripped during explosion.
This caused inconsistency: scalar inherited options preserved the "*"
marker but array options did not.
what:
- Update regex to capture trailing "*" in new `inherited` group
- Append "*" to base key when inherited marker is present
- Ensures inherited array options like "status-format[0]*" produce
  "status-format*" keys, consistent with scalar inherited options

…tests
why: Ensure explode_arrays correctly preserves the "*" marker for inherited
array options (e.g., "status-format[0]*" → "status-format*"), consistent
with scalar inherited options.
what:
- Add ExplodeArraysInheritedCase NamedTuple for parametrized tests
- Add 3 test cases: inherited arrays, non-inherited arrays, mixed indices
- Import explode_arrays function for direct unit testing

why: Users upgrading to 0.50.0 need clear guidance on deprecated methods
and the new unified options/hooks API.
what:
- Document new unified options API (show_options, show_option, set_option,
  unset_option) available on all tmux objects
- Document new hooks API (set_hook, show_hook, show_hooks, unset_hook)
- Add deprecation notes for Window.set_window_option(),
  Window.show_window_option(), Window.show_window_options()
- Add deprecation notes for `g` parameter in favor of `global_`
- Include before/after code examples for each migration

why: Users need a conceptual guide explaining the unified options/hooks
API, when to use different methods, and how to work with indexed hooks.
what:
- Create docs/topics/options_and_hooks.md with comprehensive guide
- Cover getting/setting options with show_options(), show_option(),
  set_option(), unset_option()
- Cover hooks API with set_hook(), show_hook(), show_hooks(), unset_hook()
- Document indexed hooks and SparseArray return type
- Include bulk hook operations with set_hooks()
- Add tmux version compatibility table
- Add options_and_hooks to topics/index.md toctree
- All doctests pass via pytest --doctest-glob

why: Users following the quickstart guide need to see basic options
usage alongside other common operations like creating windows and panes.
what:
- Add "Working with options" section before "Final notes"
- Include examples for show_option(), show_options(), set_option(),
  unset_option()
- Add seealso reference to the detailed options-and-hooks topic guide
- All doctests pass via pytest --doctest-glob