dorian
/
paramiko
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Don't actually need :class: anywhere now

This commit is contained in:
Jeff Forcier 2014-02-21 12:16:11 -08:00
parent f09b562fa8
commit f836c98e5c
24 changed files with 278 additions and 278 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
paramiko/__init__.py
View File

@ -26,9 +26,9 @@ replaced ``telnet`` and ``rsh`` for secure access to remote shells, but the
protocol also includes the ability to open arbitrary channels to remote protocol also includes the ability to open arbitrary channels to remote
services across an encrypted tunnel. (This is how ``sftp`` works, for example.) services across an encrypted tunnel. (This is how ``sftp`` works, for example.)
The high-level client API starts with creation of an :class:`.SSHClient` object. The high-level client API starts with creation of an `.SSHClient` object.
For more direct control, pass a socket (or socket-like object) to a For more direct control, pass a socket (or socket-like object) to a
:class:`.Transport`, and use `start_server <.Transport.start_server>` or `.Transport`, and use `start_server <.Transport.start_server>` or
`start_client <.Transport.start_client>` to negoatite `start_client <.Transport.start_client>` to negoatite
with the remote host as either a server or client. As a client, you are with the remote host as either a server or client. As a client, you are
responsible for authenticating using a password or private key, and checking responsible for authenticating using a password or private key, and checking
@ -38,7 +38,7 @@ public key matches what you expected to see.) As a server, you are
responsible for deciding which users, passwords, and keys to allow, and what responsible for deciding which users, passwords, and keys to allow, and what
kind of channels to allow. kind of channels to allow.
Once you have finished, either side may request flow-controlled :class:`channels <Channel>` Once you have finished, either side may request flow-controlled `channels <Channel>`
to the other side, which are python objects that act like sockets, but send and to the other side, which are python objects that act like sockets, but send and
receive data over the encrypted session. receive data over the encrypted session.

6
paramiko/agent.py
View File

@ -44,7 +44,7 @@ class AgentSSH(object):
""" """
Client interface for using private keys from an SSH agent running on the Client interface for using private keys from an SSH agent running on the
local machine. If an SSH agent is running, this class can be used to local machine. If an SSH agent is running, this class can be used to
connect to it and retreive :class:`.PKey` objects which can be used when connect to it and retreive `.PKey` objects which can be used when
attempting to authenticate to remote SSH servers. attempting to authenticate to remote SSH servers.
Because the SSH agent protocol uses environment variables and unix-domain Because the SSH agent protocol uses environment variables and unix-domain
@ -62,7 +62,7 @@ class AgentSSH(object):
will be returned. will be returned.
:return: a list of keys available on the SSH agent :return: a list of keys available on the SSH agent
:rtype: tuple of :class:`.AgentKey` :rtype: tuple of `.AgentKey`
""" """
return self._keys return self._keys
@ -307,7 +307,7 @@ class Agent(AgentSSH):
""" """
Client interface for using private keys from an SSH agent running on the Client interface for using private keys from an SSH agent running on the
local machine. If an SSH agent is running, this class can be used to local machine. If an SSH agent is running, this class can be used to
connect to it and retreive :class:`.PKey` objects which can be used when connect to it and retreive `.PKey` objects which can be used when
attempting to authenticate to remote SSH servers. attempting to authenticate to remote SSH servers.
Because the SSH agent protocol uses environment variables and unix-domain Because the SSH agent protocol uses environment variables and unix-domain

