Skip to content

Latest commit

 

History

History
213 lines (141 loc) · 5.87 KB

MIGRATION

File metadata and controls

213 lines (141 loc) · 5.87 KB

Migration notes

Migration and deprecation notes for libtmux are here, see {ref}changelog as well.

1. 📌 For safety, **always** pin the package
2. 📖 Check the migration notes _(You are here)_
3. 📣 If you feel something got deprecated and it interrupted you - past, present, or future - voice your opinion on the [tracker].

   We want to make libtmux fun, reliable, and useful for users.

   API changes can be painful.

   If we can do something to draw the sting, we'll do it. We're taking a balanced approach. That's why these notes are here!

   (Please pin the package. 🙏)

   [tracker]: https://github.com/tmux-python/libtmux/discussions

Upcoming Release

Detailed migration steps for the next version will be posted here.

libtmux 0.46.0 (2025-02-25)

Imports removed from libtmux.test (#580)

Root-level of imports from libtmux.test are no longer possible.

# Before 0.46.0
from libtmux.test import namer
# From 0.46.0 onward
from libtmux.test.named import namer

Same thing with constants:

# Before 0.46.0
from libtmux.test import (
  RETRY_INTERVAL_SECONDS,
  RETRY_TIMEOUT_SECONDS,
  TEST_SESSION_PREFIX
)
# From 0.46.0 onward
from libtmux.test.constants import (
  RETRY_INTERVAL_SECONDS,
  RETRY_TIMEOUT_SECONDS,
  TEST_SESSION_PREFIX
)

libtmux 0.45.0 (2025-02-23)

Test helpers: Module moves

Test helper functionality has been split into focused modules (#578):

  • libtmux.test module split into:
    • libtmux.test.constants: Test-related constants (TEST_SESSION_PREFIX, etc.)
    • libtmux.test.environment: Environment variable mocking
    • libtmux.test.random: Random string generation utilities
    • libtmux.test.temporary: Temporary session/window management

Breaking: Import paths have changed. Update imports:

# Old (0.44.x and earlier)
from libtmux.test import (
    TEST_SESSION_PREFIX,
    get_test_session_name,
    get_test_window_name,
    namer,
    temp_session,
    temp_window,
    EnvironmentVarGuard,
)
# New (0.45.0+)
from libtmux.test.constants import TEST_SESSION_PREFIX
from libtmux.test.environment import EnvironmentVarGuard
from libtmux.test.random import get_test_session_name, get_test_window_name, namer
from libtmux.test.temporary import temp_session, temp_window

0.35.0: Commands require explicit targets (2024-03-17)

Commands require explicit targets (#535)

  • {meth}Server.cmd(), {meth}Session.cmd(), {meth}Window.cmd(), {meth}Pane.cmd() require passing target instead of ['-t', target], ['-tTargetName'], etc. This change is to avoid issues mistakenly interpreting -t in other shell values as targets.

    Before:

    session.cmd('send-keys', 'echo hello', '-t', '0')

    With 0.35.0 and after:

    session.cmd('send-keys', 'echo hello', target='0')

0.33.0: Deprecations for splitting (2024-03-03)

Deprecations (#532)

  • Window.split_window() to {meth}Window.split()
  • Pane.split_window() to {meth}Pane.split()

0.31.0: Renaming and command cleanup (2024-02-17)

Cleanups (#527)

  • Commands: Param change

    {meth}Server.cmd(), {meth}Session.cmd(), {meth}Window.cmd(), {meth}Pane.cmd()

    • Use cmd: str as first positional
    • Removed unused keyword arguments **kwargs

Renamings (#527)

  • Session.attached_window renamed to {meth}Session.active_window
    • Session.attached_window deprecated
  • Session.attached_pane renamed to {meth}Session.active_pane
    • Session.attached_pane deprecated
  • Window.attached_pane renamed to {meth}Window.active_pane
    • Window.attached_pane deprecated

0.28.0: Resizing and detached by default (2024-02-15)

Detach by default

  • {meth}Session.new_window() + {meth}Window.split_window() no longer attaches by default (#523)

    • 0.28.0 and greater: Defaults to attach=False.
    • 0.27.1 and below: Defaults to attach=True.

    For the old behavior in 0.28.0 and beyond, pass attach=True explicitly.

Resizing panes

  • Pane.resize_pane() renamed to {meth}Pane.resize() (via #523)

    This convention will be more consistent with {meth}Window.resize().

  • {meth}Pane.resize_pane()'s params changed (#523)

    • No longer accepts -U, -D, -L, -R directly, instead accepts {class}~libtmux.constants.ResizeAdjustmentDirection (see below).

      • 0.27.1 and below: pane.resize_pane("-D", 20), pane.resize_pane("-R", 20)

      • 0.28.0 and beyond:

        from libtmux.constants import ResizeAdjustmentDirection
pane.resize_pane(adjustment_direction=ResizeAdjustmentDirection.Down, adjustment=25)
pane.resize_pane(
  adjustment_direction=ResizeAdjustmentDirection.Right, adjustment=25
)

0.17.0: Simplified attributes (2022-12-26)

Finding objects / relations

  • 0.16 and below: session._windows(), session.list_windows(), etc.

    0.17 and after: {attr}session.windows <libtmux.Session.windows>

  • 0.16 and below: session.find_where({'window_name': my_window})

    0.17 and after: {meth}session.windows.get(window_name=my_window, default=None) <libtmux.Session.windows>

    • If not found and not default, raises {exc}~libtmux._internal.query_list.ObjectDoesNotExist
    • If multiple objects found, raises {exc}~libtmux._internal.query_list.MultipleObjectsReturned

  • 0.16 and below: session.where({'window_name': my_window})

    0.17 and after: {meth}session.windows.filter(window_name=my_window) <libtmux.Session.windows>

Accessing attributes

  • 0.16 and below: window['id']

    0.17 and after: window.id

  • 0.16 and below: window.get('id')

    0.17 and after: window.id

  • 0.16 and below: window.get('id', None)

    0.17 and after: getattr(window, 'id', None)