Overhaul error handling and messaging

[AlexanderPico]

In coordination with py4cytoscape via Barry:

I’m working on the py4cytoscape branch called ReturnVals … I haven’t merged my changes into Master yet. Please take a look and let me know whether my changes are sound and consider making the same changes to RCy3. Generally, I did the following: Made all console output call the new narrate() function, which checks to see whether iPython is running. If so, it prints the message (e.g., “Layout complete”); otherwise, the message is not printed. In R, I suspect the right thing to do is something along the lines of this: https://rstudio.github.io/rstudioapi/reference/isAvailable.html Created an exception class called CyError, which returns an error description string to the caller. The error description contains text describing the error, gives the offending value(s), and possibly recommends some action. It does not contain the name of the function in which the error occurred – that is prepended to the error description automatically by the CyError constructor. The mechanics of this may differ in R, as I understand that R doesn’t have exception classes, but does have stop(). Even so, a central function in R could find the caller name (https://stackoverflow.com/questions/15595478/how-to-get-the-name-of-the-calling-function-inside-the-called-routine) and do the prepend, then do the stop(). Changed the documentation for each function that now throws CyError instead of returning “”, None, or error text. Note that CyError is not a RCy3 concept … I added it a while ago to better enable error checking that RCy3 started. To see the extent and types of CyError, do a global search on CyError and observe how/where it’s used. Changed property value validation to call verify_* functions in py4cytoscape_utils.py. These functions will validate colors, opacities, and dimensions … either as single values, a list of values, or None. So, the loops that repeatedly called functions like is_not_hex_color() have been replaced by a single call to functions like verify_hex_colors(). Similarly, a verify_slot() function centralizes slot number checking in custom graphics. The functions I changed (relative to Master, which is last week’s release) are below. Most are self-explanatory, but I have added comments as needed:

Module	Function	Comment
Commands.py	*	Changed _handle_error to not pass function name … CyError now figures out the function name. Note that code is organized somewhat differently than in RCy3
	_command_2_post_query_body	Changed error text so it shows more context
	_handle_error	Figures out caller name so CyError can add it to the error message
Cytoscape_system	Cytoscape_ping	Changed print() to narrate()
	Cytoscape_version_infoCytoscape_free_memory	Eliminated writing error text and added CyError
CyError	*	Created error class constructor that adds name of caller to error message text
Filters	Apply_filterCreate_column_filterCreate_degree_filterCreate_composite_filter	Eliminated writing error text and added CyError. Cleaned up error text wording so it shows context.
Layouts	Set_layout_properties	Made property name warning into a hard CyError
Network_selection	Get_selected_nodesget_selected_edges	Converted printed warning into narrate()
Network_views	get_network_view_suid	Converted printed warning into narrate()
Networks	Get_netowrk_nameGet_network_suid	Improved error message to deliver context
	Export_network	Changed warnings and prints to narrate()
	Add_cy_edges	Converted warning to hard CyError
	Create_network_from_dataframe	Return CyError instead of text error string. Converted prints to narrates()
Py4cytoscape_logger	Added narrate()
Py4cytoscape_utils	verify_hex_colorsverify_opacity,verify_dimensionsverify_slot	Added verification functions
	Node_name_to_node_suidEdge_name_to_edge_suidNode_suid_to_node_nameEdge_suid_to_edge_nameTable_column_existsVerify_supported_versions	Removed prints, changed to hard CyError, and improved message context
Sessions	Open_session	Changed print to narrate()
	Save_session	Changed printed warning and Null return to hard CyError. Changed warning to narrate()
Style_bypasses	Set_node_property_bypassClear_node_property_bypassSet_edge_property_bypassClear_edge_property_bypassset_node_shape_bypassset_edge_line_style_bypassset_edge_source_arrow_shape_bypassset_edge_target_arrow_shape_bypass	Changed printed warning and null (or False) return to hard CyError and rephrased error
	Clear_network_property_bypass	Improved error context
	Set_node_color_bypassSet_node_size_bypassSet_node_width_bypassSet_node_height_bypassSet_node_font_size_bypassSet_node_label_color_bypassset_node_border_width_bypassset_node_border_color_bypassset_node_opacity_bypassset_node_fill_opacity_bypassset_node_border_opacity_bypassset_node_label_opacity_bypassset_edge_opacity_bypassset_edge_color_bypassset_edge_label_color_bypassset_edge_line_width_bypassset_edge_source_arrow_color_bypassset_edge_target_arrow_color_bypassset_edge_label_opacity_bypass	Replace verification loop with call to verify_* function
	set_edge_font_size_bypass	Remove error counter and replace verification loop with call to verify_* function
Style_defaults	set_node_border_color_defaultset_node_border_opacity_defaultset_node_color_defaultset_nodecustom*set_node_fill_opacity_defaultset_node_label_color_defaultset_node_label_opacity_defaultset_node_selection_color_defaultset_edge_color_defaultset_edge_label_color_defaultset_edge_label_opacity_defaultset_edge_opacity_defaultset_edge_selection_color_defaultset_edge_source_arrow_color_defaultset_edge_target_arrow_color_defaultset_background_color_default	Replaced color and explicit opacity, size, width, height, and slot checks with calls to verify_functions
	set_node_custom_bar_chart	Improved message context
	set_node_font_size_defaultset_node_height_defaultset_node_size_defaultset_node_width_defaultset_edge_font_size_defaultset_edge_line_width_default	Added parameter verification where there was none before
	set_node_shape_default	Replace print and null return with hard CyError
Style_dependencies	get_style_dependenciesset_style_dependencies	Replace print and null return with hard CyError, rephrased error message
Style_mappings	map_visual_propertyset_node_tooltip_mappingset_edge_label_mapping_update_visual_property	Improved message context
	set_node_border_color_mappingset_node_border_opacity_mappingset_node_color_mappingset_node_combo_opacity_mappingset_node_fill_opacity_mappingset_node_label_color_mappingset_node_label_opacity_mappingset_node_width_mappingset_edge_color_mappingset_edge_label_color_mappingset_edge_label_opacity_mappingset_edge_line_width_mappingset_edge_opacity_mappingset_edge_target_arrow_color_mappingset_edge_source_arrow_color_mapping	Replaced color and explicit opacity, size, width, and height checks with calls to verify_functions.
	set_node_font_size_mappingset_node_height_mappingset_node_size_mappingset_edge_font_size_mapping	Added parameter verification where there was none before
Style_values	get_node_propertyget_edge_propertyget_network_propertyget_node_position	Improved message context
Styles	copy_visual_styleset_visual_style	Improved message context
	export_visual_styles	Changed print to narrate()
Tables	get_table_columns	Improved message context and changed print to narrate()
	load_table_data	Changed string return to hard CyError, improved message context
	map_table_column	Improved message context and return hard CyError
User_interface	_check_panel_name	Improved message context