paramiko.Channel

From ed280d5ac360e2af796e9bd973d7b4df89f0c449 Mon Sep 17 00:00:00 2001 From: "Jeremy T. Bouse" Date: Fri, 27 Nov 2009 16:20:12 -0500 Subject: Imported Upstream version 1.7.4 --- docs/public/paramiko.Channel-class.html | 1241 ------------------------------- 1 file changed, 1241 deletions(-) delete mode 100644 docs/public/paramiko.Channel-class.html (limited to 'docs/public/paramiko.Channel-class.html') diff --git a/docs/public/paramiko.Channel-class.html b/docs/public/paramiko.Channel-class.html deleted file mode 100644 index 89bff06..0000000 --- a/docs/public/paramiko.Channel-class.html +++ /dev/null @@ -1,1241 +0,0 @@ - - - - - paramiko.Channel - - - - - - - - - - - - - - - - - - -

- - Package paramiko :: - Class Channel -
-

- - -

[show private | hide private]

[frames | no frames]

- - -

Type 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.
	`__del__(self)` -
str -	`__repr__(self)` - -Return a string representation of this object, for debugging.
	`close(self)` - -Close the channel.
bool -	`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, but -but not for reading or writing).
int -	`get_id(self)` - -Return the ID # for this channel.
str -	`get_name(self)` - -Get the name of this channel that was previously set by `set_name`.
bool -	`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.
bool -	`invoke_shell(self)` - -Request an interactive shell session on this channel.
bool -	`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.
`ChannelFile` -	`makefile_stderr(self, - *params)` - -Return a file-like object associated with this channel's stderr -stream.
str -	`recv(self, - nbytes)` - -Receive data from the channel.
int -	`recv_exit_status(self)` - -Return the exit status from the process on the server.
boolean -	`recv_ready(self)` - -Returns true if data is buffered and ready to be read from this -channel.
str -	`recv_stderr(self, - nbytes)` - -Receive data from the channel's stderr stream.
boolean -	`recv_stderr_ready(self)` - -Returns true if data is buffered and ready to be read from this -channel's stderr stream.
bool -	`resize_pty(self, - width, - height)` - -Resize the pseudo-terminal.
int -	`send(self, - s)` - -Send data to the channel.
	`send_exit_status(self, - status)` - -Send the exit status of an executed command to the client.
int -	`send_stderr(self, - s)` - -Send data to the channel on the "stderr" stream.
	`sendall(self, - s)` - -Send data to the channel, without allowing partial results.
	`sendall_stderr(self, - s)` - -Send data to the channel's "stderr" stream, without allowing -partial results.
bool -	`set_combine_stderr(self, - combine)` - -Set whether stderr should be combined into stdout on this channel.
	`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.
	`shutdown_read(self)` - -Shutdown the receiving side of this socket, closing the stream in the -incoming direction.
	`shutdown_write(self)` - -Shutdown the sending side of this socket, closing the stream in the -outgoing direction.
Inherited from object
	`__delattr__(...)` - -x.__delattr__('name') <==> del x.name
	`__getattribute__(...)` - -x.__getattribute__('name') <==> x.name
	`__hash__(x)` - -x.__hash__() <==> hash(x)
	`__new__(T, - S, - ...)` - -T.__new__(S, ...) -> a new object with type S, a subtype of T
	`__reduce__(...)` - -helper for pickle
	`__reduce_ex__(...)` - -helper for pickle
	`__setattr__(...)` - -x.__setattr__('name', value) <==> x.name = value
	`__str__(x)` - -x.__str__() <==> str(x)

- - - - - - - - -

Class Variable Summary
`int`	`MIN_PACKET_SIZE` = 1024

- - - - - - -

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

- Return a string representation of this object, for debugging. -

Returns:: - str -

Overrides:: __builtin__.object.__repr__

- - -

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 their Transport is closed or when they are - garbage collected. -

: -

- - -

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, stdout, and - stderr of the command being executed.

- When the command finishes executing, the channel will be closed and - can't be reused. You must open a new channel if you wish to execute - another command. -

Parameters:: command - - a shell command to execute. -
- (type=str) -