2
paramiko/auth_handler.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.AuthHandler` `.AuthHandler`
""" """
import threading import threading

4
paramiko/buffered_pipe.py
View File

@ -29,7 +29,7 @@ import time
class PipeTimeout (IOError): class PipeTimeout (IOError):
""" """
Indicates that a timeout was reached on a read from a :class:`.BufferedPipe`. Indicates that a timeout was reached on a read from a `.BufferedPipe`.
""" """
pass pass
@ -38,7 +38,7 @@ class BufferedPipe (object):
""" """
A buffer that obeys normal read (with timeout) & close semantics for a A buffer that obeys normal read (with timeout) & close semantics for a
file or socket, but is fed data from another thread. This is used by file or socket, but is fed data from another thread. This is used by
:class:`.Channel`. `.Channel`.
""" """
def __init__(self): def __init__(self):

32
paramiko/channel.py
View File

@ -42,7 +42,7 @@ MIN_PACKET_SIZE = 1024
class Channel (object): class Channel (object):
""" """
A secure tunnel across an SSH :class:`.Transport`. A Channel is meant to behave 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 like a socket, and has an API that should be indistinguishable from the
python socket API. python socket API.
@ -58,12 +58,12 @@ class Channel (object):
def __init__(self, chanid): def __init__(self, chanid):
""" """
Create a new channel. The channel is not associated with any Create a new channel. The channel is not associated with any
particular session or :class:`.Transport` until the Transport attaches it. particular session or `.Transport` until the Transport attaches it.
Normally you would only call this method from the constructor of a Normally you would only call this method from the constructor of a
subclass of :class:`.Channel`. subclass of `.Channel`.
:param chanid: the ID of this channel, as passed by an existing :param chanid: the ID of this channel, as passed by an existing
:class:`.Transport`. `.Transport`.
:type chanid: int :type chanid: int
""" """
self.chanid = chanid self.chanid = chanid
@ -347,7 +347,7 @@ class Channel (object):
If a handler is passed in, the handler is called from another thread If a handler is passed in, the handler is called from another thread
whenever a new x11 connection arrives. The default handler queues up whenever a new x11 connection arrives. The default handler queues up
incoming x11 connections, which may be retrieved using incoming x11 connections, which may be retrieved using
:class:`Transport.accept`. The handler's calling signature is:: `Transport.accept`. The handler's calling signature is::
handler(channel: Channel, (address: str, port: int)) handler(channel: Channel, (address: str, port: int))
@ -416,10 +416,10 @@ class Channel (object):
def get_transport(self): def get_transport(self):
""" """
Return the :class:`.Transport` associated with this channel. Return the `.Transport` associated with this channel.
:return: the :class:`.Transport` that was used to create this channel. :return: the `.Transport` that was used to create this channel.
:rtype: :class:`.Transport` :rtype: `.Transport`
""" """
return self.transport return self.transport
@ -446,8 +446,8 @@ class Channel (object):
def get_id(self): def get_id(self):
""" """
Return the ID # for this channel. The channel ID is unique across Return the ID # for this channel. The channel ID is unique across
a :class:`.Transport` and usually a small number. It's also the number a `.Transport` and usually a small number. It's also the number
passed to :class:`ServerInterface.check_channel_request` when determining passed to `ServerInterface.check_channel_request` when determining
whether to accept a channel request in server mode. whether to accept a channel request in server mode.
:return: the ID of this channel. :return: the ID of this channel.
@ -564,7 +564,7 @@ class Channel (object):
""" """
Close the channel. All future read/write operations on the channel Close the channel. All future read/write operations on the channel
will fail. The remote end will receive no more data (after queued data will fail. The remote end will receive no more data (after queued data
is flushed). Channels are automatically closed when their :class:`.Transport` is flushed). Channels are automatically closed when their `.Transport`
is closed or when they are garbage collected. is closed or when they are garbage collected.
""" """
self.lock.acquire() self.lock.acquire()
@ -829,7 +829,7 @@ class Channel (object):
the built-in ``file()`` function in python. the built-in ``file()`` function in python.
:return: object which can be used for python file I/O. :return: object which can be used for python file I/O.
:rtype: :class:`.ChannelFile` :rtype: `.ChannelFile`
""" """
return ChannelFile(*([self] + list(params))) return ChannelFile(*([self] + list(params)))
@ -845,7 +845,7 @@ class Channel (object):
server, it only makes sense to open this file for writing. server, it only makes sense to open this file for writing.
:return: object which can be used for python file I/O. :return: object which can be used for python file I/O.
:rtype: :class:`.ChannelFile` :rtype: `.ChannelFile`
.. versionadded:: 1.1 .. versionadded:: 1.1
""" """
@ -1227,11 +1227,11 @@ class Channel (object):
class ChannelFile (BufferedFile): class ChannelFile (BufferedFile):
""" """
A file-like wrapper around :class:`.Channel`. A ChannelFile is created by calling A file-like wrapper around `.Channel`. A ChannelFile is created by calling
:class:`Channel.makefile`. `Channel.makefile`.
@bug: To correctly emulate the file object created from a socket's @bug: To correctly emulate the file object created from a socket's
``makefile`` method, a :class:`.Channel` and its ``ChannelFile`` should be able ``makefile`` method, a `.Channel` and its ``ChannelFile`` should be able
to be closed or garbage-collected independently. Currently, closing to be closed or garbage-collected independently. Currently, closing
the ``ChannelFile`` does nothing but flush the buffer. the ``ChannelFile`` does nothing but flush the buffer.
""" """

56
paramiko/client.py
View File

@ -41,7 +41,7 @@ from paramiko.util import retry_on_signal
class SSHClient (object): class SSHClient (object):
""" """
A high-level representation of a session with an SSH server. This class A high-level representation of a session with an SSH server. This class
wraps :class:`.Transport`, :class:`.Channel`, and :class:`.SFTPClient` to take care of most wraps `.Transport`, `.Channel`, and `.SFTPClient` to take care of most
aspects of authenticating and opening channels. A typical use case is:: aspects of authenticating and opening channels. A typical use case is::
client = SSHClient() client = SSHClient()
@ -103,7 +103,7 @@ class SSHClient (object):
Load host keys from a local host-key file. Host keys read with this Load host keys from a local host-key file. Host keys read with this
method will be checked after keys loaded via `load_system_host_keys`, method will be checked after keys loaded via `load_system_host_keys`,
but will be saved back by `save_host_keys` (so they can be modified). but will be saved back by `save_host_keys` (so they can be modified).
The missing host key policy :class:`.AutoAddPolicy` adds keys to this set and The missing host key policy `.AutoAddPolicy` adds keys to this set and
saves them, when connecting to a previously-unknown server. saves them, when connecting to a previously-unknown server.
This method can be called multiple times. Each new set of host keys This method can be called multiple times. Each new set of host keys
@ -143,11 +143,11 @@ class SSHClient (object):
def get_host_keys(self): def get_host_keys(self):
""" """
Get the local :class:`.HostKeys` object. This can be used to examine the Get the local `.HostKeys` object. This can be used to examine the
local host keys or change them. local host keys or change them.
:return: the local host keys :return: the local host keys
:rtype: :class:`.HostKeys` :rtype: `.HostKeys`
""" """
return self._host_keys return self._host_keys
@ -164,13 +164,13 @@ class SSHClient (object):
def set_missing_host_key_policy(self, policy): def set_missing_host_key_policy(self, policy):
""" """
Set the policy to use when connecting to a server that doesn't have a Set the policy to use when connecting to a server that doesn't have a
host key in either the system or local :class:`.HostKeys` objects. The host key in either the system or local `.HostKeys` objects. The
default policy is to reject all unknown servers (using :class:`.RejectPolicy`). default policy is to reject all unknown servers (using `.RejectPolicy`).
You may substitute :class:`.AutoAddPolicy` or write your own policy class. You may substitute `.AutoAddPolicy` or write your own policy class.
:param policy: the policy to use when receiving a host key from a :param policy: the policy to use when receiving a host key from a
previously-unknown server previously-unknown server
:type policy: :class:`.MissingHostKeyPolicy` :type policy: `.MissingHostKeyPolicy`
""" """
self._policy = policy self._policy = policy
@ -183,7 +183,7 @@ class SSHClient (object):
and any local host keys (`load_host_keys`). If the server's hostname and any local host keys (`load_host_keys`). If the server's hostname
is not found in either set of host keys, the missing host key policy is not found in either set of host keys, the missing host key policy
is used (see `set_missing_host_key_policy`). The default policy is is used (see `set_missing_host_key_policy`). The default policy is
to reject the key and raise an :class:`.SSHException`. to reject the key and raise an `.SSHException`.
Authentication is attempted in the following order of priority: Authentication is attempted in the following order of priority:
@ -206,7 +206,7 @@ class SSHClient (object):
a private key a private key
:type password: str :type password: str
:param pkey: an optional private key to use for authentication :param pkey: an optional private key to use for authentication
:type pkey: :class:`.PKey` :type pkey: `.PKey`
:param key_filename: the filename, or list of filenames, of optional :param key_filename: the filename, or list of filenames, of optional
private key(s) to try for authentication private key(s) to try for authentication
:type key_filename: str or list(str) :type key_filename: str or list(str)
@ -220,7 +220,7 @@ class SSHClient (object):
:param compress: set to True to turn on compression :param compress: set to True to turn on compression
:type compress: bool :type compress: bool
:param sock: an open socket or socket-like object (such as a :param sock: an open socket or socket-like object (such as a
:class:`.Channel`) to use for communication to the target host `.Channel`) to use for communication to the target host
:type sock: socket :type sock: socket
:raises BadHostKeyException: if the server's host key could not be :raises BadHostKeyException: if the server's host key could not be
@ -286,7 +286,7 @@ class SSHClient (object):
def close(self): def close(self):
""" """
Close this SSHClient and its underlying :class:`.Transport`. Close this SSHClient and its underlying `.Transport`.
""" """
if self._transport is None: if self._transport is None:
return return
@ -299,7 +299,7 @@ class SSHClient (object):
def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False): def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False):
""" """
Execute a command on the SSH server. A new :class:`.Channel` is opened and Execute a command on the SSH server. A new `.Channel` is opened and
the requested command is executed. The command's input and output the requested command is executed. The command's input and output
streams are returned as python ``file``-like objects representing streams are returned as python ``file``-like objects representing
stdin, stdout, and stderr. stdin, stdout, and stderr.
@ -308,10 +308,10 @@ class SSHClient (object):
:type command: str :type command: str
:param bufsize: interpreted the same way as by the built-in ``file()`` function in python :param bufsize: interpreted the same way as by the built-in ``file()`` function in python
:type bufsize: int :type bufsize: int
:param timeout: set command's channel timeout. See :class:`Channel.settimeout`.settimeout :param timeout: set command's channel timeout. See `Channel.settimeout`.settimeout
:type timeout: int :type timeout: int
:return: the stdin, stdout, and stderr of the executing command :return: the stdin, stdout, and stderr of the executing command
:rtype: tuple(:class:`.ChannelFile`, :class:`.ChannelFile`, :class:`.ChannelFile`) :rtype: tuple(`.ChannelFile`, `.ChannelFile`, `.ChannelFile`)
:raises SSHException: if the server fails to execute the command :raises SSHException: if the server fails to execute the command
""" """
@ -328,7 +328,7 @@ class SSHClient (object):
def invoke_shell(self, term='vt100', width=80, height=24, width_pixels=0, def invoke_shell(self, term='vt100', width=80, height=24, width_pixels=0,
height_pixels=0): height_pixels=0):
""" """
Start an interactive shell session on the SSH server. A new :class:`.Channel` Start an interactive shell session on the SSH server. A new `.Channel`
is opened and connected to a pseudo-terminal using the requested is opened and connected to a pseudo-terminal using the requested
terminal type and size. terminal type and size.
@ -343,7 +343,7 @@ class SSHClient (object):
:param height_pixels: the height (in pixels) of the terminal window :param height_pixels: the height (in pixels) of the terminal window
:type height_pixels: int :type height_pixels: int
:return: a new channel connected to the remote shell :return: a new channel connected to the remote shell
:rtype: :class:`.Channel` :rtype: `.Channel`
:raises SSHException: if the server fails to invoke a shell :raises SSHException: if the server fails to invoke a shell
""" """
@ -357,18 +357,18 @@ class SSHClient (object):
Open an SFTP session on the SSH server. Open an SFTP session on the SSH server.
:return: a new SFTP session object :return: a new SFTP session object
:rtype: :class:`.SFTPClient` :rtype: `.SFTPClient`
""" """
return self._transport.open_sftp_client() return self._transport.open_sftp_client()
def get_transport(self): def get_transport(self):
""" """
Return the underlying :class:`.Transport` object for this SSH connection. Return the underlying `.Transport` object for this SSH connection.
This can be used to perform lower-level tasks, like opening specific This can be used to perform lower-level tasks, like opening specific
kinds of channels. kinds of channels.
:return: the Transport for this connection :return: the Transport for this connection
:rtype: :class:`.Transport` :rtype: `.Transport`
""" """
return self._transport return self._transport
@ -482,19 +482,19 @@ class SSHClient (object):
class MissingHostKeyPolicy (object): class MissingHostKeyPolicy (object):
""" """
Interface for defining the policy that :class:`.SSHClient` should use when the Interface for defining the policy that `.SSHClient` should use when the
SSH server's hostname is not in either the system host keys or the SSH server's hostname is not in either the system host keys or the
application's keys. Pre-made classes implement policies for automatically application's keys. Pre-made classes implement policies for automatically
adding the key to the application's :class:`.HostKeys` object (:class:`.AutoAddPolicy`), adding the key to the application's `.HostKeys` object (`.AutoAddPolicy`),
and for automatically rejecting the key (:class:`.RejectPolicy`). and for automatically rejecting the key (`.RejectPolicy`).
This function may be used to ask the user to verify the key, for example. This function may be used to ask the user to verify the key, for example.
""" """
def missing_host_key(self, client, hostname, key): def missing_host_key(self, client, hostname, key):
""" """
Called when an :class:`.SSHClient` receives a server key for a server that Called when an `.SSHClient` receives a server key for a server that
isn't in either the system or local :class:`.HostKeys` object. To accept isn't in either the system or local `.HostKeys` object. To accept
the key, simply return. To reject, raised an exception (which will the key, simply return. To reject, raised an exception (which will
be passed to the calling application). be passed to the calling application).
""" """
@ -504,7 +504,7 @@ class MissingHostKeyPolicy (object):
class AutoAddPolicy (MissingHostKeyPolicy): class AutoAddPolicy (MissingHostKeyPolicy):
""" """
Policy for automatically adding the hostname and new host key to the Policy for automatically adding the hostname and new host key to the
local :class:`.HostKeys` object, and saving it. This is used by :class:`.SSHClient`. local `.HostKeys` object, and saving it. This is used by `.SSHClient`.
""" """
def missing_host_key(self, client, hostname, key): def missing_host_key(self, client, hostname, key):
@ -518,7 +518,7 @@ class AutoAddPolicy (MissingHostKeyPolicy):
class RejectPolicy (MissingHostKeyPolicy): class RejectPolicy (MissingHostKeyPolicy):
""" """
Policy for automatically rejecting the unknown hostname & key. This is Policy for automatically rejecting the unknown hostname & key. This is
used by :class:`.SSHClient`. used by `.SSHClient`.
""" """
def missing_host_key(self, client, hostname, key): def missing_host_key(self, client, hostname, key):
@ -530,7 +530,7 @@ class RejectPolicy (MissingHostKeyPolicy):
class WarningPolicy (MissingHostKeyPolicy): class WarningPolicy (MissingHostKeyPolicy):
""" """
Policy for logging a python-style warning for an unknown host key, but Policy for logging a python-style warning for an unknown host key, but
accepting it. This is used by :class:`.SSHClient`. accepting it. This is used by `.SSHClient`.
""" """
def missing_host_key(self, client, hostname, key): def missing_host_key(self, client, hostname, key):
warnings.warn('Unknown %s host key for %s: %s' % warnings.warn('Unknown %s host key for %s: %s' %

2
paramiko/config.py
View File

@ -18,7 +18,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.SSHConfig`. `.SSHConfig`.
""" """
import fnmatch import fnmatch

4
paramiko/dsskey.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.DSSKey` `.DSSKey`
""" """
from Crypto.PublicKey import DSA from Crypto.PublicKey import DSA
@ -159,7 +159,7 @@ class DSSKey (PKey):
key generation (used by ``pyCrypto.PublicKey``). key generation (used by ``pyCrypto.PublicKey``).
:type progress_func: function :type progress_func: function
:return: new private key :return: new private key
:rtype: :class:`.DSSKey` :rtype: `.DSSKey`
""" """
dsa = DSA.generate(bits, rng.read, progress_func) dsa = DSA.generate(bits, rng.read, progress_func)
key = DSSKey(vals=(dsa.p, dsa.q, dsa.g, dsa.y)) key = DSSKey(vals=(dsa.p, dsa.q, dsa.g, dsa.y))

2
paramiko/file.py
View File

@ -94,7 +94,7 @@ class BufferedFile (object):
def next(self): def next(self):
""" """
Returns the next line from the input, or raises :class:`.StopIteration` when Returns the next line from the input, or raises `.StopIteration` when
EOF is hit. Unlike python file objects, it's okay to mix calls to EOF is hit. Unlike python file objects, it's okay to mix calls to
`next` and `readline`. `next` and `readline`.

8
paramiko/hostkeys.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.HostKeys` `.HostKeys`
""" """
import base64 import base64
@ -140,7 +140,7 @@ class HostKeys (UserDict.DictMixin):
:param keytype: key type (``"ssh-rsa"`` or ``"ssh-dss"``) :param keytype: key type (``"ssh-rsa"`` or ``"ssh-dss"``)
:type keytype: str :type keytype: str
:param key: the key to add :param key: the key to add
:type key: :class:`.PKey` :type key: `.PKey`
""" """
for e in self._entries: for e in self._entries:
if (hostname in e.hostnames) and (e.key.get_name() == keytype): if (hostname in e.hostnames) and (e.key.get_name() == keytype):
@ -209,7 +209,7 @@ class HostKeys (UserDict.DictMixin):
:param hostname: the hostname (or IP) to lookup :param hostname: the hostname (or IP) to lookup
:type hostname: str :type hostname: str
:return: keys associated with this host (or ``None``) :return: keys associated with this host (or ``None``)
:rtype: dict(str, :class:`.PKey`) :rtype: dict(str, `.PKey`)
""" """
class SubDict (UserDict.DictMixin): class SubDict (UserDict.DictMixin):
def __init__(self, hostname, entries, hostkeys): def __init__(self, hostname, entries, hostkeys):
@ -257,7 +257,7 @@ class HostKeys (UserDict.DictMixin):
:param hostname: hostname (or IP) of the SSH server :param hostname: hostname (or IP) of the SSH server
:type hostname: str :type hostname: str
:param key: the key to check :param key: the key to check
:type key: :class:`.PKey` :type key: `.PKey`
:return: ``True`` if the key is associated with the hostname; ``False`` :return: ``True`` if the key is associated with the hostname; ``False``
if not if not
:rtype: bool :rtype: bool

