diff --git a/library/tcbsd_route.py b/library/tcbsd_route.py index c9208c9..e0c5dcc 100644 --- a/library/tcbsd_route.py +++ b/library/tcbsd_route.py @@ -111,14 +111,31 @@ class Route(object): + """ + A single static route in TwinCAT/BSD land. + + Parameters + ---------- + name : str + The name of the route. + address : str + The IPv4 address of the remote. + net_id : str + The associated AMS Net ID of the host. + type : str + The type of the route (typically TCP_IP). + flags : str + Flags for the route (typically 64, whatever that means) + """ + def __init__(self, name, address, net_id="", type="", flags=""): if not net_id: net_id = "%s.1.1" % (hostname_to_ip_address(address),) self.name = name self.address = address self.net_id = net_id - self.type_ = type or "TCP_IP" - self.flags = flags or "64" + self.type_ = str(type or "TCP_IP") + self.flags = str(flags or "64") def validate(self): assert self.name, "Name not set" @@ -179,10 +196,35 @@ def __str__(self): def hostname_to_ip_address(hostname): + """ + Convert the provided hostname to an IPv4 address. + + Parameters + ---------- + hostname : str + The hostname or IP. + + Returns + ------- + str + An IP address for the provided host. + """ return socket.gethostbyname(hostname) def load_routes_from_file(filename): + """ + Load static routes from the provided filename. + + Parameters + ---------- + filename : str + The XML filename on disk. + + Returns + ------- + list of Route + """ with open(filename, "rb") as fp: routes = lxml.etree.fromstring(fp.read()) @@ -193,6 +235,18 @@ def load_routes_from_file(filename): def routes_to_xml(routes): + """ + Convert the provided routes to XML elements. + + Parameters + ---------- + routes : list of Route + The routes. + + Returns + ------- + lxml.etree.Element + """ tc_config = lxml.etree.Element( "TcConfig", nsmap={"xsi": "http://www.w3.org/2001/XMLSchema-instance"} ) @@ -205,6 +259,16 @@ def routes_to_xml(routes): def save_routes_to_file(filename, routes): + """ + Save the provided routes to ``filename``. + + Parameters + ---------- + filename : str + The destination filename to write to. + routes : list of Route + Routes to save. + """ tc_config = routes_to_xml(routes) # NOTE: TCBSD writes tabs here; so let's conform lxml.etree.indent(tc_config, space="\t") @@ -220,6 +284,20 @@ def save_routes_to_file(filename, routes): def find_matching_routes(routes, route): + """ + Find matching routes in the ``routes`` list. + + Parameters + ---------- + routes : list of Route + route : Route + + Yields + ------ + Route + Route which matches either the name, Net ID, or IP address of + ``route``. + """ for existing in routes: if ( existing.name == route.name @@ -294,6 +372,17 @@ def remove_route_if_existing(routes, remove_route): def combine_results(dest_results, results): + """ + Combine results from separate runs of ``ensure_route_exists`` or + ``remove_route_if_existing``. + + Parameters + ---------- + dest_results : dict + The destination dictionary. + results : dict + The source dictionary to add onto the destination. + """ for key in dest_results: if isinstance(dest_results[key], int): dest_results[key] += results.get(key, 0) @@ -303,6 +392,7 @@ def combine_results(dest_results, results): def run_module(): + """Run the route modifying module.""" # define available arguments/parameters a user can pass to the module module_args = dict( file=dict(