Merge pull request #3 from tony/api-overhaul

API cleanup for 0.4

Author: tony

CHANGES

@@ -4,9 +4,24 @@ Changelog
 
 Here you can find the recent changes to libtmux
 
-- libtmux forked from `tmuxp`_.
+- :release:`0.4.0 <2016-05-23>`
+- :support:`-` attributes for formatters are now accessible via
+  ``Session``, ``Window`` and ``Pane`` objects. ``session.name``
+  is equivalent to ``session.get('session_name')``, you can do the
+  same with other properties in ``_info``. ``window.name``,
+  ``pane.current_path``, ``session.id``, ``window.id``, ``pane.id``,
+  ``session.index``, ``window.index``, ``pane.index``, etc.
+- :support:`-` ``attached_sessions``, ``attached_window`` and
+  ``attached_pane`` are now properties.
+- :support:`-` ``_TMUX`` metadata object changed to ``_info``.
+- :support:`-` ``.findWhere()`` is now ``find_where``.
+- :support:`-` README and usage fixes
+
+- :release:`0.3.0 <2016-05-23>`
+- switch to pytest 
 
 - :release:`0.1.0 <2016-05-22>`
+- libtmux forked from `tmuxp`_.
 
 .. _tmuxp: https://github.com/tony/tmuxp
 

README.rst

@@ -1,20 +1,15 @@
-libtmux - library for managing tmux workspaces
+libtmux - scripting library for tmux
 
 |pypi| |docs| |build-status| |coverage| |license|
 
-libtmux is the library that powers `tmuxp`_, a tool that helps tmux users
-manage their workspaces.
+libtmux is the tool behind `tmuxp`_, a tmux workspace manager in python.
 
-Take control of tmux via python.
+it builds upon tmux' `target`_ and `formats`_ to create an object
+mappings to traverse, inspect and interact with live tmux sesssions.
 
-View the `documentation`_ homepage,  `API`_ information and `architectural 
+view the `documentation`_ homepage,  `API`_ information and `architectural
 details`_.
 
-.. _tmuxp: https://github.com/tony/tmuxp
-.. _documentation: https://libtmux.readthedocs.io/
-.. _API: https://libtmux.readthedocs.io/api.html
-.. _architectural details: https://libtmux.readthedocs.io/internals.html
-
 install
 -------
 
@@ -56,17 +51,17 @@ list sessions::
 
 find session::
 
-    >>> server.getById('$3')
+    >>> server.get_by_id('$3')
     Session($3 foo)
 
 find session by dict lookup::
 
-    >>> server.findWhere({ "session_name": "foo" })
+    >>> server.find_where({ "session_name": "foo" })
     Session($3 foo)
 
 assign session to ``session``::
 
-    >>> session = server.findWhere({ "session_name": "foo" })
+    >>> session = server.find_where({ "session_name": "foo" })
 
 play with session::
 
@@ -131,6 +126,15 @@ powerful traversal features::
     >>> pane.window.session
     Session($3 foo)
 
+.. _BSD: http://opensource.org/licenses/BSD-3-Clause
+.. _developing and testing: http://libtmux.readthedocs.io/developing.html
+.. _tmuxp: https://github.com/tony/tmuxp
+.. _documentation: https://libtmux.readthedocs.io/
+.. _API: https://libtmux.readthedocs.io/api.html
+.. _architectural details: https://libtmux.readthedocs.io/internals.html
+.. _formats: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMAT
+.. _target: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS
+
 Project details
 ---------------
 
@@ -168,10 +172,6 @@ tests           .. code-block:: bash
                     $ make test
 ==============  ==========================================================
 
-.. _BSD: http://opensource.org/licenses/BSD-3-Clause
-.. _developing and testing: http://libtmux.readthedocs.io/developing.html
-.. _Issues tracker: https://github.com/tony/libtmux/issues
-
 .. |pypi| image:: https://img.shields.io/pypi/v/libtmux.svg
     :alt: Python Package
     :target: http://badge.fury.io/py/libtmux

doc/quickstart.rst

@@ -91,7 +91,7 @@ find our current session with:
 
 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.getById` and :meth:`Server.findWhere` exists as a lookup.
