Merge branch 'master' into master

Author: tony

.github/workflows/publish-docs.yml

@@ -31,7 +31,7 @@ jobs:
     - name: Install poetry
       run: |
         curl -O -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py
-        python get-poetry.py -y
+        python get-poetry.py -y --version 1.0.10
         echo "::set-env name=PATH::$HOME/.poetry/bin:$PATH"
         rm get-poetry.py
 

.github/workflows/tests.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       matrix:
         python-version: [ '2.7', '3.x' ]
-        tmux-version: [ '2.6', '2.7', '2.8', '3.0', 'master' ]
+        tmux-version: [ '2.6', '2.7', '2.8', '3.0a', '3.1b', 'master' ]
     steps:
     - uses: actions/checkout@v1
 
@@ -28,7 +28,7 @@ jobs:
     - name: Install poetry
       run: |
         curl -O -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py
-        python get-poetry.py -y
+        python get-poetry.py -y --version 1.0.10
         echo "::set-env name=PATH::$HOME/.poetry/bin:$PATH"
         rm get-poetry.py
 

CHANGES

@@ -6,7 +6,21 @@ Here you can find the recent changes to libtmux
 
 current
 -------
-- :issue:`251`: Enchance subprocess interaction std[in|out|err]. Needed for interact with big buffer
+- :issue:`251`: Enchance subprocess interaction std[in|out|err]. Needed
+  for interact with big buffer
+- :issue:`303` Add ``common.get_libtmux_version`` which gives the tmux
+  version as a loose constraint. Fix linking to terms inside docs, and
+  duplicate description of module which sphinx warned about in api.rst.
+- :issue:`266` Fix issue on local tests where env variables would cause
+  show-environment to pause tests indefinitely.
+- *Insert changes/features/fixes for next release here*
+
+libtmux 0.8.4 (2020-10-25)
+--------------------------
+- :issue:`234`: ``Window.split_window``: Allow passing ``percent``, Thank
+  you @jinankjain!
+- :issue:`289`: Fix warning due to invalid escape sequences, Thank you
+  @tirkarthi!
 - :issue:`295`: Publish docs via our own action
 - :issue:`295`: Move more packaging over to poetry, though we'll keep
   setup.py for the moment to ensure compatibility package maintainers.

docs/api.rst

@@ -86,6 +86,8 @@ Internals
 
 .. automethod:: libtmux.common.handle_option_error
 
+.. automethod:: libtmux.common.get_libtmux_version
+
 Exceptions
 ----------
 

docs/developing.md

@@ -41,6 +41,54 @@ CI. See the configuration in `pyproject.toml` and `setup.cfg`:
 
 ## Releasing
 
+Since this software is used by tens of thousands of users daily, we don't want
+to release breaking changes. Additionally this is packaged on large Linux/BSD
+distros, so we must be mindful of architectural changes.
+
+Choose what the next version is. Assuming it's version 0.9.0, it could be:
+
+- 0.9.0post0: postrelease, if there was a packaging issue
+- 0.9.1: bugfix / security / tweak
+- 0.10.0: breaking changes, new features
+
+Let's assume we pick 0.9.1
+
+`CHANGES`: Assure any PRs merged since last release are mentioned. Give a
+thank you to the contributor. Set the header with the new version and the date.
+Leave the "current" header and _Insert changes/features/fixes for next release here_ at
+the top::
+
+    current
+    -------
+    - *Insert changes/features/fixes for next release here*
+
+    libtmux 0.9.1 (2020-10-12)
+    --------------------------
+    - :issue:`1`: Fix bug
+
+`libtmux/__init__.py` and `__about__.py` - Set version
+
+`git commit -m 'Tag v0.9.1'`
+
+`git tag v0.9.1`
+
+`pip install wheel twine`
+
+`python setup.py sdist bdist_wheel`
+
+`twine upload dist/*`
+
+### Twine
+
+`twine upload dist/*`
+
+You will be asked for PyPI login information.
+
+### Releasing with Poetry (hypothetical)
+
+This isn't used yet since package maintainers may want setup.py in the source.
+See https://github.com/tmux-python/tmuxp/issues/625.
+
 As of 0.10, [poetry] handles virtualenv creation, package requirements, versioning,
 building, and publishing. Therefore there is no setup.py or requirements files.
 