2
paramiko/kex_gex.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
Variant on :class:`KexGroup1 <paramiko.kex_group1.KexGroup1>` where the prime "p" and Variant on `KexGroup1 <paramiko.kex_group1.KexGroup1>` where the prime "p" and
generator "g" are provided by the server. A bit more work is required on the generator "g" are provided by the server. A bit more work is required on the
client side, and a B{lot} more on the server side. client side, and a B{lot} more on the server side.
""" """

28
paramiko/pkey.py
View File

@ -52,9 +52,9 @@ class PKey (object):
``data`` is given, the key's public part(s) will be filled in from ``data`` is given, the key's public part(s) will be filled in from
the string. the string.
:param msg: an optional SSH :class:`.Message` containing a public key of this :param msg: an optional SSH `.Message` containing a public key of this
type. type.
:type msg: :class:`.Message` :type msg: `.Message`
:param data: an optional string containing a public key of this type :param data: an optional string containing a public key of this type
:type data: str :type data: str
@ -65,7 +65,7 @@ class PKey (object):
def __str__(self): def __str__(self):
""" """
Return a string of an SSH :class:`.Message` made up of the public part(s) of Return a string of an SSH `.Message` made up of the public part(s) of
this key. This string is suitable for passing to `__init__` to this key. This string is suitable for passing to `__init__` to
re-create the key object later. re-create the key object later.
@ -82,7 +82,7 @@ class PKey (object):
corresponding private key. corresponding private key.
:param other: key to compare to. :param other: key to compare to.
:type other: :class:`.PKey` :type other: `.PKey`
:return: 0 if the two keys are equivalent, non-0 otherwise. :return: 0 if the two keys are equivalent, non-0 otherwise.
:rtype: int :rtype: int
""" """
@ -146,15 +146,15 @@ class PKey (object):
def sign_ssh_data(self, rng, data): def sign_ssh_data(self, rng, data):
""" """
Sign a blob of data with this private key, and return a :class:`.Message` Sign a blob of data with this private key, and return a `.Message`
representing an SSH signature message. representing an SSH signature message.
:param rng: a secure random number generator. :param rng: a secure random number generator.
:type rng: :class:`Crypto.Util.rng.RandomPool` :type rng: `Crypto.Util.rng.RandomPool`
:param data: the data to sign. :param data: the data to sign.
:type data: str :type data: str
:return: an SSH signature message. :return: an SSH signature message.
:rtype: :class:`.Message` :rtype: `.Message`
""" """
return '' return ''
@ -166,7 +166,7 @@ class PKey (object):
:param data: the data that was signed. :param data: the data that was signed.
:type data: str :type data: str
:param msg: an SSH signature message :param msg: an SSH signature message
:type msg: :class:`.Message` :type msg: `.Message`
:return: ``True`` if the signature verifies correctly; ``False`` :return: ``True`` if the signature verifies correctly; ``False``
otherwise. otherwise.
:rtype: boolean :rtype: boolean
@ -177,9 +177,9 @@ class PKey (object):
""" """
Create a key object by reading a private key file. If the private Create a key object by reading a private key file. If the private
key is encrypted and ``password`` is not ``None``, the given password key is encrypted and ``password`` is not ``None``, the given password
will be used to decrypt the key (otherwise :class:`.PasswordRequiredException` will be used to decrypt the key (otherwise `.PasswordRequiredException`
is thrown). Through the magic of python, this factory method will is thrown). Through the magic of python, this factory method will
exist in all subclasses of PKey (such as :class:`.RSAKey` or :class:`.DSSKey`), but exist in all subclasses of PKey (such as `.RSAKey` or `.DSSKey`), but
is useless on the abstract PKey class. is useless on the abstract PKey class.
:param filename: name of the file to read :param filename: name of the file to read
@ -188,7 +188,7 @@ class PKey (object):
if it's encrypted if it's encrypted
:type password: str :type password: str
:return: a new key object based on the given private key :return: a new key object based on the given private key
:rtype: :class:`.PKey` :rtype: `.PKey`
:raises IOError: if there was an error reading the file :raises IOError: if there was an error reading the file
:raises PasswordRequiredException: if the private key file is :raises PasswordRequiredException: if the private key file is
@ -204,7 +204,7 @@ class PKey (object):
Create a key object by reading a private key from a file (or file-like) Create a key object by reading a private key from a file (or file-like)
object. If the private key is encrypted and ``password`` is not ``None``, object. If the private key is encrypted and ``password`` is not ``None``,
the given password will be used to decrypt the key (otherwise the given password will be used to decrypt the key (otherwise
:class:`.PasswordRequiredException` is thrown). `.PasswordRequiredException` is thrown).
:param file_obj: the file to read from :param file_obj: the file to read from
:type file_obj: file :type file_obj: file
@ -212,7 +212,7 @@ class PKey (object):
encrypted encrypted
:type password: str :type password: str
:return: a new key object based on the given private key :return: a new key object based on the given private key
:rtype: :class:`.PKey` :rtype: `.PKey`
:raises IOError: if there was an error reading the key :raises IOError: if there was an error reading the key
:raises PasswordRequiredException: if the private key file is encrypted, :raises PasswordRequiredException: if the private key file is encrypted,
@ -259,7 +259,7 @@ class PKey (object):
``"BEGIN xxx PRIVATE KEY"`` for some ``xxx``, base64-decode the text we ``"BEGIN xxx PRIVATE KEY"`` for some ``xxx``, base64-decode the text we
find, and return it as a string. If the private key is encrypted and find, and return it as a string. If the private key is encrypted and
``password`` is not ``None``, the given password will be used to decrypt ``password`` is not ``None``, the given password will be used to decrypt
the key (otherwise :class:`.PasswordRequiredException` is thrown). the key (otherwise `.PasswordRequiredException` is thrown).
:param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block. :param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block.
:type tag: str :type tag: str

6
paramiko/proxy.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.ProxyCommand`. `.ProxyCommand`.
""" """
import os import os
@ -33,14 +33,14 @@ class ProxyCommand(object):
Wraps a subprocess running ProxyCommand-driven programs. Wraps a subprocess running ProxyCommand-driven programs.
This class implements a the socket-like interface needed by the This class implements a the socket-like interface needed by the
:class:`.Transport` and :class:`.Packetizer` classes. Using this class instead of a `.Transport` and `.Packetizer` classes. Using this class instead of a
regular socket makes it possible to talk with a Popen'd command that will regular socket makes it possible to talk with a Popen'd command that will
proxy traffic between the client and a server hosted in another machine. proxy traffic between the client and a server hosted in another machine.
""" """
def __init__(self, command_line): def __init__(self, command_line):
""" """
Create a new CommandProxy instance. The instance created by this Create a new CommandProxy instance. The instance created by this
class can be passed as an argument to the :class:`.Transport` class. class can be passed as an argument to the `.Transport` class.
:param command_line: the command that should be executed and :param command_line: the command that should be executed and
used as the proxy. used as the proxy.

4
paramiko/rsakey.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.RSAKey` `.RSAKey`
""" """
from Crypto.PublicKey import RSA from Crypto.PublicKey import RSA
@ -135,7 +135,7 @@ class RSAKey (PKey):
key generation (used by ``pyCrypto.PublicKey``). key generation (used by ``pyCrypto.PublicKey``).
:type progress_func: function :type progress_func: function
:return: new private key :return: new private key
:rtype: :class:`.RSAKey` :rtype: `.RSAKey`
""" """
rsa = RSA.generate(bits, rng.read, progress_func) rsa = RSA.generate(bits, rng.read, progress_func)
key = RSAKey(vals=(rsa.e, rsa.n)) key = RSAKey(vals=(rsa.e, rsa.n))

