feat: Basic dataclass

Author: tony

MIGRATION

@@ -19,6 +19,39 @@ well.
    [tracker]: https://github.com/tmux-python/libtmux/discussions
 ```
 
+## 0.17.x: Simplified attributes
+
+### Finding windows
+
+- 0.16 and below: `session._windows()`
+
+  0.17 and after: {attr}`session.windows <libtmux.Session.windows>`
+
+  - If not found, raises exception
+  - If multiple objects found, raises exception
+
+- 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>`
+
+  Returns `None`
+
+- 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)`
+
 ## Next release
 
 _Migration instructions for the upcoming release will be added here_

README.md

@@ -69,14 +69,14 @@ current tmux server / session / window pane.
 List sessions:
 
 ```python
->>> server.list_sessions()
+>>> server.sessions
 [Session($1 ...), Session($0 ...)]
 ```
 
 Find session:
 
 ```python
->>> server.get_by_id('$1')
+>>> server.sessions.filter(session_id='$1')[0]
 Session($1 ...)
 ```
 
@@ -85,7 +85,7 @@ Find session by dict lookup:
 ```python
 >>> server.sessions[0].rename_session('foo')
 Session($1 foo)
->>> server.find_where({ "session_name": "foo" })
+>>> server.sessions.filter(session_name="foo")[0]
 Session($1 foo)
 ```
 
@@ -150,12 +150,14 @@ Type inside the pane (send key strokes):
 
 >>> pane.send_keys('echo hey', enter=False)
 >>> pane.enter()
+Pane(%1 ...)
 ```
 
 Grab the output of pane:
 
 ```python
 >>> pane.clear()  # clear the pane
+Pane(%1 ...)
 >>> pane.send_keys("cowsay 'hello'", enter=True)
 >>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))  # doctest: +SKIP
 $ cowsay 'hello'

docs/about.md

@@ -85,8 +85,8 @@ How is libtmux able to keep references to panes, windows and sessions?
 > Window index refers to the # of the window in the session.
 >
 > To assert pane, window and session data, libtmux will use
-> {meth}`Server.list_sessions()`, {meth}`Session.list_windows()`,
-> {meth}`Window.list_panes()` to update objects.
+> {meth}`Server.sessions()`, {meth}`Session.windows()`,
+> {meth}`Window.panes()` to update objects.
 
 ## Naming conventions
 

docs/internals/dataclasses.md

@@ -0,0 +1,8 @@
+# Dataclass helpers - `libtmux._internal.dataclasses`
+
+```{eval-rst}
+.. automodule:: libtmux._internal.dataclasses
+   :members:
+   :special-members:
+
+```

docs/internals/index.md

@@ -3,9 +3,9 @@
 # Internals
 
 :::{warning}
+Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
 
-These APIs are internal and not covered by versioning policy.
-
+If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
 :::
 
 ## Environmental variables
@@ -23,3 +23,10 @@ to split `tmux(1)`'s formatting information.
 
 If you find any compatibility problems with the default, or better yet find a string copacetic
 many environments and tmux releases, note it at <https://github.com/tmux-python/libtmux/discussions/355>.
+
+## Changes
+
+```{toctree}
+dataclasses
+query_list
+``

docs/internals/query_list.md

@@ -0,0 +1,6 @@
+# List querying - `libtmux._internal.query_list`
+
+```{eval-rst}
+.. automodule:: libtmux._internal.query_list
+   :members:
+```

docs/quickstart.md

@@ -125,33 +125,33 @@ Windows and Panes.
 If you have multiple tmux sessions open, you can see that all of the
 methods in {class}`Server` are available.
 
-We can list sessions with {meth}`Server.list_sessions`:
+We can list sessions with {meth}`Server.sessions`:
 
 ```python
->>> server.list_sessions()
+>>> server.sessions
 [Session($1 ...), Session($0 ...)]
 ```
 
 This returns a list of {class}`Session` objects you can grab. We can
 find our current session with:
 
 ```python
->>> server.list_sessions()[0]
+>>> server.sessions[0]
 Session($1 ...)
 ```
 
 However, this isn't guaranteed, libtmux works against current tmux information, the
 session's name could be changed, or another tmux session may be created,
-so {meth}`Server.get_by_id` and {meth}`Server.find_where` exists as a lookup.
+so {meth}`Server.sessions` and {meth}`Server.windows` exists as a lookup.
 
 ## Get session by ID
 
 tmux sessions use the `$[0-9]` convention as a way to identify sessions.
 
-`$1` is whatever the ID `list_sessions()` returned above.
+`$1` is whatever the ID `sessions()` returned above.
 
 ```python
->>> server.get_by_id('$1')
+>>> server.sessions.filter(session_id='$1')[0]
 Session($1 ...)
 ```
 
@@ -163,13 +163,16 @@ You may `session = server.get_by_id('$<yourId>')` to use the session object.
 >>> server.sessions[0].rename_session('foo')
 Session($1 foo)
 