@@ -53,6 +101,7 @@ Update `__version__` in `__about__.py` and `pyproject.toml`::
     poetry build
     poetry deploy
 
+[twine]: https://twine.readthedocs.io/
 [poetry]: https://python-poetry.org/
 [entr(1)]: http://eradman.com/entrproject/
 [black]: https://github.com/psf/black

libtmux/__about__.py

@@ -1,6 +1,6 @@
 __title__ = 'libtmux'
 __package_name__ = 'libtmux'
-__version__ = '0.8.3'
+__version__ = '0.8.4'
 __description__ = 'scripting library / orm for tmux'
 __email__ = '[email protected]'
 __author__ = 'Tony Narlock'

libtmux/__init__.py

@@ -1,15 +1,5 @@
 # -*- coding: utf-8 -*-
 # flake8: NOQA
-"""API for interfacing with tmux servers, sessions, windows and panes.
-
-libtmux
-~~~~~~~
-
-:copyright: Copyright 2016-2018 Tony Narlock.
-:license: MIT, see LICENSE for details
-
-"""
-
 from .__about__ import (
     __author__,
     __copyright__,

libtmux/_compat.py

@@ -20,22 +20,22 @@
     itervalues = lambda d: d.itervalues()
     iteritems = lambda d: d.iteritems()
 
+    from itertools import imap, izip
+
+    import ConfigParser as configparser
+    import cPickle as pickle
     from cStringIO import StringIO as BytesIO
     from StringIO import StringIO
-    import cPickle as pickle
-    import ConfigParser as configparser
-
-    from itertools import izip, imap
 
     range_type = xrange
 
     cmp = cmp
 
     input = raw_input
+    from collections import MutableMapping
     from string import lower as ascii_lowercase
-    import urlparse
 
-    from collections import MutableMapping
+    import urlparse
 
     exec('def reraise(tp, value, tb=None):\n raise tp, value, tb')
 
@@ -60,9 +60,9 @@ def console_to_str(s):
     itervalues = lambda d: iter(d.values())
     iteritems = lambda d: iter(d.items())
 
-    from io import StringIO, BytesIO
-    import pickle
     import configparser
+    import pickle
+    from io import BytesIO, StringIO
 
     izip = zip
     imap = map
@@ -71,9 +71,9 @@ def console_to_str(s):
     cmp = lambda a, b: (a > b) - (a < b)
 
     input = input
-    from string import ascii_lowercase
     import urllib.parse as urllib
     import urllib.parse as urlparse
+    from string import ascii_lowercase
     from urllib.request import urlretrieve
 
     console_encoding = sys.__stdout__.encoding
@@ -97,6 +97,7 @@ def reraise(tp, value, tb=None):
 
 number_types = integer_types + (float,)
 
+
 def str_from_console(s):
     try:
         return text_type(s)

libtmux/common.py

@@ -15,7 +15,7 @@
 from distutils.version import LooseVersion
 
 from . import exc
-from ._compat import console_to_str, str_from_console, MutableMapping
+from ._compat import MutableMapping, console_to_str, str_from_console
 
 logger = logging.getLogger(__name__)
 
@@ -229,7 +229,7 @@ def __init__(self, *args, **kwargs):
 
 class TmuxMappingObject(MutableMapping):
 
-    """Base: :py:class:`MutableMapping`.
+    r"""Base: :py:class:`MutableMapping`.
 
     Convenience container. Base class for :class:`Pane`, :class:`Window`,
     :class:`Session` and :class:`Server`.
@@ -664,3 +664,16 @@ def handle_option_error(error):
         raise exc.AmbiguousOption(error)
     else:
         raise exc.OptionError(error)  # Raise generic option error
+
+
+def get_libtmux_version():
+    """Return libtmux version is a PEP386 compliant format.
+
+    Returns
+    -------
+    distutils.version.LooseVersion
+        libtmux version
+    """
+    from libtmux.__about__ import __version__
+
+    return LooseVersion(__version__)

libtmux/pane.py

@@ -18,7 +18,7 @@
 
 class Pane(TmuxMappingObject, TmuxRelationalObject):
     """
-    A :term:`tmux(1)` :term:`pane` [#]_.
+    A :term:`tmux(1)` :term:`Pane` [#]_.
 
     ``Pane`` instances can send commands directly to a pane, or traverse
     between linked tmux objects.
@@ -153,9 +153,11 @@ def clear(self):
     def reset(self):
         """Reset and clear pane history. """
 
-        self.cmd('send-keys', '-R \; clear-history')
+        self.cmd('send-keys', r'-R \; clear-history')
 
-    def split_window(self, attach=False, vertical=True, start_directory=None):
+    def split_window(
+        self, attach=False, vertical=True, start_directory=None, percent=None
+    ):
         """
         Split window at pane and return newly created :class:`Pane`.
 
@@ -167,6 +169,8 @@ def split_window(self, attach=False, vertical=True, start_directory=None):
             split vertically
         start_directory : str, optional
             specifies the working directory in which the new pane is created.
+        percent: int, optional
+            percentage to occupy with respect to current pane
 
         Returns
         -------
@@ -177,6 +181,7 @@ def split_window(self, attach=False, vertical=True, start_directory=None):
             start_directory=start_directory,
             attach=attach,
             vertical=vertical,
+            percent=percent,
         )
 
     def set_width(self, width):