140
paramiko/server.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.ServerInterface` is an interface to override for server support. `.ServerInterface` is an interface to override for server support.
""" """
import threading import threading
@ -96,9 +96,9 @@ class ServerInterface (object):
- `check_channel_forward_agent_request` - `check_channel_forward_agent_request`
The ``chanid`` parameter is a small number that uniquely identifies the The ``chanid`` parameter is a small number that uniquely identifies the
channel within a :class:`.Transport`. A :class:`.Channel` object is not created channel within a `.Transport`. A `.Channel` object is not created
unless this method returns ``OPEN_SUCCEEDED`` -- once a unless this method returns ``OPEN_SUCCEEDED`` -- once a
:class:`.Channel` object is created, you can call :class:`Channel.get_id` to `.Channel` object is created, you can call `Channel.get_id` to
retrieve the channel ID. retrieve the channel ID.
The return value should either be ``OPEN_SUCCEEDED`` (or The return value should either be ``OPEN_SUCCEEDED`` (or
@ -146,16 +146,16 @@ class ServerInterface (object):
Determine if a client may open channels with no (further) Determine if a client may open channels with no (further)
authentication. authentication.
Return :class:`.AUTH_FAILED` if the client must authenticate, or Return `.AUTH_FAILED` if the client must authenticate, or
:class:`.AUTH_SUCCESSFUL` if it's okay for the client to not `.AUTH_SUCCESSFUL` if it's okay for the client to not
authenticate. authenticate.
The default implementation always returns :class:`.AUTH_FAILED`. The default implementation always returns `.AUTH_FAILED`.
:param username: the username of the client. :param username: the username of the client.
:type username: str :type username: str
:return: :class:`.AUTH_FAILED` if the authentication fails; :return: `.AUTH_FAILED` if the authentication fails;
:class:`.AUTH_SUCCESSFUL` if it succeeds. `.AUTH_SUCCESSFUL` if it succeeds.
:rtype: int :rtype: int
""" """
return AUTH_FAILED return AUTH_FAILED
@ -165,23 +165,23 @@ class ServerInterface (object):
Determine if a given username and password supplied by the client is Determine if a given username and password supplied by the client is
acceptable for use in authentication. acceptable for use in authentication.
Return :class:`.AUTH_FAILED` if the password is not accepted, Return `.AUTH_FAILED` if the password is not accepted,
:class:`.AUTH_SUCCESSFUL` if the password is accepted and completes `.AUTH_SUCCESSFUL` if the password is accepted and completes
the authentication, or :class:`.AUTH_PARTIALLY_SUCCESSFUL` if your the authentication, or `.AUTH_PARTIALLY_SUCCESSFUL` if your
authentication is stateful, and this key is accepted for authentication is stateful, and this key is accepted for
authentication, but more authentication is required. (In this latter authentication, but more authentication is required. (In this latter
case, `get_allowed_auths` will be called to report to the client what case, `get_allowed_auths` will be called to report to the client what
options it has for continuing the authentication.) options it has for continuing the authentication.)
The default implementation always returns :class:`.AUTH_FAILED`. The default implementation always returns `.AUTH_FAILED`.
:param username: the username of the authenticating client. :param username: the username of the authenticating client.
:type username: str :type username: str
:param password: the password given by the client. :param password: the password given by the client.
:type password: str :type password: str
:return: :class:`.AUTH_FAILED` if the authentication fails; :return: `.AUTH_FAILED` if the authentication fails;
:class:`.AUTH_SUCCESSFUL` if it succeeds; `.AUTH_SUCCESSFUL` if it succeeds;
:class:`.AUTH_PARTIALLY_SUCCESSFUL` if the password auth is `.AUTH_PARTIALLY_SUCCESSFUL` if the password auth is
successful, but authentication must continue. successful, but authentication must continue.
:rtype: int :rtype: int
""" """
@ -194,9 +194,9 @@ class ServerInterface (object):
check the username and key and decide if you would accept a signature check the username and key and decide if you would accept a signature
made using this key. made using this key.
Return :class:`.AUTH_FAILED` if the key is not accepted, Return `.AUTH_FAILED` if the key is not accepted,
:class:`.AUTH_SUCCESSFUL` if the key is accepted and completes the `.AUTH_SUCCESSFUL` if the key is accepted and completes the
authentication, or :class:`.AUTH_PARTIALLY_SUCCESSFUL` if your authentication, or `.AUTH_PARTIALLY_SUCCESSFUL` if your
authentication is stateful, and this password is accepted for authentication is stateful, and this password is accepted for
authentication, but more authentication is required. (In this latter authentication, but more authentication is required. (In this latter
case, `get_allowed_auths` will be called to report to the client what case, `get_allowed_auths` will be called to report to the client what
@ -206,15 +206,15 @@ class ServerInterface (object):
If you're willing to accept the key, paramiko will do the work of If you're willing to accept the key, paramiko will do the work of
verifying the client's signature. verifying the client's signature.
The default implementation always returns :class:`.AUTH_FAILED`. The default implementation always returns `.AUTH_FAILED`.
:param username: the username of the authenticating client :param username: the username of the authenticating client
:type username: str :type username: str
:param key: the key object provided by the client :param key: the key object provided by the client
:type key: :class:`PKey <pkey.PKey>` :type key: `PKey <pkey.PKey>`
:return: :class:`.AUTH_FAILED` if the client can't authenticate :return: `.AUTH_FAILED` if the client can't authenticate
with this key; :class:`.AUTH_SUCCESSFUL` if it can; with this key; `.AUTH_SUCCESSFUL` if it can;
:class:`.AUTH_PARTIALLY_SUCCESSFUL` if it can authenticate with `.AUTH_PARTIALLY_SUCCESSFUL` if it can authenticate with
this key but must continue with authentication this key but must continue with authentication
:rtype: int :rtype: int
""" """
@ -227,21 +227,21 @@ class ServerInterface (object):
``"keyboard-interactive"`` auth type, which requires you to send a ``"keyboard-interactive"`` auth type, which requires you to send a
series of questions for the client to answer. series of questions for the client to answer.
Return :class:`.AUTH_FAILED` if this auth method isn't supported. Otherwise, Return `.AUTH_FAILED` if this auth method isn't supported. Otherwise,
you should return an :class:`.InteractiveQuery` object containing the prompts you should return an `.InteractiveQuery` object containing the prompts
and instructions for the user. The response will be sent via a call and instructions for the user. The response will be sent via a call
to `check_auth_interactive_response`. to `check_auth_interactive_response`.
The default implementation always returns :class:`.AUTH_FAILED`. The default implementation always returns `.AUTH_FAILED`.
:param username: the username of the authenticating client :param username: the username of the authenticating client
:type username: str :type username: str
:param submethods: a comma-separated list of methods preferred by the :param submethods: a comma-separated list of methods preferred by the
client (usually empty) client (usually empty)
:type submethods: str :type submethods: str
:return: :class:`.AUTH_FAILED` if this auth method isn't supported; otherwise :return: `.AUTH_FAILED` if this auth method isn't supported; otherwise
an object containing queries for the user an object containing queries for the user
:rtype: int or :class:`.InteractiveQuery` :rtype: int or `.InteractiveQuery`
""" """
return AUTH_FAILED return AUTH_FAILED
@ -251,29 +251,29 @@ class ServerInterface (object):
supported. You should override this method in server mode if you want supported. You should override this method in server mode if you want
to support the ``"keyboard-interactive"`` auth type. to support the ``"keyboard-interactive"`` auth type.
Return :class:`.AUTH_FAILED` if the responses are not accepted, Return `.AUTH_FAILED` if the responses are not accepted,
:class:`.AUTH_SUCCESSFUL` if the responses are accepted and complete `.AUTH_SUCCESSFUL` if the responses are accepted and complete
the authentication, or :class:`.AUTH_PARTIALLY_SUCCESSFUL` if your the authentication, or `.AUTH_PARTIALLY_SUCCESSFUL` if your
authentication is stateful, and this set of responses is accepted for authentication is stateful, and this set of responses is accepted for
authentication, but more authentication is required. (In this latter authentication, but more authentication is required. (In this latter
case, `get_allowed_auths` will be called to report to the client what case, `get_allowed_auths` will be called to report to the client what
options it has for continuing the authentication.) options it has for continuing the authentication.)
If you wish to continue interactive authentication with more questions, If you wish to continue interactive authentication with more questions,
you may return an :class:`.InteractiveQuery` object, which should cause the you may return an `.InteractiveQuery` object, which should cause the
client to respond with more answers, calling this method again. This client to respond with more answers, calling this method again. This
cycle can continue indefinitely. cycle can continue indefinitely.
The default implementation always returns :class:`.AUTH_FAILED`. The default implementation always returns `.AUTH_FAILED`.
:param responses: list of responses from the client :param responses: list of responses from the client
:type responses: list(str) :type responses: list(str)
:return: :class:`.AUTH_FAILED` if the authentication fails; :return: `.AUTH_FAILED` if the authentication fails;
:class:`.AUTH_SUCCESSFUL` if it succeeds; `.AUTH_SUCCESSFUL` if it succeeds;
:class:`.AUTH_PARTIALLY_SUCCESSFUL` if the interactive auth is `.AUTH_PARTIALLY_SUCCESSFUL` if the interactive auth is
successful, but authentication must continue; otherwise an object successful, but authentication must continue; otherwise an object
containing queries for the user containing queries for the user
:rtype: int or :class:`.InteractiveQuery` :rtype: int or `.InteractiveQuery`
""" """
return AUTH_FAILED return AUTH_FAILED
@ -338,7 +338,7 @@ class ServerInterface (object):
:param kind: the kind of global request being made. :param kind: the kind of global request being made.
:type kind: str :type kind: str
:param msg: any extra arguments to the request. :param msg: any extra arguments to the request.
:type msg: :class:`.Message` :type msg: `.Message`
:return: ``True`` or a tuple of data if the request was granted; :return: ``True`` or a tuple of data if the request was granted;
``False`` otherwise. ``False`` otherwise.
:rtype: bool :rtype: bool
@ -357,8 +357,8 @@ class ServerInterface (object):
The default implementation always returns ``False``. The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the pty request arrived on. :param channel: the `.Channel` the pty request arrived on.
:type channel: :class:`.Channel` :type channel: `.Channel`
:param term: type of terminal requested (for example, ``"vt100"``). :param term: type of terminal requested (for example, ``"vt100"``).
:type term: str :type term: str
:param width: width of screen in characters. :param width: width of screen in characters.
@ -386,8 +386,8 @@ class ServerInterface (object):
The default implementation always returns ``False``. The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the request arrived on. :param channel: the `.Channel` the request arrived on.
:type channel: :class:`.Channel` :type channel: `.Channel`
:return: ``True`` if this channel is now hooked up to a shell; ``False`` :return: ``True`` if this channel is now hooked up to a shell; ``False``
if a shell can't or won't be provided. if a shell can't or won't be provided.
:rtype: bool :rtype: bool
@ -402,8 +402,8 @@ class ServerInterface (object):
The default implementation always returns ``False``. The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the request arrived on. :param channel: the `.Channel` the request arrived on.
:type channel: :class:`.Channel` :type channel: `.Channel`
:param command: the command to execute. :param command: the command to execute.
:type command: str :type command: str
:return: ``True`` if this channel is now hooked up to the stdin, :return: ``True`` if this channel is now hooked up to the stdin,
@ -423,16 +423,16 @@ class ServerInterface (object):
subsystem. An example of a subsystem is ``sftp``. subsystem. An example of a subsystem is ``sftp``.
The default implementation checks for a subsystem handler assigned via The default implementation checks for a subsystem handler assigned via
:class:`Transport.set_subsystem_handler`. `Transport.set_subsystem_handler`.
If one has been set, the handler is invoked and this method returns If one has been set, the handler is invoked and this method returns
``True``. Otherwise it returns ``False``. ``True``. Otherwise it returns ``False``.
.. note:: Because the default implementation uses the :class:`.Transport` to .. note:: Because the default implementation uses the `.Transport` to
identify valid subsystems, you probably won't need to override this identify valid subsystems, you probably won't need to override this
method. method.
:param channel: the :class:`.Channel` the pty request arrived on. :param channel: the `.Channel` the pty request arrived on.
:type channel: :class:`.Channel` :type channel: `.Channel`
:param name: name of the requested subsystem. :param name: name of the requested subsystem.
:type name: str :type name: str
:return: ``True`` if this channel is now hooked up to the requested :return: ``True`` if this channel is now hooked up to the requested
@ -453,8 +453,8 @@ class ServerInterface (object):
The default implementation always returns ``False``. The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the pty request arrived on. :param channel: the `.Channel` the pty request arrived on.
:type channel: :class:`.Channel` :type channel: `.Channel`
:param width: width of screen in characters. :param width: width of screen in characters.
:type width: int :type width: int
:param height: height of screen in characters. :param height: height of screen in characters.
@ -474,12 +474,12 @@ class ServerInterface (object):
""" """
Determine if the client will be provided with an X11 session. If this Determine if the client will be provided with an X11 session. If this
method returns ``True``, X11 applications should be routed through new method returns ``True``, X11 applications should be routed through new
SSH channels, using :class:`Transport.open_x11_channel`. SSH channels, using `Transport.open_x11_channel`.
The default implementation always returns ``False``. The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the X11 request arrived on :param channel: the `.Channel` the X11 request arrived on
:type channel: :class:`.Channel` :type channel: `.Channel`
:param single_connection: ``True`` if only a single X11 channel should :param single_connection: ``True`` if only a single X11 channel should
be opened be opened
:type single_connection: bool :type single_connection: bool
@ -502,8 +502,8 @@ class ServerInterface (object):
The default implementation always returns ``False``. The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the request arrived on :param channel: the `.Channel` the request arrived on
:type channel: :class:`.Channel` :type channel: `.Channel`
:return: ``True`` if the AgentForward was loaded; ``False`` if not :return: ``True`` if the AgentForward was loaded; ``False`` if not
:rtype: bool :rtype: bool
""" """
@ -517,9 +517,9 @@ class ServerInterface (object):
authentication is complete. authentication is complete.
The ``chanid`` parameter is a small number that uniquely identifies the The ``chanid`` parameter is a small number that uniquely identifies the
channel within a :class:`.Transport`. A :class:`.Channel` object is not created channel within a `.Transport`. A `.Channel` object is not created
unless this method returns ``OPEN_SUCCEEDED`` -- once a unless this method returns ``OPEN_SUCCEEDED`` -- once a
:class:`.Channel` object is created, you can call :class:`Channel.get_id` to `.Channel` object is created, you can call `Channel.get_id` to
retrieve the channel ID. retrieve the channel ID.
The origin and destination parameters are (ip_address, port) tuples The origin and destination parameters are (ip_address, port) tuples
@ -555,7 +555,7 @@ class SubsystemHandler (threading.Thread):
""" """
Handler for a subsytem in server mode. If you create a subclass of this Handler for a subsytem in server mode. If you create a subclass of this
class and pass it to class and pass it to
:class:`Transport.set_subsystem_handler`, `Transport.set_subsystem_handler`,
an object of this an object of this
class will be created for each request for this subsystem. Each new object class will be created for each request for this subsystem. Each new object
will be executed within its own new thread by calling `start_subsystem`. will be executed within its own new thread by calling `start_subsystem`.
@ -569,19 +569,19 @@ class SubsystemHandler (threading.Thread):
""" """
def __init__(self, channel, name, server): def __init__(self, channel, name, server):
""" """
Create a new handler for a channel. This is used by :class:`.ServerInterface` Create a new handler for a channel. This is used by `.ServerInterface`
to start up a new handler when a channel requests this subsystem. You to start up a new handler when a channel requests this subsystem. You
don't need to override this method, but if you do, be sure to pass the don't need to override this method, but if you do, be sure to pass the
``channel`` and ``name`` parameters through to the original ``__init__`` ``channel`` and ``name`` parameters through to the original ``__init__``
method here. method here.
:param channel: the channel associated with this subsystem request. :param channel: the channel associated with this subsystem request.
:type channel: :class:`.Channel` :type channel: `.Channel`
:param name: name of the requested subsystem. :param name: name of the requested subsystem.
:type name: str :type name: str
:param server: the server object for the session that started this :param server: the server object for the session that started this
subsystem subsystem
:type server: :class:`.ServerInterface` :type server: `.ServerInterface`
""" """
threading.Thread.__init__(self, target=self._run) threading.Thread.__init__(self, target=self._run)
self.__channel = channel self.__channel = channel
@ -591,10 +591,10 @@ class SubsystemHandler (threading.Thread):
def get_server(self): def get_server(self):
""" """
Return the :class:`.ServerInterface` object associated with this channel and Return the `.ServerInterface` object associated with this channel and
subsystem. subsystem.
:rtype: :class:`.ServerInterface` :rtype: `.ServerInterface`
""" """
return self.__server return self.__server
@ -620,21 +620,21 @@ class SubsystemHandler (threading.Thread):
returns, the channel is closed. returns, the channel is closed.
The combination of ``transport`` and ``channel`` are unique; this handler The combination of ``transport`` and ``channel`` are unique; this handler
corresponds to exactly one :class:`.Channel` on one :class:`.Transport`. corresponds to exactly one `.Channel` on one `.Transport`.
.. note:: It is the responsibility of this method to exit if the .. note:: It is the responsibility of this method to exit if the
underlying :class:`.Transport` is closed. This can be done by checking underlying `.Transport` is closed. This can be done by checking
:class:`Transport.is_active` or noticing an EOF `Transport.is_active` or noticing an EOF
on the :class:`.Channel`. If this method loops forever without checking on the `.Channel`. If this method loops forever without checking
for this case, your python interpreter may refuse to exit because for this case, your python interpreter may refuse to exit because
this thread will still be running. this thread will still be running.
:param name: name of the requested subsystem. :param name: name of the requested subsystem.
:type name: str :type name: str
:param transport: the server-mode :class:`.Transport`. :param transport: the server-mode `.Transport`.
:type transport: :class:`.Transport` :type transport: `.Transport`
:param channel: the channel associated with this subsystem request. :param channel: the channel associated with this subsystem request.
:type channel: :class:`.Channel` :type channel: `.Channel`
""" """
pass pass

4
paramiko/sftp_attr.py
View File

@ -68,8 +68,8 @@ class SFTPAttributes (object):
:type obj: object :type obj: object
:param filename: the filename associated with this file. :param filename: the filename associated with this file.
:type filename: str :type filename: str
:return: new :class:`.SFTPAttributes` object with the same attribute fields. :return: new `.SFTPAttributes` object with the same attribute fields.
:rtype: :class:`.SFTPAttributes` :rtype: `.SFTPAttributes`
""" """
attr = cls() attr = cls()
attr.st_size = obj.st_size attr.st_size = obj.st_size

32
paramiko/sftp_client.py
View File

@ -52,19 +52,19 @@ def _to_unicode(s):
class SFTPClient (BaseSFTP): class SFTPClient (BaseSFTP):
""" """
SFTP client object. ``SFTPClient`` is used to open an sftp session across SFTP client object. ``SFTPClient`` is used to open an sftp session across
an open ssh :class:`.Transport` and do remote file operations. an open ssh `.Transport` and do remote file operations.
""" """
def __init__(self, sock): def __init__(self, sock):
""" """
Create an SFTP client from an existing :class:`.Channel`. The channel Create an SFTP client from an existing `.Channel`. The channel
should already have requested the ``"sftp"`` subsystem. should already have requested the ``"sftp"`` subsystem.
An alternate way to create an SFTP client context is by using An alternate way to create an SFTP client context is by using
`from_transport`. `from_transport`.
:param sock: an open :class:`.Channel` using the ``"sftp"`` subsystem :param sock: an open `.Channel` using the ``"sftp"`` subsystem
:type sock: :class:`.Channel` :type sock: `.Channel`
:raises SSHException: if there's an exception while negotiating :raises SSHException: if there's an exception while negotiating
sftp sftp
@ -91,13 +91,13 @@ class SFTPClient (BaseSFTP):
def from_transport(cls, t): def from_transport(cls, t):
""" """
Create an SFTP client channel from an open :class:`.Transport`. Create an SFTP client channel from an open `.Transport`.
:param t: an open :class:`.Transport` which is already authenticated :param t: an open `.Transport` which is already authenticated
:type t: :class:`.Transport` :type t: `.Transport`
:return: a new :class:`.SFTPClient` object, referring to an sftp session :return: a new `.SFTPClient` object, referring to an sftp session
(channel) across the transport (channel) across the transport
:rtype: :class:`.SFTPClient` :rtype: `.SFTPClient`
""" """
chan = t.open_session() chan = t.open_session()
if chan is None: if chan is None:
@ -124,11 +124,11 @@ class SFTPClient (BaseSFTP):
def get_channel(self): def get_channel(self):
""" """
Return the underlying :class:`.Channel` object for this SFTP session. This Return the underlying `.Channel` object for this SFTP session. This
might be useful for doing things like setting a timeout on the channel. might be useful for doing things like setting a timeout on the channel.
:return: the SSH channel :return: the SSH channel
:rtype: :class:`.Channel` :rtype: `.Channel`
.. versionadded:: 1.7.1 .. versionadded:: 1.7.1
""" """
@ -140,7 +140,7 @@ class SFTPClient (BaseSFTP):
The list is in arbitrary order. It does not include the special The list is in arbitrary order. It does not include the special
entries ``'.'`` and ``'..'`` even if they are present in the folder. entries ``'.'`` and ``'..'`` even if they are present in the folder.
This method is meant to mirror ``os.listdir`` as closely as possible. This method is meant to mirror ``os.listdir`` as closely as possible.
For a list of full :class:`.SFTPAttributes` objects, see `listdir_attr`. For a list of full `.SFTPAttributes` objects, see `listdir_attr`.
:param path: path to list (defaults to ``'.'``) :param path: path to list (defaults to ``'.'``)
:type path: str :type path: str
@ -151,12 +151,12 @@ class SFTPClient (BaseSFTP):
def listdir_attr(self, path='.'): def listdir_attr(self, path='.'):
""" """
Return a list containing :class:`.SFTPAttributes` objects corresponding to Return a list containing `.SFTPAttributes` objects corresponding to
files in the given ``path``. The list is in arbitrary order. It does files in the given ``path``. The list is in arbitrary order. It does
not include the special entries ``'.'`` and ``'..'`` even if they are not include the special entries ``'.'`` and ``'..'`` even if they are
present in the folder. present in the folder.
The returned :class:`.SFTPAttributes` objects will each have an additional The returned `.SFTPAttributes` objects will each have an additional
field: ``longname``, which may contain a formatted string of the file's field: ``longname``, which may contain a formatted string of the file's
attributes, in unix format. The content of this string will probably attributes, in unix format. The content of this string will probably
depend on the SFTP server implementation. depend on the SFTP server implementation.
@ -164,7 +164,7 @@ class SFTPClient (BaseSFTP):
:param path: path to list (defaults to ``'.'``) :param path: path to list (defaults to ``'.'``)
:type path: str :type path: str
:return: list of attributes :return: list of attributes
:rtype: list of :class:`.SFTPAttributes` :rtype: list of `.SFTPAttributes`
.. versionadded:: 1.2 .. versionadded:: 1.2
""" """
@ -783,5 +783,5 @@ class SFTPClient (BaseSFTP):
class SFTP (SFTPClient): class SFTP (SFTPClient):
"an alias for :class:`.SFTPClient` for backwards compatability" "an alias for `.SFTPClient` for backwards compatability"
pass pass

16
paramiko/sftp_file.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.SFTPFile` `.SFTPFile`
""" """
from __future__ import with_statement from __future__ import with_statement
@ -181,9 +181,9 @@ class SFTPFile (BufferedFile):
def settimeout(self, timeout): def settimeout(self, timeout):
""" """
Set a timeout on read/write operations on the underlying socket or Set a timeout on read/write operations on the underlying socket or
ssh :class:`.Channel`. ssh `.Channel`.
.. seealso:: :class:`Channel.settimeout` .. seealso:: `Channel.settimeout`
:param timeout: seconds to wait for a pending read/write operation :param timeout: seconds to wait for a pending read/write operation
before raising ``socket.timeout``, or ``None`` for no timeout before raising ``socket.timeout``, or ``None`` for no timeout
:type timeout: float :type timeout: float
@ -193,9 +193,9 @@ class SFTPFile (BufferedFile):
def gettimeout(self): def gettimeout(self):
""" """
Returns the timeout in seconds (as a float) associated with the socket Returns the timeout in seconds (as a float) associated with the socket
or ssh :class:`.Channel` used for this file. or ssh `.Channel` used for this file.
.. seealso:: :class:`Channel.gettimeout` .. seealso:: `Channel.gettimeout`
:rtype: float :rtype: float
""" """
return self.sftp.sock.gettimeout() return self.sftp.sock.gettimeout()
@ -203,9 +203,9 @@ class SFTPFile (BufferedFile):
def setblocking(self, blocking): def setblocking(self, blocking):
""" """
Set blocking or non-blocking mode on the underiying socket or ssh Set blocking or non-blocking mode on the underiying socket or ssh
:class:`.Channel`. `.Channel`.
.. seealso:: :class:`Channel.setblocking` .. seealso:: `Channel.setblocking`
:param blocking: 0 to set non-blocking mode; non-0 to set blocking :param blocking: 0 to set non-blocking mode; non-0 to set blocking
mode. mode.
:type blocking: int :type blocking: int
@ -226,7 +226,7 @@ class SFTPFile (BufferedFile):
def stat(self): def stat(self):
""" """
Retrieve information about this file from the remote system. This is Retrieve information about this file from the remote system. This is
exactly like :class:`SFTP.stat`, except that it operates on an already-open exactly like `SFTP.stat`, except that it operates on an already-open
file. file.
:return: an object containing attributes about this file. :return: an object containing attributes about this file.

