Improved option management, add hook management

CHANGES

@@ -34,6 +34,149 @@ $ uvx --from 'libtmux' --prerelease allow python
 
 _Future release notes will be placed here_
 
+### Overview
+
+libtmux 0.50 brings a major enhancement to option and hook management. The new
+{class}`~options.OptionsMixin` and {class}`~hooks.HooksMixin` classes provide a
+unified, typed API for managing tmux options and hooks across all object types.
+
+**Highlights:**
+
+- **Unified Options API**: New `show_option()`, `show_options()`, `set_option()`,
+  and `unset_option()` methods available on Server, Session, Window, and Pane.
+- **Hook Management**: Full programmatic control over tmux hooks with support for
+  indexed hook arrays and bulk operations.
+- **SparseArray**: New internal data structure for handling tmux's sparse indexed
+  arrays (e.g., `command-alias[0]`, `command-alias[99]`).
+- **tmux 3.2+ baseline**: Removed support for tmux versions below 3.2a, enabling
+  cleaner code and full hook/option feature support.
+
+### What's New
+
+#### Unified Options API (#516)
+
+All tmux objects now share a consistent options interface through
+{class}`~options.OptionsMixin`:
+
+```python
+import libtmux
+
+server = libtmux.Server()
+session = server.sessions[0]
+window = session.windows[0]
+pane = window.panes[0]
+
+# Get all options as a structured dict
+session.show_options()
+# {'activity-action': 'other', 'base-index': 0, ...}
+
+# Get a single option value
+session.show_option('base-index')
+# 0
+
+# Set an option
+window.set_option('automatic-rename', True)
+
+# Unset an option (revert to default)
+window.unset_option('automatic-rename')
+```
+
+**New methods on Server, Session, Window, and Pane:**
+
+| Method | Description |
+|--------|-------------|
+| `show_options()` | Get all options as a structured dict |
+| `show_option(name)` | Get a single option value |
+| `set_option(name, value)` | Set an option |
+| `unset_option(name)` | Unset/remove an option |
+
+**New parameters for `set_option()`:**
+
+| Parameter | tmux flag | Description |
+|-----------|-----------|-------------|
+| `_format` | `-F` | Expand format strings in value |
+| `unset` | `-u` | Unset the option |
+| `global_` | `-g` | Set as global option |
+| `unset_panes` | `-U` | Also unset in child panes |
+| `prevent_overwrite` | `-o` | Don't overwrite if exists |
+| `suppress_warnings` | `-q` | Suppress warnings |
+| `append` | `-a` | Append to existing value |
+
+#### Hook Management (#516)
+
+New {class}`~hooks.HooksMixin` provides programmatic control over tmux hooks:
+
+```python
+session = server.sessions[0]
+
+# Set a hook
+session.set_hook('session-renamed', 'display-message "Renamed!"')
+
+# Get hook value
+session.show_hook('session-renamed')
+# 'display-message "Renamed!"'
+
+# Get all hooks
+session.show_hooks()
+# {'session-renamed': 'display-message "Renamed!"'}
+
+# Remove a hook
+session.unset_hook('session-renamed')
+```
+
+**Indexed hooks and bulk operations:**
+
+tmux hooks support multiple values via indices (e.g., `session-renamed[0]`,
+`session-renamed[1]`). The bulk operations API makes this easy:
+
+```python
+# 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"',
+})
+```
+
+**Hook methods available on Server, Session, Window, and Pane:**
+
+| Method | Description |
+|--------|-------------|
+| `set_hook(hook, value)` | Set a hook |
+| `show_hook(hook)` | Get 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 |
+| `set_hooks(hook, values)` | Set multiple indexed hooks at once |
+
+#### SparseArray for Indexed Options (#516)
+
+tmux uses sparse indexed arrays for options like `command-alias[0]`,
+`command-alias[99]`, `terminal-features[0]`. Python lists can't represent
+gaps in indices, so libtmux introduces {class}`~_internal.sparse_array.SparseArray`:
+
+```python
+>>> from libtmux._internal.sparse_array import SparseArray
+
+>>> arr: SparseArray[str] = SparseArray()
+>>> arr.add(0, "first")
+>>> arr.add(99, "ninety-ninth")  # Gap in indices preserved!
+>>> arr[0]
+'first'
+>>> arr[99]
+'ninety-ninth'
+>>> list(arr.keys())
+[0, 99]
+>>> list(arr.iter_values())  # Values in index order
+['first', 'ninety-ninth']
+```
+
+#### New Constants (#516)
+
+- {class}`~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
+
 ## libtmux 0.49.0 (2025-11-29)
 
 ### Breaking Changes
@@ -48,6 +191,35 @@ deprecation announced in v0.48.0.
 - Removed version guards throughout the codebase
 - For users on older tmux, use libtmux v0.48.x
 
+#### Deprecated Window methods (#516)
+
+The following methods are deprecated and will be removed in a future release:
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `Window.set_window_option()` | `Window.set_option()` |
+| `Window.show_window_option()` | `Window.show_option()` |
+| `Window.show_window_options()` | `Window.show_options()` |
+
+The old methods will emit a {class}`DeprecationWarning` when called:
+
+```python
+window.set_window_option('automatic-rename', 'on')
+# DeprecationWarning: Window.set_window_option() is deprecated
+
+# Use the new method instead:
+window.set_option('automatic-rename', True)
+```
+
+### tmux Version Compatibility
+
+| Feature | Minimum tmux |
+|---------|-------------|
+| All options/hooks features | 3.2+ |
+| Window/Pane hook scopes (`-w`, `-p`) | 3.2+ |
+| `client-active`, `window-resized` hooks | 3.3+ |
+| `pane-title-changed` hook | 3.5+ |
+
 ## libtmux 0.48.0 (2025-11-28)
 
 ### Breaking Changes

MIGRATION

@@ -25,6 +25,93 @@ _Detailed migration steps for the next version will be posted here._
 
 <!-- To the maintainers and contributors: please add migration details for the upcoming release here -->
 
+## libtmux 0.50.0: Unified Options and Hooks API (#516)
+
+### New unified options API
+
+All tmux objects (Server, Session, Window, Pane) now share a consistent options
+interface through {class}`~libtmux.options.OptionsMixin`:
+
+```python
+# Get all options
+session.show_options()
+
+# Get a single option
+session.show_option('base-index')
+
+# Set an option
+window.set_option('automatic-rename', True)
+
+# Unset an option
+window.unset_option('automatic-rename')
+```
+
+### New hooks API
+
+All tmux objects now support hook management through
+{class}`~libtmux.hooks.HooksMixin`:
+
+```python
+# Set a hook
+session.set_hook('session-renamed', 'display-message "Renamed!"')
+
+# Get hook value
+session.show_hook('session-renamed')
+
+# Get all hooks
+session.show_hooks()
+
+# Remove a hook
+session.unset_hook('session-renamed')
+```
+
+### Deprecated Window methods
+
+The following `Window` methods are deprecated and will be removed in a future
+release:
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `Window.set_window_option()` | {meth}`Window.set_option() <libtmux.Window.set_option>` |
+| `Window.show_window_option()` | {meth}`Window.show_option() <libtmux.Window.show_option>` |
+| `Window.show_window_options()` | {meth}`Window.show_options() <libtmux.Window.show_options>` |
+
+**Before (deprecated):**
+
+```python
+window.set_window_option('automatic-rename', 'on')
+window.show_window_option('automatic-rename')
+window.show_window_options()
+```
+
+**After (0.50.0+):**
+
+```python
+window.set_option('automatic-rename', True)
+window.show_option('automatic-rename')
+window.show_options()
+```
+
+### Deprecated `g` parameter
+
+The `g` parameter for global options is deprecated in favor of `global_`:
+
+**Before (deprecated):**
+
+```python
+session.show_option('status', g=True)
+session.set_option('status', 'off', g=True)
+```
+
+**After (0.50.0+):**
+
+```python
+session.show_option('status', global_=True)
+session.set_option('status', 'off', global_=True)
+```
+
+Using the old `g` parameter will emit a {class}`DeprecationWarning`.
+
 ## libtmux 0.46.0 (2025-02-25)
 
 #### Imports removed from libtmux.test (#580)

docs/api/hooks.md

@@ -0,0 +1,6 @@
+# Hooks
+
+```{eval-rst}
+.. automodule:: libtmux.hooks
+   :members:
+```

docs/api/index.md

@@ -11,6 +11,8 @@ servers
 sessions
 windows
 panes
+options
+hooks
 constants
 common
 exceptions

docs/api/options.md

@@ -0,0 +1,6 @@
+# Options
+
+```{eval-rst}
+.. automodule:: libtmux.options
+   :members:
+```

docs/internals/constants.md

@@ -0,0 +1,15 @@
+# Internal Constants - `libtmux._internal.constants`
+
+:::{warning}
+Be careful with these! These constants are private, internal as they're **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need a data structure here made public or stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.constants
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :show-inheritance:
+```

