Skip to content

Commit 097ab3a

Browse files
tonytony
committed
deprecations(fix): Revert 0.50 deprecations to soft warnings
why: The window option methods (set_window_option, show_window_options, show_window_option) and the g parameter were only soft-deprecated in v0.50.0 (2025-11-30). Converting to hard errors in v0.51.0 is too aggressive - users need more time to migrate. what: - Revert window option methods from DeprecatedError to DeprecationWarning - Revert g parameter on options/hooks methods to DeprecationWarning - Fix docstring versions from 0.26 to 0.50 (typo in original commit) - Update CHANGES and MIGRATION tables to reflect soft deprecation - Update tests to expect DeprecationWarning instead of DeprecatedError
1 parent b4cc75a commit 097ab3a

File tree

8 files changed

+94
-71
lines changed

8 files changed

+94
-71
lines changed

‎CHANGES‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ _Upcoming changes will be written here._
4646

4747
#### APIs deprecated (#611)
4848

49-
Legacy API methods now raise {exc}`~libtmux.exc.DeprecatedError` (hard error) instead of emitting {class}`DeprecationWarning`.
49+
Legacy API methods (deprecated in 0.16-0.33) now raise {exc}`~libtmux.exc.DeprecatedError` (hard error) instead of emitting {class}`DeprecationWarning`.
5050

5151
See {doc}`migration` for full context and examples.
5252

@@ -58,9 +58,14 @@ See {doc}`migration` for full context and examples.
5858
| `resize_pane()`, `select_pane()`, `split_window()` | {meth}`~libtmux.Pane.resize`, {meth}`~libtmux.Pane.select`, {meth}`~libtmux.Pane.split` | 0.28.0 / 0.30.0 / 0.33.0 | 0.51.0 | Pane |
5959
| `attached_window`, `attached_pane` | {attr}`~libtmux.Session.active_window`, {attr}`~libtmux.Session.active_pane` / {attr}`~libtmux.Window.active_pane` | 0.31.0 | 0.51.0 | Session/Window |
6060
| `list_*()`, `_list_*()`, `_update_*()`, `children`, `where()`, `find_where()`, `get_by_id()` | {attr}`~libtmux.Server.sessions` / {attr}`~libtmux.Session.windows` / {attr}`~libtmux.Window.panes` with {meth}`~libtmux.common.QueryList.filter` / {meth}`~libtmux.common.QueryList.get` | 0.16.0 / 0.17.0 | 0.51.0 | Query/filter helpers |
61-
| Dict-style access (`obj["key"]`, `obj.get(...)`) | Attribute access (e.g., {attr}`~libtmux.window.Window.window_name`) | 0.16.0 | 0.51.0 | All tmux objects |
62-
| `set_window_option()`, `show_window_option()`, `show_window_options()` | {meth}`~libtmux.window.Window.set_option`, {meth}`~libtmux.window.Window.show_option`, {meth}`~libtmux.window.Window.show_options` | 0.50.0 | 0.51.0 | Window |
63-
| `g` parameter on options/hooks methods | `global_` on {meth}`~libtmux.options.OptionsMixin.set_option`, {meth}`~libtmux.options.OptionsMixin.show_option`, {meth}`~libtmux.options.OptionsMixin.show_options` | 0.50.0 | 0.51.0 | Options & hooks |
61+
| Dict-style access (`obj["key"]`, `obj.get(...)`) | Attribute access (e.g., {attr}`~libtmux.window.Window.window_name`) | 0.17.0 | 0.51.0 | All tmux objects |
62+
63+
The following deprecations from 0.50.0 continue to emit {class}`DeprecationWarning` (soft deprecation):
64+
65+
| Deprecated API | Replacement | Deprecated | Note |
66+
|----------------|-------------|------------|------|
67+
| `set_window_option()`, `show_window_option()`, `show_window_options()` | {meth}`~libtmux.window.Window.set_option`, {meth}`~libtmux.window.Window.show_option`, {meth}`~libtmux.window.Window.show_options` | 0.50.0 | Window |
68+
| `g` parameter on options/hooks methods | `global_` on {meth}`~libtmux.options.OptionsMixin.set_option`, {meth}`~libtmux.options.OptionsMixin.show_option`, {meth}`~libtmux.options.OptionsMixin.show_options` | 0.50.0 | Options & hooks |
6469

6570
## libtmux 0.50.0 (2025-11-30)
6671

