Improved splitting (#532)

## New param: `Session.new_window()`

- `direction`: `WindowDirection` (`Before`, `After`)

## New method: `Pane.split()`

- New param: `direction`, via `PaneDirection` (`Above`, `Below`, `Left`, `Right`)

  Replaces `vertical`'s old behavior.
- New param: `full_window_split`

## Deprecate `Pane.split_window()`

## New method: `Window.split()`

- New param: `direction`, via `PaneDirection` (`Above`, `Below`, `Left`, `Right`)

  Replaces `vertical`'s old behavior.
- New param: `full_window_split`, `zoom`

## Deprecate `Window.split_window()`

Author: tony

CHANGES

@@ -15,6 +15,39 @@ $ pip install --user --upgrade --pre libtmux
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version above -->
 
+### Breaking changes
+
+#### Improved new sessions (#532)
+
+- `Session.new_window()` to {meth}`Session.new_window()`
+
+  - Learned `direction`, via {class}`~libtmux.constants.WindowDirection`).
+
+#### Improved window splitting (#532)
+
+- `Window.split_window()` to {meth}`Window.split()`
+
+  - Deprecate `Window.split_window()`
+
+- `Pane.split_window()` to {meth}`Pane.split()`
+
+  - Deprecate `Pane.split_window()`
+  - Learned `direction`, via {class}`~libtmux.constants.PaneDirection`).
+
+    - Deprecate `vertical` and `horizontal` in favor of `direction`.
+
+  - Learned `zoom`
+
+#### Tweak: Pane position (#532)
+
+It's now possible to retrieve the position of a pane in a window via a
+`bool` helper::
+
+- {attr}`Pane.at_left`
+- {attr}`Pane.at_right`
+- {attr}`Pane.at_bottom`
+- {attr}`Pane.at_right`
+
 ### Development
 
 - poetry: 1.7.1 -> 1.8.1

MIGRATION

@@ -25,6 +25,13 @@ _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 -->
 
+## 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)

README.md

@@ -182,7 +182,7 @@ Grab remaining tmux window:
 
 ```python
 >>> window = session.active_window
->>> window.split_window(attach=False)
+>>> window.split(attach=False)
 Pane(%2 Window(@1 1:... Session($1 ...)))
 ```
 
@@ -196,14 +196,14 @@ Window(@1 1:libtmuxower, Session($1 ...))
 Split window (create a new pane):
 
 ```python
->>> pane = window.split_window()
->>> pane = window.split_window(attach=False)
+>>> pane = window.split()
+>>> pane = window.split(attach=False)
 >>> pane.select()
 Pane(%3 Window(@1 1:..., Session($1 ...)))
 >>> window = session.new_window(attach=False, window_name="test")
 >>> window
 Window(@2 2:test, Session($1 ...))
->>> pane = window.split_window(attach=False)
+>>> pane = window.split(attach=False)
 >>> pane
 Pane(%5 Window(@2 2:test, Session($1 ...)))
 ```

docs/quickstart.md

@@ -149,7 +149,7 @@ Create a pane from a window:
 '%2'
 ```
 
-Raw output directly to a {class}`Pane` (in practice, you'd use {meth}`Window.split_window()`):
+Raw output directly to a {class}`Pane` (in practice, you'd use {meth}`Window.split()`):
 
 ```python
 >>> Pane.from_pane_id(pane_id=window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0], server=window.server)
@@ -312,10 +312,10 @@ to grab our current window.
 
 `window` now has access to all of the objects inside of {class}`Window`.
 
-Let's create a pane, {meth}`Window.split_window`:
+Let's create a pane, {meth}`Window.split`:
 
 ```python
->>> window.split_window(attach=False)
+>>> window.split(attach=False)
 Pane(%2 Window(@1 ...:..., Session($1 ...)))
 ```
 
@@ -341,15 +341,15 @@ You have two ways you can move your cursor to new sessions, windows and panes.
 For one, arguments such as `attach=False` can be omittted.
 
 ```python
->>> pane = window.split_window()
+>>> pane = window.split()
 ```
 
 This gives you the {class}`Pane` along with moving the cursor to a new window. You
 can also use the `.select_*` available on the object, in this case the pane has
 {meth}`Pane.select()`.
 
 ```python
->>> pane = window.split_window(attach=False)
+>>> pane = window.split(attach=False)
 ```
 
 ```python
@@ -371,7 +371,7 @@ As long as you have the object, or are iterating through a list of them, you can
 
 ```python
 >>> window = session.new_window(attach=False, window_name="test")
->>> pane = window.split_window(attach=False)
+>>> pane = window.split(attach=False)
 >>> pane.send_keys('echo hey', enter=False)
 ```
 

src/libtmux/constants.py

@@ -19,3 +19,34 @@ class ResizeAdjustmentDirection(enum.Enum):
     ResizeAdjustmentDirection.Left: "-L",
     ResizeAdjustmentDirection.Right: "-R",
 }
+
+
+class WindowDirection(enum.Enum):
+    """Used for *adjustment* in :meth:`Session.new_window()`."""
+
+    Before = "BEFORE"
+    After = "AFTER"
+
+
+WINDOW_DIRECTION_FLAG_MAP: t.Dict[WindowDirection, str] = {
+    WindowDirection.Before: "-b",
+    WindowDirection.After: "-a",
+}
+
+
+class PaneDirection(enum.Enum):
+    """Used for *adjustment* in :meth:`Pane.split()`."""
+
+    Above = "ABOVE"
+    Below = "BELOW"  # default with no args
+    Right = "RIGHT"
+    Left = "LEFT"
+
+
+PANE_DIRECTION_FLAG_MAP: t.Dict[PaneDirection, t.List[str]] = {
+    # -v is assumed, but for explicitness it is passed
+    PaneDirection.Above: ["-v", "-b"],
+    PaneDirection.Below: ["-v"],
+    PaneDirection.Right: ["-h"],
+    PaneDirection.Left: ["-h", "-b"],
+}

src/libtmux/neo.py

@@ -89,6 +89,10 @@ class Obj:
     next_session_id: t.Union[str, None] = None
     origin_flag: t.Union[str, None] = None
     pane_active: t.Union[str, None] = None  # Not detected by script
+    pane_at_bottom: t.Union[str, None] = None
+    pane_at_left: t.Union[str, None] = None
+    pane_at_right: t.Union[str, None] = None
+    pane_at_top: t.Union[str, None] = None
     pane_bg: t.Union[str, None] = None
     pane_bottom: t.Union[str, None] = None
     pane_current_command: t.Union[str, None] = None
@@ -110,7 +114,6 @@ class Obj:
     pane_top: t.Union[str, None] = None
     pane_tty: t.Union[str, None] = None
     pane_width: t.Union[str, None] = None
-
     pid: t.Union[str, None] = None
     scroll_position: t.Union[str, None] = None
     scroll_region_lower: t.Union[str, None] = None