18
paramiko/sftp_handle.py
View File

@ -41,7 +41,7 @@ class SFTPHandle (object):
SFTP. If ``flags`` is passed in, it's used to determine if the file SFTP. If ``flags`` is passed in, it's used to determine if the file
is open in append mode. is open in append mode.
:param flags: optional flags as passed to :class:`SFTPServerInterface.open` :param flags: optional flags as passed to `SFTPServerInterface.open`
:type flags: int :type flags: int
""" """
self.__flags = flags self.__flags = flags
@ -76,7 +76,7 @@ class SFTPHandle (object):
to be 64 bits. to be 64 bits.
If the end of the file has been reached, this method may return an If the end of the file has been reached, this method may return an
empty string to signify EOF, or it may also return :class:`.SFTP_EOF`. empty string to signify EOF, or it may also return `.SFTP_EOF`.
The default implementation checks for an attribute on ``self`` named The default implementation checks for an attribute on ``self`` named
``readfile``, and if present, performs the read operation on the python ``readfile``, and if present, performs the read operation on the python
@ -124,7 +124,7 @@ class SFTPHandle (object):
:type offset: int or long :type offset: int or long
:param data: data to write into the file. :param data: data to write into the file.
:type data: str :type data: str
:return: an SFTP error code like :class:`.SFTP_OK`. :return: an SFTP error code like `.SFTP_OK`.
""" """
writefile = getattr(self, 'writefile', None) writefile = getattr(self, 'writefile', None)
if writefile is None: if writefile is None:
@ -148,13 +148,13 @@ class SFTPHandle (object):
def stat(self): def stat(self):
""" """
Return an :class:`.SFTPAttributes` object referring to this open file, or an Return an `.SFTPAttributes` object referring to this open file, or an
error code. This is equivalent to :class:`SFTPServerInterface.stat`, except error code. This is equivalent to `SFTPServerInterface.stat`, except
it's called on an open file instead of a path. it's called on an open file instead of a path.
:return: an attributes object for the given file, or an SFTP error :return: an attributes object for the given file, or an SFTP error
code (like :class:`.SFTP_PERMISSION_DENIED`). code (like `.SFTP_PERMISSION_DENIED`).
:rtype: :class:`.SFTPAttributes` or error code :rtype: `.SFTPAttributes` or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -165,8 +165,8 @@ class SFTPHandle (object):
check for the presence of fields before using them. check for the presence of fields before using them.
:param attr: the attributes to change on this file. :param attr: the attributes to change on this file.
:type attr: :class:`.SFTPAttributes` :type attr: `.SFTPAttributes`
:return: an error code like :class:`.SFTP_OK`. :return: an error code like `.SFTP_OK`.
:rtype: int :rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED

20
paramiko/sftp_server.py
View File

@ -40,26 +40,26 @@ _hash_class = {
class SFTPServer (BaseSFTP, SubsystemHandler): class SFTPServer (BaseSFTP, SubsystemHandler):
""" """
Server-side SFTP subsystem support. Since this is a :class:`.SubsystemHandler`, Server-side SFTP subsystem support. Since this is a `.SubsystemHandler`,
it can be (and is meant to be) set as the handler for ``"sftp"`` requests. it can be (and is meant to be) set as the handler for ``"sftp"`` requests.
Use :class:`Transport.set_subsystem_handler` to activate this class. Use `Transport.set_subsystem_handler` to activate this class.
""" """
def __init__(self, channel, name, server, sftp_si=SFTPServerInterface, *largs, **kwargs): def __init__(self, channel, name, server, sftp_si=SFTPServerInterface, *largs, **kwargs):
""" """
The constructor for SFTPServer is meant to be called from within the The constructor for SFTPServer is meant to be called from within the
:class:`.Transport` as a subsystem handler. ``server`` and any additional `.Transport` as a subsystem handler. ``server`` and any additional
parameters or keyword parameters are passed from the original call to parameters or keyword parameters are passed from the original call to
:class:`Transport.set_subsystem_handler`. `Transport.set_subsystem_handler`.
:param channel: channel passed from the :class:`.Transport`. :param channel: channel passed from the `.Transport`.
:type channel: :class:`.Channel` :type channel: `.Channel`
:param name: name of the requested subsystem. :param name: name of the requested subsystem.
:type name: str :type name: str
:param server: the server object associated with this channel and :param server: the server object associated with this channel and
subsystem subsystem
:type server: :class:`.ServerInterface` :type server: `.ServerInterface`
:param sftp_si: a subclass of :class:`.SFTPServerInterface` to use for handling :param sftp_si: a subclass of `.SFTPServerInterface` to use for handling
individual requests. individual requests.
:type sftp_si: class :type sftp_si: class
""" """
@ -128,7 +128,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
:param e: an errno code, as from ``OSError.errno``. :param e: an errno code, as from ``OSError.errno``.
:type e: int :type e: int
:return: an SFTP error code like :class:`.SFTP_NO_SUCH_FILE`. :return: an SFTP error code like `.SFTP_NO_SUCH_FILE`.
:rtype: int :rtype: int
""" """
if e == errno.EACCES: if e == errno.EACCES:
@ -155,7 +155,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
absolute path). absolute path).
:type filename: str :type filename: str
:param attr: attributes to change. :param attr: attributes to change.
:type attr: :class:`.SFTPAttributes` :type attr: `.SFTPAttributes`
""" """
if sys.platform != 'win32': if sys.platform != 'win32':
# mode operations are meaningless on win32 # mode operations are meaningless on win32

