2. Builtin Transport Modules

Pushy provides various builtin transports, which are defined here. Each transport module provides a pushy.transport.Popen() function for creating a transport object, whose class inherits from pushy.transport.BaseTransport.

2.1. Base Transport

pushy.transport.Popen(command, **kwargs)

Executes command, returning an object representing the process, with pipes for standard I/O.

Each transport module must define this function, which will be used to return an object specific to that transport. For example, the local module provides a Popen function which simply wraps subprocess.Popen(). Each transport may expect different keyword parameters.

class pushy.transport.BaseTransport

The base class for all transports.

address

The address to which this transport connection was made.

stdin

The standard input file object for the process created by this transport.

stdout

The standard output file object for the process created by this transport.

stderr

The standard error file object for the process created by this transport.

Note

Some transports may not provide access to standard error, in which case they must provide a file like object which simply returns nothing when read from. Pushy only reads from stderr when an error has occurred. The absence of a real stderr file will not stop Pushy from working, but it will mean that diagnosing problems with Pushy will be more difficult.

getfile(remote_path, local_path)

If defined by a transport, this method is used by pushy.PushyClient.getfile() for copying a file to the local host from the remote host that this transport connects to, making use of any transport-specific file transfer capabilities.

putfile(local_path, remote_path)

If defined by a transport, this method is used by pushy.PushyClient.putfile() for copying a file from the local host to the remote host that this transport connects to, making use of any transport-specific file transfer capabilities.

2.2. local - Local Transport

The local transport is for creating and connecting to a Python interpreter on the local host. It will, by default, spawn a new Python interpreter using the same Python executable (i.e. sys.executable). The pushy.transport.local module defines a single class, Popen, which provides the local transport.

local Address Format

The address format for the local transport is simply local:

>>> import pushy
>>> con = pushy.connect("local:")

class pushy.transport.local.Popen(command, address)

Defines the local transport, for creating and connecting to new Python interpreters on the local host.

getfile(source_path, destination_path)

Implements pushy.transport.BaseTransport.getfile(), calling shutil.copyfile() to perform the copy.

putfile(source_path, destination_path)

Implements pushy.transport.BaseTransport.putfile(), calling shutil.copyfile() to perform the copy.

Example

In this example we create a new local connection. As we can see from the parent ID of the “remote” process, it is a subprocess of the main Python interpreter.

>>> import os, platform
>>> platform.node()
'fork'
>>> os.getpid()
2386
>>> import pushy
>>> con = pushy.connect("local:")
>>> con.modules.platform.node()
'fork'
>>> con.modules.os.getppid()
2386

2.3. ssh - Secure Shell (SSH) Transport

The primary driver for Pushy’s inception, the ssh transport provides a means of creating and connecting to a new Python interpreter on a remote host, via SSH (Secure Shell). Not only is the remote Python interpreter started up on the fly, but Pushy doesn’t need to be installed on the remote host, and nothing is transferred onto the remote filesystem. The ssh transport makes Pushy a safe alternative to traditional nailed-up, privileged services.

ssh Address Format

The address format for the ssh transport is ssh::<hostname>, where <hostname> is substituted with the hostname (or IP address) of the remote host to connect to.

>>> import pushy
>>> con = pushy.connect("ssh:my.remotehost.com")

It is possible to specify an alternative port, and specify the username and password. See Popen for more information on the parameters.

class pushy.transport.ssh.Popen(command, address, username=None, password=None, use_native=None, port=None, missing_host_key_policy="reject")

Defines the ssh transport, for creating and connecting to new Python interpreters on a remote host, via SSH (Secure Shell). Pushy is able to connect via SSH using either Paramiko, or, if available, a native SSH client, such as those provided by OpenSSH and PuTTY.

The username and password arguments may be omitted, in which case the current username will be used, and no password will be provided. In the absence of a password, public-key authentication will be attempted.

Parameters:

• username (string or None) – The username with which to authenticate and run the remote Python process as. If omitted, the current user’s username will instead be used.
• password (string or None) – The password with which to authenticate. If omitted, public-key authentication will be attempted.
• use_native (bool or None) – On Windows, Paramiko has been found to be faster than PuTTY, and so it is the default. On other platforms, the native ssh program is preferred. The preference may be overridden by passing a boolean value as the use_native argument.
• port (int or None) – The port of the SSH daemon to connect to, or None to use the default port.
• missing_host_key_policy (string) – The policy to set for the Paramiko SSH transport to decide what happens when connecting to a host with an unknown host key. This parameter has a default value of “reject”, and can be assigned one of the values “reject”, “autoadd”, or “warning”. This parameter is ignored by the native SSH transport.

getfile(source_path, destination_path)

Implements pushy.transport.BaseTransport.getfile(), using SFTP (Secure File Transfer Protocol) to perform the copy.

putfile(source_path, destination_path)

Implements pushy.transport.BaseTransport.putfile(), using SFTP to perform the copy.

2.4. smb - Microsoft Windows Named Pipe (SMB) Transport

Whilst the ssh transport works perfectly well with SSH daemons on Microsoft Windows, it is not typical for systems running Windows to have an SSH daemon installed. The smb transport allows one to connect to a Windows system by installing a named pipe server, running as a Windows service. With the appropriate permissions, it is possible to remotely install a Windows service. Pushy does not yet have this feature, but it is planned for a future release.

smb Address Format

The address format for the smb transport is smb::<hostname>, where <hostname> is substituted with the hostname (or IP address) of the remote host to connect to.

>>> import pushy
>>> con = pushy.connect("smb:my.remotehost.com")

It is possible to specify the username and password, and the authenticaton domain. See Popen for more information on the parameters.

class pushy.transport.smb.Popen(command, address, username=None, password=None, domain="")

Defines the smb transport, for creating and connecting to new Python interpreters on a remoe host, via Microsoft Windows Named Pipes (SMB). Pushy is able to connect using native Microsoft Windows API calls, if the client is running on Microsoft Windows, and the ctypes module is available. Otherwise, Pushy will fall back to Impacket’s SMB module if it is available.

Parameters:

• address – The address of the target host, in UNC notation.
• username (string or None) – The username with which to authenticate and run the remote Python process as. If omitted, the current user’s username will instead be used.
• password (string or None) – The password with which to authenticate.
• domain (string) – The Microsoft Windows domain with which to authenticate.

2.5. daemon - TCP/IP Daemon Transport

Sometimes you really do just want a long-lived server, and that’s what the daemon transport is for. In conjunction with pushy.server.run(), the daemon transport allows one to connect to a long-lived Python interpreter via a TCP/IP socket.

daemon Address Format

The address format for the daemon transport is daemon::<hostname>, where <hostname> is substituted with the hostname (or IP address) of the remote host to connect to.

>>> import pushy
>>> con = pushy.connect("daemon:my.remotehost.com")

It is possible to specify an alternative port. See Popen for more information on the parameters.

class pushy.transport.daemon.Popen(command, address[, port])

Note

The command argument is ignored by the daemon transport, as there is no need to create a new Python interpreter.

Parameters:

• address – The hostname or IP address to which the transport connect.
• port (Integer) – The port to connect to, which is, by default: pushy.server.DEFAULT_PORT.

Example

First, start a Pushy daemon server:

$ hostname
fork
$ python -m pushy.server

And now we can create a daemon transport connection:

>>> import pushy
>>> con = pushy.connect("daemon:fork")