+so :meth:`Server.get_by_id` and :meth:`Server.find_where` exists as a lookup.
 
 Get session by ID
 -----------------
@@ -103,33 +103,29 @@ tmux sessions use the ``$[0-9]`` convention as a way to identify sessions.
 .. code-block::  python
 
 
-    >>> server.getById('$3')
+    >>> server.get_by_id('$3')
     Session($3 foo)
 
-You may ``session = getById('$<yourId>')`` to use the session object.
+You may ``session = server.get_by_id('$<yourId>')`` to use the session object.
 
 Get session by name / other properties
 --------------------------------------
 
-I really like `Backbone`_'s approach to handling collections of structured
-data. So I made a :meth:`Server.findWhere` method modelled after
-`Backbone.Collection.prototype.findWhere`_.
-
 .. code-block:: python
 
-    >>> server.findWhere({ "session_name": "foo" })
+    >>> server.find_where({ "session_name": "foo" })
     Session($3 foo)
 
-With ``findWhere``, pass in a dict and return the first object found. In
+With ``find_where``, pass in a dict and return the first object found. In
 this case, a :class:`Server` holds a collection of child :class:`Session`.
-:class:`Session` and :class:`Window` both utilize ``findWhere`` to sift
+:class:`Session` and :class:`Window` both utilize ``find_where`` to sift
 through Windows and Panes, respectively.
 
 So you may now use:
 
 .. code-block:: python
 
-    >>> session = server.findWhere({ "session_name": "foo" })
+    >>> session = server.find_where({ "session_name": "foo" })
 
 to give us a ``session`` object to play with.
 
@@ -203,7 +199,7 @@ And kill:
 
     >>> window.kill_window()
 
-Use :meth:`Session.list_windows()` and :meth:`Session.findWhere()` to list and sort 
+Use :meth:`Session.list_windows()` and :meth:`Session.find_where()` to list and sort 
 through active :class:`Window`'s.
 
 Manipulating windows
@@ -302,8 +298,6 @@ sessions in the background. :)
     and our `test suite`_ (see :ref:`developing`.)
 
 .. _sliderepl: http://discorporate.us/projects/sliderepl/
-.. _backbone: http:/ /backbonejs.org
-.. _Backbone.Collection.prototype.findWhere: http://backbonejs.org/#Collection-findWhere
 .. _workspacebuilder.py: https://github.com/tony/libtmux/blob/master/libtmux/workspacebuilder.py
 .. _test suite: https://github.com/tony/libtmux/tree/master/tests
 .. _ptpython: https://github.com/jonathanslenders/ptpython

libtmux/common.py

@@ -198,31 +198,38 @@ class TmuxMappingObject(collections.MutableMapping):
     :class:`Session` and :class:`Server`.
 
     Instance attributes for useful information :term:`tmux(1)` uses for
-    Session, Window, Pane, stored :attr:`self._TMUX`. For example, a
+    Session, Window, Pane, stored :attr:`self._info`. For example, a
     :class:`Window` will have a ``window_id`` and ``window_name``.
 
     """
 
     def __getitem__(self, key):
-        return self._TMUX[key]
+        return self._info[key]
 
     def __setitem__(self, key, value):
-        self._TMUX[key] = value
+        self._info[key] = value
         self.dirty = True
 
     def __delitem__(self, key):
-        del self._TMUX[key]
+        del self._info[key]
         self.dirty = True
 
     def keys(self):
         """Return list of keys."""
-        return self._TMUX.keys()
+        return self._info.keys()
 
     def __iter__(self):
-        return self._TMUX.__iter__()
+        return self._info.__iter__()
 
     def __len__(self):
-        return len(self._TMUX.keys())
+        return len(self._info.keys())
+
+    def __getattr__(self, key):
+        try:
+            return self._info[self.formatter_prefix + key]
+        except:
+            raise AttributeError('%s has no property %s' %
+                                 (self.__class__, key))
 
 
 class TmuxRelationalObject(object):
@@ -234,10 +241,10 @@ class TmuxRelationalObject(object):
     :class:`Window`)
 
     Children of :class:`TmuxRelationalObject` are going to have a
-    ``self.children``, ``self.childIdAttribute`` and ``self.list_children``.
+    ``self.children``, ``self.child_id_attribute`` and ``self.list_children``.
 
     ================ ================== ===================== ============================
-    Object           ``.children``      ``.childIdAttribute`` method
+    Object           ``.children``      ``.child_id_attribute`` method
     ================ ================== ===================== ============================
     :class:`Server`  ``self._sessions`` 'session_id'          :meth:`Server.list_sessions`
     :class:`Session` ``self._windows``  'window_id'           :meth:`Session.list_windows`
@@ -247,13 +254,11 @@ class TmuxRelationalObject(object):
 
     """
 