‎MIGRATION‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,9 @@ sections below for detailed migration examples and code samples.
3434
| Window | `select_window()` | `select()` | 0.30.0 (2024-02-16) | 0.51.0 |
3535
| Window | `kill_window()` | `kill()` | 0.30.0 (2024-02-16) | 0.51.0 |
3636
| Window | `split_window()` | `split()` | 0.33.0 (2024-03-17) | 0.51.0 |
37-
| Window | `set_window_option()` | `set_option()` | 0.50.0 (2025-11-30) | 0.51.0 |
38-
| Window | `show_window_option()` | `show_option()` | 0.50.0 (2025-11-30) | 0.51.0 |
39-
| Window | `show_window_options()` | `show_options()` | 0.50.0 (2025-11-30) | 0.51.0 |
37+
| Window | `set_window_option()` | `set_option()` | 0.50.0 (2025-11-30) | _(warning)_ |
38+
| Window | `show_window_option()` | `show_option()` | 0.50.0 (2025-11-30) | _(warning)_ |
39+
| Window | `show_window_options()` | `show_options()` | 0.50.0 (2025-11-30) | _(warning)_ |
4040
| Pane | `select_pane()` | `select()` | 0.30.0 (2024-02-16) | 0.51.0 |
4141
| Pane | `resize_pane()` | `resize()` | 0.28.0 (2024-02-14) | 0.51.0 |
4242
| Pane | `split_window()` | `split()` | 0.33.0 (2024-03-17) | 0.51.0 |
@@ -53,7 +53,7 @@ sections below for detailed migration examples and code samples.
5353

5454
| Method(s) | Deprecated | Replacement | Since | Raises |
5555
|-----------|------------|-------------|-------|--------|
56-
| Options/hooks methods | `g` | `global_` | 0.50.0 (2025-11-30) | 0.51.0 |
56+
| Options/hooks methods | `g` | `global_` | 0.50.0 (2025-11-30) | _(warning)_ |
5757
| `split_window()` / `split()` | `percent` | `size` | 0.28.0 (2024-02-14) | 0.51.0 |
5858
| `split_window()` / `split()` | `vertical`/`horizontal` | `direction` (PaneDirection) | 0.33.0 (2024-03-17) | 0.51.0 |
5959
| `resize_pane()` | `-U`, `-D`, `-L`, `-R` | `adjustment_direction` | 0.28.0 (2024-02-14) | 0.51.0 |

‎src/libtmux/hooks.py‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,6 @@
4747
)
4848
from libtmux.options import handle_option_error
4949

50-
from . import exc
51-
5250
if t.TYPE_CHECKING:
5351
from typing_extensions import Self
5452

