Merge pull request #6 from tony/docs-powerup

Refactor handbook

Author: tony

Makefile

@@ -1,8 +1,20 @@
+WATCH_FILES= find . -type f -not -path '*/\.*' | grep -i '.*[.]py$$' 2> /dev/null
+
+
 test:
-	py.test
+	py.test $(test)
+
+entr_warn:
+	@echo "----------------------------------------------------------"
+	@echo "     ! File watching functionality non-operational !      "
+	@echo ""
+	@echo "Install entr(1) to automatically run tasks on file change."
+	@echo "See http://entrproject.org/"
+	@echo "----------------------------------------------------------"
+
 
 watch_test:
-	if command -v entr > /dev/null; then find . -type f -not -path '*/\.*' | grep -i '.*[.]py' | entr -c make test; else make test; echo "\nInstall entr(1) to automatically run tests on file change.\n See http://entrproject.org/"; fi
+	if command -v entr > /dev/null; then ${WATCH_FILES} | entr -c $(MAKE) test; else $(MAKE) test entr_warn; fi
 
 build_docs:
 	cd doc && $(MAKE) html
@@ -14,6 +26,4 @@ flake8:
 	flake8 libtmux tests
 
 watch_flake8:
-	if command -v entr > /dev/null; then find . -type f -not -path '*/\.*' | grep -i '.*[.][py]' | entr -c make flake8; else make flake8; echo "\nInstall entr(1) to automatically run tests on file change.\n See http://entrproject.org/"; fi
-
-.PHONY: flake8
+	if command -v entr > /dev/null; then ${WATCH_FILES} | entr -c $(MAKE) flake8; else $(MAKE) flake8 entr_warn; fi

README.rst

@@ -37,6 +37,8 @@ pilot your tmux session via python
    $ pip install ptpython
    $ ptpython
 
+connect to a live tmux session:
+
 .. code-block:: python
 
     >>> import libtmux

TODO

@@ -2,4 +2,8 @@
 TODO
 ====
 
+- Remove duplicate between ``_list_panes``, ``_panes``, etc.
+- Retrieve active windows and window count from formatter command
+- tmux PR to get count of sessions in a server
+
 .. # vim: set filetype=rst:

doc/Makefile

@@ -156,8 +156,10 @@ checkbuild:
 	rm -rf $(BUILDDIR)
 	$(SPHINXBUILD) -n -q ./ $(BUILDDIR)
 
+WATCH_FILES= find .. -type f -not -path '*/\.*' | grep -i '.*[.]rst\|CHANGES\|TODO\|.*conf\.py' 2> /dev/null
+
 watch:
-	if command -v entr > /dev/null; then find .. -type f -not -path '*/\.*' | grep -i '.*[.]rst\|CHANGES\|TODO\|conf.py' | entr -c make html; else make html; echo "\nInstall entr(1) to automatically run tests on file change.\n See http://entrproject.org/"; fi
+	if command -v entr > /dev/null; then ${WATCH_FILES} | entr -c $(MAKE) html; else $(MAKE) html; fi
 
 serve:
 	echo 'docs built to <http://0.0.0.0:8023/_build/html>'; python -m SimpleHTTPServer 8023

doc/about.rst

@@ -9,7 +9,11 @@ About
 
 .. module:: libtmux
 
-libtmux is an *abstraction layer* against tmux' command line arguments.
+libtmux is an `abstraction layer`_ for tmux.
+
+It builds upon the concept of targets ``-t``, to direct commands against
+individual session, windows and panes and ``FORMATS``, template variables 
+exposed by tmux to describe their properties.
 
 :class:`common.TmuxRelationalObject` acts as a container to connect the
 relations of :class:`Server`, :class:`Session`, :class:`Window` and
@@ -25,8 +29,10 @@ Object                   Child                   Parent
 ======================== ======================= =========================
 
 Internally, tmux allows multiple servers to be ran on a system. Each one
-uses a socket. Most users worry since tmux will communicate to a default
-server automatically. If one doesn't exist, tmux does it for you.
+uses a socket. The server-client architecture is executed so cleanly,
+many users don't think about it. tmux automatically connects to a default
+socket name and location for you if none (``-L``, ``-S``) is specified.
+A server will be created automatically upon starting if none exists.
 
 A server can have multiple sessions. ``Ctrl-a s`` can be used to switch
 between sessions running on the server.
@@ -49,7 +55,7 @@ Object                   Prefix                  Example
 Similarities to Tmux and Pythonics
 ----------------------------------
 
-libtmux is was built in the spirit of understanding how tmux operates
+libtmux was built in the spirit of understanding how tmux operates
 and how python objects and tools can abstract the API's in a pleasant way.
 
 libtmux uses ``FORMATTERS`` in tmux to give identity attributes to
@@ -82,8 +88,8 @@ 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.
 
