Merge branch 'master' into dev/dev-skrub

Author: lmeyerov

CHANGELOG.md

@@ -7,6 +7,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Development]
 
+## [0.36.0 - 2025-02-05]
+
 ### Breaking
 
 * `from_cugraph` returns using the src/dst bindings of `cugraph.Graph` object instead of base `Plottable`
@@ -42,6 +44,45 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 * ci tests dgl
 * plugin tests check for module imports
 
+## [0.35.10 - 2025-01-24]
+
+### Fixes: 
+
+* Spanner: better handling of spanner_config issues: #634, #644
+
+## [0.35.9 - 2025-01-22]
+
+### Docs 
+
+* Spanner: minor changes to html and markdown in notebook for proper rendering in readthedocs 
+
+## [0.35.8 - 2025-01-22]
+
+### Docs
+
+* Spanner: fix for plots rendering in readthedocs demo notebooks
+
+
+## [0.35.7 - 2025-01-22]
+
+### Feat 
+
+* added support for Google Spanner Graph and Google Spanner `spanner_gql_to_g` and `spanner_query_to_df` 
+* added new Google Spanner Graph demo notebook 
+
+## [0.35.6 - 2025-01-11]
+
+### Docs
+
+* Fix typo in new shaping tutorial
+* Privacy-preserving analytics
+
+## [0.35.5 - 2025-01-10]
+
+### Docs
+
+* New tutorial on graph shaping
+
 ## [0.35.4 - 2024-12-28]
 
 ### Fixes

demos/demos_databases_apis/spanner/google_spanner_finance_graph.ipynb

@@ -13,6 +13,7 @@
 import docutils.nodes, os, logging, re, sys
 from docutils import nodes
 from packaging.version import Version
+from sphinx.application import Sphinx
 
 
 sys.path.insert(0, os.path.abspath("../.."))
@@ -759,12 +760,38 @@ def assert_external_images_removed(app, doctree, fromdocname):
         assert "://" not in image_uri, f"Failed to remove external image: {image_uri}"
 
 
-def setup(app):
+def setup(app: Sphinx):
     """
     Connect the replace_iframe_src function to the doctree-resolved event.
     """    
+    
     app.connect("doctree-resolved", ignore_svg_images_for_latex)
     app.connect("doctree-resolved", remove_external_images_for_latex)
     app.connect('doctree-resolved', replace_iframe_src)
     app.connect("doctree-resolved", assert_external_images_removed)
-    app.add_css_file('graphistry.css', priority=900)
+
+    def on_builder(app: Sphinx) -> None:
+        if not hasattr(app, 'builder'):
+            print('No app.builder found for app type=', type(app))
+            # use dir to enumerate field names & types
+            attr_and_types: str = '\n'.join([f'{name}: {type(getattr(app, name))}' for name in dir(app)])
+            print(f'attr_and_types:\n---\n{attr_and_types}\n---\n')
+            return
+
+        if (app.builder.name == "html" or app.builder.name == "readthedocs"):
+            app.add_css_file('graphistry.css', priority=900)
+            app.add_js_file("https://plausible.io/js/script.hash.outbound-links.js", **{
+                "defer": "true",
+                "data-domain": "pygraphistry.readthedocs.io",
+            })
+            app.add_js_file(None, body="""
+                window.plausible = window.plausible || function() {
+                    (window.plausible.q = window.plausible.q || []).push(arguments)
+                }
+            """)
+            return
+        
+        print('No custom handling for app.builder.name=', app.builder.name)
+
+    app.connect('builder-inited', on_builder)
+

demos/more_examples/simple/table_to_graph_three_ways.ipynb

@@ -11,3 +11,5 @@ Getting Started
    For developers <../demos/for_developers.ipynb>
 
    CSV upload miniapp <../demos/upload_csv_miniapp.ipynb>
+
+   Visually analyze any table as a graph: Our 3 favorite shapings <../demos/more_examples/simple/table_to_graph_three_ways.ipynb>

docs/source/conf.py

