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
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
: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
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
@ -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
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
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
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.
Because the SSH agent protocol uses environment variables and unix-domain
@ -62,7 +62,7 @@ class AgentSSH(object):
will be returned.
:return: a list of keys available on the SSH agent
:rtype: tuple of :class:`.AgentKey`
:rtype: tuple of `.AgentKey`
"""
return self._keys
@ -307,7 +307,7 @@ class Agent(AgentSSH):
"""
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
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.
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.
"""
:class:`.AuthHandler`
`.AuthHandler`
"""
import threading

4
paramiko/buffered_pipe.py
View File

@ -29,7 +29,7 @@ import time
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
@ -38,7 +38,7 @@ class BufferedPipe (object):
"""
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
:class:`.Channel`.
`.Channel`.
"""
def __init__(self):

32
paramiko/channel.py
View File

@ -42,7 +42,7 @@ MIN_PACKET_SIZE = 1024
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
python socket API.
@ -58,12 +58,12 @@ class Channel (object):
def __init__(self, chanid):
"""
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
subclass of :class:`.Channel`.
subclass of `.Channel`.
:param chanid: the ID of this channel, as passed by an existing
:class:`.Transport`.
`.Transport`.
:type chanid: int
"""
self.chanid = chanid
@ -347,7 +347,7 @@ class Channel (object):
If a handler is passed in, the handler is called from another thread
whenever a new x11 connection arrives. The default handler queues up
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))
@ -416,10 +416,10 @@ class Channel (object):
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.
:rtype: :class:`.Transport`
:return: the `.Transport` that was used to create this channel.
:rtype: `.Transport`
"""
return self.transport
@ -446,8 +446,8 @@ class Channel (object):
def get_id(self):
"""
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
passed to :class:`ServerInterface.check_channel_request` when determining
a `.Transport` and usually a small number. It's also the number
passed to `ServerInterface.check_channel_request` when determining
whether to accept a channel request in server mode.
:return: the ID of this channel.
@ -564,7 +564,7 @@ class Channel (object):
"""
Close the channel. All future read/write operations on the channel
will fail. The remote end will receive no more data (after queued data
is flushed). Channels are automatically closed when their :class:`.Transport`
is flushed). Channels are automatically closed when their `.Transport`
is closed or when they are garbage collected.
"""
self.lock.acquire()
@ -829,7 +829,7 @@ class Channel (object):
the built-in ``file()`` function in python.
:return: object which can be used for python file I/O.
:rtype: :class:`.ChannelFile`
:rtype: `.ChannelFile`
"""
return ChannelFile(*([self] + list(params)))
@ -845,7 +845,7 @@ class Channel (object):
server, it only makes sense to open this file for writing.
:return: object which can be used for python file I/O.
:rtype: :class:`.ChannelFile`
:rtype: `.ChannelFile`
.. versionadded:: 1.1
"""
@ -1227,11 +1227,11 @@ class Channel (object):
class ChannelFile (BufferedFile):
"""
A file-like wrapper around :class:`.Channel`. A ChannelFile is created by calling
:class:`Channel.makefile`.
A file-like wrapper around `.Channel`. A ChannelFile is created by calling
`Channel.makefile`.
@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
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):
"""
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::
client = SSHClient()
@ -103,7 +103,7 @@ class SSHClient (object):
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`,
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.
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):
"""
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.
:return: the local host keys
:rtype: :class:`.HostKeys`
:rtype: `.HostKeys`
"""
return self._host_keys
@ -164,13 +164,13 @@ class SSHClient (object):
def set_missing_host_key_policy(self, policy):
"""
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
default policy is to reject all unknown servers (using :class:`.RejectPolicy`).
You may substitute :class:`.AutoAddPolicy` or write your own policy class.
host key in either the system or local `.HostKeys` objects. The
default policy is to reject all unknown servers (using `.RejectPolicy`).
You may substitute `.AutoAddPolicy` or write your own policy class.
:param policy: the policy to use when receiving a host key from a
previously-unknown server
:type policy: :class:`.MissingHostKeyPolicy`
:type policy: `.MissingHostKeyPolicy`
"""
self._policy = policy
@ -183,7 +183,7 @@ class SSHClient (object):
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 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:
@ -206,7 +206,7 @@ class SSHClient (object):
a private key
:type password: str
: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
private key(s) to try for authentication
:type key_filename: str or list(str)
@ -220,7 +220,7 @@ class SSHClient (object):
:param compress: set to True to turn on compression
:type compress: bool
: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
:raises BadHostKeyException: if the server's host key could not be
@ -286,7 +286,7 @@ class SSHClient (object):
def close(self):
"""
Close this SSHClient and its underlying :class:`.Transport`.
Close this SSHClient and its underlying `.Transport`.
"""
if self._transport is None:
return
@ -299,7 +299,7 @@ class SSHClient (object):
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
streams are returned as python ``file``-like objects representing
stdin, stdout, and stderr.
@ -308,10 +308,10 @@ class SSHClient (object):
:type command: str
:param bufsize: interpreted the same way as by the built-in ``file()`` function in python
: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
: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
"""
@ -328,7 +328,7 @@ class SSHClient (object):
def invoke_shell(self, term='vt100', width=80, height=24, width_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
terminal type and size.
@ -343,7 +343,7 @@ class SSHClient (object):
:param height_pixels: the height (in pixels) of the terminal window
:type height_pixels: int
:return: a new channel connected to the remote shell
:rtype: :class:`.Channel`
:rtype: `.Channel`
: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.
:return: a new SFTP session object
:rtype: :class:`.SFTPClient`
:rtype: `.SFTPClient`
"""
return self._transport.open_sftp_client()
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
kinds of channels.
:return: the Transport for this connection
:rtype: :class:`.Transport`
:rtype: `.Transport`
"""
return self._transport
@ -482,19 +482,19 @@ class SSHClient (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
application's keys. Pre-made classes implement policies for automatically
adding the key to the application's :class:`.HostKeys` object (:class:`.AutoAddPolicy`),
and for automatically rejecting the key (:class:`.RejectPolicy`).
adding the key to the application's `.HostKeys` object (`.AutoAddPolicy`),
and for automatically rejecting the key (`.RejectPolicy`).
This function may be used to ask the user to verify the key, for example.
"""
def missing_host_key(self, client, hostname, key):
"""
Called when an :class:`.SSHClient` receives a server key for a server that
isn't in either the system or local :class:`.HostKeys` object. To accept
Called when an `.SSHClient` receives a server key for a server that
isn't in either the system or local `.HostKeys` object. To accept
the key, simply return. To reject, raised an exception (which will
be passed to the calling application).
"""
@ -504,7 +504,7 @@ class MissingHostKeyPolicy (object):
class AutoAddPolicy (MissingHostKeyPolicy):
"""
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):
@ -518,7 +518,7 @@ class AutoAddPolicy (MissingHostKeyPolicy):
class RejectPolicy (MissingHostKeyPolicy):
"""
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):
@ -530,7 +530,7 @@ class RejectPolicy (MissingHostKeyPolicy):
class WarningPolicy (MissingHostKeyPolicy):
"""
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):
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.
"""
:class:`.SSHConfig`.
`.SSHConfig`.
"""
import fnmatch

4
paramiko/dsskey.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
"""
:class:`.DSSKey`
`.DSSKey`
"""
from Crypto.PublicKey import DSA
@ -159,7 +159,7 @@ class DSSKey (PKey):
key generation (used by ``pyCrypto.PublicKey``).
:type progress_func: function
:return: new private key
:rtype: :class:`.DSSKey`
:rtype: `.DSSKey`
"""
dsa = DSA.generate(bits, rng.read, progress_func)
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):
"""
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
`next` and `readline`.

8
paramiko/hostkeys.py
View File

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

2
paramiko/kex_gex.py
View File

@ -17,7 +17,7 @@
# 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
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
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 msg: :class:`.Message`
:type msg: `.Message`
:param data: an optional string containing a public key of this type
:type data: str
@ -65,7 +65,7 @@ class PKey (object):
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
re-create the key object later.
@ -82,7 +82,7 @@ class PKey (object):
corresponding private key.
:param other: key to compare to.
:type other: :class:`.PKey`
:type other: `.PKey`
:return: 0 if the two keys are equivalent, non-0 otherwise.
:rtype: int
"""
@ -146,15 +146,15 @@ class PKey (object):
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.
: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.
:type data: str
:return: an SSH signature message.
:rtype: :class:`.Message`
:rtype: `.Message`
"""
return ''
@ -166,7 +166,7 @@ class PKey (object):
:param data: the data that was signed.
:type data: str
:param msg: an SSH signature message
:type msg: :class:`.Message`
:type msg: `.Message`
:return: ``True`` if the signature verifies correctly; ``False``
otherwise.
:rtype: boolean
@ -177,9 +177,9 @@ class PKey (object):
"""
Create a key object by reading a private key file. If the private
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
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.
:param filename: name of the file to read
@ -188,7 +188,7 @@ class PKey (object):
if it's encrypted
:type password: str
: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 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)
object. If the private key is encrypted and ``password`` is not ``None``,
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
:type file_obj: file
@ -212,7 +212,7 @@ class PKey (object):
encrypted
:type password: str
: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 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
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
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.
:type tag: str

6
paramiko/proxy.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
"""
:class:`.ProxyCommand`.
`.ProxyCommand`.
"""
import os
@ -33,14 +33,14 @@ class ProxyCommand(object):
Wraps a subprocess running ProxyCommand-driven programs.
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
proxy traffic between the client and a server hosted in another machine.
"""
def __init__(self, command_line):
"""
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
used as the proxy.

4
paramiko/rsakey.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
"""
:class:`.RSAKey`
`.RSAKey`
"""
from Crypto.PublicKey import RSA
@ -135,7 +135,7 @@ class RSAKey (PKey):
key generation (used by ``pyCrypto.PublicKey``).
:type progress_func: function
:return: new private key
:rtype: :class:`.RSAKey`
:rtype: `.RSAKey`
"""
rsa = RSA.generate(bits, rng.read, progress_func)
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.
"""
:class:`.ServerInterface` is an interface to override for server support.
`.ServerInterface` is an interface to override for server support.
"""
import threading
@ -96,9 +96,9 @@ class ServerInterface (object):
- `check_channel_forward_agent_request`
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
: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.
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)
authentication.
Return :class:`.AUTH_FAILED` if the client must authenticate, or
:class:`.AUTH_SUCCESSFUL` if it's okay for the client to not
Return `.AUTH_FAILED` if the client must authenticate, or
`.AUTH_SUCCESSFUL` if it's okay for the client to not
authenticate.
The default implementation always returns :class:`.AUTH_FAILED`.
The default implementation always returns `.AUTH_FAILED`.
:param username: the username of the client.
:type username: str
:return: :class:`.AUTH_FAILED` if the authentication fails;
:class:`.AUTH_SUCCESSFUL` if it succeeds.
:return: `.AUTH_FAILED` if the authentication fails;
`.AUTH_SUCCESSFUL` if it succeeds.
:rtype: int
"""
return AUTH_FAILED
@ -165,23 +165,23 @@ class ServerInterface (object):
Determine if a given username and password supplied by the client is
acceptable for use in authentication.
Return :class:`.AUTH_FAILED` if the password is not accepted,
:class:`.AUTH_SUCCESSFUL` if the password is accepted and completes
the authentication, or :class:`.AUTH_PARTIALLY_SUCCESSFUL` if your
Return `.AUTH_FAILED` if the password is not accepted,
`.AUTH_SUCCESSFUL` if the password is accepted and completes
the authentication, or `.AUTH_PARTIALLY_SUCCESSFUL` if your
authentication is stateful, and this key is accepted for
authentication, but more authentication is required. (In this latter
case, `get_allowed_auths` will be called to report to the client what
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.
:type username: str
:param password: the password given by the client.
:type password: str
:return: :class:`.AUTH_FAILED` if the authentication fails;
:class:`.AUTH_SUCCESSFUL` if it succeeds;
:class:`.AUTH_PARTIALLY_SUCCESSFUL` if the password auth is
:return: `.AUTH_FAILED` if the authentication fails;
`.AUTH_SUCCESSFUL` if it succeeds;
`.AUTH_PARTIALLY_SUCCESSFUL` if the password auth is
successful, but authentication must continue.
:rtype: int
"""
@ -194,9 +194,9 @@ class ServerInterface (object):
check the username and key and decide if you would accept a signature
made using this key.
Return :class:`.AUTH_FAILED` if the key is not accepted,
:class:`.AUTH_SUCCESSFUL` if the key is accepted and completes the
authentication, or :class:`.AUTH_PARTIALLY_SUCCESSFUL` if your
Return `.AUTH_FAILED` if the key is not accepted,
`.AUTH_SUCCESSFUL` if the key is accepted and completes the
authentication, or `.AUTH_PARTIALLY_SUCCESSFUL` if your
authentication is stateful, and this password is accepted for
authentication, but more authentication is required. (In this latter
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
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
:type username: str
:param key: the key object provided by the client
:type key: :class:`PKey <pkey.PKey>`
:return: :class:`.AUTH_FAILED` if the client can't authenticate
with this key; :class:`.AUTH_SUCCESSFUL` if it can;
:class:`.AUTH_PARTIALLY_SUCCESSFUL` if it can authenticate with
:type key: `PKey <pkey.PKey>`
:return: `.AUTH_FAILED` if the client can't authenticate
with this key; `.AUTH_SUCCESSFUL` if it can;
`.AUTH_PARTIALLY_SUCCESSFUL` if it can authenticate with
this key but must continue with authentication
:rtype: int
"""
@ -227,21 +227,21 @@ class ServerInterface (object):
``"keyboard-interactive"`` auth type, which requires you to send a
series of questions for the client to answer.
Return :class:`.AUTH_FAILED` if this auth method isn't supported. Otherwise,
you should return an :class:`.InteractiveQuery` object containing the prompts
Return `.AUTH_FAILED` if this auth method isn't supported. Otherwise,
you should return an `.InteractiveQuery` object containing the prompts
and instructions for the user. The response will be sent via a call
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
:type username: str
:param submethods: a comma-separated list of methods preferred by the
client (usually empty)
: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
:rtype: int or :class:`.InteractiveQuery`
:rtype: int or `.InteractiveQuery`
"""
return AUTH_FAILED
@ -251,29 +251,29 @@ class ServerInterface (object):
supported. You should override this method in server mode if you want
to support the ``"keyboard-interactive"`` auth type.
Return :class:`.AUTH_FAILED` if the responses are not accepted,
:class:`.AUTH_SUCCESSFUL` if the responses are accepted and complete
the authentication, or :class:`.AUTH_PARTIALLY_SUCCESSFUL` if your
Return `.AUTH_FAILED` if the responses are not accepted,
`.AUTH_SUCCESSFUL` if the responses are accepted and complete
the authentication, or `.AUTH_PARTIALLY_SUCCESSFUL` if your
authentication is stateful, and this set of responses is accepted for
authentication, but more authentication is required. (In this latter
case, `get_allowed_auths` will be called to report to the client what
options it has for continuing the authentication.)
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
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
:type responses: list(str)
:return: :class:`.AUTH_FAILED` if the authentication fails;
:class:`.AUTH_SUCCESSFUL` if it succeeds;
:class:`.AUTH_PARTIALLY_SUCCESSFUL` if the interactive auth is
:return: `.AUTH_FAILED` if the authentication fails;
`.AUTH_SUCCESSFUL` if it succeeds;
`.AUTH_PARTIALLY_SUCCESSFUL` if the interactive auth is
successful, but authentication must continue; otherwise an object
containing queries for the user
:rtype: int or :class:`.InteractiveQuery`
:rtype: int or `.InteractiveQuery`
"""
return AUTH_FAILED
@ -338,7 +338,7 @@ class ServerInterface (object):
:param kind: the kind of global request being made.
:type kind: str
: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;
``False`` otherwise.
:rtype: bool
@ -357,8 +357,8 @@ class ServerInterface (object):
The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the pty request arrived on.
:type channel: :class:`.Channel`
:param channel: the `.Channel` the pty request arrived on.
:type channel: `.Channel`
:param term: type of terminal requested (for example, ``"vt100"``).
:type term: str
:param width: width of screen in characters.
@ -386,8 +386,8 @@ class ServerInterface (object):
The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the request arrived on.
:type channel: :class:`.Channel`
:param channel: the `.Channel` the request arrived on.
:type channel: `.Channel`
:return: ``True`` if this channel is now hooked up to a shell; ``False``
if a shell can't or won't be provided.
:rtype: bool
@ -402,8 +402,8 @@ class ServerInterface (object):
The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the request arrived on.
:type channel: :class:`.Channel`
:param channel: the `.Channel` the request arrived on.
:type channel: `.Channel`
:param command: the command to execute.
:type command: str
: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``.
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
``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
method.
:param channel: the :class:`.Channel` the pty request arrived on.
:type channel: :class:`.Channel`
:param channel: the `.Channel` the pty request arrived on.
:type channel: `.Channel`
:param name: name of the requested subsystem.
:type name: str
: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``.
:param channel: the :class:`.Channel` the pty request arrived on.
:type channel: :class:`.Channel`
:param channel: the `.Channel` the pty request arrived on.
:type channel: `.Channel`
:param width: width of screen in characters.
:type width: int
: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
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``.
:param channel: the :class:`.Channel` the X11 request arrived on
:type channel: :class:`.Channel`
:param channel: the `.Channel` the X11 request arrived on
:type channel: `.Channel`
:param single_connection: ``True`` if only a single X11 channel should
be opened
:type single_connection: bool
@ -502,8 +502,8 @@ class ServerInterface (object):
The default implementation always returns ``False``.
:param channel: the :class:`.Channel` the request arrived on
:type channel: :class:`.Channel`
:param channel: the `.Channel` the request arrived on
:type channel: `.Channel`
:return: ``True`` if the AgentForward was loaded; ``False`` if not
:rtype: bool
"""
@ -517,9 +517,9 @@ class ServerInterface (object):
authentication is complete.
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
: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.
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
class and pass it to
:class:`Transport.set_subsystem_handler`,
`Transport.set_subsystem_handler`,
an object of this
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`.
@ -569,19 +569,19 @@ class SubsystemHandler (threading.Thread):
"""
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
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__``
method here.
:param channel: the channel associated with this subsystem request.
:type channel: :class:`.Channel`
:type channel: `.Channel`
:param name: name of the requested subsystem.
:type name: str
:param server: the server object for the session that started this
subsystem
:type server: :class:`.ServerInterface`
:type server: `.ServerInterface`
"""
threading.Thread.__init__(self, target=self._run)
self.__channel = channel
@ -591,10 +591,10 @@ class SubsystemHandler (threading.Thread):
def get_server(self):
"""
Return the :class:`.ServerInterface` object associated with this channel and
Return the `.ServerInterface` object associated with this channel and
subsystem.
:rtype: :class:`.ServerInterface`
:rtype: `.ServerInterface`
"""
return self.__server
@ -620,21 +620,21 @@ class SubsystemHandler (threading.Thread):
returns, the channel is closed.
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
underlying :class:`.Transport` is closed. This can be done by checking
:class:`Transport.is_active` or noticing an EOF
on the :class:`.Channel`. If this method loops forever without checking
underlying `.Transport` is closed. This can be done by checking
`Transport.is_active` or noticing an EOF
on the `.Channel`. If this method loops forever without checking
for this case, your python interpreter may refuse to exit because
this thread will still be running.
:param name: name of the requested subsystem.
:type name: str
:param transport: the server-mode :class:`.Transport`.
:type transport: :class:`.Transport`
:param transport: the server-mode `.Transport`.
:type transport: `.Transport`
:param channel: the channel associated with this subsystem request.
:type channel: :class:`.Channel`
:type channel: `.Channel`
"""
pass

4
paramiko/sftp_attr.py
View File

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

32
paramiko/sftp_client.py
View File

@ -52,19 +52,19 @@ def _to_unicode(s):
class SFTPClient (BaseSFTP):
"""
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):
"""
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.
An alternate way to create an SFTP client context is by using
`from_transport`.
:param sock: an open :class:`.Channel` using the ``"sftp"`` subsystem
:type sock: :class:`.Channel`
:param sock: an open `.Channel` using the ``"sftp"`` subsystem
:type sock: `.Channel`
:raises SSHException: if there's an exception while negotiating
sftp
@ -91,13 +91,13 @@ class SFTPClient (BaseSFTP):
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
:type t: :class:`.Transport`
:return: a new :class:`.SFTPClient` object, referring to an sftp session
:param t: an open `.Transport` which is already authenticated
:type t: `.Transport`
:return: a new `.SFTPClient` object, referring to an sftp session
(channel) across the transport
:rtype: :class:`.SFTPClient`
:rtype: `.SFTPClient`
"""
chan = t.open_session()
if chan is None:
@ -124,11 +124,11 @@ class SFTPClient (BaseSFTP):
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.
:return: the SSH channel
:rtype: :class:`.Channel`
:rtype: `.Channel`
.. versionadded:: 1.7.1
"""
@ -140,7 +140,7 @@ class SFTPClient (BaseSFTP):
The list is in arbitrary order. It does not include the special
entries ``'.'`` and ``'..'`` even if they are present in the folder.
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 ``'.'``)
:type path: str
@ -151,12 +151,12 @@ class SFTPClient (BaseSFTP):
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
not include the special entries ``'.'`` and ``'..'`` even if they are
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
attributes, in unix format. The content of this string will probably
depend on the SFTP server implementation.
@ -164,7 +164,7 @@ class SFTPClient (BaseSFTP):
:param path: path to list (defaults to ``'.'``)
:type path: str
:return: list of attributes
:rtype: list of :class:`.SFTPAttributes`
:rtype: list of `.SFTPAttributes`
.. versionadded:: 1.2
"""
@ -783,5 +783,5 @@ class SFTPClient (BaseSFTP):
class SFTP (SFTPClient):
"an alias for :class:`.SFTPClient` for backwards compatability"
"an alias for `.SFTPClient` for backwards compatability"
pass