docs/internals/index.md

@@ -11,6 +11,8 @@ If you need an internal API stabilized please [file an issue](https://github.com
 ```{toctree}
 dataclasses
 query_list
+constants
+sparse_array
 ```
 
 ## Environmental variables

docs/internals/sparse_array.md

@@ -0,0 +1,14 @@
+# Internal Sparse Array - `libtmux._internal.sparse_array`
+
+:::{warning}
+Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.sparse_array
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/quickstart.md

@@ -441,6 +441,38 @@ automatically sent, the leading space character prevents adding it to the user's
 shell history. Omitting `enter=false` means the default behavior (sending the
 command) is done, without needing to use `pane.enter()` after.
 
+## Working with options
+
+libtmux provides a unified API for managing tmux options across Server, Session,
+Window, and Pane objects.
+
+### Getting options
+
+```python
+>>> server.show_option('buffer-limit')
+50
+
+>>> window.show_options()  # doctest: +ELLIPSIS
+{...}
+```
+
+### Setting options
+
+```python
+>>> window.set_option('automatic-rename', False)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> window.show_option('automatic-rename')
+False
+
+>>> window.unset_option('automatic-rename')  # doctest: +ELLIPSIS
+Window(@... ...)
+```
+
+:::{seealso}
+See {ref}`options-and-hooks` for more details on options and hooks.
+:::
+
 ## Final notes
 
 These objects created use tmux's internal usage of ID's to make servers,

docs/topics/index.md

@@ -10,4 +10,5 @@ Explore libtmux’s core functionalities and underlying principles at a high lev
 
 context_managers
 traversal
+options_and_hooks
 ```