From fd917ed78713725c26c46c22c924d913e8b734b7 Mon Sep 17 00:00:00 2001 From: Ivan Alejandro Date: Mon, 14 Apr 2014 16:10:09 -0300 Subject: Improve backend docstrings. * Update wording to match pep-0257 * Add docstrings for signals emitted by the Backend. --- src/leap/bitmask/backend.py | 205 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 184 insertions(+), 21 deletions(-) (limited to 'src/leap') diff --git a/src/leap/bitmask/backend.py b/src/leap/bitmask/backend.py index c71553a3..c7fc3dc4 100644 --- a/src/leap/bitmask/backend.py +++ b/src/leap/bitmask/backend.py @@ -82,7 +82,7 @@ class ILEAPService(ILEAPComponent): def start(self): """ - Starts the service. + Start the service. """ pass @@ -94,13 +94,13 @@ class ILEAPService(ILEAPComponent): def terminate(self): """ - Terminates the service, not necessarily in a nice way. + Terminate the service, not necessarily in a nice way. """ pass def status(self): """ - Returns a json object with the current status for the service. + Return a json object with the current status for the service. :rtype: object (list, str, dict) """ @@ -111,7 +111,7 @@ class ILEAPService(ILEAPComponent): def set_configs(self, keyval): """ - Sets the config parameters for this Service. + Set the config parameters for this Service. :param keyval: values to configure :type keyval: dict, {str: str} @@ -120,7 +120,7 @@ class ILEAPService(ILEAPComponent): def get_configs(self, keys): """ - Returns the configuration values for the list of keys. + Return the configuration values for the list of keys. :param keys: keys to retrieve :type keys: list of str @@ -158,7 +158,7 @@ class Provider(object): def setup_provider(self, provider): """ - Initiates the setup for a provider + Initiate the setup for a provider :param provider: URL for the provider :type provider: unicode @@ -280,7 +280,7 @@ class EIP(object): def setup_eip(self, domain): """ - Initiates the setup for a provider + Initiate the setup for a provider :param domain: URL for the provider :type domain: unicode @@ -308,7 +308,7 @@ class EIP(object): def _start_eip(self): """ - Starts EIP + Start EIP """ provider_config = self._provider_config eip_config = eipconfig.EIPConfig() @@ -331,7 +331,7 @@ class EIP(object): def start(self): """ - Starts the service. + Start the service. """ signaler = self._signaler @@ -366,19 +366,19 @@ class EIP(object): def stop(self, shutdown=False): """ - Stops the service. + Stop the service. """ self._vpn.terminate(shutdown) def terminate(self): """ - Terminates the service, not necessarily in a nice way. + Terminate the service, not necessarily in a nice way. """ self._vpn.killit() def status(self): """ - Returns a json object with the current status for the service. + Return a json object with the current status for the service. :rtype: object (list, str, dict) """ @@ -389,7 +389,7 @@ class EIP(object): def _provider_is_initialized(self, domain): """ - Returns if the given domain is initialized or not. + Return whether the given domain is initialized or not. :param domain: the domain to check :type domain: str @@ -405,12 +405,13 @@ class EIP(object): def get_initialized_providers(self, domains): """ - Signals a list of the given domains and if they are initialized or not. + Signal a list of the given domains and if they are initialized or not. :param domains: the list of domains to check. :type domain: list of str - :signal type: list of tuples (str, bool) + Signals: + eip_get_initialized_providers -> list of tuple(unicode, bool) """ filtered_domains = [] for domain in domains: @@ -423,12 +424,15 @@ class EIP(object): def get_gateways_list(self, domain): """ - Signals a list of gateways for the given provider. + Signal a list of gateways for the given provider. :param domain: the domain to get the gateways. :type domain: str - :signal type: list of str + Signals: + eip_get_gateways_list -> list of unicode + eip_get_gateways_list_error + eip_uninitialized_provider """ if not self._provider_is_initialized(domain): if self._signaler is not None: @@ -479,7 +483,7 @@ class Authenticate(object): def login(self, domain, username, password): """ - Executes the whole authentication process for a user + Execute the whole authentication process for a user :param domain: the domain where we need to authenticate. :type domain: unicode @@ -511,7 +515,7 @@ class Authenticate(object): def change_password(self, current_password, new_password): """ - Changes the user's password. + Change the user's password. :param current_password: the current password of the user. :type current_password: str @@ -530,7 +534,7 @@ class Authenticate(object): def logout(self): """ - Logs out the current session. + Log out the current session. Expects a session_id to exists, might raise AssertionError """ if not self._is_logged_in(): @@ -550,7 +554,7 @@ class Authenticate(object): def get_logged_in_status(self): """ - Signals if the user is currently logged in or not. + Signal if the user is currently logged in or not. """ if self._signaler is None: return @@ -947,55 +951,214 @@ class Backend(object): # send_multipart and this backend class will be really simple. def setup_provider(self, provider): + """ + Initiate the setup for a provider. + + :param provider: URL for the provider + :type provider: unicode + + Signals: + prov_unsupported_client + prov_unsupported_api + prov_name_resolution -> { PASSED_KEY: bool, ERROR_KEY: str } + prov_https_connection -> { PASSED_KEY: bool, ERROR_KEY: str } + prov_download_provider_info -> { PASSED_KEY: bool, ERROR_KEY: str } + """ self._call_queue.put(("provider", "setup_provider", None, provider)) def cancel_setup_provider(self): + """ + Cancel the ongoing setup provider (if any). + """ self._call_queue.put(("provider", "cancel_setup_provider", None)) def provider_bootstrap(self, provider): + """ + Second stage of bootstrapping for a provider. + + :param provider: URL for the provider + :type provider: unicode + + Signals: + prov_problem_with_provider + prov_download_ca_cert -> {PASSED_KEY: bool, ERROR_KEY: str} + prov_check_ca_fingerprint -> {PASSED_KEY: bool, ERROR_KEY: str} + prov_check_api_certificate -> {PASSED_KEY: bool, ERROR_KEY: str} + """ self._call_queue.put(("provider", "bootstrap", None, provider)) def register_user(self, provider, username, password): + """ + Register a user using the domain and password given as parameters. + + :param domain: the domain we need to register the user. + :type domain: unicode + :param username: the user name + :type username: unicode + :param password: the password for the username + :type password: unicode + + Signals: + srp_registration_finished + srp_registration_taken + srp_registration_failed + """ self._call_queue.put(("register", "register_user", None, provider, username, password)) def setup_eip(self, provider): + """ + Initiate the setup for a provider + + :param domain: URL for the provider + :type domain: unicode + + Signals: + eip_config_ready -> {PASSED_KEY: bool, ERROR_KEY: str} + eip_client_certificate_ready -> {PASSED_KEY: bool, ERROR_KEY: str} + eip_cancelled_setup + """ self._call_queue.put(("eip", "setup_eip", None, provider)) def cancel_setup_eip(self): + """ + Cancel the ongoing setup EIP (if any). + """ self._call_queue.put(("eip", "cancel_setup_eip", None)) def start_eip(self): + """ + Start the EIP service. + + Signals: + backend_bad_call + eip_alien_open_vpn_already_running + eip_connected + eip_connection_aborted + eip_network_unreachable + eip_no_pkexec_error + eip_no_polkit_agent_error + eip_no_tun_kext_error + eip_open_vpn_already_running + eip_open_vpn_not_found_error + eip_process_finished + eip_process_restart_ping + eip_process_restart_tls + eip_state_changed -> str + eip_status_changed -> str + eip_vpn_launcher_exception + """ self._call_queue.put(("eip", "start", None)) def stop_eip(self, shutdown=False): + """ + Stop the EIP service. + """ self._call_queue.put(("eip", "stop", None, shutdown)) def terminate_eip(self): + """ + Terminate the EIP service, not necessarily in a nice way. + """ self._call_queue.put(("eip", "terminate", None)) def eip_get_gateways_list(self, domain): + """ + Signal a list of gateways for the given provider. + + :param domain: the domain to get the gateways. + :type domain: str + + # TODO discuss how to document the expected result object received of + # the signal + :signal type: list of str + + Signals: + eip_get_gateways_list -> list of unicode + eip_get_gateways_list_error + eip_uninitialized_provider + """ self._call_queue.put(("eip", "get_gateways_list", None, domain)) def eip_get_initialized_providers(self, domains): + """ + Signal a list of the given domains and if they are initialized or not. + + :param domains: the list of domains to check. + :type domain: list of str + + Signals: + eip_get_initialized_providers -> list of tuple(unicode, bool) + + """ self._call_queue.put(("eip", "get_initialized_providers", None, domains)) def login(self, provider, username, password): + """ + Execute the whole authentication process for a user + + :param domain: the domain where we need to authenticate. + :type domain: unicode + :param username: username for this session + :type username: str + :param password: password for this user + :type password: str + + Signals: + srp_auth_error + srp_auth_ok + srp_auth_bad_user_or_password + srp_auth_server_error + srp_auth_connection_error + srp_auth_error + """ self._call_queue.put(("authenticate", "login", None, provider, username, password)) def logout(self): + """ + Log out the current session. + + Signals: + srp_logout_ok + srp_logout_error + srp_not_logged_in_error + """ self._call_queue.put(("authenticate", "logout", None)) def cancel_login(self): + """ + Cancel the ongoing login (if any). + """ self._call_queue.put(("authenticate", "cancel_login", None)) def change_password(self, current_password, new_password): + """ + Change the user's password. + + :param current_password: the current password of the user. + :type current_password: str + :param new_password: the new password for the user. + :type new_password: str + + Signals: + srp_not_logged_in_error + srp_password_change_ok + srp_password_change_badpw + srp_password_change_error + """ self._call_queue.put(("authenticate", "change_password", None, current_password, new_password)) def get_logged_in_status(self): + """ + Signal if the user is currently logged in or not. + + Signals: + srp_status_logged_in + srp_status_not_logged_in + """ self._call_queue.put(("authenticate", "get_logged_in_status", None)) ########################################################################### -- cgit v1.2.3