From b4418f72ffd2c3ac32e254124ad53aa903852ca6 Mon Sep 17 00:00:00 2001 From: Seth Schoen Date: Mon, 9 Feb 2015 14:42:16 -0800 Subject: [PATCH] Improve docstrings --- .../client/standalone_authenticator.py | 70 +++++++++++++------ 1 file changed, 48 insertions(+), 22 deletions(-) diff --git a/letsencrypt/client/standalone_authenticator.py b/letsencrypt/client/standalone_authenticator.py index 646afc6a8..7af869893 100644 --- a/letsencrypt/client/standalone_authenticator.py +++ b/letsencrypt/client/standalone_authenticator.py @@ -47,8 +47,9 @@ class StandaloneAuthenticator(object): """Signal handler for the parent process. This handler receives inter-process communication from the - child process in the form of Unix signals.""" - # signal handler for use in parent process + child process in the form of Unix signals. + + :param int sig: Which signal the process received.""" # subprocess → client READY : SIGIO # subprocess → client INUSE : SIGUSR1 # subprocess → client CANTBIND: SIGUSR2 @@ -66,8 +67,9 @@ class StandaloneAuthenticator(object): """Signal handler for the child process. This handler receives inter-process communication from the parent - process in the form of Unix signals.""" - # signal handler for use in subprocess + process in the form of Unix signals. + + :param int sig: Which signal the process received.""" # client → subprocess CLEANUP : SIGINT if sig == signal.SIGINT: try: @@ -97,7 +99,10 @@ class StandaloneAuthenticator(object): This method will set a new OpenSSL context object for this connection when an incoming connection provides an SNI name - (in order to serve the appropriate certificate, if any).""" + (in order to serve the appropriate certificate, if any). + + :param OpenSSL.Connection connection: The TLS connection object + on which the SNI extension was received.""" sni_name = connection.get_servername() if sni_name in self.tasks: @@ -121,6 +126,10 @@ class StandaloneAuthenticator(object): up to delay_amount seconds to hear from the child process via a signal. + :param int port: Which TCP port to bind. + :param float delay_amount: How long in seconds to wait for the + subprocess to notify us whether it succeeded. + :returns: True or False according to whether we were notified that the child process succeeded or failed in binding the port.""" @@ -158,7 +167,11 @@ class StandaloneAuthenticator(object): Normally does not return; instead, the child process exits from within this function or from within the child process signal - handler.""" + handler. + + :param int port: Which TCP port to bind. + :param le_util.Key key: The private key to use to respond to + DVSNI challenge requests.""" signal.signal(signal.SIGINT, self.subproc_signal_handler) self.sock = socket.socket() try: @@ -208,7 +221,8 @@ class StandaloneAuthenticator(object): specified port to perform the specified DVSNI challenges. :param int port: The TCP port to bind. - :param str key: The private key to use (in PEM format). + :param le_util.Key key: The private key to use to respond to + DVSNI challenge requests. :returns: True or False to indicate success or failure creating the subprocess. """ @@ -231,22 +245,31 @@ class StandaloneAuthenticator(object): def get_chall_pref(self, unused_domain): # pylint: disable=no-self-use - """IAuthenticator interface method: Return a list of challenge - types that this authenticator can perform for this domain. In - the case of the StandaloneAuthenticator, the only challenge - type that can ever be performed is dvsni. - """ + """IAuthenticator interface method get_chall_pref. + + Return a list of challenge types that this authenticator + can perform for this domain. In the case of the + StandaloneAuthenticator, the only challenge type that can ever + be performed is dvsni. + + :returns: A list containing only 'dvsni'.""" return ["dvsni"] def perform(self, chall_list): - """IAuthenticator interface method: Attempt to perform the + """IAuthenticator interface method perform. + + Attempt to perform the specified challenges, returning the status of each. For the StandaloneAuthenticator, because there is no convenient way to add additional requests, this should only be invoked once; subsequent invocations are an error. To perform validations for multiple independent sets of domains, a separate StandaloneAuthenticator should be instantiated. - """ + + :param list chall_list: A list of the the challenge objects to + be attempted by this authenticator. + :returns: A list in the same order containing, in each position, + the successfully configured challenge, False, or None.""" if self.child_pid or self.tasks: # We should not be willing to continue with perform # if there were existing pending challenges. @@ -285,14 +308,17 @@ class StandaloneAuthenticator(object): return results_if_failure def cleanup(self, chall_list): - """IAuthenticator interface method: Remove each of the specified - challenges from the list of challenges that still need to be - performed. (In the case of the StandaloneAuthenticator, if some - challenges are removed from the list, the authenticator socket - will still respond to those challenges.) Once all challenges - have been removed from the list, the listener is deactivated and - stops listening. - """ + """IAuthenticator interface method cleanup. + + Remove each of the specified challenges from the list of + challenges that still need to be performed. (In the case of + the StandaloneAuthenticator, if some challenges are removed + from the list, the authenticator socket will still respond to + those challenges.) Once all challenges have been removed from + the list, the listener is deactivated and stops listening. + + :param list chall_list: A list of the the challenge objects to + be deactivated.""" # Remove this from pending tasks list for chall in chall_list: assert isinstance(chall, challenge_util.DvsniChall)