diff --git a/paramiko/transport.py b/paramiko/transport.py index 5f32680..dfb3df8 100644 --- a/paramiko/transport.py +++ b/paramiko/transport.py @@ -150,7 +150,8 @@ class Transport (threading.Thread): address and used for communication. Exceptions from the ``socket`` call may be thrown in this case. - :param socket sock: a socket or socket-like object to create the session over. + :param socket sock: + a socket or socket-like object to create the session over. """ if isinstance(sock, (str, unicode)): # convert "host:port" into (host, port) @@ -249,8 +250,6 @@ class Transport (threading.Thread): def __repr__(self): """ Returns a string representation of this object, for debugging. - - :rtype: str """ out = '` - :type server: `.ServerInterface` :raises SSHException: if negotiation fails (and no ``event`` was passed in) @@ -420,8 +414,8 @@ class Transport (threading.Thread): key info, not just the public half. Only one key of each type (RSA or DSS) is kept. - :param key: the host key to add, usually an `.RSAKey` or `.DSSKey`. - :type key: `.PKey` + :param .PKey key: + the host key to add, usually an `.RSAKey` or `.DSSKey`. """ self.server_key_dict[key.get_name()] = key @@ -436,8 +430,9 @@ class Transport (threading.Thread): key of the type agreed on. If the host key has not been negotiated yet, ``None`` is returned. In client mode, the behavior is undefined. - :return: host key of the type negotiated by the client, or ``None``. - :rtype: `.PKey` + :return: + host key (`.PKey`) of the type negotiated by the client, or + ``None``. """ try: return self.server_key_dict[self.host_key_type] @@ -467,7 +462,6 @@ class Transport (threading.Thread): not in a standard location. :return: True if a moduli file was successfully loaded; False otherwise. - :rtype: bool .. note:: This has no effect when used in client mode. """ @@ -510,8 +504,7 @@ class Transport (threading.Thread): :raises SSHException: if no session is currently active. - :return: public key of the remote server - :rtype: `.PKey` + :return: public key (`.PKey`) of the remote server """ if (not self.active) or (not self.initial_kex_done): raise SSHException('No existing session') @@ -521,9 +514,9 @@ class Transport (threading.Thread): """ Return true if this session is active (open). - :return: True if the session is still active (open); False if the - session is closed - :rtype: bool + :return: + True if the session is still active (open); False if the session is + closed """ return self.active @@ -545,11 +538,10 @@ class Transport (threading.Thread): Request a new channel to the client, of type ``"x11"``. This is just an alias for ``open_channel('x11', src_addr=src_addr)``. - :param src_addr: the source address of the x11 server (port is the + :param tuple src_addr: + the source address (``(str, int)``) of the x11 server (port is the x11 port, ie. 6010) - :type src_addr: (str, int) :return: a new `.Channel` - :rtype: `.Channel` :raises SSHException: if the request is rejected or the session ends prematurely @@ -564,7 +556,6 @@ class Transport (threading.Thread): This is just an alias for ``open_channel('auth-agent@openssh.com')``. :return: a new `.Channel` - :rtype: `.Channel` :raises SSHException: if the request is rejected or the session ends prematurely @@ -591,18 +582,16 @@ class Transport (threading.Thread): session. You may only request a channel after negotiating encryption (using `connect` or `start_client`) and authenticating. - :param kind: the kind of channel requested (usually ``"session"``, + :param str kind: + the kind of channel requested (usually ``"session"``, ``"forwarded-tcpip"``, ``"direct-tcpip"``, or ``"x11"``) - :type kind: str - :param dest_addr: the destination address of this port forwarding, - if ``kind`` is ``"forwarded-tcpip"`` or ``"direct-tcpip"`` (ignored - for other channel types) - :type dest_addr: (str, int) + :param tuple dest_addr: + the destination address (address + port tuple) of this port + forwarding, if ``kind`` is ``"forwarded-tcpip"`` or + ``"direct-tcpip"`` (ignored for other channel types) :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 `.Channel` on success - :rtype: `.Channel` :raises SSHException: if the request is rejected or the session ends prematurely @@ -669,15 +658,13 @@ class Transport (threading.Thread): forwarded connections into the accept queue, to be picked up via `accept`. - :param address: the address to bind when forwarding - :type address: str - :param port: the port to forward, or 0 to ask the server to allocate - any port - :type port: int - :param handler: optional handler for incoming forwarded connections - :type handler: function(Channel, (str, int), (str, int)) - :return: the port # allocated by the server - :rtype: int + :param str address: the address to bind when forwarding + :param int port: + the port to forward, or 0 to ask the server to allocate any port + :param callable handler: + optional handler for incoming forwarded connections, of the form + ``func(Channel, (str, int), (str, int))``. + :return: the port number (`int`) allocated by the server :raises SSHException: if the server refused the TCP forward request """ @@ -703,10 +690,8 @@ class Transport (threading.Thread): connections to the given address & port will be forwarded across this ssh connection. - :param address: the address to stop forwarding - :type address: str - :param port: the port to stop forwarding - :type port: int + :param str address: the address to stop forwarding + :param int port: the port to stop forwarding """ if not self.active: return @@ -719,9 +704,9 @@ class Transport (threading.Thread): SFTP session will be opened with the remote host, and a new `.SFTPClient` object will be returned. - :return: a new `.SFTPClient` object, referring to an sftp session - (channel) across this transport - :rtype: `.SFTPClient` + :return: + a new `.SFTPClient` referring to an sftp session (channel) across + this transport """ return SFTPClient.from_transport(self) @@ -732,9 +717,9 @@ class Transport (threading.Thread): also be used as a keep-alive for long lived connections traversing firewalls. - :param bytes: the number of random bytes to send in the payload of the - ignored packet -- defaults to a random number from 10 to 41. - :type bytes: int + :param int bytes: + the number of random bytes to send in the payload of the ignored + packet -- defaults to a random number from 10 to 41. """ m = Message() m.add_byte(chr(MSG_IGNORE)) @@ -775,9 +760,9 @@ class Transport (threading.Thread): "keepalive" packet will be sent (and ignored by the remote host). This can be useful to keep connections alive over a NAT, for example. - :param interval: seconds to wait before sending a keepalive packet (or + :param int interval: + seconds to wait before sending a keepalive packet (or 0 to disable keepalives). - :type interval: int """ self.packetizer.set_keepalive(interval, lambda x=weakref.proxy(self): x.global_request('keepalive@lag.net', wait=False)) @@ -787,18 +772,17 @@ class Transport (threading.Thread): Make a global request to the remote host. These are normally extensions to the SSH2 protocol. - :param kind: name of the request. - :type kind: str - :param data: an optional tuple containing additional data to attach - to the request. - :type data: tuple - :param wait: ``True`` if this method should not return until a response - is received; ``False`` otherwise. - :type wait: bool - :return: a `.Message` containing possible additional data if the - request was successful (or an empty `.Message` if ``wait`` was - ``False``); ``None`` if the request was denied. - :rtype: `.Message` + :param str kind: name of the request. + :param tuple data: + an optional tuple containing additional data to attach to the + request. + :param bool wait: + ``True`` if this method should not return until a response is + received; ``False`` otherwise. + :return: + a `.Message` containing possible additional data if the request was + successful (or an empty `.Message` if ``wait`` was ``False``); + ``None`` if the request was denied. """ if wait: self.completion_event = threading.Event() @@ -826,11 +810,9 @@ class Transport (threading.Thread): server mode. If no channel is opened before the given timeout, ``None`` is returned. - :param timeout: seconds to wait for a channel, or ``None`` to wait - forever - :type timeout: int + :param int timeout: + seconds to wait for a channel, or ``None`` to wait forever :return: a new `.Channel` opened by the client - :rtype: `.Channel` """ self.lock.acquire() try: @@ -867,17 +849,16 @@ class Transport (threading.Thread): 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 - you don't want to do host key verification. - :type hostkey: `.PKey` - :param username: the username to authenticate as. - :type username: str - :param password: a password to use for authentication, if you want to - use password authentication; otherwise ``None``. - :type password: str - :param pkey: a private key to use for authentication, if you want to - use private key authentication; otherwise ``None``. - :type pkey: `.PKey` + :param .PKey hostkey: + the host key expected from the server, or ``None`` if you don't + want to do host key verification. + :param str username: the username to authenticate as. + :param str password: + a password to use for authentication, if you want to use password + authentication; otherwise ``None``. + :param .PKey pkey: + a private key to use for authentication, if you want to use private + key authentication; otherwise ``None``. :raises SSHException: if the SSH2 negotiation fails, the host key supplied by the server is incorrect, or authentication fails. @@ -914,8 +895,8 @@ class Transport (threading.Thread): calls like `start_client`. The exception (if any) is cleared after this call. - :return: an exception, or ``None`` if there is no stored exception. - :rtype: Exception + :return: + an exception, or ``None`` if there is no stored exception. .. versionadded:: 1.1 """ @@ -937,11 +918,9 @@ class Transport (threading.Thread): Any extra parameters (including keyword arguments) are saved and passed to the `.SubsystemHandler` constructor later. - :param name: name of the subsystem. - :type name: str - :param handler: subclass of `.SubsystemHandler` that handles this - subsystem. - :type handler: class + :param str name: name of the subsystem. + :param class handler: + subclass of `.SubsystemHandler` that handles this subsystem. """ try: self.lock.acquire() @@ -953,10 +932,10 @@ class Transport (threading.Thread): """ Return true if this session is active and authenticated. - :return: True if the session is still open and has been authenticated + :return: + True if the session is still open and has been authenticated successfully; False if authentication failed and/or the session is closed. - :rtype: bool """ return self.active and (self.auth_handler is not None) and self.auth_handler.is_authenticated() @@ -966,8 +945,7 @@ class Transport (threading.Thread): session is not authenticated (or authentication failed), this method returns ``None``. - :return: username that was authenticated, or ``None``. - :rtype: string + :return: username that was authenticated (a `str`), or ``None``. """ if not self.active or (self.auth_handler is None): return None @@ -980,11 +958,10 @@ class Transport (threading.Thread): list of authentication types supported by the server, by catching the `.BadAuthenticationType` exception raised. - :param username: the username to authenticate as - :type username: string - :return: list of auth types permissible for the next stage of + :param str username: the username to authenticate as + :return: + `list` of auth types permissible for the next stage of authentication (normally empty) - :rtype: list :raises BadAuthenticationType: if "none" authentication isn't allowed by the server for this user @@ -1027,20 +1004,17 @@ class Transport (threading.Thread): this method will return a list of auth types permissible for the next step. Otherwise, in the normal case, an empty list is returned. - :param username: the username to authenticate as - :type username: str - :param password: the password to authenticate with - :type password: basestring - :param event: an event to trigger when the authentication attempt is - complete (whether it was successful or not) - :type event: threading.Event - :param fallback: ``True`` if an attempt at an automated "interactive" - password auth should be made if the server doesn't support normal - password auth - :type fallback: bool - :return: list of auth types permissible for the next stage of + :param str username: the username to authenticate as + :param basestring password: the password to authenticate with + :param .threading.Event event: + an event to trigger when the authentication attempt is complete + (whether it was successful or not) + :param bool fallback: + ``True`` if an attempt at an automated "interactive" password auth + should be made if the server doesn't support normal password auth + :return: + `list` of auth types permissible for the next stage of authentication (normally empty) - :rtype: list :raises BadAuthenticationType: if password authentication isn't allowed by the server for this user (and no event was passed in) @@ -1101,16 +1075,14 @@ class Transport (threading.Thread): this method will return a list of auth types permissible for the next step. Otherwise, in the normal case, an empty list is returned. - :param username: the username to authenticate as - :type username: string - :param key: the private key to authenticate with - :type key: `.PKey` - :param event: an event to trigger when the authentication attempt is - complete (whether it was successful or not) - :type event: threading.Event - :return: list of auth types permissible for the next stage of + :param str username: the username to authenticate as + :param .PKey key: the private key to authenticate with + :param .threading.Event event: + an event to trigger when the authentication attempt is complete + (whether it was successful or not) + :return: + `list` of auth types permissible for the next stage of authentication (normally empty) - :rtype: list :raises BadAuthenticationType: if public-key authentication isn't allowed by the server for this user (and no event was passed in) @@ -1161,15 +1133,12 @@ class Transport (threading.Thread): this method will return a list of auth types permissible for the next step. Otherwise, in the normal case, an empty list is returned. - :param username: the username to authenticate as - :type username: string - :param handler: a handler for responding to server questions - :type handler: callable - :param submethods: a string list of desired submethods (optional) - :type submethods: str - :return: list of auth types permissible for the next stage of + :param str username: the username to authenticate as + :param callable handler: a handler for responding to server questions + :param str submethods: a string list of desired submethods (optional) + :return: + `list` of auth types permissible for the next stage of authentication (normally empty). - :rtype: list :raises BadAuthenticationType: if public-key authentication isn't allowed by the server for this user @@ -1193,8 +1162,7 @@ class Transport (threading.Thread): the `.logging` module for more info.) SSH Channels will log to a sub-channel of the one specified. - :param name: new channel name for logging - :type name: str + :param str name: new channel name for logging .. versionadded:: 1.1 """ @@ -1206,8 +1174,7 @@ class Transport (threading.Thread): """ Return the channel name used for this transport's logging. - :return: channel name. - :rtype: str + :return: channel name as a `str` .. versionadded:: 1.2 """ @@ -1219,9 +1186,9 @@ class Transport (threading.Thread): the logs. Normally you would want this off (which is the default), but if you are debugging something, it may be useful. - :param hexdump: ``True`` to log protocol traffix (in hex) to the log; - ``False`` otherwise. - :type hexdump: bool + :param bool hexdump: + ``True`` to log protocol traffix (in hex) to the log; ``False`` + otherwise. """ self.packetizer.set_hexdump(hexdump) @@ -1230,8 +1197,7 @@ class Transport (threading.Thread): Return ``True`` if the transport is currently logging hex dumps of protocol traffic. - :return: ``True`` if hex dumps are being logged - :rtype: bool + :return: ``True`` if hex dumps are being logged, else ``False``. .. versionadded:: 1.4 """ @@ -1243,9 +1209,9 @@ class Transport (threading.Thread): 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 - traffic; ``False`` to refuse compression - :type compress: bool + :param bool compress: + ``True`` to ask the remote client/server to compress traffic; + ``False`` to refuse compression .. versionadded:: 1.5.2 """ @@ -1261,8 +1227,9 @@ class Transport (threading.Thread): socket. If the socket-like object has no ``'getpeername'`` method, then ``("unknown", 0)`` is returned. - :return: the address if the remote host, if known - :rtype: tuple(str, int) + :return: + the address of the remote host, if known, as a ``(str, int)`` + tuple. """ gp = getattr(self.sock, 'getpeername', None) if gp is None: @@ -2057,8 +2024,6 @@ class SecurityOptions (object): def __repr__(self): """ Returns a string representation of this object, for debugging. - - :rtype: str """ return '' % repr(self._transport)