54
paramiko/sftp_si.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
""" """
:class:`.SFTPServerInterface` is an interface to override for SFTP server support. `.SFTPServerInterface` is an interface to override for SFTP server support.
""" """
import os import os
@ -29,7 +29,7 @@ from paramiko.sftp import *
class SFTPServerInterface (object): class SFTPServerInterface (object):
""" """
This class defines an interface for controlling the behavior of paramiko This class defines an interface for controlling the behavior of paramiko
when using the :class:`.SFTPServer` subsystem to provide an SFTP server. when using the `.SFTPServer` subsystem to provide an SFTP server.
Methods on this class are called from the SFTP session's thread, so you can Methods on this class are called from the SFTP session's thread, so you can
block as long as necessary without affecting other sessions (even other block as long as necessary without affecting other sessions (even other
@ -48,7 +48,7 @@ class SFTPServerInterface (object):
:param server: the server object associated with this channel and :param server: the server object associated with this channel and
SFTP subsystem SFTP subsystem
:type server: :class:`.ServerInterface` :type server: `.ServerInterface`
""" """
super(SFTPServerInterface, self).__init__(*largs, **kwargs) super(SFTPServerInterface, self).__init__(*largs, **kwargs)
@ -72,10 +72,10 @@ class SFTPServerInterface (object):
def open(self, path, flags, attr): def open(self, path, flags, attr):
""" """
Open a file on the server and create a handle for future operations Open a file on the server and create a handle for future operations
on that file. On success, a new object subclassed from :class:`.SFTPHandle` on that file. On success, a new object subclassed from `.SFTPHandle`
should be returned. This handle will be used for future operations should be returned. This handle will be used for future operations
on the file (read, write, etc). On failure, an error code such as on the file (read, write, etc). On failure, an error code such as
:class:`.SFTP_PERMISSION_DENIED` should be returned. `.SFTP_PERMISSION_DENIED` should be returned.
``flags`` contains the requested mode for opening (read-only, ``flags`` contains the requested mode for opening (read-only,
write-append, etc) as a bitset of flags from the ``os`` module: write-append, etc) as a bitset of flags from the ``os`` module:
@ -103,9 +103,9 @@ class SFTPServerInterface (object):
requested mode for opening the file. requested mode for opening the file.
:type flags: int :type flags: int
:param attr: requested attributes of the file if it is newly created. :param attr: requested attributes of the file if it is newly created.
:type attr: :class:`.SFTPAttributes` :type attr: `.SFTPAttributes`
:return: a new :class:`.SFTPHandle` or error code. :return: a new `.SFTPHandle` or error code.
:rtype :class:`.SFTPHandle` :rtype `.SFTPHandle`
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -115,21 +115,21 @@ class SFTPServerInterface (object):
posix notation (``"/"`` separates folder names) and may be an absolute posix notation (``"/"`` separates folder names) and may be an absolute
or relative path. or relative path.
The list of files is expected to be a list of :class:`.SFTPAttributes` The list of files is expected to be a list of `.SFTPAttributes`
objects, which are similar in structure to the objects returned by objects, which are similar in structure to the objects returned by
``os.stat``. In addition, each object should have its ``filename`` ``os.stat``. In addition, each object should have its ``filename``
field filled in, since this is important to a directory listing and field filled in, since this is important to a directory listing and
not normally present in ``os.stat`` results. The method not normally present in ``os.stat`` results. The method
:class:`SFTPAttributes.from_stat` will usually do what you want. `SFTPAttributes.from_stat` will usually do what you want.
In case of an error, you should return one of the ``SFTP_*`` error In case of an error, you should return one of the ``SFTP_*`` error
codes, such as :class:`.SFTP_PERMISSION_DENIED`. codes, such as `.SFTP_PERMISSION_DENIED`.
:param path: the requested path (relative or absolute) to be listed. :param path: the requested path (relative or absolute) to be listed.
:type path: str :type path: str
:return: a list of the files in the given folder, using :return: a list of the files in the given folder, using
:class:`.SFTPAttributes` objects. `.SFTPAttributes` objects.
:rtype: list of :class:`.SFTPAttributes` or error code :rtype: list of `.SFTPAttributes` or error code
.. note:: You should normalize the given ``path`` first (see the .. note:: You should normalize the given ``path`` first (see the
``os.path`` module) and check appropriate permissions before returning ``os.path`` module) and check appropriate permissions before returning
@ -141,7 +141,7 @@ class SFTPServerInterface (object):
def stat(self, path): def stat(self, path):
""" """
Return an :class:`.SFTPAttributes` object for a path on the server, or an Return an `.SFTPAttributes` object for a path on the server, or an
error code. If your server supports symbolic links (also known as error code. If your server supports symbolic links (also known as
"aliases"), you should follow them. (`lstat` is the corresponding "aliases"), you should follow them. (`lstat` is the corresponding
call that doesn't follow symlinks/aliases.) call that doesn't follow symlinks/aliases.)
@ -150,14 +150,14 @@ class SFTPServerInterface (object):
file statistics for. file statistics for.
:type path: str :type path: str
:return: an attributes object for the given file, or an SFTP error :return: an attributes object for the given file, or an SFTP error
code (like :class:`.SFTP_PERMISSION_DENIED`). code (like `.SFTP_PERMISSION_DENIED`).
:rtype: :class:`.SFTPAttributes` or error code :rtype: `.SFTPAttributes` or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
def lstat(self, path): def lstat(self, path):
""" """
Return an :class:`.SFTPAttributes` object for a path on the server, or an Return an `.SFTPAttributes` object for a path on the server, or an
error code. If your server supports symbolic links (also known as error code. If your server supports symbolic links (also known as
"aliases"), you should not follow them -- instead, you should "aliases"), you should not follow them -- instead, you should
return data on the symlink or alias itself. (`stat` is the return data on the symlink or alias itself. (`stat` is the
@ -167,8 +167,8 @@ class SFTPServerInterface (object):
file statistics for. file statistics for.
:type path: str :type path: str
:return: an attributes object for the given file, or an SFTP error :return: an attributes object for the given file, or an SFTP error
code (like :class:`.SFTP_PERMISSION_DENIED`). code (like `.SFTP_PERMISSION_DENIED`).
:rtype: :class:`.SFTPAttributes` or error code :rtype: `.SFTPAttributes` or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -179,7 +179,7 @@ class SFTPServerInterface (object):
:param path: the requested path (relative or absolute) of the file :param path: the requested path (relative or absolute) of the file
to delete. to delete.
:type path: str :type path: str
:return: an SFTP error code like :class:`.SFTP_OK`. :return: an SFTP error code like `.SFTP_OK`.
:rtype: int :rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -201,7 +201,7 @@ class SFTPServerInterface (object):
:type oldpath: str :type oldpath: str
:param newpath: the requested new path of the file. :param newpath: the requested new path of the file.
:type newpath: str :type newpath: str
:return: an SFTP error code like :class:`.SFTP_OK`. :return: an SFTP error code like `.SFTP_OK`.
:rtype: int :rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -220,8 +220,8 @@ class SFTPServerInterface (object):
folder. folder.
:type path: str :type path: str
:param attr: requested attributes of the new folder. :param attr: requested attributes of the new folder.
:type attr: :class:`.SFTPAttributes` :type attr: `.SFTPAttributes`
:return: an SFTP error code like :class:`.SFTP_OK`. :return: an SFTP error code like `.SFTP_OK`.
:rtype: int :rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -235,7 +235,7 @@ class SFTPServerInterface (object):
:param path: requested path (relative or absolute) of the folder :param path: requested path (relative or absolute) of the folder
to remove. to remove.
:type path: str :type path: str
:return: an SFTP error code like :class:`.SFTP_OK`. :return: an SFTP error code like `.SFTP_OK`.
:rtype: int :rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -250,8 +250,8 @@ class SFTPServerInterface (object):
change. change.
:type path: str :type path: str
:param attr: requested attributes to change on the file. :param attr: requested attributes to change on the file.
:type attr: :class:`.SFTPAttributes` :type attr: `.SFTPAttributes`
:return: an error code like :class:`.SFTP_OK`. :return: an error code like `.SFTP_OK`.
:rtype: int :rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -288,7 +288,7 @@ class SFTPServerInterface (object):
:param path: path (relative or absolute) of the symbolic link. :param path: path (relative or absolute) of the symbolic link.
:type path: str :type path: str
:return: the target path of the symbolic link, or an error code like :return: the target path of the symbolic link, or an error code like
:class:`.SFTP_NO_SUCH_FILE`. `.SFTP_NO_SUCH_FILE`.
:rtype: str or error code :rtype: str or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED

6
paramiko/ssh_exception.py
View File

@ -82,7 +82,7 @@ class PartialAuthentication (AuthenticationException):
class ChannelException (SSHException): class ChannelException (SSHException):
""" """
Exception raised when an attempt to open a new :class:`.Channel` fails. Exception raised when an attempt to open a new `.Channel` fails.
:ivar code: the error code returned by the server :ivar code: the error code returned by the server
:type code: int :type code: int
@ -101,9 +101,9 @@ class BadHostKeyException (SSHException):
:ivar hostname: the hostname of the SSH server :ivar hostname: the hostname of the SSH server
:type hostname: str :type hostname: str
:ivar key: the host key presented by the server :ivar key: the host key presented by the server
:type key: :class:`.PKey` :type key: `.PKey`
:ivar expected_key: the host key expected :ivar expected_key: the host key expected
:type expected_key: :class:`.PKey` :type expected_key: `.PKey`
.. versionadded:: 1.6 .. versionadded:: 1.6
""" """

90
paramiko/transport.py
View File

@ -70,7 +70,7 @@ class Transport (threading.Thread):
""" """
An SSH Transport attaches to a stream (usually a socket), negotiates an An SSH Transport attaches to a stream (usually a socket), negotiates an
encrypted session, authenticates, and then creates stream tunnels, called encrypted session, authenticates, and then creates stream tunnels, called
:class:`channels <Channel>`, across the session. Multiple channels can be multiplexed `channels <Channel>`, across the session. Multiple channels can be multiplexed
across a single session (and often are, in the case of port forwardings). across a single session (and often are, in the case of port forwardings).
""" """
@ -283,20 +283,20 @@ class Transport (threading.Thread):
def get_security_options(self): def get_security_options(self):
""" """
Return a :class:`.SecurityOptions` object which can be used to tweak the Return a `.SecurityOptions` object which can be used to tweak the
encryption algorithms this transport will permit, and the order of encryption algorithms this transport will permit, and the order of
preference for them. preference for them.
:return: an object that can be used to change the preferred algorithms :return: an object that can be used to change the preferred algorithms
for encryption, digest (hash), public key, and key exchange. for encryption, digest (hash), public key, and key exchange.
:rtype: :class:`.SecurityOptions` :rtype: `.SecurityOptions`
""" """
return SecurityOptions(self) return SecurityOptions(self)
def start_client(self, event=None): def start_client(self, event=None):
""" """
Negotiate a new SSH2 session as a client. This is the first step after Negotiate a new SSH2 session as a client. This is the first step after
creating a new :class:`.Transport`. A separate thread is created for protocol creating a new `.Transport`. A separate thread is created for protocol
negotiation. negotiation.
If an event is passed in, this method returns immediately. When If an event is passed in, this method returns immediately. When
@ -308,8 +308,8 @@ class Transport (threading.Thread):
Otherwise an SSHException is raised. Otherwise an SSHException is raised.
After a successful negotiation, you will usually want to authenticate, After a successful negotiation, you will usually want to authenticate,
calling :class:`auth_password <Transport.auth_password>` or calling `auth_password <Transport.auth_password>` or
:class:`auth_publickey <Transport.auth_publickey>`. `auth_publickey <Transport.auth_publickey>`.
.. note:: `connect` is a simpler method for connecting as a client. .. note:: `connect` is a simpler method for connecting as a client.
@ -348,7 +348,7 @@ class Transport (threading.Thread):
def start_server(self, event=None, server=None): def start_server(self, event=None, server=None):
""" """
Negotiate a new SSH2 session as a server. This is the first step after Negotiate a new SSH2 session as a server. This is the first step after
creating a new :class:`.Transport` and setting up your server host key(s). A creating a new `.Transport` and setting up your server host key(s). A
separate thread is created for protocol negotiation. separate thread is created for protocol negotiation.
If an event is passed in, this method returns immediately. When If an event is passed in, this method returns immediately. When
@ -361,15 +361,15 @@ class Transport (threading.Thread):
After a successful negotiation, the client will need to authenticate. After a successful negotiation, the client will need to authenticate.
Override the methods Override the methods
:class:`get_allowed_auths <ServerInterface.get_allowed_auths>`, `get_allowed_auths <ServerInterface.get_allowed_auths>`,
:class:`check_auth_none <ServerInterface.check_auth_none>`, `check_auth_none <ServerInterface.check_auth_none>`,
:class:`check_auth_password <ServerInterface.check_auth_password>`, and `check_auth_password <ServerInterface.check_auth_password>`, and
:class:`check_auth_publickey <ServerInterface.check_auth_publickey>` in the `check_auth_publickey <ServerInterface.check_auth_publickey>` in the
given ``server`` object to control the authentication process. given ``server`` object to control the authentication process.
After a successful authentication, the client should request to open After a successful authentication, the client should request to open
a channel. Override a channel. Override
:class:`check_channel_request <ServerInterface.check_channel_request>` in the `check_channel_request <ServerInterface.check_channel_request>` in the
given ``server`` object to allow channels to be opened. given ``server`` object to allow channels to be opened.
.. note:: After calling this method (or `start_client` or `connect`), .. note:: After calling this method (or `start_client` or `connect`),
@ -379,8 +379,8 @@ class Transport (threading.Thread):
:param event: an event to trigger when negotiation is complete. :param event: an event to trigger when negotiation is complete.
:type event: threading.Event :type event: threading.Event
:param server: an object used to perform authentication and create :param server: an object used to perform authentication and create
:class:`channels <Channel>` `channels <Channel>`
:type server: :class:`server.ServerInterface` :type server: `server.ServerInterface`
:raises SSHException: if negotiation fails (and no ``event`` was passed :raises SSHException: if negotiation fails (and no ``event`` was passed
in) in)
@ -418,9 +418,9 @@ class Transport (threading.Thread):
key info, not just the public half. Only one key of each type (RSA or key info, not just the public half. Only one key of each type (RSA or
DSS) is kept. DSS) is kept.
:param key: the host key to add, usually an :class:`RSAKey <rsakey.RSAKey>` or :param key: the host key to add, usually an `RSAKey <rsakey.RSAKey>` or
:class:`DSSKey <dsskey.DSSKey>`. `DSSKey <dsskey.DSSKey>`.
:type key: :class:`PKey <pkey.PKey>` :type key: `PKey <pkey.PKey>`
""" """
self.server_key_dict[key.get_name()] = key self.server_key_dict[key.get_name()] = key
@ -436,7 +436,7 @@ class Transport (threading.Thread):
yet, ``None`` is returned. In client mode, the behavior is undefined. yet, ``None`` is returned. In client mode, the behavior is undefined.
:return: host key of the type negotiated by the client, or ``None``. :return: host key of the type negotiated by the client, or ``None``.
:rtype: :class:`PKey <pkey.PKey>` :rtype: `PKey <pkey.PKey>`
""" """
try: try:
return self.server_key_dict[self.host_key_type] return self.server_key_dict[self.host_key_type]
@ -504,13 +504,13 @@ class Transport (threading.Thread):
.. note:: Previously this call returned a tuple of (key type, key string). .. note:: Previously this call returned a tuple of (key type, key string).
You can get the same effect by calling You can get the same effect by calling
:class:`PKey.get_name <pkey.PKey.get_name>` for the key type, and `PKey.get_name <pkey.PKey.get_name>` for the key type, and
``str(key)`` for the key string. ``str(key)`` for the key string.
:raises SSHException: if no session is currently active. :raises SSHException: if no session is currently active.
:return: public key of the remote server :return: public key of the remote server
:rtype: :class:`PKey <pkey.PKey>` :rtype: `PKey <pkey.PKey>`
""" """
if (not self.active) or (not self.initial_kex_done): if (not self.active) or (not self.initial_kex_done):
raise SSHException('No existing session') raise SSHException('No existing session')
@ -531,8 +531,8 @@ class Transport (threading.Thread):
Request a new channel to the server, of type ``"session"``. This Request a new channel to the server, of type ``"session"``. This
is just an alias for ``open_channel('session')``. is just an alias for ``open_channel('session')``.
:return: a new :class:`.Channel` :return: a new `.Channel`
:rtype: :class:`.Channel` :rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends :raises SSHException: if the request is rejected or the session ends
prematurely prematurely
@ -547,8 +547,8 @@ class Transport (threading.Thread):
:param src_addr: the source address of the x11 server (port is the :param src_addr: the source address of the x11 server (port is the
x11 port, ie. 6010) x11 port, ie. 6010)
:type src_addr: (str, int) :type src_addr: (str, int)
:return: a new :class:`.Channel` :return: a new `.Channel`
:rtype: :class:`.Channel` :rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends :raises SSHException: if the request is rejected or the session ends
prematurely prematurely
@ -561,8 +561,8 @@ class Transport (threading.Thread):
``"auth-agent@openssh.com"``. ``"auth-agent@openssh.com"``.
This is just an alias for ``open_channel('auth-agent@openssh.com')``. This is just an alias for ``open_channel('auth-agent@openssh.com')``.
:return: a new :class:`.Channel` :return: a new `.Channel`
:rtype: :class:`.Channel` :rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends :raises SSHException: if the request is rejected or the session ends
prematurely prematurely
@ -584,7 +584,7 @@ class Transport (threading.Thread):
def open_channel(self, kind, dest_addr=None, src_addr=None): def open_channel(self, kind, dest_addr=None, src_addr=None):
""" """
Request a new channel to the server. :class:`.Channels <Channel>` are socket-like Request a new channel to the server. `.Channels <Channel>` are socket-like
objects used for the actual transfer of data across the session. objects used for the actual transfer of data across the session.
You may only request a channel after negotiating encryption (using You may only request a channel after negotiating encryption (using
`connect` or `start_client`) and authenticating. `connect` or `start_client`) and authenticating.
@ -599,8 +599,8 @@ class Transport (threading.Thread):
:param src_addr: the source address of this port forwarding, if :param src_addr: the source address of this port forwarding, if
``kind`` is ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"`` ``kind`` is ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``
:type src_addr: (str, int) :type src_addr: (str, int)
:return: a new :class:`.Channel` on success :return: a new `.Channel` on success
:rtype: :class:`.Channel` :rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends :raises SSHException: if the request is rejected or the session ends
prematurely prematurely
@ -717,9 +717,9 @@ class Transport (threading.Thread):
an SFTP session will be opened with the remote host, and a new an SFTP session will be opened with the remote host, and a new
SFTPClient object will be returned. SFTPClient object will be returned.
:return: a new :class:`.SFTPClient` object, referring to an sftp session :return: a new `.SFTPClient` object, referring to an sftp session
(channel) across this transport (channel) across this transport
:rtype: :class:`.SFTPClient` :rtype: `.SFTPClient`
""" """
return SFTPClient.from_transport(self) return SFTPClient.from_transport(self)
@ -793,10 +793,10 @@ class Transport (threading.Thread):
:param wait: ``True`` if this method should not return until a response :param wait: ``True`` if this method should not return until a response
is received; ``False`` otherwise. is received; ``False`` otherwise.
:type wait: bool :type wait: bool
:return: a :class:`.Message` containing possible additional data if the :return: a `.Message` containing possible additional data if the
request was successful (or an empty :class:`.Message` if ``wait`` was request was successful (or an empty `.Message` if ``wait`` was
``False``); ``None`` if the request was denied. ``False``); ``None`` if the request was denied.
:rtype: :class:`.Message` :rtype: `.Message`
""" """
if wait: if wait:
self.completion_event = threading.Event() self.completion_event = threading.Event()
@ -828,7 +828,7 @@ class Transport (threading.Thread):
forever forever
:type timeout: int :type timeout: int
:return: a new Channel opened by the client :return: a new Channel opened by the client
:rtype: :class:`.Channel` :rtype: `.Channel`
""" """
self.lock.acquire() self.lock.acquire()
try: try:
@ -850,14 +850,14 @@ class Transport (threading.Thread):
Negotiate an SSH2 session, and optionally verify the server's host key Negotiate an SSH2 session, and optionally verify the server's host key
and authenticate using a password or private key. This is a shortcut and authenticate using a password or private key. This is a shortcut
for `start_client`, `get_remote_server_key`, and for `start_client`, `get_remote_server_key`, and
:class:`Transport.auth_password` or :class:`Transport.auth_publickey`. Use those `Transport.auth_password` or `Transport.auth_publickey`. Use those
methods if you want more control. methods if you want more control.
You can use this method immediately after creating a Transport to You can use this method immediately after creating a Transport to
negotiate encryption with a server. If it fails, an exception will be negotiate encryption with a server. If it fails, an exception will be
thrown. On success, the method will return cleanly, and an encrypted thrown. On success, the method will return cleanly, and an encrypted
session exists. You may immediately call `open_channel` or session exists. You may immediately call `open_channel` or
`open_session` to get a :class:`.Channel` object, which is used for data `open_session` to get a `.Channel` object, which is used for data
transfer. transfer.
.. note:: If you fail to supply a password or private key, this method may .. note:: If you fail to supply a password or private key, this method may
@ -866,7 +866,7 @@ class Transport (threading.Thread):
:param hostkey: the host key expected from the server, or ``None`` if :param hostkey: the host key expected from the server, or ``None`` if
you don't want to do host key verification. you don't want to do host key verification.
:type hostkey: :class:`PKey<pkey.PKey>` :type hostkey: `PKey<pkey.PKey>`
:param username: the username to authenticate as. :param username: the username to authenticate as.
:type username: str :type username: str
:param password: a password to use for authentication, if you want to :param password: a password to use for authentication, if you want to
@ -874,7 +874,7 @@ class Transport (threading.Thread):
:type password: str :type password: str
:param pkey: a private key to use for authentication, if you want to :param pkey: a private key to use for authentication, if you want to
use private key authentication; otherwise ``None``. use private key authentication; otherwise ``None``.
:type pkey: :class:`PKey<pkey.PKey>` :type pkey: `PKey<pkey.PKey>`
:raises SSHException: if the SSH2 negotiation fails, the host key :raises SSHException: if the SSH2 negotiation fails, the host key
supplied by the server is incorrect, or authentication fails. supplied by the server is incorrect, or authentication fails.
@ -928,15 +928,15 @@ class Transport (threading.Thread):
""" """
Set the handler class for a subsystem in server mode. If a request Set the handler class for a subsystem in server mode. If a request
for this subsystem is made on an open ssh channel later, this handler for this subsystem is made on an open ssh channel later, this handler
will be constructed and called -- see :class:`.SubsystemHandler` for more will be constructed and called -- see `.SubsystemHandler` for more
detailed documentation. detailed documentation.
Any extra parameters (including keyword arguments) are saved and Any extra parameters (including keyword arguments) are saved and
passed to the :class:`.SubsystemHandler` constructor later. passed to the `.SubsystemHandler` constructor later.
:param name: name of the subsystem. :param name: name of the subsystem.
:type name: str :type name: str
:param handler: subclass of :class:`.SubsystemHandler` that handles this :param handler: subclass of `.SubsystemHandler` that handles this
subsystem. subsystem.
:type handler: class :type handler: class
""" """
@ -975,7 +975,7 @@ class Transport (threading.Thread):
Try to authenticate to the server using no authentication at all. Try to authenticate to the server using no authentication at all.
This will almost always fail. It may be useful for determining the This will almost always fail. It may be useful for determining the
list of authentication types supported by the server, by catching the list of authentication types supported by the server, by catching the
:class:`.BadAuthenticationType` exception raised. `.BadAuthenticationType` exception raised.
:param username: the username to authenticate as :param username: the username to authenticate as
:type username: string :type username: string
@ -1101,7 +1101,7 @@ class Transport (threading.Thread):
:param username: the username to authenticate as :param username: the username to authenticate as
:type username: string :type username: string
:param key: the private key to authenticate with :param key: the private key to authenticate with
:type key: :class:`PKey <pkey.PKey>` :type key: `PKey <pkey.PKey>`
:param event: an event to trigger when the authentication attempt is :param event: an event to trigger when the authentication attempt is
complete (whether it was successful or not) complete (whether it was successful or not)
:type event: threading.Event :type event: threading.Event
@ -2041,7 +2041,7 @@ class SecurityOptions (object):
exchange algorithms, listed in order of preference. exchange algorithms, listed in order of preference.
Changing the contents and/or order of these fields affects the underlying Changing the contents and/or order of these fields affects the underlying
:class:`.Transport` (but only if you change them before starting the session). `.Transport` (but only if you change them before starting the session).
If you try to add an algorithm that paramiko doesn't recognize, If you try to add an algorithm that paramiko doesn't recognize,
``ValueError`` will be raised. If you try to assign something besides a ``ValueError`` will be raised. If you try to assign something besides a
tuple to one of the fields, ``TypeError`` will be raised. tuple to one of the fields, ``TypeError`` will be raised.

14
paramiko/util.py
View File

@ -154,9 +154,9 @@ def generate_key_bytes(hashclass, salt, key, nbytes):
through a secure hash into some keyworthy bytes. This specific algorithm through a secure hash into some keyworthy bytes. This specific algorithm
is used for encrypting/decrypting private key files. is used for encrypting/decrypting private key files.
:param hashclass: class from :class:`Crypto.Hash` that can be used as a secure :param hashclass: class from `Crypto.Hash` that can be used as a secure
hashing function (like ``MD5`` or ``SHA``). hashing function (like ``MD5`` or ``SHA``).
:type hashclass: :class:`Crypto.Hash` :type hashclass: `Crypto.Hash`
:param salt: data to salt the hash with. :param salt: data to salt the hash with.
:type salt: string :type salt: string
:param key: human-entered password or passphrase. :param key: human-entered password or passphrase.
@ -185,26 +185,26 @@ def generate_key_bytes(hashclass, salt, key, nbytes):
def load_host_keys(filename): def load_host_keys(filename):
""" """
Read a file of known SSH host keys, in the format used by openssh, and Read a file of known SSH host keys, in the format used by openssh, and
return a compound dict of ``hostname -> keytype ->`` :class:`PKey <paramiko.pkey.PKey>`. return a compound dict of ``hostname -> keytype ->`` `PKey <paramiko.pkey.PKey>`.
The hostname may be an IP address or DNS name. The keytype will be either The hostname may be an IP address or DNS name. The keytype will be either
``"ssh-rsa"`` or ``"ssh-dss"``. ``"ssh-rsa"`` or ``"ssh-dss"``.
This type of file unfortunately doesn't exist on Windows, but on posix, This type of file unfortunately doesn't exist on Windows, but on posix,
it will usually be stored in ``os.path.expanduser("~/.ssh/known_hosts")``. it will usually be stored in ``os.path.expanduser("~/.ssh/known_hosts")``.
Since 1.5.3, this is just a wrapper around :class:`.HostKeys`. Since 1.5.3, this is just a wrapper around `.HostKeys`.
:param filename: name of the file to read host keys from :param filename: name of the file to read host keys from
:type filename: str :type filename: str
:return: dict of host keys, indexed by hostname and then keytype :return: dict of host keys, indexed by hostname and then keytype
:rtype: dict(hostname, dict(keytype, :class:`PKey <paramiko.pkey.PKey>`)) :rtype: dict(hostname, dict(keytype, `PKey <paramiko.pkey.PKey>`))
""" """
from paramiko.hostkeys import HostKeys from paramiko.hostkeys import HostKeys
return HostKeys(filename) return HostKeys(filename)
def parse_ssh_config(file_obj): def parse_ssh_config(file_obj):
""" """
Provided only as a backward-compatible wrapper around :class:`.SSHConfig`. Provided only as a backward-compatible wrapper around `.SSHConfig`.
""" """
config = SSHConfig() config = SSHConfig()
config.parse(file_obj) config.parse(file_obj)
@ -212,7 +212,7 @@ def parse_ssh_config(file_obj):
def lookup_ssh_host_config(hostname, config): def lookup_ssh_host_config(hostname, config):
""" """
Provided only as a backward-compatible wrapper around :class:`.SSHConfig`. Provided only as a backward-compatible wrapper around `.SSHConfig`.
""" """
return config.lookup(hostname) return config.lookup(hostname)