->>> server.find_where({ "session_name": "foo" })
+>>> server.sessions.filter(session_name="foo")[0]
+Session($1 foo)
+
+>>> server.sessions.get(session_name="foo")
 Session($1 foo)
 ```
 
-With `find_where`, pass in a dict and return the first object found. In
+With `filter`, pass in attributes and return a list of matches. In
 this case, a {class}`Server` holds a collection of child {class}`Session`.
-{class}`Session` and {class}`Window` both utilize `find_where` to sift
+{class}`Session` and {class}`Window` both utilize `filter` to sift
 through Windows and Panes, respectively.
 
 So you may now use:
@@ -178,7 +181,7 @@ So you may now use:
 >>> server.sessions[0].rename_session('foo')
 Session($1 foo)
 
->>> session = server.find_where({ "session_name": "foo" })
+>>> session = server.sessions.get(session_name="foo")
 >>> session
 Session($1 foo)
 ```
@@ -213,7 +216,7 @@ Let's delete that window ({meth}`Session.kill_window`).
 Method 1: Use passthrough to tmux's `target` system.
 
 ```python
->>> session.kill_window(window.id)
+>>> session.kill_window(window.window_id)
 ```
 
 The window in the bg dissappeared. This was the equivalent of
@@ -260,7 +263,7 @@ And kill:
 >>> window.kill_window()
 ```
 
-Use {meth}`Session.list_windows()` and {meth}`Session.find_where()` to list and sort
+Use {meth}`Session.windows` and {meth}`Session.windows.filter()` to list and sort
 through active {class}`Window`'s.
 
 ## Manipulating windows
@@ -346,6 +349,7 @@ using {meth}`Pane.enter()`:
 
 ```python
 >>> pane.enter()
+Pane(%1 ...)
 ```
 
 ### Avoid cluttering shell history

docs/reference/properties.md

@@ -49,25 +49,24 @@ Session($1 libtmux_...)
 Quick access to basic attributes:
 
 ```python
->>> session.name
+>>> session.session_name
 'libtmux_...'
 
->>> session.id
+>>> session.session_id
 '$1'
 ```
 
 To see all attributes for a session:
 
 ```python
->>> sorted(list(session._info.keys()))
+from libtmux.neo import Obj
+
+>>> sorted(list(Obj.__dataclass_fields__.keys()))
 ['session_attached', 'session_created', ...]
 ```
 
-Some may conflict with python API, to access them, you can use `.get()`, to get the count
-of sessions in a window:
-
 ```python
->>> session.get('session_windows')
+>>> session.session_windows
 '...'
 ```
 
@@ -85,30 +84,23 @@ Window(@1 ...:..., Session($1 ...))
 Basics:
 
 ```python
->>> window.name
+>>> window.window_name
 '...'
 
->>> window.id
+>>> window.window_id
 '@1'
 
->>> window.height
+>>> window.window_height
 '...'
 
->>> window.width
+>>> window.window_width
 '...'
 ```
 
-Everything available:
-
-```python
->>> sorted(list(window.keys()))
-['session_id', 'session_name', 'window_active', ..., 'window_width']
-```
-
-Use `get()` for details not accessible via properties:
+Use attribute access for details not accessible via properties:
 
 ```python
->>> window.get('window_panes')
+>>> window.window_panes
 '1'
 ```
 
@@ -126,33 +118,20 @@ Pane(%1 Window(@1 ...:..., Session($1 libtmux_...)))
 Basics:
 
 ```python
->>> pane.current_command
+>>> pane.pane_current_command
 '...'
 
->>> type(pane.current_command)
+>>> type(pane.pane_current_command)
 <class 'str'>
 
->>> pane.height
+>>> pane.pane_height
 '...'
 
->>> pane.width
+>>> pane.pane_width
 '...'
 
->>> pane.index
+>>> pane.pane_index
 '0'
 ```
 
-Everything:
-
-````python
->>> sorted(list(pane._info.keys()))
-['alternate_on', 'alternate_saved_x', ..., 'wrap_flag']
-
-Use `get()` for details keys:
-
-```python
->>> pane.get('pane_width')
-'...'
-````
-
 [formats]: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMATS

src/libtmux/_internal/query_list.py

@@ -269,6 +269,8 @@ class QueryList(List[T]):
     'Elmhurst'
     >>> query.filter(foods__fruit__in="orange")[0]['city']
     'Tampa'
+    >>> query.get(foods__fruit__in="orange")['city']
+    'Tampa'
     """
 
     data: "Sequence[T]"
@@ -314,6 +316,8 @@ def __eq__(
     def filter(
         self, matcher: Optional[Union[Callable[[T], bool], T]] = None, **kwargs: Any
     ) -> "QueryList[T]":
+        """Filter list of objects."""
+
         def filter_lookup(obj: Any) -> bool:
             for path, v in kwargs.items():
                 try:
@@ -356,6 +360,12 @@ def get(
         default: Optional[Any] = no_arg,
         **kwargs: Any,
     ) -> Optional[T]:
+        """Retrieve one object
+
+        Raises exception if multiple objects found.
+
+        Raises exception if no object found, unless ``default``
+        """
         objs = self.filter(matcher=matcher, **kwargs)
         if len(objs) > 1:
             raise Exception("Multiple objects returned")