summaryrefslogtreecommitdiff
path: root/src/leap/bitmask
diff options
context:
space:
mode:
authorIvan Alejandro <ivanalejandro0@gmail.com>2014-04-14 16:10:09 -0300
committerIvan Alejandro <ivanalejandro0@gmail.com>2014-04-15 15:00:09 -0300
commitfd917ed78713725c26c46c22c924d913e8b734b7 (patch)
tree9d2362d695a282247f78392f917f6c5acf6d6981 /src/leap/bitmask
parent37577fdf037f2987ae3eb9493457dd8d4447aaf7 (diff)
Improve backend docstrings.
* Update wording to match pep-0257 * Add docstrings for signals emitted by the Backend.
Diffstat (limited to 'src/leap/bitmask')
-rw-r--r--src/leap/bitmask/backend.py205
1 files changed, 184 insertions, 21 deletions
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))
###########################################################################