Returns:: - True if the operation succeeded; - False if not. -
- (type=bool) -

- - -

fileno(self) -

Returns an OS-level file descriptor which can be used for polling, - but but not for reading or 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 OS-level FDs are created, which will use up FDs - faster than normal. You won't notice this effect unless you open - hundreds or thousands of channels simultaneously, but it's still - notable. -

Returns:: - an OS-level file descriptor -
- (type=int) -

Warning: This method causes channel reads to be slightly less efficient. -

- -

- - -

get_id(self) -

- Return the ID # for this channel. The channel ID is unique across a - Transport and usually a small number. - It's also the number passed to ServerInterface.check_channel_request - when determining whether to accept a channel request in server - mode. -

Returns:: - the ID of this channel. -
- (type=int) -

Since: ivysaur -

- -

- - -

get_name(self) -

- Get the name of this channel that was previously set by set_name. -

Returns:: - the name of this channel. -
- (type=str) -

- - -

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 a shell invoked with invoke_shell. It isn't necessary (or - desirable) to call this method if you're going to exectue a single - command with exec_command. -

Parameters:: term - - the terminal type to emulate (for example, - 'vt100'). -
- (type=str) -; width - - width (in characters) of the terminal screen -
- (type=int) -; height - - height (in characters) of the terminal screen -
- (type=int) -

Returns:: - True if the operation succeeded; - False if not. -
- (type=bool) -

- - -

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, - stdout, and stderr of the shell.

Normally you would call get_pty before this, in which case the - shell will operate through the pty, and the channel will be connected - to the stdin and stdout of the pty.

- When the shell exits, the channel will be closed and can't be - reused. You must open a new channel if you wish to open another - shell. -

Returns:: - True if the operation succeeded; - False if not. -
- (type=bool) -

- - -

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.

- When the subsystem finishes, the channel will be closed and can't be - reused. -

Parameters:: subsystem - - name of the subsystem being requested. -
- (type=str) -

Returns:: - True if the operation succeeded; - False if not. -
- (type=bool) -

- - -

makefile(self, - *params) -

- Return a file-like object associated with this channel. 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) -

- - -

makefile_stderr(self, - *params) -

Return a file-like object associated with this channel's stderr - stream. Only channels using exec_command or invoke_shell without a pty will ever have - data on the stderr stream.

- The optional mode and bufsize arguments - are interpreted the same way as by the built-in file() - function in python. For a client, it only makes sense to open this file - for reading. For a server, it only makes sense to open this file for - writing. -

Returns:: - object which can be used for python file I/O. -
- (type=ChannelFile) -

Since: 1.1 -

- -

- - -

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=str) -

Raises:: socket.timeout - - if no data is ready before the timeout set by settimeout. -

- - -

recv_exit_status(self) -

- Return the exit status from the process on the server. This is - mostly useful for retrieving the reults of an exec_command. If the command hasn't - finished yet, this method will wait until it does, or until the channel - is closed. If no exit status is provided by the server, -1 is - returned. -

Returns:: - the exit code of the process on the server. -
- (type=int) -

Since: 1.2 -

- -

- - -

recv_ready(self) -

- Returns true if data is buffered and ready to be read from this - channel. A False result does not mean that the channel has - closed; it means you may need to wait before more data arrives. -

Returns:: - True if a recv call on this channel would - immediately return at least one byte; False - otherwise. -
- (type=boolean) -

- - -

recv_stderr(self, - nbytes) -

- Receive data from the channel's stderr stream. Only channels using - exec_command or invoke_shell without a pty will ever have - data on the stderr stream. 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=str) -

Raises:: socket.timeout - - if no data is ready before the timeout set by settimeout. -

Since: 1.1 -

- -

- - -

recv_stderr_ready(self) -

- Returns true if data is buffered and ready to be read from this - channel's stderr stream. Only channels using exec_command or invoke_shell without a pty will ever have - data on the stderr stream. -

Returns:: - True if a recv_stderr call on this channel - would immediately return at least one byte; False - otherwise. -
- (type=boolean) -

Since: 1.1 -