16
paramiko/sftp_file.py
View File

@ -17,7 +17,7 @@
# 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
"""
:class:`.SFTPFile`
`.SFTPFile`
"""
from __future__ import with_statement
@ -181,9 +181,9 @@ class SFTPFile (BufferedFile):
def settimeout(self, timeout):
"""
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
before raising ``socket.timeout``, or ``None`` for no timeout
:type timeout: float
@ -193,9 +193,9 @@ class SFTPFile (BufferedFile):
def gettimeout(self):
"""
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
"""
return self.sftp.sock.gettimeout()
@ -203,9 +203,9 @@ class SFTPFile (BufferedFile):
def setblocking(self, blocking):
"""
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
mode.
:type blocking: int
@ -226,7 +226,7 @@ class SFTPFile (BufferedFile):
def stat(self):
"""
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.
: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
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
"""
self.__flags = flags
@ -76,7 +76,7 @@ class SFTPHandle (object):
to be 64 bits.
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
``readfile``, and if present, performs the read operation on the python
@ -124,7 +124,7 @@ class SFTPHandle (object):
:type offset: int or long
:param data: data to write into the file.
: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)
if writefile is None:
@ -148,13 +148,13 @@ class SFTPHandle (object):
def stat(self):
"""
Return an :class:`.SFTPAttributes` object referring to this open file, or an
error code. This is equivalent to :class:`SFTPServerInterface.stat`, except
Return an `.SFTPAttributes` object referring to this open file, or an
error code. This is equivalent to `SFTPServerInterface.stat`, except
it's called on an open file instead of a path.
:return: an attributes object for the given file, or an SFTP error
code (like :class:`.SFTP_PERMISSION_DENIED`).
:rtype: :class:`.SFTPAttributes` or error code
code (like `.SFTP_PERMISSION_DENIED`).
:rtype: `.SFTPAttributes` or error code
"""
return SFTP_OP_UNSUPPORTED
@ -165,8 +165,8 @@ class SFTPHandle (object):
check for the presence of fields before using them.
:param attr: the attributes to change on this file.
:type attr: :class:`.SFTPAttributes`
:return: an error code like :class:`.SFTP_OK`.
:type attr: `.SFTPAttributes`
:return: an error code like `.SFTP_OK`.
:rtype: int
"""
return SFTP_OP_UNSUPPORTED

20
paramiko/sftp_server.py
View File

@ -40,26 +40,26 @@ _hash_class = {
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.
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):
"""
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
:class:`Transport.set_subsystem_handler`.
`Transport.set_subsystem_handler`.
:param channel: channel passed from the :class:`.Transport`.
:type channel: :class:`.Channel`
:param channel: channel passed from the `.Transport`.
:type channel: `.Channel`
:param name: name of the requested subsystem.
:type name: str
:param server: the server object associated with this channel and
subsystem
:type server: :class:`.ServerInterface`
:param sftp_si: a subclass of :class:`.SFTPServerInterface` to use for handling
:type server: `.ServerInterface`
:param sftp_si: a subclass of `.SFTPServerInterface` to use for handling
individual requests.
:type sftp_si: class
"""
@ -128,7 +128,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
:param e: an errno code, as from ``OSError.errno``.
: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
"""
if e == errno.EACCES:
@ -155,7 +155,7 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
absolute path).
:type filename: str
:param attr: attributes to change.
:type attr: :class:`.SFTPAttributes`
:type attr: `.SFTPAttributes`
"""
if sys.platform != '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.
"""
:class:`.SFTPServerInterface` is an interface to override for SFTP server support.
`.SFTPServerInterface` is an interface to override for SFTP server support.
"""
import os
@ -29,7 +29,7 @@ from paramiko.sftp import *
class SFTPServerInterface (object):
"""
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
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
SFTP subsystem
:type server: :class:`.ServerInterface`
:type server: `.ServerInterface`
"""
super(SFTPServerInterface, self).__init__(*largs, **kwargs)
@ -72,10 +72,10 @@ class SFTPServerInterface (object):
def open(self, path, flags, attr):
"""
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
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,
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.
:type flags: int
:param attr: requested attributes of the file if it is newly created.
:type attr: :class:`.SFTPAttributes`
:return: a new :class:`.SFTPHandle` or error code.
:rtype :class:`.SFTPHandle`
:type attr: `.SFTPAttributes`
:return: a new `.SFTPHandle` or error code.
:rtype `.SFTPHandle`
"""
return SFTP_OP_UNSUPPORTED
@ -115,21 +115,21 @@ class SFTPServerInterface (object):
posix notation (``"/"`` separates folder names) and may be an absolute
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
``os.stat``. In addition, each object should have its ``filename``
field filled in, since this is important to a directory listing and
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
codes, such as :class:`.SFTP_PERMISSION_DENIED`.
codes, such as `.SFTP_PERMISSION_DENIED`.
:param path: the requested path (relative or absolute) to be listed.
:type path: str
:return: a list of the files in the given folder, using
:class:`.SFTPAttributes` objects.
:rtype: list of :class:`.SFTPAttributes` or error code
`.SFTPAttributes` objects.
:rtype: list of `.SFTPAttributes` or error code
.. note:: You should normalize the given ``path`` first (see the
``os.path`` module) and check appropriate permissions before returning
@ -141,7 +141,7 @@ class SFTPServerInterface (object):
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
"aliases"), you should follow them. (`lstat` is the corresponding
call that doesn't follow symlinks/aliases.)
@ -150,14 +150,14 @@ class SFTPServerInterface (object):
file statistics for.
:type path: str
:return: an attributes object for the given file, or an SFTP error
code (like :class:`.SFTP_PERMISSION_DENIED`).
:rtype: :class:`.SFTPAttributes` or error code
code (like `.SFTP_PERMISSION_DENIED`).
:rtype: `.SFTPAttributes` or error code
"""
return SFTP_OP_UNSUPPORTED
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
"aliases"), you should not follow them -- instead, you should
return data on the symlink or alias itself. (`stat` is the
@ -167,8 +167,8 @@ class SFTPServerInterface (object):
file statistics for.
:type path: str
:return: an attributes object for the given file, or an SFTP error
code (like :class:`.SFTP_PERMISSION_DENIED`).
:rtype: :class:`.SFTPAttributes` or error code
code (like `.SFTP_PERMISSION_DENIED`).
:rtype: `.SFTPAttributes` or error code
"""
return SFTP_OP_UNSUPPORTED
@ -179,7 +179,7 @@ class SFTPServerInterface (object):
:param path: the requested path (relative or absolute) of the file
to delete.
:type path: str
:return: an SFTP error code like :class:`.SFTP_OK`.
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
"""
return SFTP_OP_UNSUPPORTED
@ -201,7 +201,7 @@ class SFTPServerInterface (object):
:type oldpath: str
:param newpath: the requested new path of the file.
:type newpath: str
:return: an SFTP error code like :class:`.SFTP_OK`.
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
"""
return SFTP_OP_UNSUPPORTED
@ -220,8 +220,8 @@ class SFTPServerInterface (object):
folder.
:type path: str
:param attr: requested attributes of the new folder.
:type attr: :class:`.SFTPAttributes`
:return: an SFTP error code like :class:`.SFTP_OK`.
:type attr: `.SFTPAttributes`
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
"""
return SFTP_OP_UNSUPPORTED
@ -235,7 +235,7 @@ class SFTPServerInterface (object):
:param path: requested path (relative or absolute) of the folder
to remove.
:type path: str
:return: an SFTP error code like :class:`.SFTP_OK`.
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
"""
return SFTP_OP_UNSUPPORTED
@ -250,8 +250,8 @@ class SFTPServerInterface (object):
change.
:type path: str
:param attr: requested attributes to change on the file.
:type attr: :class:`.SFTPAttributes`
:return: an error code like :class:`.SFTP_OK`.
:type attr: `.SFTPAttributes`
:return: an error code like `.SFTP_OK`.
:rtype: int
"""
return SFTP_OP_UNSUPPORTED
@ -288,7 +288,7 @@ class SFTPServerInterface (object):
:param path: path (relative or absolute) of the symbolic link.
:type path: str
: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
"""
return SFTP_OP_UNSUPPORTED

6
paramiko/ssh_exception.py
View File

@ -82,7 +82,7 @@ class PartialAuthentication (AuthenticationException):
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
:type code: int
@ -101,9 +101,9 @@ class BadHostKeyException (SSHException):
:ivar hostname: the hostname of the SSH server
:type hostname: str
:ivar key: the host key presented by the server
:type key: :class:`.PKey`
:type key: `.PKey`
:ivar expected_key: the host key expected
:type expected_key: :class:`.PKey`
:type expected_key: `.PKey`
.. 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
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).
"""
@ -283,20 +283,20 @@ class Transport (threading.Thread):
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
preference for them.
:return: an object that can be used to change the preferred algorithms
for encryption, digest (hash), public key, and key exchange.
:rtype: :class:`.SecurityOptions`
:rtype: `.SecurityOptions`
"""
return SecurityOptions(self)
def start_client(self, event=None):
"""
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.
If an event is passed in, this method returns immediately. When
@ -308,8 +308,8 @@ class Transport (threading.Thread):
Otherwise an SSHException is raised.
After a successful negotiation, you will usually want to authenticate,
calling :class:`auth_password <Transport.auth_password>` or
:class:`auth_publickey <Transport.auth_publickey>`.
calling `auth_password <Transport.auth_password>` or
`auth_publickey <Transport.auth_publickey>`.
.. 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):
"""
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.
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.
Override the methods
:class:`get_allowed_auths <ServerInterface.get_allowed_auths>`,
:class:`check_auth_none <ServerInterface.check_auth_none>`,
:class:`check_auth_password <ServerInterface.check_auth_password>`, and
:class:`check_auth_publickey <ServerInterface.check_auth_publickey>` in the
`get_allowed_auths <ServerInterface.get_allowed_auths>`,
`check_auth_none <ServerInterface.check_auth_none>`,
`check_auth_password <ServerInterface.check_auth_password>`, and
`check_auth_publickey <ServerInterface.check_auth_publickey>` in the
given ``server`` object to control the authentication process.
After a successful authentication, the client should request to open
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.
.. 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.
:type event: threading.Event
:param server: an object used to perform authentication and create
:class:`channels <Channel>`
:type server: :class:`server.ServerInterface`
`channels <Channel>`
:type server: `server.ServerInterface`
:raises SSHException: if negotiation fails (and no ``event`` was passed
in)
@ -418,9 +418,9 @@ class Transport (threading.Thread):
key info, not just the public half. Only one key of each type (RSA or
DSS) is kept.
:param key: the host key to add, usually an :class:`RSAKey <rsakey.RSAKey>` or
:class:`DSSKey <dsskey.DSSKey>`.
:type key: :class:`PKey <pkey.PKey>`
:param key: the host key to add, usually an `RSAKey <rsakey.RSAKey>` or
`DSSKey <dsskey.DSSKey>`.
:type key: `PKey <pkey.PKey>`
"""
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.
:return: host key of the type negotiated by the client, or ``None``.
:rtype: :class:`PKey <pkey.PKey>`
:rtype: `PKey <pkey.PKey>`
"""
try:
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).
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.
:raises SSHException: if no session is currently active.
: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):
raise SSHException('No existing session')
@ -531,8 +531,8 @@ class Transport (threading.Thread):
Request a new channel to the server, of type ``"session"``. This
is just an alias for ``open_channel('session')``.
:return: a new :class:`.Channel`
:rtype: :class:`.Channel`
:return: a new `.Channel`
:rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends
prematurely
@ -547,8 +547,8 @@ class Transport (threading.Thread):
:param src_addr: the source address of the x11 server (port is the
x11 port, ie. 6010)
:type src_addr: (str, int)
:return: a new :class:`.Channel`
:rtype: :class:`.Channel`
:return: a new `.Channel`
:rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends
prematurely
@ -561,8 +561,8 @@ class Transport (threading.Thread):
``"auth-agent@openssh.com"``.
This is just an alias for ``open_channel('auth-agent@openssh.com')``.
:return: a new :class:`.Channel`
:rtype: :class:`.Channel`
:return: a new `.Channel`
:rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends
prematurely
@ -584,7 +584,7 @@ class Transport (threading.Thread):
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.
You may only request a channel after negotiating encryption (using
`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
``kind`` is ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``
:type src_addr: (str, int)
:return: a new :class:`.Channel` on success
:rtype: :class:`.Channel`
:return: a new `.Channel` on success
:rtype: `.Channel`
:raises SSHException: if the request is rejected or the session ends
prematurely
@ -717,9 +717,9 @@ class Transport (threading.Thread):
an SFTP session will be opened with the remote host, and a new
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
:rtype: :class:`.SFTPClient`
:rtype: `.SFTPClient`
"""
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
is received; ``False`` otherwise.
:type wait: bool
:return: a :class:`.Message` containing possible additional data if the
request was successful (or an empty :class:`.Message` if ``wait`` was
:return: a `.Message` containing possible additional data if the
request was successful (or an empty `.Message` if ``wait`` was
``False``); ``None`` if the request was denied.
:rtype: :class:`.Message`
:rtype: `.Message`
"""
if wait:
self.completion_event = threading.Event()
@ -828,7 +828,7 @@ class Transport (threading.Thread):
forever
:type timeout: int
:return: a new Channel opened by the client
:rtype: :class:`.Channel`
:rtype: `.Channel`
"""
self.lock.acquire()
try:
@ -850,14 +850,14 @@ class Transport (threading.Thread):
Negotiate an SSH2 session, and optionally verify the server's host key
and authenticate using a password or private key. This is a shortcut
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.
You can use this method immediately after creating a Transport to
negotiate encryption with a server. If it fails, an exception will be
thrown. On success, the method will return cleanly, and an encrypted
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.
.. 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
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.
:type username: str
:param password: a password to use for authentication, if you want to
@ -874,7 +874,7 @@ class Transport (threading.Thread):
:type password: str
:param pkey: a private key to use for authentication, if you want to
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
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
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.
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.
:type name: str
:param handler: subclass of :class:`.SubsystemHandler` that handles this
:param handler: subclass of `.SubsystemHandler` that handles this
subsystem.
:type handler: class
"""
@ -975,7 +975,7 @@ class Transport (threading.Thread):
Try to authenticate to the server using no authentication at all.
This will almost always fail. It may be useful for determining 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
:type username: string
@ -1101,7 +1101,7 @@ class Transport (threading.Thread):
:param username: the username to authenticate as
:type username: string
: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
complete (whether it was successful or not)
:type event: threading.Event
@ -2041,7 +2041,7 @@ class SecurityOptions (object):
exchange algorithms, listed in order of preference.
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,
``ValueError`` will be raised. If you try to assign something besides a
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
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``).
:type hashclass: :class:`Crypto.Hash`
:type hashclass: `Crypto.Hash`
:param salt: data to salt the hash with.
:type salt: string
:param key: human-entered password or passphrase.
@ -185,26 +185,26 @@ def generate_key_bytes(hashclass, salt, key, nbytes):
def load_host_keys(filename):
"""
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
``"ssh-rsa"`` or ``"ssh-dss"``.
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")``.
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
:type filename: str
: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
return HostKeys(filename)
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.parse(file_obj)
@ -212,7 +212,7 @@ def parse_ssh_config(file_obj):
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)