Migration notes

Migration and deprecation notes for libtmux are here, see Changelog as well.

Welcome on board! 👋

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. 🙏)

Upcoming Release

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

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

Commands require explicit targets (#535)

• Server.cmd(), Session.cmd(), Window.cmd(), 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 Window.split()

• Pane.split_window() to Pane.split()

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

Cleanups (#527)

• Commands: Param change

  Server.cmd(), Session.cmd(), Window.cmd(), Pane.cmd()

  • Use cmd: str as first positional

  • Removed unused keyword arguments **kwargs

Renamings (#527)

• Session.attached_window renamed to Session.active_window()

  • Session.attached_window deprecated

• Session.attached_pane renamed to Session.active_pane()

  • Session.attached_pane deprecated

• Window.attached_pane renamed to Window.active_pane()

  • Window.attached_pane deprecated

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

Detach by default

• Session.new_window() + 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 Pane.resize() (via #523)

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

• Pane.resize_pane()’s params changed (#523)

  • No longer accepts -U, -D, -L, -R directly, instead accepts 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: session.windows

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

  0.17 and after: session.windows.get(window_name=my_window, default=None)

  • If not found and not default, raises ObjectDoesNotExist

  • If multiple objects found, raises MultipleObjectsReturned

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

  0.17 and after: session.windows.filter(window_name=my_window)

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)