Cleanup / rename / doc updates / changelog, re #398

paramiko/channel.py

@@ -284,14 +284,16 @@ def resize_pty(self, width=80, height=24, width_pixels=0, height_pixels=0):
         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 @@ def update_environment_variables(self, environment):
             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):

paramiko/client.py

@@ -398,8 +398,14 @@ def close(self):
             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 @@ def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False,
             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 @@ def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False,
         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)

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.)