API Changes - Simplify EnvironmentMixin

CHANGES

@@ -12,6 +12,55 @@ $ pip install --user --upgrade --pre libtmux
 
 - _Insert changes/features/fixes for next release here_
 
+# Breaking changes
+
+- Deprecated individual item lookups ({issue}`390`)
+
+  - Removed key lookups from {meth}`libtmux.common.EnvironmentMixin.show_environment`
+
+    Only `EnvironmentMixin.show_environment()` (without an argument) exists, and
+    it still returns a `dict`.
+
+  - Add key lookups via {meth}`libtmux.common.EnvironmentMixin.getenv`
+
+    ```python
+    # Before
+    server.show_environment('DISPLAY')
+
+    # After
+    server.getenv('DISPLAY')
+
+    # Before
+    session.show_environment('DISPLAY')
+
+    # After
+    session.getenv('DISPLAY')
+    ```
+
+  - Removed key lookups from {meth}`Session.show_options`
+
+    ```python
+    session.show_options()  # still returns dict, without an argument
+
+    # Old
+    session.show_options('DISPLAY')
+
+    # Now
+    session.show_option('DISPLAY')
+    ```
+
+  - Removed key lookups from {meth}`Window.show_window_options`
+
+    ```python
+    window.show_window_options()  # still returns dict, without an argument
+
+    # Old
+    window.show_window_options('DISPLAY')
+
+    # Now
+    window.show_window_option('DISPLAY')
+    ```
+
 ### Development
 
 - Fix incorrect function name `findWhere()` ({issue}`391`)

libtmux/common.py

@@ -108,11 +108,43 @@ def remove_environment(self, name):
                 proc.stderr = proc.stderr[0]
             raise ValueError("tmux set-environment stderr: %s" % proc.stderr)
 
-    def show_environment(self, name=None):
-        """Show environment ``$ tmux show-environment -t [session] <name>``.
+    def show_environment(self):
+        """Show environment ``$ tmux show-environment -t [session]``.
 
-        Return dict of environment variables for the session or the value of a
-        specific variable if the name is specified.
+        Return dict of environment variables for the session.
+
+        .. versionchanged:: 0.13
+
+           Removed per-item lookups. Use :meth:`libtmux.common.EnvironmentMixin.getenv`.
+
+        Returns
+        -------
+        dict
+            environmental variables in dict, if no name, or str if name
+            entered.
+        """
+        tmux_args = ["show-environment"]
+        if self._add_option:
+            tmux_args += [self._add_option]
+        vars = self.cmd(*tmux_args).stdout
+        vars = [tuple(item.split("=", 1)) for item in vars]
+        vars_dict = {}
+        for t in vars:
+            if len(t) == 2:
+                vars_dict[t[0]] = t[1]
+            elif len(t) == 1:
+                vars_dict[t[0]] = True
+            else:
+                raise ValueError("unexpected variable %s", t)
+
+        return vars_dict
+
+    def getenv(self, name):
+        """Show environment variable ``$ tmux show-environment -t [session] <name>``.
+
+        Return the value of a specific variable if the name is specified.
+
+        .. versionadded:: 0.13
 
         Parameters
         ----------
@@ -121,15 +153,13 @@ def show_environment(self, name=None):
 
         Returns
         -------
-        str or dict
-            environmental variables in dict, if no name, or str if name
-            entered.
+        str
+            Value of environment variable
         """
         tmux_args = ["show-environment"]
         if self._add_option:
             tmux_args += [self._add_option]
-        if name:
-            tmux_args += [name]
+        tmux_args += [name]
         vars = self.cmd(*tmux_args).stdout
         vars = [tuple(item.split("=", 1)) for item in vars]
         vars_dict = {}
@@ -141,10 +171,7 @@ def show_environment(self, name=None):
             else:
                 raise ValueError("unexpected variable %s", t)
 
-        if name:
-            return vars_dict.get(name)
-
-        return vars_dict
+        return vars_dict.get(name)
 
 
 class tmux_cmd:

libtmux/session.py

@@ -421,7 +421,7 @@ def set_option(self, option, value, _global=False):
         if isinstance(proc.stderr, list) and len(proc.stderr):
             handle_option_error(proc.stderr[0])
 
-    def show_options(self, option=None, _global=False):
+    def show_options(self, _global=False):
         """
         Return a dict of options for the window.
 
@@ -430,9 +430,6 @@ def show_options(self, option=None, _global=False):
 
         Parameters
         ----------
-        option : str, optional
-            name of option, e.g. 'visual-silence'. Defaults to None, which
-            returns all options.
         _global : bool, optional
             Pass ``-g`` flag for global variable (server-wide)
 
@@ -450,11 +447,8 @@ def show_options(self, option=None, _global=False):
         if _global:
             tmux_args += ("-g",)
 