@@ -141,11 +139,12 @@ def set_hook(
141139
scope = self.default_hook_scope
142140

143141
if g:
144-
raise exc.DeprecatedError(
145-
deprecated="g parameter",
146-
replacement="global_ parameter",
147-
version="0.50.0",
142+
warnings.warn(
143+
"g argument is deprecated in favor of global_",
144+
category=DeprecationWarning,
145+
stacklevel=2,
148146
)
147+
global_ = g
149148

150149
flags: list[str] = []
151150

‎src/libtmux/options.py‎

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@
7272
import re
7373
import shlex
7474
import typing as t
75+
import warnings
7576

7677
from libtmux._internal.sparse_array import SparseArray
7778
from libtmux.common import CmdMixin
@@ -668,11 +669,12 @@ def set_option(
668669
flags.append("-a")
669670

670671
if g is not None:
671-
raise exc.DeprecatedError(
672-
deprecated="g parameter",
673-
replacement="global_ parameter",
674-
version="0.50.0",
672+
warnings.warn(
673+
"g argument is deprecated in favor of global_",
674+
category=DeprecationWarning,
675+
stacklevel=2,
675676
)
677+
global_ = g
676678

677679
if global_ is not None and global_:
678680
assert isinstance(global_, bool)
@@ -828,11 +830,12 @@ def _show_options_raw(
828830
flags: tuple[str, ...] = ()
829831

830832
if g:
831-
raise exc.DeprecatedError(
832-
deprecated="g parameter",
833-
replacement="global_ parameter",
834-
version="0.50.0",
833+
warnings.warn(
834+
"g argument is deprecated in favor of global_",
835+
category=DeprecationWarning,
836+
stacklevel=2,
835837
)
838+
global_ = g
836839

837840
if global_:
838841
flags += ("-g",)
@@ -1060,11 +1063,12 @@ def _show_option_raw(
10601063
flags: tuple[str | int, ...] = ()
10611064

10621065
if g:
1063-
raise exc.DeprecatedError(
1064-
deprecated="g parameter",
1065-
replacement="global_ parameter",
1066-
version="0.50.0",
1066+
warnings.warn(
1067+
"g argument is deprecated in favor of global_",
1068+
category=DeprecationWarning,
1069+
stacklevel=2,
10671070
)
1071+
global_ = g
10681072

10691073
if global_:
10701074
flags += ("-g",)
@@ -1241,11 +1245,12 @@ def show_option(
12411245
False
12421246
"""
12431247
if g:
1244-
raise exc.DeprecatedError(
1245-
deprecated="g parameter",
1246-
replacement="global_ parameter",
1247-
version="0.50.0",
1248+
warnings.warn(
1249+
"g argument is deprecated in favor of global_",
1250+
category=DeprecationWarning,
1251+
stacklevel=2,
12481252
)
1253+
global_ = g
12491254

12501255
return self._show_option(
12511256
option=option,

‎src/libtmux/window.py‎

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
import logging
1212
import shlex
1313
import typing as t
14+
import warnings
1415

1516
from libtmux._internal.query_list import QueryList
1617
from libtmux.common import tmux_cmd
@@ -855,29 +856,35 @@ def set_window_option(
855856
) -> Window:
856857
"""Set option for tmux window. Deprecated by :meth:`Window.set_option()`.
857858
858-
.. deprecated:: 0.26
859+
.. deprecated:: 0.50
859860
860861
Deprecated by :meth:`Window.set_option()`.
861862
862863
"""
863-
raise exc.DeprecatedError(
864-
deprecated="Window.set_window_option()",
865-
replacement="Window.set_option()",
866-
version="0.50.0",
864+
warnings.warn(
865+
"Window.set_window_option() is deprecated in favor of Window.set_option()",
866+
category=DeprecationWarning,
867+
stacklevel=2,
867868
)
869+
return self.set_option(option=option, value=value)
868870

869871
def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
870872
"""Show options for tmux window. Deprecated by :meth:`Window.show_options()`.
871873
872-
.. deprecated:: 0.26
874+
.. deprecated:: 0.50
873875
874876
Deprecated by :meth:`Window.show_options()`.
875877
876878
"""
877-
raise exc.DeprecatedError(
878-
deprecated="Window.show_window_options()",
879-
replacement="Window.show_options()",
880-
version="0.50.0",
879+
warnings.warn(
880+
"Window.show_window_options() is deprecated"
881+
" in favor of Window.show_options()",
882+
category=DeprecationWarning,
883+
stacklevel=2,
884+
)
885+
return self.show_options(
886+
global_=g or False,
887+
scope=OptionScope.Window,
881888
)
882889

883890
def show_window_option(
@@ -887,15 +894,20 @@ def show_window_option(
887894
) -> str | int | None:
888895
"""Return option for target window. Deprecated by :meth:`Window.show_option()`.
889896
890-
.. deprecated:: 0.26
897+
.. deprecated:: 0.50
891898
892899
Deprecated by :meth:`Window.show_option()`.
893900
894901
"""
895-
raise exc.DeprecatedError(
896-
deprecated="Window.show_window_option()",
897-
replacement="Window.show_option()",
898-
version="0.50.0",
902+
warnings.warn(
903+
"Window.show_window_option() is deprecated"
904+
" in favor of Window.show_option()",
905+
category=DeprecationWarning,
906+
stacklevel=2,
907+
)
908+
return self.show_option(
909+
option=option,
910+
global_=g,
899911
)
900912

901913
def get(self, key: str, default: t.Any | None = None) -> t.Any:

‎tests/legacy_api/test_window.py‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -57,32 +57,32 @@ def test_kill_window_raises_deprecated_error(session: Session) -> None:
5757
window.kill_window()
5858

5959

60-
def test_set_window_option_raises_deprecated_error(session: Session) -> None:
61-
"""Test Window.set_window_option() raises exc.DeprecatedError."""
60+
def test_set_window_option_emits_deprecation_warning(session: Session) -> None:
61+
"""Test Window.set_window_option() emits DeprecationWarning."""
6262
window = session.active_window
6363

64-
with pytest.raises(
65-
exc.DeprecatedError, match=r"Window\.set_window_option\(\) was deprecated"
64+
with pytest.warns(
65+
DeprecationWarning, match=r"Window\.set_window_option\(\) is deprecated"
6666
):
6767
window.set_window_option("main-pane-height", 20)
6868

6969

70-
def test_show_window_options_raises_deprecated_error(session: Session) -> None:
71-
"""Test Window.show_window_options() raises exc.DeprecatedError."""
70+
def test_show_window_options_emits_deprecation_warning(session: Session) -> None:
71+
"""Test Window.show_window_options() emits DeprecationWarning."""
7272
window = session.active_window
7373

74-
with pytest.raises(
75-
exc.DeprecatedError, match=r"Window\.show_window_options\(\) was deprecated"
74+
with pytest.warns(
75+
DeprecationWarning, match=r"Window\.show_window_options\(\) is deprecated"
7676
):
7777
window.show_window_options()
7878

7979

80-
def test_show_window_option_raises_deprecated_error(session: Session) -> None:
81-
"""Test Window.show_window_option() raises exc.DeprecatedError."""
80+
def test_show_window_option_emits_deprecation_warning(session: Session) -> None:
81+
"""Test Window.show_window_option() emits DeprecationWarning."""
8282
window = session.active_window
8383

84-
with pytest.raises(
85-
exc.DeprecatedError, match=r"Window\.show_window_option\(\) was deprecated"
84+
with pytest.warns(
85+
DeprecationWarning, match=r"Window\.show_window_option\(\) is deprecated"
8686
):
8787
window.show_window_option("main-pane-height")
8888

‎tests/test_options.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1351,12 +1351,12 @@ def test_convert_values_preserves_sparse_keys() -> None:
13511351
assert result[99] == 100
13521352

13531353

1354-
def test_show_option_g_parameter_raises_deprecated_error(
1354+
def test_show_option_g_parameter_emits_deprecation_warning(
13551355
session: Session,
13561356
) -> None:
1357-
"""Test show_option() raises DeprecatedError when g parameter is used."""
1357+
"""Test show_option() emits DeprecationWarning when g parameter is used."""
13581358
server = session.server
1359-
with pytest.raises(exc.DeprecatedError, match=r"g parameter was deprecated"):
1359+
with pytest.warns(DeprecationWarning, match=r"g argument is deprecated"):
13601360
server.show_option("buffer-limit", g=True)
13611361

13621362

‎tests/test_window.py‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -725,46 +725,48 @@ class DeprecatedMethodTestCase(t.NamedTuple):
725725
expected_error_match: str # Regex pattern to match error message
726726

727727

728-
DEPRECATED_WINDOW_METHOD_TEST_CASES: list[DeprecatedMethodTestCase] = [
728+
# These methods were deprecated in 0.50.0 and still emit warnings (not errors)
729+
DEPRECATED_WARNING_WINDOW_METHOD_TEST_CASES: list[DeprecatedMethodTestCase] = [
729730
DeprecatedMethodTestCase(
730731
test_id="set_window_option",
731732
method_name="set_window_option",
732733
args=("main-pane-height", 20),
733734
kwargs={},
734-
expected_error_match=r"Window\.set_window_option\(\) was deprecated",
735+
expected_error_match=r"Window\.set_window_option\(\) is deprecated",
735736
),
736737
DeprecatedMethodTestCase(
737738
test_id="show_window_options",
738739
method_name="show_window_options",
739740
args=(),
740741
kwargs={},
741-
expected_error_match=r"Window\.show_window_options\(\) was deprecated",
742+
expected_error_match=r"Window\.show_window_options\(\) is deprecated",
742743
),
743744
DeprecatedMethodTestCase(
744745
test_id="show_window_option",
745746
method_name="show_window_option",
746747
args=("main-pane-height",),
747748
kwargs={},
748-
expected_error_match=r"Window\.show_window_option\(\) was deprecated",
749+
expected_error_match=r"Window\.show_window_option\(\) is deprecated",
749750
),
750751
]
751752

752753

753-
def _build_deprecated_method_params() -> list[t.Any]:
754-
"""Build pytest params for deprecated method tests."""
754+
def _build_deprecated_warning_method_params() -> list[t.Any]:
755+
"""Build pytest params for deprecated method warning tests."""
755756
return [
756-
pytest.param(tc, id=tc.test_id) for tc in DEPRECATED_WINDOW_METHOD_TEST_CASES
757+
pytest.param(tc, id=tc.test_id)
758+
for tc in DEPRECATED_WARNING_WINDOW_METHOD_TEST_CASES
757759
]
758760

759761

760-
@pytest.mark.parametrize("test_case", _build_deprecated_method_params())
761-
def test_deprecated_window_methods_raise_error(
762+
@pytest.mark.parametrize("test_case", _build_deprecated_warning_method_params())
763+
def test_deprecated_window_methods_emit_warning(
762764
session: Session,
763765
test_case: DeprecatedMethodTestCase,
764766
) -> None:
765-
"""Verify deprecated Window methods raise DeprecatedError."""
767+
"""Verify deprecated Window methods emit DeprecationWarning (0.50.0 deprecations)."""
766768
window = session.new_window(window_name="test_deprecation")
767769
method = getattr(window, test_case.method_name)
768770

769-
with pytest.raises(exc.DeprecatedError, match=test_case.expected_error_match):
771+
with pytest.warns(DeprecationWarning, match=test_case.expected_error_match):
770772
method(*test_case.args, **test_case.kwargs)

0 commit comments

Comments
 (0)