From f09b562fa874d3358daa7dfd4ca7f2c8b5d47b68 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Feb 2014 12:15:29 -0800 Subject: [PATCH] Replace accidental class-refs on local method-refs --- paramiko/__init__.py | 4 +-- paramiko/agent.py | 2 +- paramiko/buffered_pipe.py | 4 +-- paramiko/channel.py | 72 +++++++++++++++++++-------------------- paramiko/client.py | 16 ++++----- paramiko/config.py | 2 +- paramiko/file.py | 12 +++---- paramiko/hostkeys.py | 4 +-- paramiko/message.py | 4 +-- paramiko/pkey.py | 2 +- paramiko/resource.py | 2 +- paramiko/server.py | 28 +++++++-------- paramiko/sftp_client.py | 14 ++++---- paramiko/sftp_file.py | 14 ++++---- paramiko/sftp_handle.py | 4 +-- paramiko/sftp_si.py | 4 +-- paramiko/transport.py | 40 +++++++++++----------- 17 files changed, 114 insertions(+), 114 deletions(-) diff --git a/paramiko/__init__.py b/paramiko/__init__.py index 1f7f6bc..b7a2efb 100644 --- a/paramiko/__init__.py +++ b/paramiko/__init__.py @@ -28,8 +28,8 @@ 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. For more direct control, pass a socket (or socket-like object) to a -:class:`.Transport`, and use :class:`start_server ` or -:class:`start_client ` to negoatite +:class:`.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 the server's host key. (Key signature and verification is done by paramiko, diff --git a/paramiko/agent.py b/paramiko/agent.py index a5413f7..45bb265 100644 --- a/paramiko/agent.py +++ b/paramiko/agent.py @@ -318,7 +318,7 @@ class Agent(AgentSSH): def __init__(self): """ Open a session with the local machine's SSH agent, if one is running. - If no agent is running, initialization will succeed, but :class:`get_keys` + If no agent is running, initialization will succeed, but `get_keys` will return an empty tuple. :raises SSHException: if an SSH agent is found, but speaks an diff --git a/paramiko/buffered_pipe.py b/paramiko/buffered_pipe.py index c400bb4..3a4b2be 100644 --- a/paramiko/buffered_pipe.py +++ b/paramiko/buffered_pipe.py @@ -86,7 +86,7 @@ class BufferedPipe (object): feeder. A ``False`` result does not mean that the feeder has closed; it means you may need to wait before more data arrives. - :return: ``True`` if a :class:`read` call would immediately return at least + :return: ``True`` if a `read` call would immediately return at least one byte; ``False`` otherwise. :rtype: bool """ @@ -173,7 +173,7 @@ class BufferedPipe (object): def close(self): """ - Close this pipe object. Future calls to :class:`read` after the buffer + Close this pipe object. Future calls to `read` after the buffer has been emptied will return immediately with an empty string. """ self._lock.acquire() diff --git a/paramiko/channel.py b/paramiko/channel.py index 5cfa905..b255c8a 100644 --- a/paramiko/channel.py +++ b/paramiko/channel.py @@ -51,7 +51,7 @@ class Channel (object): you any more data until you read some of it. (This won't affect other channels on the same transport -- all channels on a single transport are flow-controlled independently.) Similarly, if the server isn't reading - data you send, calls to :class:`send` may block, unless you set a timeout. This + data you send, calls to `send` may block, unless you set a timeout. This is exactly like a normal network socket, so it shouldn't be too surprising. """ @@ -127,9 +127,9 @@ class Channel (object): """ Request a pseudo-terminal from the server. This is usually used right after creating a client channel, to ask the server to provide some - basic terminal semantics for a shell invoked with :class:`invoke_shell`. + basic terminal semantics for a shell invoked with `invoke_shell`. It isn't necessary (or desirable) to call this method if you're going - to exectue a single command with :class:`exec_command`. + to exectue a single command with `exec_command`. :param term: the terminal type to emulate (for example, ``'vt100'``) :type term: str @@ -168,7 +168,7 @@ class Channel (object): allows it, the channel will then be directly connected to the stdin, stdout, and stderr of the shell. - Normally you would call :class:`get_pty` before this, in which case the + Normally you would call `get_pty` before this, in which case the shell will operate through the pty, and the channel will be connected to the stdin and stdout of the pty. @@ -247,7 +247,7 @@ class Channel (object): def resize_pty(self, width=80, height=24, width_pixels=0, height_pixels=0): """ Resize the pseudo-terminal. This can be used to change the width and - height of the terminal emulation created in a previous :class:`get_pty` call. + height of the terminal emulation created in a previous `get_pty` call. :param width: new width (in characters) of the terminal screen :type width: int @@ -278,10 +278,10 @@ class Channel (object): """ Return true if the remote process has exited and returned an exit status. You may use this to poll the process status if you don't - want to block in :class:`recv_exit_status`. Note that the server may not + want to block in `recv_exit_status`. Note that the server may not return an exit status in some cases (like bad servers). - :return: True if :class:`recv_exit_status` will return immediately + :return: True if `recv_exit_status` will return immediately :rtype: bool .. versionadded:: 1.7.3 """ @@ -290,7 +290,7 @@ class Channel (object): def recv_exit_status(self): """ Return the exit status from the process on the server. This is - mostly useful for retrieving the reults of an :class:`exec_command`. + mostly useful for retrieving the reults of an `exec_command`. If the command hasn't finished yet, this method will wait until it does, or until the channel is closed. If no exit status is provided by the server, -1 is returned. @@ -427,7 +427,7 @@ class Channel (object): """ Set a name for this channel. Currently it's only used to set the name of the channel in logfile entries. The name can be fetched with the - :class:`get_name` method. + `get_name` method. :param name: new channel name :type name: str @@ -436,7 +436,7 @@ class Channel (object): def get_name(self): """ - Get the name of this channel that was previously set by :class:`set_name`. + Get the name of this channel that was previously set by `set_name`. :return: the name of this channel. :rtype: str @@ -461,13 +461,13 @@ class Channel (object): The default is ``False``, but in some cases it may be convenient to have both streams combined. - If this is ``False``, and :class:`exec_command` is called (or ``invoke_shell`` - with no pty), output to stderr will not show up through the :class:`recv` - and :class:`recv_ready` calls. You will have to use :class:`recv_stderr` and - :class:`recv_stderr_ready` to get stderr output. + If this is ``False``, and `exec_command` is called (or ``invoke_shell`` + with no pty), output to stderr will not show up through the `recv` + and `recv_ready` calls. You will have to use `recv_stderr` and + `recv_stderr_ready` to get stderr output. - If this is ``True``, data will never show up via :class:`recv_stderr` or - :class:`recv_stderr_ready`. + If this is ``True``, data will never show up via `recv_stderr` or + `recv_stderr_ready`. :param combine: ``True`` if stderr output should be combined into stdout on this channel. @@ -517,7 +517,7 @@ class Channel (object): """ Returns the timeout in seconds (as a float) associated with socket operations, or ``None`` if no timeout is set. This reflects the last - call to :class:`setblocking` or :class:`settimeout`. + call to `setblocking` or `settimeout`. :return: timeout in seconds, or ``None``. :rtype: float @@ -530,10 +530,10 @@ class Channel (object): the channel is set to non-blocking mode; otherwise it's set to blocking mode. Initially all channels are in blocking mode. - In non-blocking mode, if a :class:`recv` call doesn't find any data, or if a - :class:`send` call can't immediately dispose of the data, an error exception + In non-blocking mode, if a `recv` call doesn't find any data, or if a + `send` call can't immediately dispose of the data, an error exception is raised. In blocking mode, the calls block until they can proceed. An - EOF condition is considered "immediate data" for :class:`recv`, so if the + EOF condition is considered "immediate data" for `recv`, so if the channel is closed in the read direction, it will never block. ``chan.setblocking(0)`` is equivalent to ``chan.settimeout(0)``; @@ -592,7 +592,7 @@ class Channel (object): channel. A ``False`` result does not mean that the channel has closed; it means you may need to wait before more data arrives. - :return: ``True`` if a :class:`recv` call on this channel would immediately + :return: ``True`` if a `recv` call on this channel would immediately return at least one byte; ``False`` otherwise. :rtype: boolean """ @@ -611,7 +611,7 @@ class Channel (object): :rtype: str :raises socket.timeout: if no data is ready before the timeout set by - :class:`settimeout`. + `settimeout`. """ try: out = self.in_buffer.read(nbytes, self.timeout) @@ -632,11 +632,11 @@ class Channel (object): def recv_stderr_ready(self): """ Returns true if data is buffered and ready to be read from this - channel's stderr stream. Only channels using :class:`exec_command` or - :class:`invoke_shell` without a pty will ever have data on the stderr + channel's stderr stream. Only channels using `exec_command` or + `invoke_shell` without a pty will ever have data on the stderr stream. - :return: ``True`` if a :class:`recv_stderr` call on this channel would + :return: ``True`` if a `recv_stderr` call on this channel would immediately return at least one byte; ``False`` otherwise. :rtype: boolean @@ -647,7 +647,7 @@ class Channel (object): def recv_stderr(self, nbytes): """ Receive data from the channel's stderr stream. Only channels using - :class:`exec_command` or :class:`invoke_shell` without a pty will ever have data + `exec_command` or `invoke_shell` without a pty will ever have data on the stderr stream. The return value is a string representing the data received. The maximum amount of data to be received at once is specified by ``nbytes``. If a string of length zero is returned, the @@ -659,7 +659,7 @@ class Channel (object): :rtype: str :raises socket.timeout: if no data is ready before the timeout set by - :class:`settimeout`. + `settimeout`. .. versionadded:: 1.1 """ @@ -685,10 +685,10 @@ class Channel (object): This means the channel is either closed (so any write attempt would return immediately) or there is at least one byte of space in the outbound buffer. If there is at least one byte of space in the - outbound buffer, a :class:`send` call will succeed immediately and return + outbound buffer, a `send` call will succeed immediately and return the number of bytes actually written. - :return: ``True`` if a :class:`send` call on this channel would immediately + :return: ``True`` if a `send` call on this channel would immediately succeed or fail :rtype: boolean """ @@ -714,7 +714,7 @@ class Channel (object): :rtype: int :raises socket.timeout: if no data could be sent before the timeout set - by :class:`settimeout`. + by `settimeout`. """ size = len(s) self.lock.acquire() @@ -749,7 +749,7 @@ class Channel (object): :rtype: int :raises socket.timeout: if no data could be sent before the timeout set - by :class:`settimeout`. + by `settimeout`. .. versionadded:: 1.1 """ @@ -775,14 +775,14 @@ class Channel (object): def sendall(self, s): """ Send data to the channel, without allowing partial results. Unlike - :class:`send`, this method continues to send data from the given string until + `send`, this method continues to send data from the given string until either all data has been sent or an error occurs. Nothing is returned. :param s: data to send. :type s: str :raises socket.timeout: if sending stalled for longer than the timeout - set by :class:`settimeout`. + set by `settimeout`. :raises socket.error: if an error occured before the entire string was sent. @@ -801,7 +801,7 @@ class Channel (object): def sendall_stderr(self, s): """ Send data to the channel's "stderr" stream, without allowing partial - results. Unlike :class:`send_stderr`, this method continues to send data + results. Unlike `send_stderr`, this method continues to send data from the given string until all data has been sent or an error occurs. Nothing is returned. @@ -809,7 +809,7 @@ class Channel (object): :type s: str :raises socket.timeout: if sending stalled for longer than the timeout - set by :class:`settimeout`. + set by `settimeout`. :raises socket.error: if an error occured before the entire string was sent. @@ -836,7 +836,7 @@ class Channel (object): def makefile_stderr(self, *params): """ Return a file-like object associated with this channel's stderr - stream. Only channels using :class:`exec_command` or :class:`invoke_shell` + stream. Only channels using `exec_command` or `invoke_shell` without a pty will ever have data on the stderr stream. The optional ``mode`` and ``bufsize`` arguments are interpreted the diff --git a/paramiko/client.py b/paramiko/client.py index 0ebc4df..6041e85 100644 --- a/paramiko/client.py +++ b/paramiko/client.py @@ -71,7 +71,7 @@ class SSHClient (object): def load_system_host_keys(self, filename=None): """ Load host keys from a system (read-only) file. Host keys read with - this method will not be saved back by :class:`save_host_keys`. + this method will not be saved back by `save_host_keys`. This method can be called multiple times. Each new set of host keys will be merged with the existing set (new replacing old if there are @@ -101,8 +101,8 @@ class SSHClient (object): def load_host_keys(self, filename): """ 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). + 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 saves them, when connecting to a previously-unknown server. @@ -121,8 +121,8 @@ class SSHClient (object): def save_host_keys(self, filename): """ Save the host keys back to a file. Only the host keys loaded with - :class:`load_host_keys` (plus any added directly) will be saved -- not any - host keys loaded with :class:`load_system_host_keys`. + `load_host_keys` (plus any added directly) will be saved -- not any + host keys loaded with `load_system_host_keys`. :param filename: the filename to save to :type filename: str @@ -179,10 +179,10 @@ class SSHClient (object): compress=False, sock=None): """ Connect to an SSH server and authenticate to it. The server's host key - is checked against the system host keys (see :class:`load_system_host_keys`) - and any local host keys (:class:`load_host_keys`). If the server's hostname + is checked against the system host keys (see `load_system_host_keys`) + 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 :class:`set_missing_host_key_policy`). The default policy is + is used (see `set_missing_host_key_policy`). The default policy is to reject the key and raise an :class:`.SSHException`. Authentication is attempted in the following order of priority: diff --git a/paramiko/config.py b/paramiko/config.py index 583c7e8..980a6cf 100644 --- a/paramiko/config.py +++ b/paramiko/config.py @@ -87,7 +87,7 @@ class LazyFqdn(object): class SSHConfig (object): """ Representation of config information as stored in the format used by - OpenSSH. Queries can be made via :class:`lookup`. The format is described in + OpenSSH. Queries can be made via `lookup`. The format is described in OpenSSH's ``ssh_config`` man page. This class is provided primarily as a convenience to posix users (since the OpenSSH format is a de-facto standard on posix) but should work fine on Windows too. diff --git a/paramiko/file.py b/paramiko/file.py index 334cff4..4f9b56b 100644 --- a/paramiko/file.py +++ b/paramiko/file.py @@ -96,7 +96,7 @@ class BufferedFile (object): """ 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`. + `next` and `readline`. :raises StopIteration: when the end of the file is reached. @@ -243,7 +243,7 @@ class BufferedFile (object): def readlines(self, sizehint=None): """ - Read all remaining lines using :class:`readline` and return them as a list. + Read all remaining lines using `readline` and return them as a list. If the optional ``sizehint`` argument is present, instead of reading up to EOF, whole lines totalling approximately sizehint bytes (possibly after rounding up to an internal buffer size) are read. @@ -300,7 +300,7 @@ class BufferedFile (object): """ Write data to the file. If write buffering is on (``bufsize`` was specified and non-zero), some or all of the data may not actually be - written yet. (Use :class:`flush` or :class:`close` to force buffered data to be + written yet. (Use `flush` or `close` to force buffered data to be written out.) :param data: data to write. @@ -334,7 +334,7 @@ class BufferedFile (object): """ Write a sequence of strings to the file. The sequence can be any iterable object producing strings, typically a list of strings. (The - name is intended to match :class:`readlines`; ``writelines`` does not add line + name is intended to match `readlines`; ``writelines`` does not add line separators.) :param sequence: an iterable sequence of strings. @@ -380,9 +380,9 @@ class BufferedFile (object): def _get_size(self): """ (subclass override) - Return the size of the file. This is called from within :class:`_set_mode` + Return the size of the file. This is called from within `_set_mode` if the file is opened in append mode, so the file position can be - tracked and :class:`seek` and :class:`tell` will work correctly. If the file is + tracked and `seek` and `tell` will work correctly. If the file is a stream that can't be randomly accessed, you don't need to override this method, """ diff --git a/paramiko/hostkeys.py b/paramiko/hostkeys.py index 704fe7e..cdf6d5c 100644 --- a/paramiko/hostkeys.py +++ b/paramiko/hostkeys.py @@ -112,7 +112,7 @@ class HostKeys (UserDict.DictMixin): verify server keys during SSH negotiation. A HostKeys object can be treated like a dict; any dict lookup is equivalent - to calling :class:`lookup`. + to calling `lookup`. .. versionadded:: 1.5.3 """ @@ -156,7 +156,7 @@ class HostKeys (UserDict.DictMixin): ``os.path.expanduser("~/.ssh/known_hosts")``. If this method is called multiple times, the host keys are merged, - not cleared. So multiple calls to ``load`` will just call :class:`add`, + not cleared. So multiple calls to `load` will just call `add`, replacing any existing entries and adding new ones. :param filename: name of the file to read host keys from diff --git a/paramiko/message.py b/paramiko/message.py index 85fb3c0..3937938 100644 --- a/paramiko/message.py +++ b/paramiko/message.py @@ -91,7 +91,7 @@ class Message (object): """ Returns the bytes of this Message that have been parsed and returned. The string passed into a Message's constructor can be regenerated by - concatenating ``get_so_far`` and :class:`get_remainder`. + concatenating ``get_so_far`` and `get_remainder`. :return: a string of the bytes parsed so far. :rtype: string @@ -118,7 +118,7 @@ class Message (object): def get_byte(self): """ Return the next byte of the Message, without decomposing it. This - is equivalent to :class:`get_bytes(1)`. + is equivalent to `get_bytes(1) `. :return: the next byte of the Message, or ``'\000'`` if there aren't any bytes remaining. diff --git a/paramiko/pkey.py b/paramiko/pkey.py index a12fc51..928b849 100644 --- a/paramiko/pkey.py +++ b/paramiko/pkey.py @@ -66,7 +66,7 @@ class PKey (object): def __str__(self): """ 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 + this key. This string is suitable for passing to `__init__` to re-create the key object later. :return: string representation of an SSH key message. diff --git a/paramiko/resource.py b/paramiko/resource.py index 1d1f8da..32947c5 100644 --- a/paramiko/resource.py +++ b/paramiko/resource.py @@ -33,7 +33,7 @@ class ResourceManager (object): with the ResourceManager can be collected but still free resources when they die. - Resources are registered using :class:`register`, and when an object is garbage + Resources are registered using `register`, and when an object is garbage collected, each registered resource is closed by having its ``close()`` method called. Multiple resources may be registered per object, but a resource will only be closed once, even if multiple objects register it. diff --git a/paramiko/server.py b/paramiko/server.py index 14f8976..41d0d42 100644 --- a/paramiko/server.py +++ b/paramiko/server.py @@ -35,7 +35,7 @@ class InteractiveQuery (object): Create a new interactive query to send to the client. The name and instructions are optional, but are generally displayed to the end user. A list of prompts may be included, or they may be added via - the :class:`add_prompt` method. + the `add_prompt` method. :param name: name of this query :type name: str @@ -88,12 +88,12 @@ class ServerInterface (object): useless), you should also override some of the channel request methods below, which are used to determine which services will be allowed on a given channel: - - :class:`check_channel_pty_request` - - :class:`check_channel_shell_request` - - :class:`check_channel_subsystem_request` - - :class:`check_channel_window_change_request` - - :class:`check_channel_x11_request` - - :class:`check_channel_forward_agent_request` + - `check_channel_pty_request` + - `check_channel_shell_request` + - `check_channel_subsystem_request` + - `check_channel_window_change_request` + - `check_channel_x11_request` + - `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 @@ -170,7 +170,7 @@ class ServerInterface (object): 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 + 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`. @@ -199,7 +199,7 @@ class ServerInterface (object): 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 + case, `get_allowed_auths` will be called to report to the client what options it has for continuing the authentication.) Note that you don't have to actually verify any key signtature here. @@ -230,7 +230,7 @@ class ServerInterface (object): 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`. + to `check_auth_interactive_response`. The default implementation always returns :class:`.AUTH_FAILED`. @@ -256,7 +256,7 @@ class ServerInterface (object): 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 + 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, @@ -333,7 +333,7 @@ class ServerInterface (object): does not support any global requests. .. note:: Port forwarding requests are handled separately, in - :class:`check_port_forward_request`. + `check_port_forward_request`. :param kind: the kind of global request being made. :type kind: str @@ -558,13 +558,13 @@ class SubsystemHandler (threading.Thread): :class:`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 :class:`start_subsystem`. + will be executed within its own new thread by calling `start_subsystem`. When that method completes, the channel is closed. For example, if you made a subclass ``MP3Handler`` and registered it as the handler for subsystem ``"mp3"``, then whenever a client has successfully authenticated and requests subsytem ``"mp3"``, an object of class - ``MP3Handler`` will be created, and :class:`start_subsystem` will be called on + ``MP3Handler`` will be created, and `start_subsystem` will be called on it from a new thread. """ def __init__(self, channel, name, server): diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index c30805a..dcd953f 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -61,7 +61,7 @@ class SFTPClient (BaseSFTP): should already have requested the ``"sftp"`` subsystem. An alternate way to create an SFTP client context is by using - :class:`from_transport`. + `from_transport`. :param sock: an open :class:`.Channel` using the ``"sftp"`` subsystem :type sock: :class:`.Channel` @@ -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 `listdir_attr`. :param path: path to list (defaults to ``'.'``) :type path: str @@ -255,7 +255,7 @@ class SFTPClient (BaseSFTP): def remove(self, path): """ Remove the file at the given path. This only works on files; for - removing folders (directories), use :class:`rmdir`. + removing folders (directories), use `rmdir`. :param path: path (absolute or relative) of the file to remove :type path: str @@ -343,7 +343,7 @@ class SFTPClient (BaseSFTP): """ Retrieve information about a file on the remote system, without following symbolic links (shortcuts). This otherwise behaves exactly - the same as :class:`stat`. + the same as `stat`. :param path: the filename to stat :type path: str @@ -394,7 +394,7 @@ class SFTPClient (BaseSFTP): """ Change the owner (``uid``) and group (``gid``) of a file. As with python's ``os.chown`` function, you must pass both arguments, so if you - only want to change one, use :class:`stat` first to retrieve the current + only want to change one, use `stat` first to retrieve the current owner and group. :param path: path of the file to change the owner and group of @@ -453,7 +453,7 @@ class SFTPClient (BaseSFTP): def readlink(self, path): """ Return the target of a symbolic link (shortcut). You can use - :class:`symlink` to create these. The result may be either an absolute or + `symlink` to create these. The result may be either an absolute or relative pathname. :param path: path of the symbolic link file @@ -523,7 +523,7 @@ class SFTPClient (BaseSFTP): def getcwd(self): """ Return the "current working directory" for this SFTP session, as - emulated by paramiko. If no directory has been set with :class:`chdir`, + emulated by paramiko. If no directory has been set with `chdir`, this method will return ``None``. :return: the current working directory on the server, or ``None`` diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py index 3ff0d68..2ebad87 100644 --- a/paramiko/sftp_file.py +++ b/paramiko/sftp_file.py @@ -255,7 +255,7 @@ class SFTPFile (BufferedFile): """ Change the owner (``uid``) and group (``gid``) of this file. As with python's ``os.chown`` function, you must pass both arguments, so if you - only want to change one, use :class:`stat` first to retrieve the current + only want to change one, use `stat` first to retrieve the current owner and group. :param uid: new owner's uid @@ -361,10 +361,10 @@ class SFTPFile (BufferedFile): Turn on/off the pipelining of write operations to this file. When pipelining is on, paramiko won't wait for the server response after each write operation. Instead, they're collected as they come in. - At the first non-write operation (including :class:`close`), all remaining + At the first non-write operation (including `close`), all remaining server responses are collected. This means that if there was an error with one of your later writes, an exception might be thrown from - within :class:`close` instead of :class:`write`. + within `close` instead of `write`. By default, files are not pipelined. @@ -379,13 +379,13 @@ class SFTPFile (BufferedFile): def prefetch(self): """ Pre-fetch the remaining contents of this file in anticipation of - future :class:`read` calls. If reading the entire file, pre-fetching can + future `read` calls. If reading the entire file, pre-fetching can dramatically improve the download speed by avoiding roundtrip latency. The file's contents are incrementally buffered in a background thread. - The prefetched data is stored in a buffer until read via the :class:`read` + The prefetched data is stored in a buffer until read via the `read` method. Once data has been read, it's removed from the buffer. The - data may be read in a random order (using :class:`seek`); chunks of the + data may be read in a random order (using `seek`); chunks of the buffer that haven't been read will continue to be buffered. .. versionadded:: 1.5.1 @@ -404,7 +404,7 @@ class SFTPFile (BufferedFile): def readv(self, chunks): """ Read a set of blocks from the file by (offset, length). This is more - efficient than doing a series of :class:`seek` and :class:`read` calls, since the + efficient than doing a series of `seek` and `read` calls, since the prefetch machinery is used to retrieve all the requested blocks at once. diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py index 3b3c6b4..a1a76c8 100644 --- a/paramiko/sftp_handle.py +++ b/paramiko/sftp_handle.py @@ -33,7 +33,7 @@ class SFTPHandle (object): by the client to refer to the underlying file. Server implementations can (and should) subclass SFTPHandle to implement - features of a file handle, like :class:`stat` or :class:`chattr`. + features of a file handle, like `stat` or `chattr`. """ def __init__(self, flags=0): """ @@ -59,7 +59,7 @@ class SFTPHandle (object): The default implementation checks for attributes on ``self`` named ``readfile`` and/or ``writefile``, and if either or both are present, their ``close()`` methods are called. This means that if you are - using the default implementations of :class:`read` and :class:`write`, this + using the default implementations of `read` and `write`, this method's default implementation should be fine also. """ readfile = getattr(self, 'readfile', None) diff --git a/paramiko/sftp_si.py b/paramiko/sftp_si.py index d1b2497..f3400c3 100644 --- a/paramiko/sftp_si.py +++ b/paramiko/sftp_si.py @@ -143,7 +143,7 @@ class SFTPServerInterface (object): """ 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 + "aliases"), you should follow them. (`lstat` is the corresponding call that doesn't follow symlinks/aliases.) :param path: the requested path (relative or absolute) to fetch @@ -160,7 +160,7 @@ class SFTPServerInterface (object): 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 + return data on the symlink or alias itself. (`stat` is the corresponding call that follows symlinks/aliases.) :param path: the requested path (relative or absolute) to fetch diff --git a/paramiko/transport.py b/paramiko/transport.py index 201ae00..44cdc77 100644 --- a/paramiko/transport.py +++ b/paramiko/transport.py @@ -128,8 +128,8 @@ class Transport (threading.Thread): """ Create a new SSH session over an existing socket, or socket-like object. This only creates the Transport object; it doesn't begin the - SSH session yet. Use :class:`connect` or :class:`start_client` to begin a client - session, or :class:`start_server` to begin a server session. + SSH session yet. Use `connect` or `start_client` to begin a client + session, or `start_server` to begin a server session. If the object is not actually a socket, it must have the following methods: @@ -301,7 +301,7 @@ class Transport (threading.Thread): If an event is passed in, this method returns immediately. When negotiation is done (successful or not), the given ``Event`` will - be triggered. On failure, :class:`is_active` will return ``False``. + be triggered. On failure, `is_active` will return ``False``. (Since 1.4) If ``event`` is ``None``, this method will not return until negotation is done. On success, the method returns normally. @@ -311,9 +311,9 @@ class Transport (threading.Thread): calling :class:`auth_password ` or :class:`auth_publickey `. - .. note:: :class:`connect` is a simpler method for connecting as a client. + .. note:: `connect` is a simpler method for connecting as a client. - .. note:: After calling this method (or :class:`start_server` or :class:`connect`), + .. note:: After calling this method (or `start_server` or `connect`), you should no longer directly read from or write to the original socket object. @@ -353,7 +353,7 @@ class Transport (threading.Thread): If an event is passed in, this method returns immediately. When negotiation is done (successful or not), the given ``Event`` will - be triggered. On failure, :class:`is_active` will return ``False``. + be triggered. On failure, `is_active` will return ``False``. (Since 1.4) If ``event`` is ``None``, this method will not return until negotation is done. On success, the method returns normally. @@ -372,7 +372,7 @@ class Transport (threading.Thread): :class:`check_channel_request ` in the given ``server`` object to allow channels to be opened. - .. note:: After calling this method (or :class:`start_client` or :class:`connect`), + .. note:: After calling this method (or `start_client` or `connect`), you should no longer directly read from or write to the original socket object. @@ -428,7 +428,7 @@ class Transport (threading.Thread): """ Return the active host key, in server mode. After negotiating with the client, this method will return the negotiated host key. If only one - type of host key was set with :class:`add_server_key`, that's the only key + type of host key was set with `add_server_key`, that's the only key that will ever be returned. But in cases where you have set more than one type of host key (for example, an RSA key and a DSS key), the key type will be negotiated by the client, and this method will return the @@ -587,7 +587,7 @@ class Transport (threading.Thread): 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. + `connect` or `start_client`) and authenticating. :param kind: the kind of channel requested (usually ``"session"``, ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``) @@ -665,7 +665,7 @@ class Transport (threading.Thread): If no handler is set, the default behavior is to send new incoming forwarded connections into the accept queue, to be picked up via - :class:`accept`. + `accept`. :param address: the address to bind when forwarding :type address: str @@ -849,19 +849,19 @@ 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 :class:`start_client`, :class:`get_remote_server_key`, and + for `start_client`, `get_remote_server_key`, and :class:`Transport.auth_password` or :class:`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 :class:`open_channel` or - :class:`open_session` to get a :class:`.Channel` object, which is used for data + session exists. You may immediately call `open_channel` or + `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 - succeed, but a subsequent :class:`open_channel` or :class:`open_session` call may + succeed, but a subsequent `open_channel` or `open_session` call may fail because you haven't authenticated yet. :param hostkey: the host key expected from the server, or ``None`` if @@ -908,7 +908,7 @@ class Transport (threading.Thread): """ Return any exception that happened during the last server request. This can be used to fetch more specific error information after using - calls like :class:`start_client`. The exception (if any) is cleared after + calls like `start_client`. The exception (if any) is cleared after this call. :return: an exception, or ``None`` if there is no stored exception. @@ -1004,8 +1004,8 @@ class Transport (threading.Thread): If an ``event`` is passed in, this method will return immediately, and the event will be triggered once authentication succeeds or fails. On - success, :class:`is_authenticated` will return ``True``. On failure, you may - use :class:`get_exception` to get more detailed error information. + success, `is_authenticated` will return ``True``. On failure, you may + use `get_exception` to get more detailed error information. Since 1.1, if no event is passed, this method will block until the authentication succeeds or fails. On failure, an exception is raised. @@ -1087,8 +1087,8 @@ class Transport (threading.Thread): If an ``event`` is passed in, this method will return immediately, and the event will be triggered once authentication succeeds or fails. On - success, :class:`is_authenticated` will return ``True``. On failure, you may - use :class:`get_exception` to get more detailed error information. + success, `is_authenticated` will return ``True``. On failure, you may + use `get_exception` to get more detailed error information. Since 1.1, if no event is passed, this method will block until the authentication succeeds or fails. On failure, an exception is raised. @@ -1237,7 +1237,7 @@ class Transport (threading.Thread): def use_compression(self, compress=True): """ Turn on/off compression. This will only have an affect before starting - the transport (ie before calling :class:`connect`, etc). By default, + the transport (ie before calling `connect`, etc). By default, compression is off since it negatively affects interactive sessions. :param compress: ``True`` to ask the remote client/server to compress