-        if option:
-            return self.show_option(option, _global=_global)
-        else:
-            tmux_args += ("show-options",)
-            session_options = self.cmd(*tmux_args).stdout
+        tmux_args += ("show-options",)
+        session_options = self.cmd(*tmux_args).stdout
 
         session_options = [tuple(item.split(" ")) for item in session_options]
 

libtmux/window.py

@@ -193,7 +193,7 @@ def set_window_option(self, option, value):
         if isinstance(cmd.stderr, list) and len(cmd.stderr):
             handle_option_error(cmd.stderr[0])
 
-    def show_window_options(self, option=None, g=False):
+    def show_window_options(self, g=False):
         """
         Return a dict of options for the window.
 
@@ -202,8 +202,6 @@ def show_window_options(self, option=None, g=False):
 
         Parameters
         ----------
-        option : str, optional
-            show a single option.
         g : str, optional
             Pass ``-g`` flag for global variable, default False.
 
@@ -217,11 +215,8 @@ def show_window_options(self, option=None, g=False):
         if g:
             tmux_args += ("-g",)
 
-        if option:
-            return self.show_window_option(option, g=g)
-        else:
-            tmux_args += ("show-window-options",)
-            cmd = self.cmd(*tmux_args).stdout
+        tmux_args += ("show-window-options",)
+        cmd = self.cmd(*tmux_args).stdout
 
         # The shlex.split function splits the args at spaces, while also
         # retaining quoted sub-strings.

tests/test_server.py

@@ -63,20 +63,20 @@ def test_show_environment(server):
     assert isinstance(_vars, dict)
 
 
-def test_set_show_environment_single(server, session):
+def test_getenv(server, session):
     """Set environment then Server.show_environment(key)."""
     server.set_environment("FOO", "BAR")
-    assert "BAR" == server.show_environment("FOO")
+    assert "BAR" == server.getenv("FOO")
 
     server.set_environment("FOO", "DAR")
-    assert "DAR" == server.show_environment("FOO")
+    assert "DAR" == server.getenv("FOO")
 
     assert "DAR" == server.show_environment()["FOO"]
 
 
 def test_show_environment_not_set(server):
     """Unset environment variable returns None."""
-    assert server.show_environment("BAR") is None
+    assert server.getenv("BAR") is None
 
 
 def test_new_session(server):

tests/test_session.py

@@ -108,10 +108,10 @@ def test_set_show_options_single(session):
     """Set option then Session.show_options(key)."""
 
     session.set_option("history-limit", 20)
-    assert session.show_options("history-limit") == 20
+    assert session.show_option("history-limit") == 20
 
     session.set_option("history-limit", 40)
-    assert session.show_options("history-limit") == 40
+    assert session.show_option("history-limit") == 40
 
     assert session.show_options()["history-limit"] == 40
 
@@ -172,35 +172,35 @@ def test_set_show_environment_single(session):
     """Set environment then Session.show_environment(key)."""
 
     session.set_environment("FOO", "BAR")
-    assert session.show_environment("FOO") == "BAR"
+    assert session.getenv("FOO") == "BAR"
 
     session.set_environment("FOO", "DAR")
-    assert session.show_environment("FOO") == "DAR"
+    assert session.getenv("FOO") == "DAR"
 
     assert session.show_environment()["FOO"] == "DAR"
 
 
 def test_show_environment_not_set(session):
     """Not set environment variable returns None."""
-    assert session.show_environment("BAR") is None
+    assert session.getenv("BAR") is None
 
 
 def test_remove_environment(session):
     """Remove environment variable."""
-    assert session.show_environment("BAM") is None
+    assert session.getenv("BAM") is None
     session.set_environment("BAM", "OK")
-    assert session.show_environment("BAM") == "OK"
+    assert session.getenv("BAM") == "OK"
     session.remove_environment("BAM")
-    assert session.show_environment("BAM") is None
+    assert session.getenv("BAM") is None
 
 
 def test_unset_environment(session):
     """Unset environment variable."""
-    assert session.show_environment("BAM") is None
+    assert session.getenv("BAM") is None
     session.set_environment("BAM", "OK")
-    assert session.show_environment("BAM") == "OK"
+    assert session.getenv("BAM") == "OK"
     session.unset_environment("BAM")
-    assert session.show_environment("BAM") is None
+    assert session.getenv("BAM") is None
 
 
 @pytest.mark.parametrize(

tests/test_window.py

@@ -184,15 +184,15 @@ def test_set_show_window_options(session):
     window = session.new_window(window_name="test_window")
 
     window.set_window_option("main-pane-height", 20)
-    assert window.show_window_options("main-pane-height") == 20
+    assert window.show_window_option("main-pane-height") == 20
 
     window.set_window_option("main-pane-height", 40)
-    assert window.show_window_options("main-pane-height") == 40
+    assert window.show_window_option("main-pane-height") == 40
     assert window.show_window_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_window_option("pane-border-format", " #P ")
-        assert window.show_window_options("pane-border-format") == " #P "
+        assert window.show_window_option("pane-border-format") == " #P "
 
 
 def test_empty_window_option_returns_None(session):