Package paramiko :: Module channel :: Class Channel
[show private | hide private]
[frames | no frames]

Class Channel

object --+
         |
        Channel


A secure tunnel across an SSH Transport. A Channel is meant to behave like a socket, and has an API that should be indistinguishable from the python socket API.

Because SSH2 has a windowing kind of flow control, if you stop reading data from a Channel and its buffer fills up, the server will be unable to send you any more data until you read some of it. (This won't affect other channels on the same transport -- all channels on a single transport are flow-controlled independently.) Similarly, if the server isn't reading data you send, calls to send may block, unless you set a timeout. This is exactly like a normal network socket, so it shouldn't be too surprising.
Method Summary
  __init__(self, chanid)
Create a new channel.
string __repr__(self)
Returns a string representation of this object, for debugging.
boolean check_pty_request(self, term, width, height, pixelwidth, pixelheight, modes)
(subclass override) Determine if a pseudo-terminal of the given dimensions (usually requested for shell access) can be provided.
boolean check_shell_request(self)
(subclass override) Determine if a shell will be provided to the client.
boolean check_subsystem_request(self, name)
(subclass override) Determine if a requested subsystem will be provided to the client.
  check_window_change_request(self, width, height, pixelwidth, pixelheight)
(subclass override) Determine if the pseudo-terminal can be resized.
  close(self)
Close the channel.
  exec_command(self, command)
Execute a command on the server.
int fileno(self)
Returns an OS-level file descriptor which can be used for polling and reading (but not for writing).
string get_name(self)
Get the name of this channel that was previously set by set_name.
  get_pty(self, term, width, height)
Request a pseudo-terminal from the server.
Transport get_transport(self)
Return the Transport associated with this channel.
float gettimeout(self)
Returns the timeout in seconds (as a float) associated with socket operations, or None if no timeout is set.
  invoke_shell(self)
Request an interactive shell session on this channel.
  invoke_subsystem(self, subsystem)
Request a subsystem on the server (for example, sftp).
ChannelFile makefile(self, *params)
Return a file-like object associated with this channel, without the non-portable side effects of fileno.
string recv(self, nbytes)
Receive data from the channel.
boolean recv_ready(self)
Returns true if data is ready to be read from this channel.
  resize_pty(self, width, height)
Resize the pseudo-terminal.
int send(self, s)
Send data to the channel.
  sendall(self, s)
Send data to the channel, without allowing partial results.
  set_name(self, name)
Set a name for this channel.
  setblocking(self, blocking)
Set blocking or non-blocking mode of the channel: if blocking is 0, the channel is set to non-blocking mode; otherwise it's set to blocking mode.
  settimeout(self, timeout)
Set a timeout on blocking read/write operations.
  shutdown(self, how)
Shut down one or both halves of the connection.
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value
  __str__(x)
x.__str__() <==> str(x)
    Inherited from type
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T

Method Details

__init__(self, chanid)
(Constructor)

Create a new channel. The channel is not associated with any particular session or Transport until the Transport attaches it. Normally you would only call this method from the constructor of a subclass of Channel.
Parameters:
chanid - the ID of this channel, as passed by an existing Transport.
           (type=int)
Overrides:
__builtin__.object.__init__

__repr__(self)
(Representation operator)

Returns a string representation of this object, for debugging.
Returns:
string
Overrides:
__builtin__.object.__repr__

check_pty_request(self, term, width, height, pixelwidth, pixelheight, modes)

(subclass override) Determine if a pseudo-terminal of the given dimensions (usually requested for shell access) can be provided.

The default implementation always returns False.
Parameters:
term - type of terminal requested (for example, "vt100").
           (type=string)
width - width of screen in characters.
           (type=int)
height - height of screen in characters.
           (type=int)
pixelwidth - width of screen in pixels, if known (may be 0 if unknown).
           (type=int)
pixelheight - height of screen in pixels, if known (may be 0 if unknown).
           (type=int)
Returns:
True if the psuedo-terminal has been allocated; False otherwise.
           (type=boolean)

check_shell_request(self)

(subclass override) Determine if a shell will be provided to the client. If this method returns True, this channel should be connected to the stdin/stdout of a shell.

The default implementation always returns False.
Returns:
True if this channel is now hooked up to a shell; False if a shell can't or won't be provided.
           (type=boolean)

check_subsystem_request(self, name)

(subclass override) Determine if a requested subsystem will be provided to the client. If this method returns True, all future I/O through this channel will be assumed to be connected to the requested subsystem. An example of a subsystem is sftp.

The default implementation always returns False.
Returns:
True if this channel is now hooked up to the requested subsystem; False if that subsystem can't or won't be provided.
           (type=boolean)

check_window_change_request(self, width, height, pixelwidth, pixelheight)

(subclass override) Determine if the pseudo-terminal can be resized.

The default implementation always returns False.
Parameters:
width - width of screen in characters.
           (type=int)
height - height of screen in characters.
           (type=int)
pixelwidth - width of screen in pixels, if known (may be 0 if unknown).
           (type=int)
pixelheight - height of screen in pixels, if known (may be 0 if unknown).
           (type=int)
Returns:
True if the terminal was resized; False if not.

close(self)

Close the channel. All future read/write operations on the channel will fail. The remote end will receive no more data (after queued data is flushed). Channels are automatically closed when they are garbage- collected, or when their Transport is closed.

exec_command(self, command)

Execute a command on the server. If the server allows it, the channel will then be directly connected to the stdin and stdout of the command being executed.
Parameters:
command - a shell command to execute.
           (type=string)

fileno(self)

Returns an OS-level file descriptor which can be used for polling and reading (but not for writing). This is primaily to allow python's select module to work.

The first time fileno is called on a channel, a pipe is created to simulate real OS-level file descriptor (FD) behavior. Because of this, two actual FDs are created -- this may be inefficient if you plan to use many channels.
Returns:
a small integer file descriptor
           (type=int)

Bug: This does not work on Windows. The problem is that pipes are used to simulate an open FD, but I haven't figured out how to make pipes enter non-blocking mode on Windows yet.

Warning: This method causes several aspects of the channel to change behavior. It is always more efficient to avoid using this method.

get_name(self)

Get the name of this channel that was previously set by set_name.
Returns:
the name of this channel
           (type=string)

get_pty(self, term='vt100', width=80, height=24)

Request a pseudo-terminal from the server. This is usually used right after creating a client channel, to ask the server to provide some basic terminal semantics for the next command you execute.
Parameters:
term - the terminal type to emulate (for example, 'vt100').
           (type=string)
width - width (in characters) of the terminal screen
           (type=int)
height - height (in characters) of the terminal screen
           (type=int)

get_transport(self)

Return the Transport associated with this channel.
Returns:
the Transport that was used to create this channel.
           (type=Transport)

gettimeout(self)

Returns the timeout in seconds (as a float) associated with socket operations, or None if no timeout is set. This reflects the last call to setblocking or settimeout.
Returns:
timeout in seconds, or None.
           (type=float)

invoke_shell(self)

Request an interactive shell session on this channel. If the server allows it, the channel will then be directly connected to the stdin and stdout of the shell.

invoke_subsystem(self, subsystem)

Request a subsystem on the server (for example, sftp). If the server allows it, the channel will then be directly connected to the requested subsystem.
Parameters:
subsystem - name of the subsystem being requested.
           (type=string)

makefile(self, *params)

Return a file-like object associated with this channel, without the non-portable side effects of fileno. The optional mode and bufsize arguments are interpreted the same way as by the built-in file() function in python.
Returns:
object which can be used for python file I/O.
           (type=ChannelFile)

recv(self, nbytes)

Receive data from the channel. The return value is a string representing the data received. The maximum amount of data to be received at once is specified by nbytes. If a string of length zero is returned, the channel stream has closed.
Parameters:
nbytes - maximum number of bytes to read.
           (type=int)
Returns:
data
           (type=string)
Raises:
socket.timeout - if no data is ready before the timeout set by settimeout.

recv_ready(self)

Returns true if data is ready to be read from this channel.
Returns:
True if a recv call on this channel would immediately return at least one byte; False otherwise.
           (type=boolean)

Note: This method doesn't work if you've called fileno.

resize_pty(self, width=80, height=24)

Resize the pseudo-terminal. This can be used to change the width and height of the terminal emulation created in a previous get_pty call.
Parameters:
width - new width (in characters) of the terminal screen
           (type=int)
height - new height (in characters) of the terminal screen
           (type=int)

send(self, s)

Send data to the channel. Returns the number of bytes sent, or 0 if the channel stream is closed. Applications are responsible for checking that all data has been sent: if only some of the data was transmitted, the application needs to attempt delivery of the remaining data.
Parameters:
s - data to send.
           (type=string)
Returns:
number of bytes actually sent.
           (type=int)
Raises:
socket.timeout - if no data could be sent before the timeout set by settimeout.

sendall(self, s)

Send data to the channel, without allowing partial results. Unlike send, this method continues to send data from the given string until either all data has been sent or an error occurs. Nothing is returned.
Parameters:
s - data to send.
           (type=string)
Raises:
socket.timeout - if sending stalled for longer than the timeout set by settimeout.
socket.error - if an error occured before the entire string was sent.

Note: If the channel is closed while only part of the data hase been sent, there is no way to determine how much data (if any) was sent. This is irritating, but identically follows python's API.

set_name(self, name)

Set a name for this channel. Currently it's only used to set the name of the log level used for debugging. The name can be fetched with the get_name method.
Parameters:
name - new channel name
           (type=string)

setblocking(self, blocking)

Set blocking or non-blocking mode of the channel: if blocking is 0, the channel is set to non-blocking mode; otherwise it's set to blocking mode. Initially all channels are in blocking mode.

In non-blocking mode, if a recv call doesn't find any data, or if a send call can't immediately dispose of the data, an error exception is raised. In blocking mode, the calls block until they can proceed.

chan.setblocking(0) is equivalent to chan.settimeout(0); chan.setblocking(1) is equivalent to chan.settimeout(None).
Parameters:
blocking - 0 to set non-blocking mode; non-0 to set blocking mode.
           (type=int)

settimeout(self, timeout)

Set a timeout on blocking read/write operations. The timeout argument can be a nonnegative float expressing seconds, or None. If a float is given, subsequent channel read/write operations will raise a timeout exception if the timeout period value has elapsed before the operation has completed. Setting a timeout of None disables timeouts on socket operations.

chan.settimeout(0.0) is equivalent to chan.setblocking(0); chan.settimeout(None) is equivalent to chan.setblocking(1).
Parameters:
timeout - seconds to wait for a pending read/write operation before raising socket.timeout, or None for no timeout.
           (type=float)

shutdown(self, how)

Shut down one or both halves of the connection. If how is 0, further receives are disallowed. If how is 1, further sends are disallowed. If how is 2, further sends and receives are disallowed. This closes the stream in one or both directions.
Parameters:
how - 0 (stop receiving), 1 (stop sending), or 2 (stop receiving and sending).
           (type=int)

Generated by Epydoc 2.0 on Sun Jan 4 02:33:11 2004 http://epydoc.sf.net