@@ -21,6 +21,7 @@ Plugins - Data Providers
    Titan <../demos/demos_databases_apis/gremlin-tinkerpop/TitanDemo.ipynb>
    Neo4j - Official <../demos/demos_databases_apis/neo4j/official/graphistry_bolt_tutorial_public.ipynb>
    Neo4j - Contributed <../demos/demos_databases_apis/neo4j/contributed/Neo4jTwitter.ipynb>
+   Google Spanner - Finance Graph <../demos/demos_databases_apis/spanner/google_spanner_finance_graph.ipynb>
    SQL - Postgres <../demos/demos_databases_apis/sql/postgres.ipynb>
    Tigergraph: Bindings <../demos/demos_databases_apis/tigergraph/tigergraph_pygraphistry_bindings.ipynb>
    Tigergraph: Fraud <../demos/demos_databases_apis/tigergraph/fraud_raw_REST_calls.ipynb>

docs/source/notebooks/intro.rst

@@ -23,6 +23,7 @@ Graph
 * `Gremlin <https://tinkerpop.apache.org>`_ (:class:`graphistry.gremlin.GremlinMixin`)
 * `Memgraph <https://memgraph.com>`_ (:meth:`graphistry.PlotterBase.PlotterBase.cypher`)
 * `Neo4j <https://neo4j.com>`_ (:meth:`graphistry.PlotterBase.PlotterBase.cypher`)
+* `Google Spanner Graph <https://cloud.google.com/spanner/docs/graph/overview>`_ (:meth:`graphistry.PlotterBase.PlotterBase.spanner_gql_to_g`)
 * `TigerGraph <https://www.tigergraph.com>`_ (:meth:`graphistry.PlotterBase.PlotterBase.gsql`)
 * `Trovares <https://trovares.com>`_
 

docs/source/notebooks/plugins.connectors.rst

@@ -65,7 +65,8 @@ class Plottable(object):
     _complex_encodings : dict
     _bolt_driver : Any
     _tigergraph : Any
-
+    _spannergraph: Any
+    
     _dataset_id: Optional[str]
     _url: Optional[str]
     _nodes_file_id: Optional[str]

docs/source/plugins.rst

@@ -35,6 +35,7 @@
     end_node_id_key,
     to_bolt_driver)
 
+
 from .arrow_uploader import ArrowUploader
 from .nodexlistry import NodeXLGraphistry
 from .tigeristry import Tigeristry
@@ -176,6 +177,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         # Integrations
         self._bolt_driver : Any = None
         self._tigergraph : Any = None
+        self._spannergraph: Any
 
         # feature engineering
         self._node_embedding = None
@@ -2271,7 +2273,31 @@ def bolt(self, driver):
         res = copy.copy(self)
         res._bolt_driver = to_bolt_driver(driver)
         return res
+    
+    def spanner_init(self: Plottable, spanner_config: Dict[str, str]) -> Plottable:
+        """
+        Initializes a SpannerGraph object with the provided configuration and connects to the instance db
+
+        spanner_config dict must contain the include the following keys, credentials_file is optional:
+            - "project_id": The GCP project ID.
+            - "instance_id": The Spanner instance ID.
+            - "database_id": The Spanner database ID.
+            - "credentials_file": json file API key for service accounts 
+
+        :param spanner_config A dictionary containing the Spanner configuration. 
+        :type (Dict[str, str])
+        :return: Plottable with a Spanner connection 
+        :rtype: Plottable
+        :raises ValueError: If any of the required keys in `spanner_config` are missing or have invalid values.
+
+        """
+        from .plugins.spannergraph import SpannerGraph
 
