This is an automated email from the git hooks/post-receive script.
x2go pushed a commit to branch master
in repository x2gobroker.
commit 9f9e5d63d17ae5248f182e2626fcd6105753d4f5
Author: Mike Gabriel <mike.gabr...@das-netzwerkteam.de>
Date: Thu Sep 13 09:46:50 2018 +0200
x2gobroker/utils.py: Provide/improve API documentation for our utility
functions.
---
x2gobroker/utils.py | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 98 insertions(+), 1 deletion(-)
diff --git a/x2gobroker/utils.py b/x2gobroker/utils.py
index 1811ebb..8f703db 100644
--- a/x2gobroker/utils.py
+++ b/x2gobroker/utils.py
@@ -17,6 +17,16 @@
# Free Software Foundation, Inc.,
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
+"""\
+Here you find a collection of tools that are used by X2Go Session
+Broker's code internally.
+
+Everything that is not directly related to specific broker code and
+potentially reusable at other places in the code tree, is placed into
+this module.
+
+"""
+
import os
import sys
import locale
@@ -95,6 +105,9 @@ def compare_versions(version_a, op, version_b):
:param version_b: another version string that is to be compared with
<version_a>
:type version_b: ``str``
+ :returns: if the comparison is ``True`` or ``False``
+ :rtype: ``bool``
+
"""
### FIXME: this comparison is not reliable with beta et al. version strings
@@ -107,6 +120,29 @@ def compare_versions(version_a, op, version_b):
def normalize_hostnames(servers):
"""\
+ Take a ``list`` or ``dict`` of servers and check if they match in
+ their domain part and strip the domain part finally off.
+
+ E.g., for servers provided as a ``list`` (tuple would be ok, too::
+
+ ['server1', 'server2'] -> ['server1', server2']
+ ['server1.domain1, 'server2.domain1'] -> ['server1', server2']
+ ['server1.domain1, 'server2.domain2'] -> (['server1', server2'],
['domain1', 'domain2']
+
+ E.g., for servers provided as a ``dict``::
+
+ {'server1': <whatever-params>, 'server2': <whatever-params> } ->
{'server1': <whatever-params>, 'server2': <whatever-params> }
+
+ {'server1.domain1': <whatever-params>, 'server2.domain1':
<whatever-params> } -> {'server1': <whatever-params>, 'server2':
<whatever-params> }
+
+ {'server1.domain1': <whatever-params>, 'server2.domain2':
<whatever-params> } -> ({'server1': <whatever-params>, 'server2':
<whatever-params> }, ['domain1', 'domain2']
+
+ :param servers: a ``list``, ``tuple`` or ``dict`` hash with either server
hostnames as items or dictionary keys
+ :type servers: ``list``, ``tuple`` or ``dict``
+
+ :returns: a ``list`` or a ``dict`` with server domains stripped of the
items / keys
+ :rtype: ``list``, ``dict`` or ``tuple``
+
"""
# test the data type of servers
@@ -147,7 +183,22 @@ def normalize_hostnames(servers):
return servers_normalized, subdomains
def matching_hostnames(server_list_a, server_list_b):
+ """\
+ Compare two list of servers, if they have matching hostnames.
+
+ This function tries to smoothly ship around asymmetric usage of
+ FQDN hostnames and short hostnames in one list.
+
+ :param server_list_a: list of servers
+ :type server_list_a: ``list`` of ``str``
+ :param server_list_b: list of servers to compare the first list with
+ :type server_list_b: ``list`` of ``str``
+ :returns: a sorted list of matching server hostnames (hostnames that
+ appear in both provided server lists.
+ :returns: ``list`` of ``str``
+
+ """
matching_hosts = []
### NORMALIZE (=reduce to hostname only) server names (list A) if possible
@@ -169,6 +220,24 @@ def matching_hostnames(server_list_a, server_list_b):
return matching_hosts
def drop_privileges(uid, gid):
+ """\
+ Drop privileges from super-user root to given ``<uid>`` and ``<gid>``.
+
+ Only works when run as root, if run with a non-super-user account,
+ ``None`` is returned.
+
+ If privileges could be dropped, the environment's HOME variable is
+ adapted to the new user account's home directory path.
+
+ Also, the umask of the account we dropped privileges to is set to
+ ``0o077``.
+
+ :param uid: the user ID of the user account to drop privileges to
+ :type uid: ``str``
+ :param gid: the group ID to drop privileges to
+ :type gid: ``str``
+
+ """
if os.getuid() != 0:
# We're not root so, like, whatever dude
return
@@ -191,7 +260,28 @@ def drop_privileges(uid, gid):
os.environ['HOME'] = pwd.getpwnam(uid).pw_dir
def split_host_address(host, default_address=None, default_port=22):
+ """\
+ Try to split a ``<host_addr>:<port>`` expression into hostname and port.
+
+ This function is supposed to work with DNS hostnames, IPv4 and IPv6
+ address.
+
+ Both parts (<host_addr> and <port>) can be omitted in the given
+ ``host`` string. If so, ``default_address`` and ``default_port`` come
+ into play.
+
+ :param host: an expression like ``<host_addr>:<port>`` (where either
+ the host address or the port can be optional)
+ :type host: ``str``
+ :param default_address: a fallback host address to be used (default: None)
+ :type default_address: ``str``
+ :param default_port: a fallback port to be used (default: 22)
+ :type default_port: ``int``
+ :returns: a tuple of host address and port
+ :rtype: ``tuple(<host_addr>, <port>)``
+
+ """
if type(host) is int:
host = str(host)
# do some stripping first...
@@ -244,7 +334,7 @@ def split_host_address(host, default_address=None,
default_port=22):
def portscan(addr, port=22):
"""\
- Performing a port scan to the requested hostname.
+ Perform a port scan to the requested hostname.
:param addr: address (IPv4, IPv6 or hostname) of the host
we want to probe
@@ -252,6 +342,9 @@ def portscan(addr, port=22):
:param port: port number (default: 22)
:type port: ``int``
+ :returns: ``True`` if the port is in use, else ``False`` (also on errors)
+ :rtype: ``bool``
+
"""
ip_proto = 0
try:
@@ -289,6 +382,8 @@ def get_key_fingerprint(key):
"""\
Retrieve the host key fingerprint of the server to be validated.
+ :param key: a Python Paramik :class:`PKey`` object
+ :type key: ``PKey``
:returns: host key fingerprint
:rtype: ``str``
@@ -300,6 +395,8 @@ def get_key_fingerprint_with_colons(key):
Retrieve the (colonized) host key fingerprint of the server
to be validated.
+ :param key: a Python Paramik :class:`PKey`` object
+ :type key: ``PKey``
:returns: host key fingerprint (with colons)
:rtype: ``str``
--
Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on
/srv/git/code.x2go.org/x2gobroker.git
_______________________________________________
x2go-commits mailing list
x2go-commits@lists.x2go.org
https://lists.x2go.org/listinfo/x2go-commits