-Idiosyncrasies
---------------
+Naming conventions
+------------------
 
 Because this is a python abstraction and commands like ``new-window``
 have dashes (-) replaced with underscores (_).
@@ -95,4 +101,3 @@ Reference
 - tmux source code http://sourceforge.net/p/tmux/tmux-code/ci/master/tree/
 
 .. _abstraction layer: http://en.wikipedia.org/wiki/Abstraction_layer
-.. _ORM: http://en.wikipedia.org/wiki/Object-relational_mapping

doc/index.rst

@@ -15,6 +15,12 @@ Explore:
 
     quickstart
     about
+    properties
+    traversing
+    servers
+    sessions
+    windows
+    panes
     api
     glossary
     developing

doc/panes.rst

@@ -0,0 +1,20 @@
+.. _Panes:
+
+=====
+Panes
+=====
+
+- hold `pseudoterminal`_'s (`pty(4)`_)
+- exist inside :ref:`Windows`
+- identified by ``%``, e.g. ``%313``
+
+.. _pseudoterminal: https://en.wikipedia.org/wiki/Pseudoterminal
+.. _pty(4): https://www.freebsd.org/cgi/man.cgi?query=pty&sektion=4
+
+.. autoclass:: libtmux.Pane
+    :noindex:
+    :members:
+    :inherited-members:
+    :private-members:
+    :show-inheritance:
+    :member-order: bysource

doc/properties.rst

@@ -0,0 +1,155 @@
+.. _Properties:
+
+==========
+Properties
+==========
+
+Get access to the data attributions behind tmux sessions, windows and panes.
+
+This is done through accessing the `formats`_ available in ``list-sessions``,
+``list-windows`` and ``list-panes``.
+
+open two terminals:
+
+terminal one: start tmux in a seperate terminal::
+
+    $ tmux
+
+.. NOTE::
+
+    Make sure you have :ref:`libtmux installed <installation>`::
+
+        pip install libtmux
+
+    To upgrade:
+
+        pip install -U libtmux
+
+terminal two, ``python`` or ``ptpython`` if you have it::
+
+    $ python
+
+import tmux::
+
+   import tmux
+
+attach default tmux :class:`libtmux.Server` to ``t``::
+
+   >>> t = libtmux.Server();
+   >>> t
+   <libtmux.server.Server object at 0x10edd31d0>
+
+Session
+-------
+
+get our ``session`` object::
+
+    >>> session = t.sessions[0]
+
+    >>> session
+    Session($0 libtmux)
+
+quick access to basic attributes::
+
+    >>> session.name
+    u'libtmux'
+
+    >>> session.id
+    u'$0'
+
+    >>> session.width
+    u'213'
+
+    >>> session.height
+    u'114'
+
+to see all attributes for a session::
+
+    >>> session._info.keys()
+    [u'session_height', u'session_windows', u'session_width', u'session_id', u'session_created', u'session_attached', u'session_grouped', u'session_name']
+
+    >>> session._info
+    {u'session_height': u'114', u'session_windows': u'3', u'session_width': u'213', u'session_id': u'$0', u'session_created': u'1464905357', u'session_attached': u'1', u'session_grouped': u'0', u'session_name': u'libtmux'}
+
+
+some may conflict with python API, to access them, you can use ``.get()``, to get the count 
+of sessions in a window::
+
+    >>> session.get('session_windows')
+    u'3'
+
+Windows
+-------
+
+The same concepts apply for window::
+
+    >>> window = session.attached_window
+
+    >>> window
+    Window(@2 2:docs, Session($0 libtmux))
+
+basics::
+
+    >>> window.name
+    u'docs'
+
+    >>> window.id
+    u'@2'
+
+    >>> window.height
+    u'114'
+
+    >>> window.width
+    u'213'
+
+everything available::
+
+    >>> window._info
+    {u'window_panes': u'4', u'window_active': u'1', u'window_height': u'114', u'window_activity_flag': u'0', u'window_width': u'213', u'session_id': u'$0', u'window_id': u'@2', u'window_layout': u'dad5,213x114,0,0[213x60,0,0,4,213x53,0,61{70x53,0,61,5,70x53,71,61,6,71x53,142,61,7}]', u'window_silence_flag': u'0', u'window_index': u'2', u'window_bell_flag': u'0', u'session_name': u'libtmux', u'window_flags': u'*', u'window_name': u'docs'}
+
+    >>> window.keys()
+    [u'window_panes', u'window_active', u'window_height', u'window_activity_flag', u'window_width', u'session_id', u'window_id', u'window_layout', u'window_silence_flag', u'window_index', u'window_bell_flag', u'session_name', u'window_flags', u'window_name']
+
+use ``get()`` for details not accessible via properties::
+
+    >>> pane.get('window_panes')
+    u'4'
+
+Panes
+-----
+
+get our pane::
+
+    >>> pane = window.attached_pane
+
+    >>> pane
+    Pane(%5 Window(@2 2:docs, Session($0 libtmux)))
+
+basics::
+
+    >>> pane.current_command
+    u'python'
+
+    >>> pane.height
+    u'53'
+
+    >>> pane.width
+    u'70'
+
+    >>> pane.index
+    u'1'
+
+everything::
+
+    >>> pane._info
+    {u'alternate_saved_x': u'0', u'alternate_saved_y': u'0', u'cursor_y': u'47', u'cursor_x': u'0', u'pane_in_mode': u'0', u'insert_flag': u'0', u'keypad_flag': u'0', u'cursor_flag': u'1', u'pane_current_command': u'python', u'window_index': u'2', u'history_size': u'216', u'scroll_region_lower': u'52', u'keypad_cursor_flag': u'0', u'history_bytes': u'38778', u'pane_active': u'1', u'pane_dead': u'0', u'pane_synchronized': u'0', u'window_id': u'@2', u'pane_index': u'1', u'pane_width': u'70', u'mouse_any_flag': u'0', u'mouse_button_flag': u'0', u'window_name': u'docs', u'pane_current_path': u'/Users/me/work/python/libtmux/doc', u'pane_tty': u'/dev/ttys007', u'pane_title': u'Python REPL (ptpython)', u'session_id': u'$0', u'alternate_on': u'0', u'mouse_standard_flag': u'0', u'wrap_flag': u'1', u'history_limit': u'2000', u'pane_pid': u'37172', u'pane_height': u'53', u'session_name': u'libtmux', u'scroll_region_upper': u'0', u'pane_id': u'%5'}
+
+    >>> pane._info.keys()
+    [u'alternate_saved_x', u'alternate_saved_y', u'cursor_y', u'cursor_x', u'pane_in_mode', u'insert_flag', u'keypad_flag', u'cursor_flag', u'pane_current_command', u'window_index', u'history_size', u'scroll_region_lower', u'keypad_cursor_flag', u'history_bytes', u'pane_active', u'pane_dead', u'pane_synchronized', u'window_id', u'pane_index', u'pane_width', u'mouse_any_flag', u'mouse_button_flag', u'window_name', u'pane_current_path', u'pane_tty', u'pane_title', u'session_id', u'alternate_on', u'mouse_standard_flag', u'wrap_flag', u'history_limit', u'pane_pid', u'pane_height', u'session_name', u'scroll_region_upper', u'pane_id']
+
+use ``get()`` for details keys::
+
+    >>> pane.get('pane_width')
+    u'70'
+
+.. _formats: http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMAT

