Merge branch 'v2.4-options'

Author: tony

.travis.yml

@@ -2,7 +2,6 @@ language: python
 
 sudo: false
 python:
-  - 2.6
   - 2.7
   - 3.3
   - 3.4
@@ -12,6 +11,7 @@ python:
   - pypy3.3-5.2-alpha1
 env:
   - TMUX_VERSION=master
+  - TMUX_VERSION=2.4
   - TMUX_VERSION=2.3
   - TMUX_VERSION=2.2
   - TMUX_VERSION=2.1

README.rst

@@ -179,7 +179,7 @@ Project details
 
 ==============  ==========================================================
 tmux support    1.8, 1.9a, 2.0, 2.1, 2.2, 2.3
-python support  2.6, 2.7, >= 3.3, pypy, pypy3
+python support  2.7, >= 3.3, pypy, pypy3
 Source          https://github.com/tony/libtmux
 Docs            http://libtmux.git-pull.com
 API             http://libtmux.git-pull.com/api.html

doc/api.rst

@@ -52,6 +52,11 @@ Pane Object
 Internals
 ---------
 
+
+.. autodata:: libtmux.common.TMUX_MIN_VERSION
+
+.. autodata:: libtmux.common.TMUX_MAX_VERSION
+
 .. autoclass:: libtmux.common.TmuxRelationalObject
     :members:
 
@@ -63,11 +68,21 @@ Internals
 
 .. autoclass:: libtmux.common.tmux_cmd
 
-.. automethod:: libtmux.common.has_required_tmux_version
-
 .. automethod:: libtmux.common.which
 
-.. automethod:: libtmux.common.is_version
+.. automethod:: libtmux.common.has_version
+
+.. automethod:: libtmux.common.has_gt_version
+
+.. automethod:: libtmux.common.has_gte_version
+
+.. automethod:: libtmux.common.has_lt_version
+
+.. automethod:: libtmux.common.has_lte_version
+
+.. automethod:: libtmux.common.has_minimum_version
+
+.. automethod:: libtmux.common.handle_option_error
 
 Exceptions
 ----------
@@ -76,12 +91,20 @@ Exceptions
 
 .. autoexception:: libtmux.exc.TmuxCommandNotFound
 
+.. autoexception:: libtmux.exc.VersionTooLow
+
 .. autoexception:: libtmux.exc.TmuxSessionExists
 
 .. autoexception:: libtmux.exc.BadSessionName
 
+.. autoexception:: libtmux.exc.OptionError
+
 .. autoexception:: libtmux.exc.UnknownOption
 
+.. autoexception:: libtmux.exc.InvalidOption
+
+.. autoexception:: libtmux.exc.AmbiguousOption
+
 Test tools
 ----------
 

doc/developing.rst

@@ -170,7 +170,7 @@ libtmux uses `travis-ci`_ for continuous integration / automatic unit
 testing.
 
 libtmux is tested against tmux 1.8 and the latest git source. Interpretters
-tested are 2.6, 2.7 and 3.3. The `travis build site`_ uses this
+tested are pypy, pypy3, 2.7 and >= 3.3. The `travis build site`_ uses this
 `.travis.yml`_ configuration:
 
 .. literalinclude:: ../.travis.yml

libtmux/common.py

@@ -9,16 +9,23 @@
 import logging
 import os
 import re
-import sys
 import subprocess
-from distutils.version import StrictVersion, LooseVersion
+import sys
+from distutils.version import LooseVersion
 
 from . import exc
 from ._compat import console_to_str
 
 logger = logging.getLogger(__name__)
 
 