- -

- - -

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

Returns:: - True if the operation succeeded; - False if not. -
- (type=bool) -

- - -

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=str) -

Returns:: - number of bytes actually sent. -
- (type=int) -

Raises:: socket.timeout - - if no data could be sent before the timeout set by settimeout. -

- - -

send_exit_status(self, - status) -

- Send the exit status of an executed command to the client. (This - really only makes sense in server mode.) Many clients expect to get - some sort of status code back from an executed command after it - completes. -

Parameters:: status - - the exit code of the process -
- (type=int) -

Since: 1.2 -

- -

- - -

send_stderr(self, - s) -

- Send data to the channel on the "stderr" stream. This is - normally only used by servers to send output from shell commands -- - clients won't use this. 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=str) -

Returns:: - number of bytes actually sent. -
- (type=int) -

Raises:: socket.timeout - - if no data could be sent before the timeout set by settimeout. -

Since: 1.1 -

- -

- - -

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=str) -

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

- -

- - -

sendall_stderr(self, - s) -

- Send data to the channel's "stderr" stream, without - allowing partial results. Unlike send_stderr, this method continues to - send data from the given string until all data has been sent or an - error occurs. Nothing is returned. -

Parameters:: s - - data to send to the client as "stderr" output. -
- (type=str) -

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

Since: 1.1 -

- -

- - -

set_combine_stderr(self, - combine) -

Set whether stderr should be combined into stdout on this channel. - The default is False, but in some cases it may be - convenient to have both streams combined.

If this is False, and exec_command is called (or - invoke_shell with no pty), output to stderr will not show - up through the recv and recv_ready calls. You will have to use recv_stderr and recv_stderr_ready to get stderr - output.

- If this is True, data will never show up via recv_stderr or recv_stderr_ready. -

Parameters:: combine - - True if stderr output should be combined into - stdout on this channel. -
- (type=bool) -

Returns:: - previous setting. -
- (type=bool) -

Since: 1.1 -

- -

- - -

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=str) -

- - -

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

- - -

shutdown_read(self) -

- Shutdown the receiving side of this socket, closing the stream in - the incoming direction. After this call, future reads on this channel - will fail instantly. This is a convenience method, equivalent to - shutdown(0), for people who don't make it a habit to - memorize unix constants from the 1970s. -

: -
Since: 1.2 -
- -

- - -

shutdown_write(self) -

- Shutdown the sending side of this socket, closing the stream in the - outgoing direction. After this call, future writes on this channel will - fail instantly. This is a convenience method, equivalent to - shutdown(1), for people who don't make it a habit to - memorize unix constants from the 1970s. -

: -
Since: 1.2 -
- -

-
- - - - - - -

Class Variable Details

- -

MIN_PACKET_SIZE

Type:: - int - -
Value:: -
-1024
-

-
- - - - - - - - - - - - - - - - - - -

Generated by Epydoc 2.1 on Sun Dec 4 11:16:47 2005

http://epydoc.sf.net

- - -- cgit v1.2.3

Type Channel

__init__(self, - chanid) - (Constructor) -

__repr__(self) - (Representation operator) -

close(self) -

exec_command(self, - command) -

fileno(self) -

get_id(self) -

get_name(self) -

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

get_transport(self) -

gettimeout(self) -

invoke_shell(self) -

invoke_subsystem(self, - subsystem) -

makefile(self, - *params) -

makefile_stderr(self, - *params) -

recv(self, - nbytes) -

recv_exit_status(self) -

recv_ready(self) -

recv_stderr(self, - nbytes) -

recv_stderr_ready(self) -

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

send(self, - s) -

send_exit_status(self, - status) -

send_stderr(self, - s) -

sendall(self, - s) -

sendall_stderr(self, - s) -

set_combine_stderr(self, - combine) -

set_name(self, - name) -

setblocking(self, - blocking) -

settimeout(self, - timeout) -

shutdown(self, - how) -

shutdown_read(self) -

shutdown_write(self) -

MIN_PACKET_SIZE

init(self, - chanid) -
(Constructor) -

repr(self) -
(Representation operator) -