# Migration notes

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

```{admonition} 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. 🙏)

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

## Next release

_Migration instructions for the upcoming release will be added here_

<!-- Maintainers and contributors: insert migration notes for the next release here -->

## 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:

      ```python
      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)`

<!---
# vim: set filetype=markdown:
-->