libtmux/server.py

@@ -26,7 +26,7 @@
 class Server(TmuxRelationalObject, EnvironmentMixin):
 
     """
-    The :term:`tmux(1)` :term:`server` [#]_.
+    The :term:`tmux(1)` :term:`Server` [#]_.
 
     - :attr:`Server._sessions` [:class:`Session`, ...]
 

libtmux/session.py

@@ -27,7 +27,7 @@
 
 class Session(TmuxMappingObject, TmuxRelationalObject, EnvironmentMixin):
     """
-    A :term:`tmux(1)` :term:`session` [#]_.
+    A :term:`tmux(1)` :term:`Session` [#]_.
 
     Holds :class:`Window` objects.
 

libtmux/window.py

@@ -20,7 +20,7 @@
 
 class Window(TmuxMappingObject, TmuxRelationalObject):
     """
-    A :term:`tmux(1)` :term:`window` [#]_.
+    A :term:`tmux(1)` :term:`Window` [#]_.
 
     Holds :class:`Pane` objects.
 
@@ -382,7 +382,13 @@ def last_pane(self):
         return self.select_pane('-l')
 
     def split_window(
-        self, target=None, start_directory=None, attach=True, vertical=True, shell=None
+        self,
+        target=None,
+        start_directory=None,
+        attach=True,
+        vertical=True,
+        shell=None,
+        percent=None,
     ):
         """
         Split window and return the created :class:`Pane`.
@@ -407,6 +413,8 @@ def split_window(
             NOTE: When this command exits the pane will close.  This feature
             is useful for long-running processes where the closing of the
             window upon completion is desired.
+        percent: int, optional
+            percentage to occupy with respect to current window
 
         Returns
         -------
@@ -446,6 +454,9 @@ def split_window(
         else:
             tmux_args += ('-h',)
 
+        if percent is not None:
+            tmux_args += ('-p %d' % percent,)
+
         tmux_args += ('-P', '-F%s' % ''.join(tmux_formats))  # output
 
         if start_directory: