From cfa81ebd780eb0c7fa82ce5e203f93a459f0318f Mon Sep 17 00:00:00 2001
From: Jeff Forcier <jeff@bitprophet.org>
Date: Wed, 30 Nov 2016 20:31:04 -0800
Subject: Cleanup / rename / doc updates / changelog, re #398

---
 paramiko/channel.py     | 17 ++++++++++-------
 paramiko/client.py      | 17 +++++++++++++----
 sites/www/changelog.rst |  8 ++++++++
 3 files changed, 31 insertions(+), 11 deletions(-)

diff --git a/paramiko/channel.py b/paramiko/channel.py
index 7735e1f1..7689b266 100644
--- a/paramiko/channel.py
+++ b/paramiko/channel.py
@@ -284,14 +284,16 @@ class Channel (ClosingContextManager):
         self.transport._send_user_message(m)
 
     @open_only
-    def update_environment_variables(self, environment):
+    def update_environment(self, environment):
         """
-        Updates this channel's environment. This operation is additive - i.e.
-        the current environment is not reset before the given environment
-        variables are set.
+        Updates this channel's remote shell environment.
 
-        :param dict environment: a dictionary containing the name and respective
-            values to set
+        .. note::
+            This operation is additive - i.e. the current environment is not
+            reset before the given environment variables are set.
+
+        :param dict environment:
+            a dictionary containing the name and respective values to set
         :raises SSHException:
             if any of the environment variables was rejected by the server or
             the channel was closed
@@ -300,7 +302,8 @@ class Channel (ClosingContextManager):
             try:
                 self.set_environment_variable(name, value)
             except SSHException as e:
-                raise SSHException("Failed to set environment variable \"%s\"." % name, e)
+                err = "Failed to set environment variable \"{0}\"."
+                raise SSHException(err.format(name), e)
 
     @open_only
     def set_environment_variable(self, name, value):
diff --git a/paramiko/client.py b/paramiko/client.py
index 681760cf..978bde51 100644
--- a/paramiko/client.py
+++ b/paramiko/client.py
@@ -398,8 +398,14 @@ class SSHClient (ClosingContextManager):
             self._agent.close()
             self._agent = None
 
-    def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False,
-                     environment=None):
+    def exec_command(
+        self,
+        command,
+        bufsize=-1,
+        timeout=None,
+        get_pty=False,
+        environment=None,
+    ):
         """
         Execute a command on the SSH server.  A new `.Channel` is opened and
         the requested command is executed.  The command's input and output
@@ -412,7 +418,9 @@ class SSHClient (ClosingContextManager):
             Python
         :param int timeout:
             set command's channel timeout. See `Channel.settimeout`.settimeout
-        :param dict environment: the command's environment
+        :param dict environment:
+            a dict of shell environment variables, to be merged into the
+            default environment that the remote command executes within.
         :return:
             the stdin, stdout, and stderr of the executing command, as a
             3-tuple
@@ -423,7 +431,8 @@ class SSHClient (ClosingContextManager):
         if get_pty:
             chan.get_pty()
         chan.settimeout(timeout)
-        chan.update_environment_variables(environment or {})
+        if environment:
+            chan.update_environment(environment)
         chan.exec_command(command)
         stdin = chan.makefile('wb', bufsize)
         stdout = chan.makefile('r', bufsize)
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst
index 0073d560..12fecdc5 100644
--- a/sites/www/changelog.rst
+++ b/sites/www/changelog.rst
@@ -2,6 +2,14 @@
 Changelog
 =========
 
+* :feature:`398` Add an ``environment`` dict argument to `Client.exec_command
+  <paramiko.client.SSHClient.exec_command>` (plus the lower level
+  `Channel.update_environment <paramiko.channel.Channel.update_environment>`
+  and `Channel.set_environment_variable
+  <paramiko.channel.Channel.set_environment_variable>` methods) which
+  implements the ``env`` SSH message type. This means the remote shell
+  environment can be set without the use of ``VARNAME=value`` shell tricks.
+  Thanks to Philip Lorenz for the pull request.
 * :support:`819 backported (>=1.15,<2.0)` Document how lacking ``gmp`` headers
   at install time can cause a significant performance hit if you build PyCrypto
   from source. (Most system-distributed packages already have this enabled.)
-- 
cgit v1.2.3