+        res = copy.copy(self)
+
+        res._spannergraph = SpannerGraph(res, spanner_config)
+        logger.debug("Created SpannerGraph object: {res._spannergraph}")
+        return res
 
     def infer_labels(self):
         """
@@ -2460,6 +2486,114 @@ def cypher(self, query: str, params: Dict[str, Any] = {}) -> Plottable:
             )\
             .nodes(nodes)\
             .edges(edges)
+    
+    
+    def spanner_gql_to_g(self: Plottable, query: str) -> Plottable:
+        """
+        Submit GQL query to google spanner graph database and return Plottable with nodes and edges populated  
+        
+        GQL must be a path query with a syntax similar to the following, it's recommended to return the path with
+        SAFE_TO_JSON(p), TO_JSON() can also be used, but not recommend. LIMIT is optional, but for large graphs with millions
+        of edges or more, it's best to filter either in the query or use LIMIT so as not to exhaust GPU memory.  
+
+        query=f'''GRAPH my_graph
+        MATCH p = (a)-[b]->(c) LIMIT 100000 return SAFE_TO_JSON(p) as path'''
+
+        :param query: GQL query string 
+        :type query: Str
+
+        :returns: Plottable with the results of GQL query as a graph
+        :rtype: Plottable
+
+        **Example: calling spanner_gql_to_g
+                ::
+
+                    import graphistry
+
+                    # credentials_file is optional, all others are required
+                    SPANNER_CONF = { "project_id":  PROJECT_ID,                 
+                                     "instance_id": INSTANCE_ID, 
+                                     "database_id": DATABASE_ID, 
+                                     "credentials_file": CREDENTIALS_FILE }
+
+                    graphistry.register(..., spanner_config=SPANNER_CONF)
+
+                    query=f'''GRAPH my_graph
+                    MATCH p = (a)-[b]->(c) LIMIT 100000 return SAFE_TO_JSON(p) as path'''
+
+                    g = graphistry.spanner_gql_to_g(query)
+
+                    g.plot()
+     
+        """
+        from .pygraphistry import PyGraphistry
+        from .plugins.spannergraph import SpannerGraph
+
+        res = copy.copy(self)
+        
+        if not hasattr(res, '_spannergraph'):
+            spanner_config = PyGraphistry._config.get("spanner", None)
+
+            if spanner_config is not None: 
+                logger.debug(f"Spanner Config: {spanner_config}")
+            else: 
+                raise ValueError('spanner_config not defined. Pass spanner_config via register() and retry query.')
+        
+            res = res.spanner_init(spanner_config)  # type: ignore[attr-defined]
+
+        return res._spannergraph.gql_to_graph(res, query)
+
+    def spanner_query_to_df(self: Plottable, query: str) -> pd.DataFrame:
+        """
+
+        Submit query to google spanner database and return a df of the results 
+        
+        query can be SQL or GQL as long as table of results are returned 
+
+        query='SELECT * from Account limit 10000'
+
+        :param query: query string 
+        :type query: Str
+
+        :returns: Pandas DataFrame with the results of query
+        :rtype: pd.DataFrame
+
+        **Example: calling spanner_query_to_df
+                ::
+
+                    import graphistry
+
+                    # credentials_file is optional, all others are required
+                    SPANNER_CONF = { "project_id":  PROJECT_ID,                 
+                                     "instance_id": INSTANCE_ID, 
+                                     "database_id": DATABASE_ID, 
+                                     "credentials_file": CREDENTIALS_FILE }
+
+                    graphistry.register(..., spanner_config=SPANNER_CONF)
+
+                    query='SELECT * from Account limit 10000'
+
+                    df = graphistry.spanner_query_to_df(query)
+
+                    g.plot()
+     
+        """
+
+        from .pygraphistry import PyGraphistry
+
+        res = copy.copy(self)
+        
+        if not hasattr(res, '_spannergraph'):
+            spanner_config = PyGraphistry._config["spanner"]
+            if spanner_config is not None: 
+                logger.debug(f"Spanner Config: {spanner_config}")
+            else: 
+                logger.warning('PyGraphistry._config["spanner"] is None')
+        
+            res = res.spanner_init(PyGraphistry._config["spanner"])  # type: ignore[attr-defined]
+
+        return res._spannergraph.query_to_df(query)
+
 
     def nodexl(self, xls_or_url, source='default', engine=None, verbose=False):
 

graphistry/Plottable.py

@@ -31,6 +31,9 @@
     bolt,
     cypher,
     tigergraph,
+    spanner_gql_to_g,
+    spanner_query_to_df,
+    spanner_init,
     gsql,
     gsql_endpoint,
     cosmos,