+#: Minimum version of tmux required to run libtmux
+TMUX_MIN_VERSION = '1.8'
+
+#: Most recent version of tmux supported
+TMUX_MAX_VERSION = '2.4'
+
+
 class EnvironmentMixin(object):
 
     """Mixin class for managing session and server level environment
@@ -274,8 +281,8 @@ class TmuxRelationalObject(object):
     Object           .children                 method
     ================ ========================= =================================
     :class:`Server`  :attr:`Server._sessions`  :meth:`Server.list_sessions`
-    :class:`Session` :attr:`Sessions._windows` :meth:`Session.list_windows`
-    :class:`Window`  :attr:`Windows._panes`    :meth:`Window.list_panes`
+    :class:`Session` :attr:`Session._windows`  :meth:`Session.list_windows`
+    :class:`Window`  :attr:`Window._panes`     :meth:`Window.list_panes`
     :class:`Pane`    n/a                       n/a
     ================ ========================= =================================
 
@@ -395,67 +402,122 @@ def _is_executable_file_or_link(exe):
     return None
 
 
-def is_version(version):
+def get_version():
+    """Return tmux version.
+
+    If tmux is built from git master, the version returned will be the latest
+    version appended with -master, e.g. ``2.4-master``.
+
+    If using OpenBSD's base system tmux, the version will have ``-openbsd``
+    appended to the latest version, e.g. ``2.4-openbsd``.
+
+    :returns: tmux version
+    :rtype: :class:`distutils.version.LooseVersion`
+    """
+    proc = tmux_cmd('-V')
+    if proc.stderr:
+        if proc.stderr[0] == 'tmux: unknown option -- V':
+            if sys.platform.startswith("openbsd"):  # openbsd has no tmux -V
+                return LooseVersion('%s-openbsd' % TMUX_MAX_VERSION)
+            raise exc.LibTmuxException(
+                'libtmux supports tmux %s and greater. This system'
+                ' is running tmux 1.3 or earlier.' % TMUX_MIN_VERSION
+            )
+        raise exc.VersionTooLow(proc.stderr)
+
+    version = proc.stdout[0].split('tmux ')[1]
+
+    # Allow latest tmux HEAD
+    if version == 'master':
+        return LooseVersion('%s-master' % TMUX_MAX_VERSION)
+
+    version = re.sub(r'[a-z]', '', version)
+
+    return LooseVersion(version)
+
+
+def has_version(version):
     """Return True if tmux version installed.
 
     :param version: version, '1.8'
-    :param type: string
+    :type version: string
+    :returns: True if version matches
     :rtype: bool
+    """
+    return get_version() == LooseVersion(version)
+
 
+def has_gt_version(min_version):
+    """Return True if tmux version greater than minimum.
+
+    :param min_version: version, e.g. '1.8'
+    :type min_version: string
+    :returns: True if version above min_version
+    :rtype: bool
     """
-    if sys.platform.startswith("openbsd"):
-        if LooseVersion(version) > LooseVersion('2.1'):
-            return 'openbsd'
-        else:
-            return False
+    return get_version() > LooseVersion(min_version)
 
-    proc = tmux_cmd('-V')
 
-    if proc.stderr:
-        raise exc.LibTmuxException(proc.stderr)
+def has_gte_version(min_version):
+    """Return True if tmux version greater or equal to minimum.
 
-    installed_version = proc.stdout[0].split('tmux ')[1]
+    :param min_version: version, e.g. '1.8'
+    :type min_version: string
+    :returns: True if version above or equal to min_version
+    :rtype: bool
+    """
+    return get_version() >= LooseVersion(min_version)
 
-    return LooseVersion(installed_version) == LooseVersion(version)
 
+def has_lte_version(max_version):
+    """Return True if tmux version less or equal to minimum.
 
-def has_required_tmux_version(version=None):
-    """Return if tmux meets version requirement. Version >1.8 or above.
+    :param max_version: version, e.g. '1.8'
+    :type max_version: string
+    :returns: True if version below or equal to max_version
+    :rtype: bool
+    """
+    return get_version() <= LooseVersion(max_version)
 
-    :versionchanged: 0.1.7
-        Versions will now remove trailing letters per `Issue 55`_.
 
-        .. _Issue 55: https://github.com/tony/tmuxp/issues/55.
+def has_lt_version(max_version):
+    """Return True if tmux version less than minimum.
 
+    :param max_version: version, e.g. '1.8'
+    :type max_version: string
+    :returns: True if version below max_version
+    :rtype: bool
     """
