Merge pull request #588 from FlorentinD/gds-session-ref-docs

Add ref docs for GDS sessions

Author: Mats-SX

doc/sphinx/README.adoc

@@ -7,9 +7,8 @@ To build the html content, do this:
 
 1. Set working directory to the root of this repository.
 2. Install sphinx into your venv: `pip install sphinx`
-3. Build the HTML: `(cd doc/sphinx && make html)`
-4. Serve the HTML: `(cd doc/sphinx/build/ && python -m http.server 8000)`
-5. Go to `localhost:8000` in your web browser.
+3. Run `./scripts/render_api_docs`
+4. Go to `localhost:8000` in your web browser.
 
 In order to make changes, iterate on steps 3-5 above.
 

doc/sphinx/source/index.rst

@@ -31,4 +31,8 @@ This API reference manual lists all available endpoints in the Neo4j Graph Data
    model/simple_rel_embedding_model
    misc
    server_version
+   sessions/gds_sessions
+   sessions/dbms_connection_info
+   sessions/session_sizes
+   sessions/gds_property_types
 

doc/sphinx/source/sessions/dbms_connection_info.rst

@@ -0,0 +1,6 @@
+DbmsConnectionInfo
+----------------
+
+.. autoclass:: graphdatascience.session.dbms_connection_info.DbmsConnectionInfo
+    :members:
+    :inherited-members:

doc/sphinx/source/sessions/gds_property_types.rst

@@ -0,0 +1,6 @@
+GdsPropertyTypes
+----------------
+
+.. autoclass:: graphdatascience.session.schema.GdsPropertyTypes
+    :members:
+    :inherited-members:

doc/sphinx/source/sessions/gds_sessions.rst

@@ -0,0 +1,16 @@
+GDS Sessions
+----------------
+
+
+.. autoclass:: graphdatascience.session.gds_sessions.GdsSessions
+    :members:
+    :inherited-members:
+
+
+.. autoclass:: graphdatascience.session.gds_sessions.AuraAPICredentials
+    :members:
+    :inherited-members:
+
+.. autoclass:: graphdatascience.session.gds_sessions.SessionInfo
+    :members:
+    :inherited-members:

doc/sphinx/source/sessions/session_sizes.rst

@@ -0,0 +1,10 @@
+SessionSizes
+----------------
+
+.. autoclass:: graphdatascience.session.session_sizes.SessionSizeByMemory
+    :members:
+    :inherited-members:
+
+.. autoclass:: graphdatascience.session.session_sizes.SessionSizes
+    :members:
+    :inherited-members:

examples/dev/gds-sessions.ipynb

@@ -254,7 +254,7 @@
     "from graphdatascience.session import GdsSessions, AuraAPICredentials\n",
     "\n",
     "# Create a new AuraSessions object\n",
-    "sessions = GdsSessions(ds_connection=AuraAPICredentials(CLIENT_ID, CLIENT_SECRET))"
+    "sessions = GdsSessions(api_credentials=AuraAPICredentials(CLIENT_ID, CLIENT_SECRET))"
    ]
   },
   {

graphdatascience/session/dbms_connection_info.py

@@ -6,9 +6,19 @@
 
 @dataclass
 class DbmsConnectionInfo:
+    """
+    Represents the connection information for a Neo4j DBMS, such as an AuraDB instance.
+    """
+
     uri: str
     username: str
     password: str
 
     def auth(self) -> Tuple[str, str]:
+        """
+        Returns the username and password for authentication.
+
+        Returns:
+            A tuple containing the username and password.
+        """
         return self.username, self.password

graphdatascience/session/gds_sessions.py

@@ -18,6 +18,14 @@
 
 @dataclass
 class SessionInfo:
+    """
+    Represents information about a session.
+
+    Attributes:
+        name (str): The name of the session.
+        size (str): The size of the session.
+    """
+
     name: str
     size: str
     type: str
@@ -31,18 +39,39 @@ def from_specific_instance_details(cls, instance_details: InstanceSpecificDetail
 
 @dataclass
 class AuraAPICredentials:
+    """
+    Represents the credentials required for accessing the Aura API.
+
+    Attributes:
+        client_id (str): The client ID for authentication.
+        client_secret (str): The client secret for authentication.
+        tenant (Optional[str]): The tenant for authentication. Needed if a client belongs to multiple tenants.
+    """
+
     client_id: str
     client_secret: str
     tenant: Optional[str] = None
 
 
 class GdsSessions:
+    """
+    Primary API class for managing GDS sessions hosted in Neo4j Aura.
+    """
+
     # Hardcoded neo4j user as sessions are always created with this user
     GDS_SESSION_USER = "neo4j"
 
-    def __init__(self, ds_connection: AuraAPICredentials) -> None:
+    def __init__(self, api_credentials: AuraAPICredentials) -> None:
+        """
+        Initializes a new instance of the GdsSessions class.
+
+        Args:
+            api_credentials (AuraAPICredentials): The Aura API credentials used for establishing a connection.
+        """
         self._aura_api = AuraApi(
-            tenant_id=ds_connection.tenant, client_id=ds_connection.client_id, client_secret=ds_connection.client_secret
+            tenant_id=api_credentials.tenant,
+            client_id=api_credentials.client_id,
+            client_secret=api_credentials.client_secret,
         )
 
     def get_or_create(
@@ -51,6 +80,19 @@ def get_or_create(
         size: SessionSizeByMemory,
         db_connection: DbmsConnectionInfo,
     ) -> AuraGraphDataScience:
+        """
+        Retrieves an existing session with the given session name and database connection,
+        or creates a new session if one does not exist.
+
+        Args:
+            session_name (str): The name of the session.
+            size (SessionSizeByMemory): The size of the session specified by memory.
+            db_connection (DbmsConnectionInfo): The database connection information.
+
+        Returns:
+            AuraGraphDataScience: The session.
+        """
+
         connected_instance = self._try_connect(session_name, db_connection)
         if connected_instance is not None:
             return connected_instance
@@ -101,6 +143,12 @@ def delete(self, session_name: str) -> bool:
         return False
 
     def list(self) -> List[SessionInfo]:
+        """
+        Retrieves the list of GDS sessions visible by the user asscociated by the given api-credentials.
+
+        Returns:
+            A list of SessionInfo objects representing the GDS sessions.
+        """
         all_instances = self._aura_api.list_instances()
         instance_details = [
             self._aura_api.list_instance(instance_id=instance.id)

graphdatascience/session/schema.py

@@ -5,6 +5,10 @@
 
 
 class GdsPropertyTypes(Enum):
+    """
+    Enumeration of supported property types inside the node/relationship schema of graphs to project into GDS sessions.
+    """
+
     LONG = "long"
     DOUBLE = "double"
     LONG_ARRAY = "long[]"