Source code for graphspace_python.api.endpoint.graphs

from graphspace_python.api.config import GRAPHS_PATH
from graphspace_python.api.obj.api_response import APIResponse

[docs]class Graphs(object): """Graphs endpoint class. Provides methods for graph related operations such as saving, fetching, updating and deleting graphs on GraphSpace. """ def __init__(self, client): self.client = client
[docs] def post_graph(self, graph): """Posts NetworkX graph to the requesting users account on GraphSpace. Args: graph (GSGraph or Graph): Object having graph details, such as name, graph_json, style_json, is_public, tags. Returns: Graph: Saved graph on GraphSpace. Raises: GraphSpaceError: If error response is received from the GraphSpace API. Example: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Creating a graph >>> from graphspace_python.graphs.classes.gsgraph import GSGraph >>> G = GSGraph() >>> G.set_name('My Sample Graph') >>> G.set_tags(['sample']) >>> G.add_node('a', popup='sample node popup text', label='A') >>> G.add_node('b', popup='sample node popup text', label='B') >>> G.add_edge('a', 'b', directed=True, popup='sample edge popup') >>> G.add_edge_style('a', 'b', directed=True, edge_style='dotted') >>> # Saving graph on GraphSpace >>> graphspace.post_graph(G) Note: Refer to the `tutorial <../tutorial/tutorial.html#creating-a-graph>`_ for more about posting graphs. """ data = graph.json() data.update({'owner_email': self.client.username}) return APIResponse('graph', self.client._make_request("POST", GRAPHS_PATH, data=data) ).graph
[docs] def get_graph(self, graph_name=None, graph_id=None, owner_email=None): """Get a graph with the given graph_name or graph_id. Args: graph_name (str, optional): Name of the graph to be fetched. Defaults to None. graph_id (int, optional): ID of the graph to be fetched. Defaults to None. owner_email (str, optional): Email of the owner of the graph. Defaults to None. Returns: Graph or None: Graph object, if graph with the given 'graph_name' or 'graph_id' exists; otherwise None. Raises: Exception: If both 'graph_name' and 'graph_id' are None. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Getting a graph by name: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Fetching a graph >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> graph.get_name() u'My Sample Graph' Getting a graph by id: >>> graph = graphspace.get_graph(graph_id=65930) >>> graph.get_name() u'My Sample Graph' Note: Refer to the `tutorial <../tutorial/tutorial.html#fetching-a-graph-from-graphspace>`_ for more about fetching graphs. """ if graph_id is not None: graph_by_id_path = GRAPHS_PATH + str(graph_id) return APIResponse('graph', self.client._make_request("GET", graph_by_id_path) ).graph if graph_name is not None: query = { 'owner_email': self.client.username if owner_email is None else owner_email, 'names[]': graph_name } if owner_email is not None and owner_email != self.client.username: query.update({'is_public': 1}) response = self.client._make_request("GET", GRAPHS_PATH, url_params=query) if response.get('total', 0) > 0: graph = response.get('graphs')[0] graph_by_id_path = GRAPHS_PATH + str(graph.get('id')) return APIResponse('graph', self.client._make_request("GET", graph_by_id_path) ).graph else: return None raise Exception('Both graph_id and graph_name can\'t be none!')
[docs] def get_public_graphs(self, tags=None, limit=20, offset=0): """Get public graphs. Args: tags (List[str], optional): Search for graphs with the given given list of tag names. In order to search for graphs with given tag as a substring, wrap the name of the tag with percentage symbol. For example, %xyz% will search for all graphs with 'xyz' in their tag names. Defaults to None. offset (int, optional): Offset the list of returned entities by this number. Defaults to 0. limit (int, optional): Number of entities to return. Defaults to 20. Returns: List[Graph]: List of public graphs. Raises: GraphSpaceError: If error response is received from the GraphSpace API. Examples: Getting public graphs: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Fetching public graphs >>> graphs = graphspace.get_public_graphs(limit=5) >>> graphs[0].get_name() u'Wnt-Pathway-Reconstruction' Getting public graphs by tags: >>> graphs = graphspace.get_public_graphs(tags=['Kegg-networks'], limit=5) >>> graphs[0].get_name() u'KEGG-Wnt-signaling-pathway-with-ranks' """ query = { 'is_public': 1, 'limit': limit, 'offset': offset } if tags is not None: query.update({'tags[]': tags}) return APIResponse('graph', self.client._make_request("GET", GRAPHS_PATH, url_params=query) ).graphs
[docs] def get_shared_graphs(self, tags=None, limit=20, offset=0): """Get graphs shared with the groups where requesting user is a member. Args: tags (List[str], optional): Search for graphs with the given given list of tag names. In order to search for graphs with given tag as a substring, wrap the name of the tag with percentage symbol. For example, %xyz% will search for all graphs with 'xyz' in their tag names. Defaults to None. offset (int, optional): Offset the list of returned entities by this number. Defaults to 0. limit (int, optional): Number of entities to return. Defaults to 20. Returns: List[Graph]: List of shared graphs. Raises: GraphSpaceError: If error response is received from the GraphSpace API. Examples: Getting shared graphs: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Fetching shared graphs >>> graphs = graphspace.get_shared_graphs(limit=5) >>> graphs[0].get_name() u'KEGG-Wnt-signaling-pathway' Getting shared graphs by tags: >>> graphs = graphspace.get_shared_graphs(tags=['Kegg-networks'], limit=5) >>> graphs[0].get_name() u'KEGG-Wnt-signaling-pathway' """ query = { 'member_email': self.client.username, 'limit': limit, 'offset': offset } if tags is not None: query.update({'tags[]': tags}) return APIResponse('graph', self.client._make_request("GET", GRAPHS_PATH, url_params=query) ).graphs
[docs] def get_my_graphs(self, tags=None, limit=20, offset=0): """Get graphs created by the requesting user. Args: tags (List[str], optional): Search for graphs with the given given list of tag names. In order to search for graphs with given tag as a substring, wrap the name of the tag with percentage symbol. For example, %xyz% will search for all graphs with 'xyz' in their tag names. Defaults to None. offset (int, optional): Offset the list of returned entities by this number. Defaults to 0. limit (int, optional): Number of entities to return. Defaults to 20. Returns: List[Graph]: List of graphs owned by the requesting user. Raises: GraphSpaceError: If error response is received from the GraphSpace API. Examples: Getting your graphs: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Fetching my graphs >>> graphs = graphspace.get_my_graphs(limit=5) >>> graphs[0].get_name() u'test' Getting your graphs by tags: >>> graphs = graphspace.get_my_graphs(tags=['Kegg-networks'], limit=5) >>> graphs[0].get_name() u'KEGG-Wnt-signaling-pathway' """ query = { 'owner_email': self.client.username, 'limit': limit, 'offset': offset } if tags is not None: query.update({'tags[]': tags}) return APIResponse('graph', self.client._make_request("GET", GRAPHS_PATH, url_params=query) ).graphs
[docs] def delete_graph(self, graph_name=None, graph_id=None, graph=None): """Delete a graph from GraphSpace provided the graph_name, graph_id or the graph object itself. Args: graph_name (str, optional): Name of the graph to be deleted. Defaults to None. graph_id (int, optional): ID of the graph to be deleted. Defaults to None. graph (GSGraph or Graph, optional): Object having graph details, such as name, graph_json, style_json, is_public, tags. Defaults to None. Returns: str: Success/Error Message from GraphSpace. Raises: Exception: If both 'graph_name' and 'graph_id' are None and graph object has no 'name' or 'id' attribute; or if graph doesnot exist. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Deleting a graph by name: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Deleting a graph >>> graphspace.delete_graph(graph_name='My Sample Graph') u'Successfully deleted graph with id=65930' Deleting a graph by id: >>> graphspace.delete_graph(graph_id=65930) u'Successfully deleted graph with id=65930' Deleting a graph by passing graph object itself as param: >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> graphspace.delete_graph(graph=graph) u'Successfully deleted graph with id=65930' Note: Refer to the `tutorial <../tutorial/tutorial.html#deleting-a-graph-on-graphspace>`_ for more about deleting graphs. """ if graph is not None: if hasattr(graph, 'id'): graph_id = graph.id elif hasattr(graph, 'name'): graph_name = graph.name if graph_id is not None: graph_by_id_path = GRAPHS_PATH + str(graph_id) response = self.client._make_request("DELETE", graph_by_id_path) return response['message'] if graph_name is not None: graph = self.get_graph(graph_name=graph_name) if graph is None or graph.id is None: raise Exception('Graph with name `%s` doesnt exist for user `%s`!' % (graph_name, self.client.username)) else: graph_by_id_path = GRAPHS_PATH + str(graph.id) response = self.client._make_request("DELETE", graph_by_id_path) return response['message'] raise Exception('Both graph_id and graph_name can\'t be none when graph object has no \'name\' or \'id\' attribute!')
[docs] def update_graph(self, graph, graph_name=None, graph_id=None, owner_email=None): """Update a graph on GraphSpace with the provided graph object. If graph_name or graph_id is also provided then the update will be performed for that graph having the given name or id. Args: graph (GSGraph or Graph): Object having graph details, such as name, graph_json, style_json, is_public, tags. graph_name (str, optional): Name of the graph to be updated. Defaults to None. graph_id (int, optional): ID of the graph to be updated. Defaults to None. owner_email (str, optional): Email of owner of the graph. Defaults to None. Returns: Graph: Updated graph on GraphSpace. Raises: Exception: If both 'graph_name' and 'graph_id' are None and graph object has no 'name' or 'id' attribute; or if graph doesnot exist. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Updating a graph by creating a new graph and replacing the existing graph: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Creating the new graph >>> G = GSGraph() >>> G.add_node('a', popup='sample node popup text', label='A updated') >>> G.add_node('b', popup='sample node popup text', label='B updated') >>> G.add_edge('a', 'b', directed=True, popup='sample edge popup') >>> G.add_edge_style('a', 'b', directed=True, edge_style='dotted') >>> G.set_name('My Sample Graph') >>> G.set_is_public(1) >>> # Updating to replace the existing graph >>> graphspace.update_graph(G) Another way of updating a graph by fetching and editing the existing graph: >>> # Fetching the graph >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> # Modifying the fetched graph >>> graph.add_node('z', popup='sample node popup text', label='Z') >>> graph.add_node_style('z', shape='ellipse', color='green', width=90, height=90) >>> graph.add_edge('a', 'z', directed=True, popup='sample edge popup') >>> graph.set_is_public(1) >>> # Updating graph >>> graphspace.update_graph(graph) If you also provide 'graph_name' or 'graph_id' as param then the update will be performed for that graph having the given name or id: >>> graphspace.update_graph(G, graph_id=65930) Note: Refer to the `tutorial <../tutorial/tutorial.html#updating-a-graph-on-graphspace>`_ for more about updating graphs. """ if graph_id is not None or hasattr(graph, 'id'): graph_id = graph_id if graph_id is not None else graph.id graph_by_id_path = GRAPHS_PATH + str(graph_id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data=graph.json()) ).graph if graph_name is not None or hasattr(graph, 'name'): graph_name = graph_name if graph_name is not None else graph.name graph1 = self.get_graph(graph_name=graph_name, owner_email=owner_email) if graph1 is None or graph1.id is None: raise Exception('Graph with name `%s` doesnt exist for user `%s`!' % (graph_name, self.client.username)) else: graph_by_id_path = GRAPHS_PATH + str(graph1.id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data=graph.json()) ).graph raise Exception('Both graph_id and graph_name can\'t be none when graph object has no \'name\' or \'id\' attribute!')
[docs] def publish_graph(self, graph_name=None, graph_id=None, graph=None): """Makes a graph publicly viewable. Args: graph_name (str, optional): Name of the graph. Defaults to None. graph_id (int, optional): ID of the graph. Defaults to None. graph (GSGraph or Graph, optional): Object having graph details, such as name, graph_json, style_json, is_public, tags. Defaults to None. Returns: Graph: Updated graph on GraphSpace. Raises: Exception: If both 'graph_name' and 'graph_id' are None and graph object has no 'name' or 'id' attribute; or if graph doesnot exist. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Make graph public by name: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Publishing the graph >>> graph = graphspace.publish_graph(graph_name='My Sample Graph') >>> graph.get_is_public() 1 Make graph public by id: >>> graph = graphspace.publish_graph(graph_id=65930) >>> graph.get_is_public() 1 Make graph public by passing graph object itself as param: >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> graphspace.publish_graph(graph=graph) Note: Refer to the `tutorial <../tutorial/tutorial.html#making-a-graph-public-on-graphspace>`_ for more about making a graph public. """ if graph is not None: if hasattr(graph, 'id'): graph_id = graph.id elif hasattr(graph, 'name'): graph_name = graph.name if graph_id is not None: graph_by_id_path = GRAPHS_PATH + str(graph_id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'is_public': 1}) ).graph if graph_name is not None: graph = self.get_graph(graph_name=graph_name) if graph is None or graph.id is None: raise Exception('Graph with name `%s` doesnt exist for user `%s`!' % (graph_name, self.client.username)) else: graph_by_id_path = GRAPHS_PATH + str(graph.id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'is_public': 1}) ).graph raise Exception('Both graph_id and graph_name can\'t be none when graph object has no \'name\' or \'id\' attribute!')
[docs] def unpublish_graph(self, graph_name=None, graph_id=None, graph=None): """Makes a graph privately viewable. Args: graph_name (str, optional): Name of the graph. Defaults to None. graph_id (int, optional): ID of the graph. Defaults to None. graph (GSGraph or Graph, optional): Object having graph details, such as name, graph_json, style_json, is_public, tags. Defaults to None. Returns: Graph: Updated graph on GraphSpace. Raises: Exception: If both 'graph_name' and 'graph_id' are None and graph object has no 'name' or 'id' attribute; or if graph doesnot exist. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Make graph private by name: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Unpublishing the graph >>> graph = graphspace.unpublish_graph(graph_name='My Sample Graph') >>> graph.get_is_public() 0 Make graph private by id: >>> graph = graphspace.unpublish_graph(graph_id=65930) >>> graph.get_is_public() 0 Make graph private by passing graph object itself as param: >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> graphspace.unpublish_graph(graph=graph) Note: Refer to the `tutorial <../tutorial/tutorial.html#making-a-graph-private-on-graphspace>`_ for more about making a graph private. """ if graph is not None: if hasattr(graph, 'id'): graph_id = graph.id elif hasattr(graph, 'name'): graph_name = graph.name if graph_id is not None: graph_by_id_path = GRAPHS_PATH + str(graph_id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'is_public': 0}) ).graph if graph_name is not None: graph = self.get_graph(graph_name=graph_name) if graph is None or graph.id is None: raise Exception('Graph with name `%s` doesnt exist for user `%s`!' % (graph_name, self.client.username)) else: graph_by_id_path = GRAPHS_PATH + str(graph.id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'is_public': 0}) ).graph raise Exception('Both graph_id and graph_name can\'t be none when graph object has no \'name\' or \'id\' attribute!')
[docs] def set_default_graph_layout(self, graph_name=None, graph_id=None, graph=None, layout_name=None, layout_id=None, layout=None): """Set a default layout (provided the layout_name, layout_id or layout object) for a graph with given graph_name, graph_id or graph object itself. Args: graph_name (str, optional): Name of the graph. Defaults to None. graph_id (int, optional): ID of the graph. Defaults to None. graph (GSGraph or Graph, optional): Object having graph details, such as name, graph_json, style_json, is_public, tags. Defaults to None. layout_name (str, optional): Name of the layout. Defaults to None. layout_id (int, optional): ID of the layout. Defaults to None. layout (GSLayout or Layout): Object having layout details, such as name, is_shared, style_json, positions_json. Returns: Graph: Updated graph on GraphSpace. Raises: Exception: If both 'layout_name' and 'layout_id' are None and layout object has no 'name' or 'id' attribute; or if both 'graph_name' and 'graph_id' are None and neither graph object has 'name' or 'id' attribute nor layout object has 'graph_id' attribute; or if graph or layout doesnot exist. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Setting a default layout when graph name is known: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Setting default layout for the graph >>> graph = graphspace.set_default_graph_layout(graph_name='My Sample Graph', layout_id=1087) >>> graph.default_layout_id 1087 Setting a default layout when graph id is known: >>> graph = graphspace.set_default_graph_layout(graph_id=65930, layout_id=1087) >>> graph.default_layout_id 1087 Setting a default layout when graph object is passed as param: >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> graph = graphspace.set_default_graph_layout(graph=graph, layout_id=1087) >>> graph.default_layout_id 1087 Setting a default layout by passing layout name: >>> graph = graphspace.set_default_graph_layout(graph_id=65930, layout_name='My Sample Layout') >>> graph.default_layout_id 1087 Setting a default layout by only passing layout object as param: >>> layout = graphspace.get_graph_layout(graph_id=65930, layout_name='My Sample Layout') >>> graph = graphspace.set_default_graph_layout(layout=layout) >>> graph.default_layout_id 1087 Note: Refer to the `tutorial <../tutorial/tutorial.html#setting-a-default-layout-for-a-graph>`_ for more about setting default graph layout. """ if graph is not None: if hasattr(graph, 'id'): graph_id = graph.id elif hasattr(graph, 'name'): graph_name = graph.name if hasattr(layout, 'graph_id'): graph_id = layout.graph_id if graph_id is None and graph_name is None: raise Exception('Both graph_id and graph_name can\'t be none when graph object has no \'name\' or \'id\' attribute and layout object has no \'graph_id\' attribute!') if layout is not None: if hasattr(layout, 'id'): layout_id = layout.id elif hasattr(layout, 'name'): layout_name = layout.name if layout_id is None and layout_name is None: raise Exception('Both layout_id and layout_name can\'t be none when layout object has no \'name\' or \'id\' attribute!') if layout_id is None: layout = self.client.get_graph_layout(layout_name=layout_name, graph_id=graph_id) if layout is None or layout.id is None: raise Exception('Layout with name `%s` of graph with graph_id=%s doesnt exist for user `%s`!' % (layout_name, graph_id, self.client.username)) else: layout_id = layout.id if graph_id is not None: graph_by_id_path = GRAPHS_PATH + str(graph_id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'default_layout_id': layout_id}) ).graph if graph_name is not None: graph = self.get_graph(graph_name=graph_name) if graph is None or graph.id is None: raise Exception('Graph with name `%s` doesnt exist for user `%s`!' % (graph_name, self.client.username)) else: graph_by_id_path = GRAPHS_PATH + str(graph.id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'default_layout_id': layout_id}) ).graph
[docs] def unset_default_graph_layout(self, graph_name=None, graph_id=None, graph=None): """Unsets the current default layout of a graph provided the graph_name, graph_id or graph object itself. Args: graph_name (str, optional): Name of the graph. Defaults to None. graph_id (int, optional): ID of the graph. Defaults to None. graph (GSGraph or Graph, optional): Object having graph details, such as name, graph_json, style_json, is_public, tags. Defaults to None. Returns: Graph: Updated graph on GraphSpace. Raises: Exception: If both 'graph_name' and 'graph_id' are None and graph object has no 'name' or 'id' attribute; or if graph doesnot exist. GraphSpaceError: If error response is received from the GraphSpace API. Examples: Unset default graph layout by graph name: >>> # Connecting to GraphSpace >>> from graphspace_python.api.client import GraphSpace >>> graphspace = GraphSpace('[email protected]', 'user1') >>> # Unset the default graph layout >>> graph = graphspace.unset_default_graph_layout(graph_name='My Sample Graph') >>> assert graph.default_layout_id is None Unset default graph layout by graph id: >>> graph = graphspace.unset_default_graph_layout(graph_id=65930) Unset default graph layout by graph object: >>> graph = graphspace.get_graph(graph_name='My Sample Graph') >>> graph = graphspace.unset_default_graph_layout(graph=graph) Note: Refer to the `tutorial <../tutorial/tutorial.html#unset-default-layout-for-a-graph>`_ for more about unsetting a default graph layout. """ if graph is not None: if hasattr(graph, 'id'): graph_id = graph.id elif hasattr(graph, 'name'): graph_name = graph.name if graph_id is not None: graph_by_id_path = GRAPHS_PATH + str(graph_id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'default_layout_id': 0}) ).graph if graph_name is not None: graph = self.get_graph(graph_name=graph_name) if graph is None or graph.id is None: raise Exception('Graph with name `%s` doesnt exist for user `%s`!' % (graph_name, self.client.username)) else: graph_by_id_path = GRAPHS_PATH + str(graph.id) return APIResponse('graph', self.client._make_request("PUT", graph_by_id_path, data={'default_layout_id': 0}) ).graph raise Exception('Both graph_id and graph_name can\'t be none when graph object has no \'name\' or \'id\' attribute!')