-    def findWhere(self, attrs):
+    def find_where(self, attrs):
         """Return object on first match.
 
-        Based on `.findWhere()`_ from `underscore.js`_.
-
-        .. _.findWhere(): http://underscorejs.org/#findWhere
-        .. _underscore.js: http://underscorejs.org/
+        :versionchanged: 0.4
+            Renamed from ``.findWhere`` to ``.find_where``.
 
         """
         try:
@@ -264,11 +269,6 @@ def findWhere(self, attrs):
     def where(self, attrs, first=False):
         """Return objects matching child objects properties.
 
-        Based on `.where()`_ from `underscore.js`_.
-
-        .. _.where(): http://underscorejs.org/#where
-        .. _underscore.js: http://underscorejs.org/
-
         :param attrs: tmux properties to match
         :type attrs: dict
         :rtype: list
@@ -290,8 +290,8 @@ def by(val, *args):
         else:
             return list(filter(by, self.children))
 
-    def getById(self, id):
-        """Return object based on ``childIdAttribute``.
+    def get_by_id(self, id):
+        """Return object based on ``child_id_attribute``.
 
         Based on `.get()`_ from `backbone.js`_.
 
@@ -304,7 +304,7 @@ def getById(self, id):
 
         """
         for child in self.children:
-            if child[self.childIdAttribute] == id:
+            if child[self.child_id_attribute] == id:
                 return child
             else:
                 continue

libtmux/pane.py

@@ -26,11 +26,11 @@ class Pane(TmuxMappingObject, TmuxRelationalObject):
         Renamed from ``.tmux`` to ``.cmd``.
 
     """
+    formatter_prefix = 'pane_'
 
     def __init__(self, window=None, **kwargs):
         if not window:
-            raise ValueError('Pane must have \
-                             ``Window`` object')
+            raise ValueError('Pane must have ``Window`` object')
 
         self.window = window
         self.session = self.window.session
@@ -41,7 +41,7 @@ def __init__(self, window=None, **kwargs):
         self.server._update_panes()
 
     @property
-    def _TMUX(self, *args):
+    def _info(self, *args):
 
         attrs = {
             'pane_id': self._pane_id

libtmux/server.py

@@ -44,7 +44,9 @@ class Server(TmuxRelationalObject, EnvironmentMixin):
     #: ``-2`` or ``-8``
     colors = None
     #: unique child ID key
-    childIdAttribute = 'session_id'
+    child_id_attribute = 'session_id'
+    #: namespace used by tmux formatter variables
+    formatter_prefix = 'server_'
 
     def __init__(
         self,
@@ -262,7 +264,13 @@ def _list_panes(self):
 
         # clear up empty dict
         panes = [
-            dict((k, v) for k, v in window.items() if v) for window in panes
+            dict(
+                (k, v) for k, v in window.items()
+                if v or
+                k == 'pane_current_path'
+            )   # preserve pane_current_path, in case it entered a new process
+                # where we may not get a cwd from.
+            for window in panes
         ]
 
         if self._panes:
@@ -281,6 +289,7 @@ def _update_panes(self):
         self._list_panes()
         return self
 
+    @property
     def attached_sessions(self):
         """Return active :class:`Session` objects.
 
@@ -296,9 +305,8 @@ def attached_sessions(self):
         for session in sessions:
             if 'session_attached' in session:
                 # for now session_active is a unicode
-                if session.get('session_attached') == '1':
-                    logger.debug('session %s attached', session.get(
-                        'session_name'))
+                if session.attached == '1':
+                    logger.debug('session %s attached', session.name)
                     attached_sessions.append(session)
                 else:
                     continue