From 3f9270c0be18b09cd39279730eac125776adbedc Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 11:11:10 -0800 Subject: [PATCH] Mass SnR of class refs with dotted ones. Boo on Sphinx for not letting me just change this behavior by default. There are a handful of incorrect items here that will get tweaked later. --- paramiko/__init__.py | 4 +- paramiko/agent.py | 6 +- paramiko/auth_handler.py | 2 +- paramiko/buffered_pipe.py | 4 +- paramiko/channel.py | 26 ++++---- paramiko/client.py | 54 ++++++++-------- paramiko/config.py | 2 +- paramiko/dsskey.py | 4 +- paramiko/file.py | 2 +- paramiko/hostkeys.py | 8 +-- paramiko/pkey.py | 26 ++++---- paramiko/proxy.py | 6 +- paramiko/rsakey.py | 4 +- paramiko/server.py | 130 +++++++++++++++++++------------------- paramiko/sftp_attr.py | 4 +- paramiko/sftp_client.py | 32 +++++----- paramiko/sftp_file.py | 8 +-- paramiko/sftp_handle.py | 14 ++-- paramiko/sftp_server.py | 16 ++--- paramiko/sftp_si.py | 52 +++++++-------- paramiko/ssh_exception.py | 6 +- paramiko/transport.py | 50 +++++++-------- paramiko/util.py | 6 +- 23 files changed, 233 insertions(+), 233 deletions(-) diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 4bf0c7e..1f7f6bc 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -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 :class:`.SSHClient` object. For more direct control, pass a socket (or socket-like object) to a -:class:`Transport`, and use :class:`start_server ` or +:class:`.Transport`, and use :class:`start_server ` or :class:`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 diff --git a/paramiko/agent.py b/paramiko/agent.py index a09851b..a5413f7 100644 --- a/paramiko/agent.py +++ b/paramiko/agent.py @@ -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 :class:`.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 :class:`.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 :class:`.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 diff --git a/paramiko/auth_handler.py b/paramiko/auth_handler.py index 56bd37d..2f73e5a 100644 --- a/paramiko/auth_handler.py +++ b/paramiko/auth_handler.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`AuthHandler` +:class:`.AuthHandler` """ import threading diff --git a/paramiko/buffered_pipe.py b/paramiko/buffered_pipe.py index 23ed9f4..c400bb4 100644 --- a/paramiko/buffered_pipe.py +++ b/paramiko/buffered_pipe.py @@ -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 :class:`.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`. + :class:`.Channel`. """ def __init__(self): diff --git a/paramiko/channel.py b/paramiko/channel.py index 7a43043..5cfa905 100644 --- a/paramiko/channel.py +++ b/paramiko/channel.py @@ -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 :class:`.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 :class:`.Transport` until the Transport attaches it. Normally you would only call this method from the constructor of a - subclass of :class:`Channel`. + subclass of :class:`.Channel`. :param chanid: the ID of this channel, as passed by an existing - :class:`Transport`. + :class:`.Transport`. :type chanid: int """ self.chanid = chanid @@ -416,10 +416,10 @@ class Channel (object): def get_transport(self): """ - Return the :class:`Transport` associated with this channel. + Return the :class:`.Transport` associated with this channel. - :return: the :class:`Transport` that was used to create this channel. - :rtype: :class:`Transport` + :return: the :class:`.Transport` that was used to create this channel. + :rtype: :class:`.Transport` """ return self.transport @@ -446,7 +446,7 @@ 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 + a :class:`.Transport` and usually a small number. It's also the number passed to :class:`ServerInterface.check_channel_request` when determining whether to accept a channel request in server mode. @@ -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 :class:`.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: :class:`.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: :class:`.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 + A file-like wrapper around :class:`.Channel`. A ChannelFile is created by calling :class:`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 :class:`.Channel` and its ``ChannelFile`` should be able to be closed or garbage-collected independently. Currently, closing the ``ChannelFile`` does nothing but flush the buffer. """ diff --git a/paramiko/client.py b/paramiko/client.py index c7f9cfc..0ebc4df 100644 --- a/paramiko/client.py +++ b/paramiko/client.py @@ -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 :class:`.Transport`, :class:`.Channel`, and :class:`.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 :class:`load_system_host_keys`, but will be saved back by :class:`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 :class:`.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 :class:`.HostKeys` object. This can be used to examine the local host keys or change them. :return: the local host keys - :rtype: :class:`HostKeys` + :rtype: :class:`.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 :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. :param policy: the policy to use when receiving a host key from a previously-unknown server - :type policy: :class:`MissingHostKeyPolicy` + :type policy: :class:`.MissingHostKeyPolicy` """ self._policy = policy @@ -183,7 +183,7 @@ class SSHClient (object): and any local host keys (:class:`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 :class:`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 :class:`.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: :class:`.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 + :class:`.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 :class:`.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 :class:`.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. @@ -311,7 +311,7 @@ class SSHClient (object): :param timeout: set command's channel timeout. See :class:`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(:class:`.ChannelFile`, :class:`.ChannelFile`, :class:`.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 :class:`.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: :class:`.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: :class:`.SFTPClient` """ return self._transport.open_sftp_client() def get_transport(self): """ - Return the underlying :class:`Transport` object for this SSH connection. + Return the underlying :class:`.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: :class:`.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 :class:`.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 :class:`.HostKeys` object (:class:`.AutoAddPolicy`), + and for automatically rejecting the key (:class:`.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 :class:`.SSHClient` receives a server key for a server that + isn't in either the system or local :class:`.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 :class:`.HostKeys` object, and saving it. This is used by :class:`.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 :class:`.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 :class:`.SSHClient`. """ def missing_host_key(self, client, hostname, key): warnings.warn('Unknown %s host key for %s: %s' % diff --git a/paramiko/config.py b/paramiko/config.py index 05f5981..583c7e8 100644 --- a/paramiko/config.py +++ b/paramiko/config.py @@ -18,7 +18,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`SSHConfig`. +:class:`.SSHConfig`. """ import fnmatch diff --git a/paramiko/dsskey.py b/paramiko/dsskey.py index 2d9f6ce..9581ec8 100644 --- a/paramiko/dsskey.py +++ b/paramiko/dsskey.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`DSSKey` +:class:`.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: :class:`.DSSKey` """ dsa = DSA.generate(bits, rng.read, progress_func) key = DSSKey(vals=(dsa.p, dsa.q, dsa.g, dsa.y)) diff --git a/paramiko/file.py b/paramiko/file.py index 58d9f8b..334cff4 100644 --- a/paramiko/file.py +++ b/paramiko/file.py @@ -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 :class:`.StopIteration` when EOF is hit. Unlike python file objects, it's okay to mix calls to ``next`` and :class:`readline`. diff --git a/paramiko/hostkeys.py b/paramiko/hostkeys.py index 2767fb4..704fe7e 100644 --- a/paramiko/hostkeys.py +++ b/paramiko/hostkeys.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`HostKeys` +:class:`.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: :class:`.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, :class:`.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: :class:`.PKey` :return: ``True`` if the key is associated with the hostname; ``False`` if not :rtype: bool diff --git a/paramiko/pkey.py b/paramiko/pkey.py index bfe7b11..a12fc51 100644 --- a/paramiko/pkey.py +++ b/paramiko/pkey.py @@ -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 :class:`.Message` containing a public key of this type. - :type msg: :class:`Message` + :type msg: :class:`.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 :class:`.Message` made up of the public part(s) of this key. This string is suitable for passing to :class:`__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: :class:`.PKey` :return: 0 if the two keys are equivalent, non-0 otherwise. :rtype: int """ @@ -146,7 +146,7 @@ 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 :class:`.Message` representing an SSH signature message. :param rng: a secure random number generator. @@ -154,7 +154,7 @@ class PKey (object): :param data: the data to sign. :type data: str :return: an SSH signature message. - :rtype: :class:`Message` + :rtype: :class:`.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: :class:`.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 :class:`.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 :class:`.RSAKey` or :class:`.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: :class:`.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). + :class:`.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: :class:`.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 :class:`.PasswordRequiredException` is thrown). :param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block. :type tag: str diff --git a/paramiko/proxy.py b/paramiko/proxy.py index 08abe9a..85c73a6 100644 --- a/paramiko/proxy.py +++ b/paramiko/proxy.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`ProxyCommand`. +:class:`.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 + :class:`.Transport` and :class:`.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 :class:`.Transport` class. :param command_line: the command that should be executed and used as the proxy. diff --git a/paramiko/rsakey.py b/paramiko/rsakey.py index 46c37d6..8e9774f 100644 --- a/paramiko/rsakey.py +++ b/paramiko/rsakey.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`RSAKey` +:class:`.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: :class:`.RSAKey` """ rsa = RSA.generate(bits, rng.read, progress_func) key = RSAKey(vals=(rsa.e, rsa.n)) diff --git a/paramiko/server.py b/paramiko/server.py index 380831e..14f8976 100644 --- a/paramiko/server.py +++ b/paramiko/server.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`ServerInterface` is an interface to override for server support. +:class:`.ServerInterface` is an interface to override for server support. """ import threading @@ -96,9 +96,9 @@ class ServerInterface (object): - :class:`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 :class:`.Transport`. A :class:`.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 + :class:`.Channel` object is created, you can call :class:`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 :class:`.AUTH_FAILED` if the client must authenticate, or + :class:`.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 :class:`.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: :class:`.AUTH_FAILED` if the authentication fails; + :class:`.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 :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 authentication is stateful, and this key is accepted for authentication, but more authentication is required. (In this latter case, :class:`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 :class:`.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: :class:`.AUTH_FAILED` if the authentication fails; + :class:`.AUTH_SUCCESSFUL` if it succeeds; + :class:`.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 :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 authentication is stateful, and this password is accepted for authentication, but more authentication is required. (In this latter case, :class:`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 :class:`.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 ` - :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 + :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 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 :class:`.AUTH_FAILED` if this auth method isn't supported. Otherwise, + you should return an :class:`.InteractiveQuery` object containing the prompts and instructions for the user. The response will be sent via a call to :class:`check_auth_interactive_response`. - The default implementation always returns :class:`AUTH_FAILED`. + The default implementation always returns :class:`.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: :class:`.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 :class:`.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 :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 authentication is stateful, and this set of responses is accepted for authentication, but more authentication is required. (In this latter case, :class:`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 :class:`.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 :class:`.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: :class:`.AUTH_FAILED` if the authentication fails; + :class:`.AUTH_SUCCESSFUL` if it succeeds; + :class:`.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 :class:`.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: :class:`.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 :class:`.Channel` the pty request arrived on. + :type channel: :class:`.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 :class:`.Channel` the request arrived on. + :type channel: :class:`.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 :class:`.Channel` the request arrived on. + :type channel: :class:`.Channel` :param command: the command to execute. :type command: str :return: ``True`` if this channel is now hooked up to the stdin, @@ -427,12 +427,12 @@ class ServerInterface (object): 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 :class:`.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 :class:`.Channel` the pty request arrived on. + :type channel: :class:`.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 :class:`.Channel` the pty request arrived on. + :type channel: :class:`.Channel` :param width: width of screen in characters. :type width: int :param height: height of screen in characters. @@ -478,8 +478,8 @@ class ServerInterface (object): The default implementation always returns ``False``. - :param channel: the :class:`Channel` the X11 request arrived on - :type channel: :class:`Channel` + :param channel: the :class:`.Channel` the X11 request arrived on + :type channel: :class:`.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 :class:`.Channel` the request arrived on + :type channel: :class:`.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 :class:`.Transport`. A :class:`.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 + :class:`.Channel` object is created, you can call :class:`Channel.get_id` to retrieve the channel ID. The origin and destination parameters are (ip_address, port) tuples @@ -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 :class:`.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: :class:`.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: :class:`.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 :class:`.ServerInterface` object associated with this channel and subsystem. - :rtype: :class:`ServerInterface` + :rtype: :class:`.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 :class:`.Channel` on one :class:`.Transport`. .. note:: It is the responsibility of this method to exit if the - underlying :class:`Transport` is closed. This can be done by checking + 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 + on the :class:`.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 :class:`.Transport`. + :type transport: :class:`.Transport` :param channel: the channel associated with this subsystem request. - :type channel: :class:`Channel` + :type channel: :class:`.Channel` """ pass diff --git a/paramiko/sftp_attr.py b/paramiko/sftp_attr.py index 267bc3a..9eb66b5 100644 --- a/paramiko/sftp_attr.py +++ b/paramiko/sftp_attr.py @@ -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 :class:`.SFTPAttributes` object with the same attribute fields. + :rtype: :class:`.SFTPAttributes` """ attr = cls() attr.st_size = obj.st_size diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index ef64a9f..c30805a 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -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 :class:`.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 :class:`.Channel`. The channel should already have requested the ``"sftp"`` subsystem. An alternate way to create an SFTP client context is by using :class:`from_transport`. - :param sock: an open :class:`Channel` using the ``"sftp"`` subsystem - :type sock: :class:`Channel` + :param sock: an open :class:`.Channel` using the ``"sftp"`` subsystem + :type sock: :class:`.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 :class:`.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 :class:`.Transport` which is already authenticated + :type t: :class:`.Transport` + :return: a new :class:`.SFTPClient` object, referring to an sftp session (channel) across the transport - :rtype: :class:`SFTPClient` + :rtype: :class:`.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 :class:`.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: :class:`.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 :class:`listdir_attr`. + For a list of full :class:`.SFTPAttributes` objects, see :class:`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 :class:`.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 :class:`.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 :class:`.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 :class:`.SFTPClient` for backwards compatability" pass diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py index f895288..3ff0d68 100644 --- a/paramiko/sftp_file.py +++ b/paramiko/sftp_file.py @@ -17,7 +17,7 @@ # 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. """ -:class:`SFTPFile` +:class:`.SFTPFile` """ from __future__ import with_statement @@ -181,7 +181,7 @@ class SFTPFile (BufferedFile): def settimeout(self, timeout): """ Set a timeout on read/write operations on the underlying socket or - ssh :class:`Channel`. + ssh :class:`.Channel`. .. seealso:: :class:`Channel.settimeout` :param timeout: seconds to wait for a pending read/write operation @@ -193,7 +193,7 @@ 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 :class:`.Channel` used for this file. .. seealso:: :class:`Channel.gettimeout` :rtype: float @@ -203,7 +203,7 @@ class SFTPFile (BufferedFile): def setblocking(self, blocking): """ Set blocking or non-blocking mode on the underiying socket or ssh - :class:`Channel`. + :class:`.Channel`. .. seealso:: :class:`Channel.setblocking` :param blocking: 0 to set non-blocking mode; non-0 to set blocking diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py index c591b31..3b3c6b4 100644 --- a/paramiko/sftp_handle.py +++ b/paramiko/sftp_handle.py @@ -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 :class:`.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 :class:`.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 + Return an :class:`.SFTPAttributes` object referring to this open file, or an error code. This is equivalent to :class:`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 :class:`.SFTP_PERMISSION_DENIED`). + :rtype: :class:`.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: :class:`.SFTPAttributes` + :return: an error code like :class:`.SFTP_OK`. :rtype: int """ return SFTP_OP_UNSUPPORTED diff --git a/paramiko/sftp_server.py b/paramiko/sftp_server.py index 867acbc..89684c1 100644 --- a/paramiko/sftp_server.py +++ b/paramiko/sftp_server.py @@ -40,7 +40,7 @@ _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 :class:`.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. """ @@ -48,18 +48,18 @@ class SFTPServer (BaseSFTP, SubsystemHandler): 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 + :class:`.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`. - :param channel: channel passed from the :class:`Transport`. - :type channel: :class:`Channel` + :param channel: channel passed from the :class:`.Transport`. + :type channel: :class:`.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: :class:`.ServerInterface` + :param sftp_si: a subclass of :class:`.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 :class:`.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: :class:`.SFTPAttributes` """ if sys.platform != 'win32': # mode operations are meaningless on win32 diff --git a/paramiko/sftp_si.py b/paramiko/sftp_si.py index b203aea..d1b2497 100644 --- a/paramiko/sftp_si.py +++ b/paramiko/sftp_si.py @@ -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. +:class:`.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 :class:`.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: :class:`.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 :class:`.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. + :class:`.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: :class:`.SFTPAttributes` + :return: a new :class:`.SFTPHandle` or error code. + :rtype :class:`.SFTPHandle` """ return SFTP_OP_UNSUPPORTED @@ -115,7 +115,7 @@ 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 :class:`.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 @@ -123,13 +123,13 @@ class SFTPServerInterface (object): :class:`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 :class:`.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 + :class:`.SFTPAttributes` objects. + :rtype: list of :class:`.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 :class:`.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. (:class:`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 :class:`.SFTP_PERMISSION_DENIED`). + :rtype: :class:`.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 :class:`.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. (:class:`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 :class:`.SFTP_PERMISSION_DENIED`). + :rtype: :class:`.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 :class:`.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 :class:`.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: :class:`.SFTPAttributes` + :return: an SFTP error code like :class:`.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 :class:`.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: :class:`.SFTPAttributes` + :return: an error code like :class:`.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`. + :class:`.SFTP_NO_SUCH_FILE`. :rtype: str or error code """ return SFTP_OP_UNSUPPORTED diff --git a/paramiko/ssh_exception.py b/paramiko/ssh_exception.py index 5b9b490..5d9f43c 100644 --- a/paramiko/ssh_exception.py +++ b/paramiko/ssh_exception.py @@ -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 :class:`.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: :class:`.PKey` :ivar expected_key: the host key expected - :type expected_key: :class:`PKey` + :type expected_key: :class:`.PKey` .. versionadded:: 1.6 """ diff --git a/paramiko/transport.py b/paramiko/transport.py index 8be0ca3..201ae00 100644 --- a/paramiko/transport.py +++ b/paramiko/transport.py @@ -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 :class:`.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: :class:`.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 :class:`.Transport`. A separate thread is created for protocol negotiation. If an event is passed in, this method returns immediately. When @@ -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 :class:`.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 @@ -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 :class:`.Channel` + :rtype: :class:`.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 :class:`.Channel` + :rtype: :class:`.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 :class:`.Channel` + :rtype: :class:`.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 ` are socket-like + Request a new channel to the server. :class:`.Channels ` are socket-like objects used for the actual transfer of data across the session. You may only request a channel after negotiating encryption (using :class:`connect` or :class:`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 :class:`.Channel` on success + :rtype: :class:`.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 :class:`.SFTPClient` object, referring to an sftp session (channel) across this transport - :rtype: :class:`SFTPClient` + :rtype: :class:`.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 :class:`.Message` containing possible additional data if the + request was successful (or an empty :class:`.Message` if ``wait`` was ``False``); ``None`` if the request was denied. - :rtype: :class:`Message` + :rtype: :class:`.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: :class:`.Channel` """ self.lock.acquire() try: @@ -857,7 +857,7 @@ class Transport (threading.Thread): 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 :class:`open_channel` or - :class:`open_session` to get a :class:`Channel` object, which is used for data + :class:`open_session` to get a :class:`.Channel` object, which is used for data transfer. .. note:: If you fail to supply a password or private key, this method may @@ -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 :class:`.SubsystemHandler` for more detailed documentation. Any extra parameters (including keyword arguments) are saved and - passed to the :class:`SubsystemHandler` constructor later. + passed to the :class:`.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 :class:`.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. + :class:`.BadAuthenticationType` exception raised. :param username: the username to authenticate as :type username: string @@ -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). + :class:`.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. diff --git a/paramiko/util.py b/paramiko/util.py index a0f4b42..f295013 100644 --- a/paramiko/util.py +++ b/paramiko/util.py @@ -192,7 +192,7 @@ def load_host_keys(filename): 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 :class:`.HostKeys`. :param filename: name of the file to read host keys from :type filename: str @@ -204,7 +204,7 @@ def load_host_keys(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 :class:`.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 :class:`.SSHConfig`. """ return config.lookup(hostname)