+    return get_version() < LooseVersion(max_version)
 
-    if not version:
-        if sys.platform.startswith("openbsd"):  # openbsd has no tmux -V
-            return '2.3'
 
-        proc = tmux_cmd('-V')
+def has_minimum_version(raises=True):
+    """Return if tmux meets version requirement. Version >1.8 or above.
 
-        if proc.stderr:
-            if proc.stderr[0] == 'tmux: unknown option -- V':
-                raise exc.LibTmuxException(
-                    'libtmux supports tmux 1.8 and greater. This system'
-                    ' is running tmux 1.3 or earlier.')
-            raise exc.LibTmuxException(proc.stderr)
+    :param raises: Will raise exception if version too low, default ``True``
+    :type raises: bool
+    :returns: True if tmux meets minimum required version
+    :rtype: bool
 
-        version = proc.stdout[0].split('tmux ')[1]
+    :versionchanged: 0.7.0
+        No longer returns version, returns True or False
+    :versionchanged: 0.1.7
+        Versions will now remove trailing letters per `Issue 55`_.
 
-    # Allow latest tmux HEAD
-    if version == 'master':
-        return version
+        .. _Issue 55: https://github.com/tony/tmuxp/issues/55.
 
-    version = re.sub(r'[a-z]', '', version)
+    """
 
-    if StrictVersion(version) <= StrictVersion("1.7"):
-        raise exc.LibTmuxException(
-            'libtmux only supports tmux 1.8 and greater. This system'
-            ' has %s installed. Upgrade your tmux to use libtmux.' % version
-        )
-    return version
+    if get_version() < LooseVersion(TMUX_MIN_VERSION):
+        if raises:
+            raise exc.VersionTooLow(
+                'libtmux only supports tmux %s and greater. This system'
+                ' has %s installed. Upgrade your tmux to use libtmux.' %
+                (TMUX_MIN_VERSION, get_version())
+            )
+        else:
+            return False
+    return True
 
 
 def session_check_name(session_name):
@@ -477,3 +539,32 @@ def session_check_name(session_name):
     elif ':' in session_name:
         raise exc.BadSessionName(
             "tmux session name \"%s\" may not contain colons.", session_name)
+
+
+def handle_option_error(error):
+    """Raises exception if error in option command found.
+
+    Purpose: As of tmux 2.4, there are now 3 different types of option errors:
+
+    - unknown option
+    - invalid option
+    - ambiguous option
+
+    Before 2.4, unknown option was the user.
+
+    All errors raised will have the base error of :exc:`exc.OptionError`. So to
+    catch any option error, use ``except exc.OptionError``.
+
+    :param error: error response from subprocess call
+    :type error: str
+    :raises: :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`excAmbiguousOption`
+    """
+    if 'unknown option' in error:
+        raise exc.UnknownOption(error)
+    elif 'invalid option' in error:
+        raise exc.InvalidOption(error)
+    elif 'ambiguous option' in error:
+        raise exc.AmbiguousOption(error)
+    else:
+        raise exc.OptionError(error)  # Raise generic option error

libtmux/exc.py

@@ -27,15 +27,43 @@ class TmuxCommandNotFound(LibTmuxException):
     pass
 
 
+class VersionTooLow(LibTmuxException):
+
+    """Raised if tmux below the minimum version to use libtmux."""
+
+    pass
+
+
 class BadSessionName(LibTmuxException):
 
     """Disallowed session name for tmux (empty, contains periods or colons)."""
 
     pass
 
 
-class UnknownOption(LibTmuxException):
+class OptionError(LibTmuxException):
+
+    """Root error for any error involving invalid, ambiguous or bad options."""
+
+    pass
+
+
+class UnknownOption(OptionError):
 
     """Option unknown to tmux show-option(s) or show-window-option(s)."""
 
     pass
+
+
+class InvalidOption(OptionError):
+
+    """Option invalid to tmux, introduced in tmux v2.4."""
+
+    pass
+
+
+class AmbiguousOption(OptionError):
+
+    """Option that could potentially match more than one."""
+
+    pass