Change GSS-API epydoc docstrings to Sphinx

1 files changed, 125 insertions, 170 deletions

diff --git a/paramiko/ssh_gss.py b/paramiko/ssh_gss.py
index 35d654af..4dfdec11 100644
--- a/paramiko/ssh_gss.py
+++ b/paramiko/ssh_gss.py
@@ -24,20 +24,20 @@ RFC 4462 with the following restrictions:
 Credential delegation is not supported in server mode,
 GSS-API key exchange is supported, but not implemented in Paramiko.
 To Use this module, you need the following additional python packages:
-U{pyasn1 >= 0.1.7 <https://pypi.python.org/pypi/pyasn1>},
-U{python-gssapi >= 0.4.0 (Unix) <https://pypi.python.org/pypi/python-gssapi>},
-U{pywin32 2.1.8 (Windows) <sourceforge.net/projects/pywin32/>}.
-
-@summary: SSH2 GSS-API / SSPI authentication module
-@version: 0.1
-@author: Sebastian Deiss
-@contact: U{https://github.com/SebastianDeiss/paramiko/issues}
-@organization: science + computing ag
-               (U{EMail<mailto:a.kruis@science-computing.de>})
-@copyright: (C) 2013-2014 U{science + computing ag
-            <https://www.science-computing.de>}
-@license: GNU Lesser General Public License (LGPL)
-@see: L{kex_gss}
+`pyasn1 >= 0.1.7 <https://pypi.python.org/pypi/pyasn1>`_,
+`python-gssapi >= 0.4.0 (Unix) <https://pypi.python.org/pypi/python-gssapi>`_,
+`pywin32 2.1.8 (Windows) <http://sourceforge.net/projects/pywin32/>`_.
+
+:summary: SSH2 GSS-API / SSPI authentication module
+:version: 0.1
+:author: Sebastian Deiss
+:contact: https://github.com/SebastianDeiss/paramiko/issues
+:organization: science + computing ag
+               `EMail <mailto:a.kruis@science-computing.de>`_
+:copyright: (C) 2013-2014 `science + computing ag
+            <https://www.science-computing.de>`_
+:license: GNU Lesser General Public License (LGPL)
+:see: `.kex_gss`
 
 Created on 07.11.2013
 """
@@ -47,9 +47,8 @@ import os
 import sys
 
 '''
-@var GSS_AUTH_AVAILABLE: Constraint that indicates if GSS-API / SSPI is
+:var bool GSS_AUTH_AVAILABLE: Constraint that indicates if GSS-API / SSPI is
                          Available.
-@type GSS_AUTH_AVAILABLE: Boolean
 '''
 GSS_AUTH_AVAILABLE = True
 
@@ -74,8 +73,7 @@ from paramiko.common import MSG_USERAUTH_REQUEST
 from paramiko.ssh_exception import SSHException
 
 """
-@var _API: Constraint for the used API
-@type _API: String
+:var str _API: Constraint for the used API
 """
 _API = "MIT"
 
@@ -95,25 +93,23 @@ def GSSAuth(auth_method, gss_deleg_creds=True):
     """
     Provide SSH2 GSS-API / SSPI authentication for Paramiko.
 
-    @param auth_method: The name of the SSH authentication mechanism
-                        (gssapi-with-mic or gss-keyex)
-    @type auth_method: String
-    @param gss_deleg_creds: Delegate client credentials or not.
-                            We delegate credentials by default.
-    @type gss_deleg_creds: Boolean
-    @return: Either an L{_SSH_GSSAPI} (Unix) object or an
-             L{_SSH_SSPI} (Windows) object
-    @rtype: Object
-
-    @raise ImportError: If no GSS-API / SSPI module could be imported.
-
-    @see: U{RFC 4462 <www.ietf.org/rfc/rfc4462.txt>}
-    @note: Check for the available API and return either an L{_SSH_GSSAPI}
-           (MIT GSSAPI) object or an L{_SSH_SSPI} (MS SSPI) object. If you
+    :param str auth_method: The name of the SSH authentication mechanism
+                            (gssapi-with-mic or gss-keyex)
+    :param bool gss_deleg_creds: Delegate client credentials or not.
+                                 We delegate credentials by default.
+    :return: Either an `._SSH_GSSAPI` (Unix) object or an
+             `_SSH_SSPI` (Windows) object
+    :rtype: Object
+
+    :raise ImportError: If no GSS-API / SSPI module could be imported.
+
+    :see: `RFC 4462 <http://www.ietf.org/rfc/rfc4462.txt>`_
+    :note: Check for the available API and return either an `._SSH_GSSAPI`
+           (MIT GSSAPI) object or an `._SSH_SSPI` (MS SSPI) object. If you
            get python-gssapi working on Windows, python-gssapi
-           will be used and a L{_SSH_GSSAPI} object will be returned.
+           will be used and a `._SSH_GSSAPI` object will be returned.
            If there is no supported API available,
-           C{None} will be returned.
+           ``None`` will be returned.
     """
     if _API == "MIT":
         return _SSH_GSSAPI(auth_method, gss_deleg_creds)
@@ -125,16 +121,14 @@ def GSSAuth(auth_method, gss_deleg_creds=True):
 
 class _SSH_GSSAuth(object):
     """
-    Contains the shared variables and methods of L{_SSH_GSSAPI} and
-    L{_SSH_SSPI}.
+    Contains the shared variables and methods of `._SSH_GSSAPI` and
+    `._SSH_SSPI`.
     """
     def __init__(self, auth_method, gss_deleg_creds):
         """
-        @param auth_method: The name of the SSH authentication mechanism
-                            (gssapi-with-mic or gss-keyex)
-        @type auth_method: String
-        @param gss_deleg_creds: Delegate client credentials or not
-        @type gss_deleg_creds: Boolean
+        :param str auth_method: The name of the SSH authentication mechanism
+                                (gssapi-with-mic or gss-keyex)
+        :param bool gss_deleg_creds: Delegate client credentials or not
         """
         self._auth_method = auth_method
         self._gss_deleg_creds = gss_deleg_creds
@@ -163,9 +157,8 @@ class _SSH_GSSAuth(object):
         I added this method, because RFC 4462 doesn't specify "ssh-connection"
         as the only service value.
 
-        @param service: The desired SSH service
-        @type service: String
-        @rtype: Void
+        :param str service: The desired SSH service
+        :rtype: Void
         """
         if service.find("ssh-"):
             self._service = service
@@ -175,9 +168,8 @@ class _SSH_GSSAuth(object):
         Setter for C{username}. If GSS-API Key Exchange is performed, the
         username is not set by C{ssh_init_sec_context}.
 
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @rtype: Void
+        :param str username: The name of the user who attempts to login
+        :rtype: Void
         """
         self._username = username
 
@@ -186,14 +178,13 @@ class _SSH_GSSAuth(object):
         This method returns a single OID, because we only support the
         Kerberos V5 mechanism.
 
-        @param mode: Client for client mode and server for server mode
-        @param mode: String
-        @return: A byte sequence containing the number of supported
+        :param str mode: Client for client mode and server for server mode
+        :return: A byte sequence containing the number of supported
                  OIDs, the length of the OID and the actual OID encoded with
                  DER
-        @note: In server mode we just return the OID length and the DER encoded
+        :rtype: Bytes
+        :note: In server mode we just return the OID length and the DER encoded
                OID.
-        @rtype: Bytes
         """
         OIDs = self._make_uint32(1)
         krb5_OID = encoder.encode(ObjectIdentifier(self._krb5_mech))
@@ -206,10 +197,9 @@ class _SSH_GSSAuth(object):
         """
         Check if the given OID is the Kerberos V5 OID (server mode).
 
-        @param desired_mech: The desired GSS-API mechanism of the client
-        @type desired_mech: String
-        @return: C{True} if the given OID is supported, otherwise C{False}
-        @rtype: Boolean
+        :param str desired_mech: The desired GSS-API mechanism of the client
+        :return: ``True`` if the given OID is supported, otherwise C{False}
+        :rtype: Boolean
         """
         mech, __ = decoder.decode(desired_mech)
         if mech.__str__() != self._krb5_mech:
@@ -222,10 +212,9 @@ class _SSH_GSSAuth(object):
         """
         Create a 32 bit unsigned integer (The byte sequence of an integer).
 
-        @param integer: The integer value to convert
-        @type integer: Integer
-        @return: The byte sequence of an 32 bit integer
-        @rtype: Bytes
+        :param int integer: The integer value to convert
+        :return: The byte sequence of an 32 bit integer
+        :rtype: Bytes
         """
         return struct.pack("!I", integer)
 
@@ -233,15 +222,11 @@ class _SSH_GSSAuth(object):
         """
         Create the SSH2 MIC filed for gssapi-with-mic.
 
-        @param session_id: The SSH session ID
-        @type session_id: String
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @param service: The requested SSH service
-        @type service: String
-        @param auth_method: The requested SSH authentication mechanism
-        @type auth_method: String
-        @return: The MIC as defined in RFC 4462. The contents of the
+        :param str session_id: The SSH session ID
+        :param str username: The name of the user who attempts to login
+        :param str service: The requested SSH service
+        :param str auth_method: The requested SSH authentication mechanism
+        :return: The MIC as defined in RFC 4462. The contents of the
                  MIC field are:
                  string    session_identifier,
                  byte      SSH_MSG_USERAUTH_REQUEST,
@@ -249,7 +234,7 @@ class _SSH_GSSAuth(object):
                  string    service (ssh-connection),
                  string    authentication-method
                            (gssapi-with-mic or gssapi-keyex)
-        @rtype: Bytes
+        :rtype: Bytes
         """
         mic = self._make_uint32(len(session_id))
         mic += session_id
@@ -267,15 +252,13 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
     """
     Implementation of the GSS-API MIT Kerberos Authentication for SSH2.
 
-    @see: L{GSSAuth}
+    :see: `.GSSAuth`
     """
     def __init__(self, auth_method, gss_deleg_creds):
         """
-        @param auth_method: The name of the SSH authentication mechanism
-                            (gssapi-with-mic or gss-keyex)
-        @type auth_method: String
-        @param gss_deleg_creds: Delegate client credentials or not
-        @type gss_deleg_creds: Boolean
+        :param str auth_method: The name of the SSH authentication mechanism
+                                (gssapi-with-mic or gss-keyex)
+        :param bool gss_deleg_creds: Delegate client credentials or not
         """
         _SSH_GSSAuth.__init__(self, auth_method, gss_deleg_creds)
 
@@ -294,21 +277,17 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
         """
         Initialize a GSS-API context.
 
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @param target: The hostname of the target to connect to
-        @type target: String
-        @param desired_mech: The negotiated GSS-API mechanism
-                             ("pseudo negotiated" mechanism, because we
-                             support just the krb5 mechanism :-))
-        @type desired_mech: String
-        @param recv_token: The GSS-API token received from the Server
-        @type recv_token: String
-        @raise SSHException: Is raised if the desired mechanism of the client
+        :param str username: The name of the user who attempts to login
+        :param str target: The hostname of the target to connect to
+        :param str desired_mech: The negotiated GSS-API mechanism
+                                 ("pseudo negotiated" mechanism, because we
+                                 support just the krb5 mechanism :-))
+        :param str recv_token: The GSS-API token received from the Server
+        :raise SSHException: Is raised if the desired mechanism of the client
                              is not supported
-        @return: A C{String} if the GSS-API has returned a token or C{None} if
+        :return: A ``String`` if the GSS-API has returned a token or ``None`` if
                  no token was returned
-        @rtype: String or None
+        :rtype: String or None
         """
         self._username = username
         self._gss_host = target
@@ -343,18 +322,16 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
         """
         Create the MIC token for a SSH2 message.
 
-        @param session_id: The SSH session ID
-        @type session_id: String
-        @param gss_kex: Generate the MIC for GSS-API Key Exchange or not
-        @type gss_kex: Boolean
-        @return: gssapi-with-mic:
+        :param str session_id: The SSH session ID
+        :param bool gss_kex: Generate the MIC for GSS-API Key Exchange or not
+        :return: gssapi-with-mic:
                  Returns the MIC token from GSS-API for the message we created
-                 with C{_ssh_build_mic}.
+                 with ``_ssh_build_mic``.
                  gssapi-keyex:
                  Returns the MIC token from GSS-API with the SSH session ID as
                  message.
-        @rtype: String
-        @see: L{_ssh_build_mic}
+        :rtype: String
+        :see: `._ssh_build_mic`
         """
         self._session_id = session_id
         if not gss_kex:
@@ -372,16 +349,13 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
         """
         Accept a GSS-API context (server mode).
 
-        @param hostname: The servers hostname
-        @type hostname: String
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @param recv_token: The GSS-API Token received from the server, if it's
-                           not the initial call
-        @type recv_token: String
-        @return: A C{String} if the GSS-API has returned a token or C{None} if
-                 no token was returned
-        @rtype: String or None
+        :param str hostname: The servers hostname
+        :param str username: The name of the user who attempts to login
+        :param str recv_token: The GSS-API Token received from the server,
+                               if it's not the initial call.
+        :return: A ``String`` if the GSS-API has returned a token or ``None``
+                if no token was returned
+        :rtype: String or None
         """
         # hostname and username are not required for GSSAPI, but for SSPI
         self._gss_host = hostname
@@ -396,14 +370,11 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
         """
         Verify the MIC token for a SSH2 message.
 
-        @param mic_token: The MIC token received from the client
-        @type mic_token: String
-        @param session_id: The SSH session ID
-        @type session_id: String
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @return: 0 if the MIC check was successful and 1 if it fails
-        @rtype: Integer
+        :param str mic_token: The MIC token received from the client
+        :param str session_id: The SSH session ID
+        :param str username: The name of the user who attempts to login
+        :return: 0 if the MIC check was successful and 1 if it fails
+        :rtype: int
         """
         self._session_id = session_id
         self._username = username
@@ -427,8 +398,8 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
         """
         Checks if credentials are delegated (server mode).
 
-        @return: C{True} if credentials are delegated, otherwise C{False}
-        @rtype: Boolean
+        :return: ``True`` if credentials are delegated, otherwise ``False``
+        :rtype: bool
         """
         if self._gss_srv_ctxt.delegated_cred is not None:
             return True
@@ -440,9 +411,8 @@ class _SSH_GSSAPI(_SSH_GSSAuth):
         to store the client credentials if credentials are delegated
         (server mode).
 
-        @param client_token: The GSS-API token received form the client
-        @type client_token: String
-        @raise NotImplementedError: Credential delegation is currently not
+        :param str client_token: The GSS-API token received form the client
+        :raise NotImplementedError: Credential delegation is currently not
                                     supported in server mode
         """
         raise NotImplementedError
@@ -452,15 +422,13 @@ class _SSH_SSPI(_SSH_GSSAuth):
     """
     Implementation of the Microsoft SSPI Kerberos Authentication for SSH2.
 
-    @see: L{GSSAuth}
+    :see: `.GSSAuth`
     """
     def __init__(self, auth_method, gss_deleg_creds):
         """
-        @param auth_method: The name of the SSH authentication mechanism
-                            (gssapi-with-mic or gss-keyex)
-        @type auth_method: String
-        @param gss_deleg_creds: Delegate client credentials or not
-        @type gss_deleg_creds: Boolean
+        :param str auth_method: The name of the SSH authentication mechanism
+                                (gssapi-with-mic or gss-keyex)
+        :param bool gss_deleg_creds: Delegate client credentials or not
         """
         _SSH_GSSAuth.__init__(self, auth_method, gss_deleg_creds)
 
@@ -477,21 +445,17 @@ class _SSH_SSPI(_SSH_GSSAuth):
         """
         Initialize a SSPI context.
 
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @param target: The FQDN of the target to connect to
-        @type target: String
-        @param desired_mech: The negotiated SSPI mechanism
-                             ("pseudo negotiated" mechanism, because we
-                             support just the krb5 mechanism :-))
-        @type desired_mech: String
-        @param recv_token: The SSPI token received from the Server
-        @type recv_token: String
-        @raise SSHException: Is raised if the desired mechanism of the client
+        :param str username: The name of the user who attempts to login
+        :param str target: The FQDN of the target to connect to
+        :param str desired_mech: The negotiated SSPI mechanism
+                                 ("pseudo negotiated" mechanism, because we
+                                 support just the krb5 mechanism :-))
+        :param recv_token: The SSPI token received from the Server
+        :raise SSHException: Is raised if the desired mechanism of the client
                              is not supported
-        @return: A C{String} if the SSPI has returned a token or C{None} if
+        :return: A ``String`` if the SSPI has returned a token or ``None`` if
                  no token was returned
-        @rtype: String or None
+        :rtype: String or None
         """
         self._username = username
         self._gss_host = target
@@ -528,18 +492,16 @@ class _SSH_SSPI(_SSH_GSSAuth):
         """
         Create the MIC token for a SSH2 message.
 
-        @param session_id: The SSH session ID
-        @type session_id: String
-        @param gss_kex: Generate the MIC for Key Exchange with SSPI or not
-        @type gss_kex: Boolean
-        @return: gssapi-with-mic:
+        :param str session_id: The SSH session ID
+        :param bool gss_kex: Generate the MIC for Key Exchange with SSPI or not
+        :return: gssapi-with-mic:
                  Returns the MIC token from SSPI for the message we created
-                 with C{_ssh_build_mic}.
+                 with ``_ssh_build_mic``.
                  gssapi-keyex:
                  Returns the MIC token from SSPI with the SSH session ID as
                  message.
-        @rtype: String
-        @see: L{_ssh_build_mic}
+        :rtype: String
+        :see: `._ssh_build_mic`
         """
         self._session_id = session_id
         if not gss_kex:
@@ -557,16 +519,13 @@ class _SSH_SSPI(_SSH_GSSAuth):
         """
         Accept a SSPI context (server mode).
 
-        @param hostname: The servers FQDN
-        @type hostname: String
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @param recv_token: The SSPI Token received from the server, if it's not
-                           the initial call
-        @type recv_token: String
-        @return: A C{String} if the SSPI has returned a token or C{None} if
+        :param str hostname: The servers FQDN
+        :param str username: The name of the user who attempts to login
+        :param str recv_token: The SSPI Token received from the server,
+                               if it's not the initial call.
+        :return: A ``String`` if the SSPI has returned a token or ``None`` if
                  no token was returned
-        @rtype: String or None
+        :rtype: String or None
         """
         self._gss_host = hostname
         self._username = username
@@ -583,14 +542,11 @@ class _SSH_SSPI(_SSH_GSSAuth):
         """
         Verify the MIC token for a SSH2 message.
 
-        @param mic_token: The MIC token received from the client
-        @type mic_token: String
-        @param session_id: The SSH session ID
-        @type session_id: String
-        @param username: The name of the user who attempts to login
-        @type username: String
-        @return: 0 if the MIC check was successful
-        @rtype: Integer
+        :param str mic_token: The MIC token received from the client
+        :param str session_id: The SSH session ID
+        :param str username: The name of the user who attempts to login
+        :return: 0 if the MIC check was successful
+        :rtype: int
         """
         self._session_id = session_id
         self._username = username
@@ -620,8 +576,8 @@ class _SSH_SSPI(_SSH_GSSAuth):
         """
         Checks if credentials are delegated (server mode).
 
-        @return: C{True} if credentials are delegated, otherwise C{False}
-        @rtype: Boolean
+        :return: ``True`` if credentials are delegated, otherwise ``False``
+        :rtype: Boolean
         """
         return (
                 self._gss_flags & sspicon.ISC_REQ_DELEGATE
@@ -635,9 +591,8 @@ class _SSH_SSPI(_SSH_GSSAuth):
         to store the client credentails if credentials are delegated
         (server mode).
 
-        @param client_token: The SSPI token received form the client
-        @type client_token: String
-        @raise NotImplementedError: Credential delegation is currently not
+        :param str client_token: The SSPI token received form the client
+        :raise NotImplementedError: Credential delegation is currently not
                                     supported in server mode
         """
         raise NotImplementedError