doc/quickstart.rst

@@ -10,32 +10,49 @@ sessions using python code.
 In this example, we will launch a tmux session and control the windows
 from inside a live tmux session.
 
-Control tmux via python
------------------------
+.. _requirements:
 
-.. seealso:: :ref:`api`
+Requirements
+------------
 
-.. todo:: Do a version of this with `sliderepl`_
+- `tmux`_
+- `pip`_ - for this handbook's examples
 
-To begin, ensure  the ``tmux`` program is installed.
+.. _pip: https://pip.pypa.io/en/stable/installing/
+.. _tmux: https://tmux.github.io/
 
-Next, ensure ``libtmux`` (note the p!) is installed:
+.. _installation:
+
+Installation
+------------
+
+Next, ensure ``libtmux`` is installed:
 
 .. code-block:: bash
 
     $ [sudo] pip install libtmux
 
+Start a tmux session
+--------------------
+
 Now, let's open a tmux session.
 
 .. code-block:: bash
 
     $ tmux new-session -n bar -s foo
 
-Why not just ``$ tmux``? We will assume you want to see the tmux changes
-in the current tmux session. So we will use:
+This tutorial will be using the session and window name in the example.
+
+Window name ``-n``: ``bar``
+Session name ``-s``: ``foo``
+
+Control tmux via python
+-----------------------
+
+.. seealso:: :ref:`api`
+
+.. todo:: Do a version of this with `sliderepl`_
 
-Window name: ``bar``
-Session name: ``foo``
 
 .. code-block:: bash
 

doc/servers.rst

@@ -0,0 +1,21 @@
+.. _Servers:
+
+=======
+Servers
+=======
+
+- identified by *socket path* and *socket name* 
+- may have >1 servers running of tmux at the same time.
+- hold :ref:`Sessions` (which hold :ref:`Windows`, which hold
+  :ref:`Panes`)
+
+In tmux, a server is automatically started on your behalf
+when you first run tmux.
+
+.. autoclass:: libtmux.Server
+    :noindex:
+    :members:
+    :inherited-members:
+    :private-members:
+    :show-inheritance:
+    :member-order: bysource