diff --git a/docs/Makefile b/docs/Makefile index f4c186009f58..b33e054fac4d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -36,6 +36,11 @@ clean: @echo "Tag is:" $(TAG) @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)/$(TAG)" $(SPHINXOPTS) $(O) + @echo "Building Interactive Java SDK doc" + + cd ${WORKING_DIR}/../flex/interactive/sdk/java && \ + mvn javadoc::javadoc -Djavadoc.output.directory=${WORKING_DIR}/$(BUILDDIR)/${TAG}/$@/flex/interactive/development/java/ -Djavadoc.output.destDir=reference + @echo "Building Java doc to $(BUILDDIR)/${TAG}/$@/reference/gae_java" cd ${WORKING_DIR}/../analytical_engine/java && \ @@ -60,6 +65,8 @@ interactive-sdk: @cd ${WORKING_DIR}/../flex/interactive/sdk/ && ./generate_sdk.sh -g java \ && ./generate_sdk.sh -g python + @cd ${WORKING_DIR}/../flex/interactive/sdk/python && pip3 install -r requirements.txt && python3 setup.py build_proto && pip3 install . + @cd ${WORKING_DIR}/../flex/interactive/sdk/ && bash generate_sdk_doc.sh -o ${WORKING_DIR}/flex/interactive/development/ coordinator-sdk-doc: diff --git a/docs/flex/interactive/development/java/EdgeApi.md b/docs/flex/interactive/development/java/EdgeApi.md index 2119374bf99d..17765c548bed 100644 --- a/docs/flex/interactive/development/java/EdgeApi.md +++ b/docs/flex/interactive/development/java/EdgeApi.md @@ -1,4 +1,5 @@ -# EdgeAPi +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst +# EdgeAPI All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -12,7 +13,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **addEdge** -> Result<String> addEdge(graphId, edgeRequest) +> [Result][Result-doc]<String> addEdge(graphId, edgeRequest) Add edge to the graph. @@ -72,7 +73,7 @@ public class Example { ### Return type -**String** +[Result][Result-doc]<**String**> ### Authorization @@ -93,7 +94,7 @@ No authorization required # **getEdge** -> Result<EdgeData> getEdge(graphId, edgeLabel, srcLabel, srcPrimaryKeyValue, dstLabel, dstPrimaryKeyValue) +> [Result][Result-doc]<EdgeData> getEdge(graphId, edgeLabel, srcLabel, srcPrimaryKeyValue, dstLabel, dstPrimaryKeyValue) Get the edge's properties with src and dst vertex primary keys. @@ -162,7 +163,7 @@ No authorization required # **updateEdge** -> Result<String> updateEdge(graphId, edgeRequest) +> [Result][Result-doc]<String> updateEdge(graphId, edgeRequest) Update edge's property @@ -209,7 +210,7 @@ public class Example { ### Return type -**String** +[Result][Result-doc]<**String**> ### Authorization diff --git a/docs/flex/interactive/development/java/GraphManagementApi.md b/docs/flex/interactive/development/java/GraphManagementApi.md index 58a9f634d523..7a53baa6a6a3 100644 --- a/docs/flex/interactive/development/java/GraphManagementApi.md +++ b/docs/flex/interactive/development/java/GraphManagementApi.md @@ -1,3 +1,5 @@ +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst + # GraphManagementApi All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -15,7 +17,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **ListGraphs** -> Result<List<GetGraphResponse>> getAllGraphs() +> [Result][Result-doc]<List<GetGraphResponse>> getAllGraphs() @@ -51,7 +53,7 @@ None. ### Return type -[**Result<List<GetGraphResponse>>**](GetGraphResponse.md) +[Result][Result-doc]<List<[GetGraphResponse](GetGraphResponse.md)>> ### Authorization @@ -70,7 +72,7 @@ No authorization required # **CreateGraph** -> Result<CreateGraphResponse> createGraph(createGraphRequest) +> [Result][Result-doc]<CreateGraphResponse> createGraph(createGraphRequest) @@ -159,7 +161,7 @@ public class Example { ### Return type -[**Result<CreateGraphResponse>**](CreateGraphResponse.md) +[Result][Result-doc]<[CreateGraphResponse](CreateGraphResponse.md)> ### Authorization @@ -180,7 +182,7 @@ No authorization required # **BulkLoading** -> Result<JobResponse> bulkLoading(graphId, schemaMapping) +> [Result][Result-doc]<JobResponse> bulkLoading(graphId, schemaMapping) @@ -313,7 +315,7 @@ public class Example { ### Return type -[**Result<JobResponse>**](JobResponse.md) +[Result][Result-doc]<[JobResponse](JobResponse.md)> ### Authorization @@ -331,7 +333,7 @@ No authorization required # **DeleteGraph** -> Result<String> deleteGraph(graphId) +> [Result][Result-doc]<String> deleteGraph(graphId) @@ -370,7 +372,7 @@ public class Example { ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization @@ -390,7 +392,7 @@ No authorization required # **GetGraphMeta** -> Result<GetGraphResponse> getGraphMeta(graphId) +> [Result][Result-doc]<GetGraphResponse> getGraphMeta(graphId) @@ -428,7 +430,7 @@ public class Example { ### Return type -[**Result<GetGraphResponse>**](GetGraphResponse.md) +[Result][Result-doc]<[GetGraphResponse](GetGraphResponse.md)> ### Authorization @@ -542,7 +544,7 @@ public class Example { ### Return type -[**Result<GetGraphSchemaResponse>**](GetGraphSchemaResponse.md) +[Result][Result-doc]<[GetGraphSchemaResponse](GetGraphSchemaResponse.md)> ### Authorization diff --git a/docs/flex/interactive/development/java/JobManagementApi.md b/docs/flex/interactive/development/java/JobManagementApi.md index 0ac14a55f9d1..14d7dc1e9ad3 100644 --- a/docs/flex/interactive/development/java/JobManagementApi.md +++ b/docs/flex/interactive/development/java/JobManagementApi.md @@ -1,3 +1,5 @@ +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst + # JobManagementApi All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -11,7 +13,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **CancelJob** -> Result<String> cancelJob(jobId) +> [Result][Result-doc]<String> cancelJob(jobId) See [bulkLoading](GraphManagementApi.md#bulkloading) about how to submit a bulk loading job. @@ -47,7 +49,7 @@ public class Example { ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization @@ -65,7 +67,7 @@ No authorization required # **GetJobById** -> Result<JobStatus> getJobById(jobId) +> [Result][Result-doc]<JobStatus> getJobById(jobId) @@ -100,7 +102,7 @@ public class Example { ### Return type -[**Result<JobStatus>**](JobStatus.md) +[Result][Result-doc]<[JobStatus](JobStatus.md)> ### Authorization @@ -149,7 +151,7 @@ This endpoint does not need any parameter. ### Return type -[**Result<List<JobStatus>>**](JobStatus.md) +[Result][Result-doc]<List<[JobStatus](JobStatus.md)>> ### Authorization diff --git a/docs/flex/interactive/development/java/ProcedureManagementApi.md b/docs/flex/interactive/development/java/ProcedureManagementApi.md index 751e222d8a2f..5d4b1d571c7d 100644 --- a/docs/flex/interactive/development/java/ProcedureManagementApi.md +++ b/docs/flex/interactive/development/java/ProcedureManagementApi.md @@ -1,3 +1,5 @@ +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst + # ProcedureManagementApi All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -13,7 +15,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **CreateProcedure** -> Result<CreateProcedureResponse> createProcedure(graphId, createProcedureRequest) +> [Result][Result-doc]<CreateProcedureResponse> createProcedure(graphId, createProcedureRequest) Create a new procedure on a graph with give id. @@ -60,7 +62,7 @@ public class Example { ### Return type -[**Result<CreateProcedureResponse>**](CreateProcedureResponse.md) +[Result][Result-doc]<[CreateProcedureResponse](CreateProcedureResponse.md)> ### Authorization @@ -81,7 +83,7 @@ No authorization required # **DeleteProcedure** -> Result<String> deleteProcedure(graphId, procedureId) +> [Result][Result-doc]<String> deleteProcedure(graphId, procedureId) @@ -120,7 +122,7 @@ public class Example { ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization @@ -178,7 +180,7 @@ public class Example { ### Return type -[**Result<GetProcedureResponse>**](GetProcedureResponse.md) +[Result][Result-doc]<[GetProcedureResponse](GetProcedureResponse.md)> ### Authorization @@ -197,7 +199,7 @@ No authorization required # **ListProcedures** -> Result<List<GetProcedureResponse>> listProcedures(graphId) +> [Result][Result-doc]<List<GetProcedureResponse>> listProcedures(graphId) @@ -237,7 +239,7 @@ public class Example { ### Return type -[**Result<List<GetProcedureResponse>>**](GetProcedureResponse.md) +[Result][Result-doc]]<List<[GetProcedureResponse](GetProcedureResponse.md)>> ### Authorization @@ -301,7 +303,7 @@ public class Example { ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization diff --git a/docs/flex/interactive/development/java/QueryServiceApi.md b/docs/flex/interactive/development/java/QueryServiceApi.md index a1227b43eb5c..5d23dc3c0172 100644 --- a/docs/flex/interactive/development/java/QueryServiceApi.md +++ b/docs/flex/interactive/development/java/QueryServiceApi.md @@ -1,3 +1,5 @@ +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst + # QueryServiceApi All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -14,7 +16,7 @@ If you attempt to submit a query to a graph that is not currently running, we wi # **CallProcedure** -> Result<IrResult.CollectiveResults> callProcedure(graphId, request) +> [Result][Result-doc]<IrResult.CollectiveResults> callProcedure(graphId, request) Submit procedure call queries to the specified graph. The output format for the query is define by the [results.proto](https://github.com/alibaba/GraphScope/blob/main/interactive_engine/executor/ir/proto/results.proto). @@ -69,7 +71,7 @@ public class Example { ### Return type -**Result<IrResult.CollectiveResults>** +[Result][Result-doc]<IrResult.CollectiveResults> ### Authorization @@ -88,7 +90,7 @@ No authorization required # **CallProcedureOnCurrentGraph** -> Result<IrResult.CollectiveResults> callProcedure(body) +> [Result][Result-doc]<IrResult.CollectiveResults> callProcedure(body) Submit a query to the running graph. @@ -139,7 +141,7 @@ public class Example { ### Return type -**Result<IrResult.CollectiveResults>** +[Result][Result-doc]<IrResult.CollectiveResults> ### Authorization diff --git a/docs/flex/interactive/development/java/ServiceManagementApi.md b/docs/flex/interactive/development/java/ServiceManagementApi.md index 39426b8644e1..000e9488c494 100644 --- a/docs/flex/interactive/development/java/ServiceManagementApi.md +++ b/docs/flex/interactive/development/java/ServiceManagementApi.md @@ -1,3 +1,5 @@ +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst + # ServiceManagementApi All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -12,7 +14,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **GetServiceStatus** -> ServiceStatus getServiceStatus() +> [Result][Result-doc]<ServiceStatus> getServiceStatus() @@ -47,7 +49,7 @@ This endpoint does not need any parameter. ### Return type -[**Result<ServiceStatus>**](ServiceStatus.md) +[Result][Result-doc]<[ServiceStatus](./ServiceStatus.md)> ### Authorization @@ -65,7 +67,7 @@ No authorization required # **RestartService** -> String restartService() +> [Result][Result-doc]<String> restartService() @@ -100,7 +102,7 @@ This endpoint does not need any parameter. ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization @@ -118,7 +120,7 @@ No authorization required # **StartService** -> Result<String> startService(startServiceRequest) +> [Result][Result-doc]<String> startService(startServiceRequest) @@ -155,7 +157,7 @@ public class Example { ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization @@ -174,7 +176,7 @@ No authorization required # **StopService** -> Result<String> stopService() +> [Result][Result-doc]<String> stopService() @@ -209,7 +211,7 @@ This endpoint does not need any parameter. ### Return type -**Result<String>** +[Result][Result-doc]<String> ### Authorization diff --git a/docs/flex/interactive/development/java/VertexApi.md b/docs/flex/interactive/development/java/VertexApi.md index f4e7d7402e69..f863da39b73e 100644 --- a/docs/flex/interactive/development/java/VertexApi.md +++ b/docs/flex/interactive/development/java/VertexApi.md @@ -1,3 +1,5 @@ +[Result-doc]: ./reference/com/alibaba/graphscope/interactive/client/common/Result.rst + # VertexApi All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -12,7 +14,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **addVertex** -> Result<String> addVertex(graphId, vertexEdgeRequest) +> [Result][Result-doc]<String> addVertex(graphId, vertexEdgeRequest) Add vertex to the graph. @@ -62,7 +64,7 @@ public class Example { ### Return type -**String** +[Result][Result-doc]<String> ### Authorization @@ -85,7 +87,7 @@ No authorization required # **getVertex** -> Result<VertexData> getVertex(graphId, label, primaryKeyValue) +> [Result][Result-doc]<VertexData> getVertex(graphId, label, primaryKeyValue) Get the vertex's properties with vertex primary key. @@ -135,7 +137,7 @@ public class Example { ### Return type -[**VertexData**](VertexData.md) +[Result][Result-doc]<[VertexData](./VertexData.md)> ### Authorization @@ -156,7 +158,7 @@ No authorization required # **updateVertex** -> Result<String> updateVertex(graphId, vertexRequest) +> [Result][Result-doc]<String> updateVertex(graphId, vertexRequest) Update the vertex's properties. @@ -201,7 +203,7 @@ public class Example { ### Return type -**String** +[Result][Result-doc]<String> ### Authorization diff --git a/docs/flex/interactive/development/java/java_sdk.md b/docs/flex/interactive/development/java/java_sdk.md index 050ceb19ee5c..279b2e9980b5 100644 --- a/docs/flex/interactive/development/java/java_sdk.md +++ b/docs/flex/interactive/development/java/java_sdk.md @@ -461,6 +461,18 @@ Class | Method | HTTP request | Description Delete Vertex/Edge is currently not supported by Interactive. ``` +## Documentation for Utilities APIs + +In addition to the documentation for service APIs, we also offer documentation for [Utility APIs](./reference/index.rst). + +- [Driver](./reference/com/alibaba/graphscope/interactive/client/Driver.rst) +- [Session](./reference/com/alibaba/graphscope/interactive/client/Session.rst) +- [DefaultSession](./reference/com/alibaba/graphscope/interactive/client/impl/DefaultSession.rst) +- [Status](./reference/com/alibaba/graphscope/interactive/client/common/Status.rst) +- [Result](./reference/com/alibaba/graphscope/interactive/client/common/Result.rst) +- [Encoder](./reference/com/alibaba/graphscope/interactive/client/utils/Encoder.rst) +- [Decoder](./reference/com/alibaba/graphscope/interactive/client/utils/Encoder.rst) + ## Documentation for Data Structures diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/Driver.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/Driver.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/Session.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/Session.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/common/Result.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/common/Result.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/common/Status.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/common/Status.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/impl/DefaultSession.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/impl/DefaultSession.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/utils/Decoder.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/utils/Decoder.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/utils/Encoder.rst b/docs/flex/interactive/development/java/reference/com/alibaba/graphscope/interactive/client/utils/Encoder.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/java/reference/index.rst b/docs/flex/interactive/development/java/reference/index.rst new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/docs/flex/interactive/development/python/EdgeApi.md b/docs/flex/interactive/development/python/EdgeApi.md index 442127dc6a29..17dd90b479b9 100644 --- a/docs/flex/interactive/development/python/EdgeApi.md +++ b/docs/flex/interactive/development/python/EdgeApi.md @@ -10,7 +10,7 @@ Method | HTTP request | Description # **add_edge** -> Result[str] add_edge(graph_id, edge_request) +> [Result](./result.rst)[str] add_edge(graph_id, edge_request) Add a edge to the graph. @@ -62,7 +62,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[str] ### Authorization @@ -86,7 +86,7 @@ No authorization required # **get_edge** -> Result[EdgeData] get_edge(graph_id, edge_label, src_label, src_primary_key_value, dst_label, dst_primary_key_value) +> [Result](./result.rst)[EdgeData] get_edge(graph_id, edge_label, src_label, src_primary_key_value, dst_label, dst_primary_key_value) Get the edge's properties with src and dst vertex primary keys. @@ -130,7 +130,7 @@ Name | Type | Description | Notes ### Return type -[**EdgeData**](EdgeData.md) +[Result](./result.rst)[[EdgeData](EdgeData.md)] ### Authorization @@ -153,7 +153,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **update_edge** -> Result[str] update_edge(graph_id, edge_request=edge_request) +> [Result](./result.rst)[str] update_edge(graph_id, edge_request=edge_request) Update edge's property @@ -198,7 +198,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[str] ### Authorization diff --git a/docs/flex/interactive/development/python/GraphManagementApi.md b/docs/flex/interactive/development/python/GraphManagementApi.md index e9507008fd69..9bfcc906b02c 100644 --- a/docs/flex/interactive/development/python/GraphManagementApi.md +++ b/docs/flex/interactive/development/python/GraphManagementApi.md @@ -1,4 +1,4 @@ -# GraphManagementApi +# GraphManagementApI All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* @@ -15,7 +15,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **CreateGraph** -> Result[CreateGraphResponse] create_graph(create_graph_request) +> [Result](./result.rst)[CreateGraphResponse] create_graph(create_graph_request) @@ -94,7 +94,8 @@ Name | Type | Description | Notes ### Return type -[**CreateGraphResponse**](CreateGraphResponse.md) +[Reesult](./result.rst)[[**CreateGraphResponse**](CreateGraphResponse.md)] + ### Authorization @@ -118,7 +119,7 @@ No authorization required # **DeleteGraph** -> Result[str] delete_graph(graph_id) +> [Result](./result.rst)[str] delete_graph(graph_id) @@ -144,7 +145,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization @@ -192,7 +193,7 @@ Name | Type | Description | Notes ### Return type -[**GetGraphResponse**](GetGraphResponse.md) +[Result](./result.rst)[[**GetGraphResponse**](GetGraphResponse.md)] ### Authorization @@ -239,7 +240,7 @@ Name | Type | Description | Notes ### Return type -[**GetGraphStatisticsResponse**](GetGraphStatisticsResponse.md) +[Result](./result.rst)[[**GetGraphStatisticsResponse**](GetGraphStatisticsResponse.md)] ### Authorization @@ -262,7 +263,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **GetGraphSchema** -> Result[GetGraphSchemaResponse] get_graph_schema(graph_id) +> [Result](./result.rst)[GetGraphSchemaResponse] get_graph_schema(graph_id) @@ -288,7 +289,7 @@ Name | Type | Description | Notes ### Return type -[**GetGraphSchemaResponse**](GetGraphSchemaResponse.md) +[Result](./result.rst)[[**GetGraphSchemaResponse**](GetGraphSchemaResponse.md)] ### Authorization @@ -308,7 +309,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **ListGraphs** -> Result[List[GetGraphResponse]] list_graphs() +> [Result](./result.rst)[List[GetGraphResponse]] list_graphs() @@ -331,7 +332,7 @@ This endpoint does not need any parameter. ### Return type -[**List[GetGraphResponse]**](GetGraphResponse.md) +[Result](./result.rst)[[**List[GetGraphResponse]**](GetGraphResponse.md)] ### Authorization @@ -352,7 +353,7 @@ No authorization required # **BulkLoading** -> Result[JobResponse] bulk_loading(graph_id, schema_mapping) +> [Result](./result.rst)[JobResponse] bulk_loading(graph_id, schema_mapping) @@ -415,7 +416,7 @@ Name | Type | Description | Notes ### Return type -[**JobResponse**](JobResponse.md) +[Result](./result.rst)[[**JobResponse**](JobResponse.md)] ### Authorization diff --git a/docs/flex/interactive/development/python/JobManagementApi.md b/docs/flex/interactive/development/python/JobManagementApi.md index 07c2992732aa..d483eecaf181 100644 --- a/docs/flex/interactive/development/python/JobManagementApi.md +++ b/docs/flex/interactive/development/python/JobManagementApi.md @@ -9,7 +9,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* | [**ListJobs**](JobManagementApi.md#ListJobs) | **GET** /v1/job | List all jobs(including history jobs) | # **CancelJob** -> Result[str] cancel_job(job_id) +> [Result](./result.rst)[str] cancel_job(job_id) @@ -42,7 +42,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization @@ -62,7 +62,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **GetJobById** -> Result[JobStatus] get_job(job_id) +> [Result](./result.rst)[JobStatus] get_job(job_id) @@ -87,7 +87,7 @@ Name | Type | Description | Notes ### Return type -[**JobStatus**](JobStatus.md) +[Result](./result.rst)[[**JobStatus**](JobStatus.md)] ### Authorization @@ -107,7 +107,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **ListJobs** -> Result[List[JobStatus]] list_jobs() +> [Result](./result.rst)[List[JobStatus]] list_jobs() @@ -128,7 +128,7 @@ This endpoint does not need any parameter. ### Return type -[**List[JobStatus]**](JobStatus.md) +[Result](./result.rst)[[**List[JobStatus]**](JobStatus.md)] ### Authorization diff --git a/docs/flex/interactive/development/python/ProcedureManagementApi.md b/docs/flex/interactive/development/python/ProcedureManagementApi.md index e6538b0c8d00..86a8cc623c69 100644 --- a/docs/flex/interactive/development/python/ProcedureManagementApi.md +++ b/docs/flex/interactive/development/python/ProcedureManagementApi.md @@ -13,7 +13,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **CreateProcedure** -> Result[CreateProcedureResponse] create_procedure(graph_id, create_procedure_request) +> [Result](./result.rst)[CreateProcedureResponse] create_procedure(graph_id, create_procedure_request) @@ -105,7 +105,7 @@ Name | Type | Description | Notes ### Return type -[**CreateProcedureResponse**](CreateProcedureResponse.md) +[Result](./result.rst)[[**CreateProcedureResponse**](CreateProcedureResponse.md)] ### Authorization @@ -128,7 +128,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **DeleteProcedure** -> Result[str] delete_procedure(graph_id, procedure_id) +> [Result](./result.rst)[str] delete_procedure(graph_id, procedure_id) @@ -155,7 +155,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization @@ -176,7 +176,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **GetProcedure** -> Result[GetProcedureResponse] get_procedure(graph_id, procedure_id) +> [Result](./result.rst)[GetProcedureResponse] get_procedure(graph_id, procedure_id) @@ -203,7 +203,7 @@ Name | Type | Description | Notes ### Return type -[**GetProcedureResponse**](GetProcedureResponse.md) +[Result](./result.rst)[[**GetProcedureResponse**](GetProcedureResponse.md)] ### Authorization @@ -224,7 +224,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **ListProcedures** -> Result[List[GetProcedureResponse]] list_procedures(graph_id) +> [Result](./result.rst)[List[GetProcedureResponse]] list_procedures(graph_id) @@ -250,7 +250,7 @@ Name | Type | Description | Notes ### Return type -[**List[GetProcedureResponse]**](GetProcedureResponse.md) +[Result](./result.rst)[[**List[GetProcedureResponse]**](GetProcedureResponse.md)] ### Authorization @@ -271,7 +271,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **UpdateProcedure** -> Result[str] update_procedure(graph_id, procedure_id, update_procedure_request=update_procedure_request) +> [Result](./result.rst)[str] update_procedure(graph_id, procedure_id, update_procedure_request=update_procedure_request) @@ -300,7 +300,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization diff --git a/docs/flex/interactive/development/python/QueryServiceApi.md b/docs/flex/interactive/development/python/QueryServiceApi.md index 807067b84ac3..df009abdfc5d 100644 --- a/docs/flex/interactive/development/python/QueryServiceApi.md +++ b/docs/flex/interactive/development/python/QueryServiceApi.md @@ -13,7 +13,7 @@ If you attempt to submit a query to a graph that is not currently running, we wi # **CallProcedure** -> Result[CollectiveResults] call_procedure(graph_id, params) +> [Result](./result.rst)[CollectiveResults] call_procedure(graph_id, params) Submit procedure call queries to the specified graph. The output format for the query is define by the [results.proto](https://github.com/alibaba/GraphScope/blob/main/interactive_engine/executor/ir/proto/results.proto). @@ -55,7 +55,7 @@ Name | Type | Description | Notes ### Return type -**CollectiveResults** +[Result](./result.rst)[**CollectiveResults**] ### Authorization @@ -76,7 +76,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **CallProcedureOnCurrentGraph** -> Result[CollectiveResults] call_procedure_current(params) +> [Result](./result.rst)[CollectiveResults] call_procedure_current(params) run queries on the running graph @@ -116,7 +116,7 @@ Name | Type | Description | Notes ### Return type -**CollectiveResults** +[Result](./result.rst)[**CollectiveResults**] ### Authorization diff --git a/docs/flex/interactive/development/python/ServiceManagementApi.md b/docs/flex/interactive/development/python/ServiceManagementApi.md index 40ceb1d9048f..d2da72bd54a6 100644 --- a/docs/flex/interactive/development/python/ServiceManagementApi.md +++ b/docs/flex/interactive/development/python/ServiceManagementApi.md @@ -11,7 +11,7 @@ All URIs are relative to *{INTERACTIVE_ADMIN_ENDPOINT}* # **GetServiceStatus** -> Result[ServiceStatus] get_service_status() +> [Result](./result.rst)[ServiceStatus] get_service_status() @@ -34,7 +34,7 @@ This endpoint does not need any parameter. ### Return type -[**ServiceStatus**](ServiceStatus.md) +[Result](./result.rst)[[**ServiceStatus**](ServiceStatus.md)] ### Authorization @@ -54,7 +54,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **RestartService** -> Result[str] restart_service() +> [Result](./result.rst)[str] restart_service() @@ -77,7 +77,7 @@ This endpoint does not need any parameter. ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization @@ -97,7 +97,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **StartService** -> Result[str] start_service(start_service_request=start_service_request) +> [Result](./result.rst)[str] start_service(start_service_request=start_service_request) @@ -125,7 +125,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization @@ -146,7 +146,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **StopService** -> Result[str] stop_service() +> [Result](./result.rst)[str] stop_service() @@ -169,7 +169,7 @@ This endpoint does not need any parameter. ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization diff --git a/docs/flex/interactive/development/python/VertexApi.md b/docs/flex/interactive/development/python/VertexApi.md index 7248068454f0..912840dfebb8 100644 --- a/docs/flex/interactive/development/python/VertexApi.md +++ b/docs/flex/interactive/development/python/VertexApi.md @@ -10,7 +10,7 @@ Method | HTTP request | Description # **add_vertex** -> Result[str] add_vertex(graph_id, vertex_edge_request) +> [Result](./result.rst)[str] add_vertex(graph_id, vertex_edge_request) Add the provided vertex to the specified graph. @@ -57,7 +57,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization @@ -82,7 +82,7 @@ No authorization required # **get_vertex** -> Result[VertexData] get_vertex(graph_id, label, primary_key_value) +> [Result](./result.rst)[VertexData] get_vertex(graph_id, label, primary_key_value) Get the vertex's properties with vertex primary key. @@ -126,7 +126,7 @@ Name | Type | Description | Notes ### Return type -[**VertexData**](VertexData.md) +[Result](./result.rst)[[**VertexData**](VertexData.md)] ### Authorization @@ -149,7 +149,7 @@ No authorization required [[Back to top]](#) [[Back to API list]](python_sdk.md#documentation-for-service-apis) [[Back to Model list]](python_sdk.md#documentation-for-data-structures) [[Back to python_sdk]](python_sdk.md) # **update_vertex** -> Result[str] update_vertex(graph_id, vertex_request=vertex_request) +> [Result](./result.rst)[str] update_vertex(graph_id, vertex_request=vertex_request) Update vertex's property @@ -194,7 +194,7 @@ Name | Type | Description | Notes ### Return type -**str** +[Result](./result.rst)[**str**] ### Authorization diff --git a/docs/flex/interactive/development/python/driver.rst b/docs/flex/interactive/development/python/driver.rst new file mode 100644 index 000000000000..ed65b42294e5 --- /dev/null +++ b/docs/flex/interactive/development/python/driver.rst @@ -0,0 +1,13 @@ +.. _driver: + +Driver +======= + +Driver Class +-------------- +.. automodule:: gs_interactive.client.driver +.. autoclass:: gs_interactive.client.driver.Driver + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + diff --git a/docs/flex/interactive/development/python/encoder.rst b/docs/flex/interactive/development/python/encoder.rst new file mode 100644 index 000000000000..2e41bdd066af --- /dev/null +++ b/docs/flex/interactive/development/python/encoder.rst @@ -0,0 +1,22 @@ +.. _encoder: + +Encoder and Deocder +=================== + +Encoder Class +-------------- +.. automodule:: gs_interactive.client.utils +.. autoclass:: gs_interactive.client.utils.Encoder + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + + +Decoder Class +-------------- +.. automodule:: gs_interactive.client.utils +.. autoclass:: gs_interactive.client.utils.Decoder + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + diff --git a/docs/flex/interactive/development/python/python_sdk.md b/docs/flex/interactive/development/python/python_sdk.md index 77d5a7a84321..45e214011f66 100644 --- a/docs/flex/interactive/development/python/python_sdk.md +++ b/docs/flex/interactive/development/python/python_sdk.md @@ -4,7 +4,7 @@ The Interactive Python SDK Reference is a comprehensive guide designed to assist ## Requirements. -Python 3.7+ +Python >= 3.8 ## Installation & Usage @@ -370,11 +370,11 @@ assert resp.is_ok() print("delete graph res: ", resp) ``` -For the full example, please refer to [Java SDK Example](https://github.com/alibaba/GraphScope/tree/main/flex/interactive/sdk/examples/java/interactive-example) +For the full example, please refer to [Python SDK Example](https://github.com/alibaba/GraphScope/tree/main/flex/interactive/sdk/examples/python/basic_example.py) ## Documentation for Service APIs -The APIs in interactive SDK are divided into five categories. +The Service APIs in interactive SDK are divided into five categories. - GraphManagementApi - ProcedureManagementApi - JobManagementApi @@ -415,6 +415,13 @@ Class | Method | HTTP request | Description *EdgeApi* | [**getEdge**](./EdgeApi.md#getEdge) | **GET** /v1/graph/{graph_id}/edge | Get the edge's properties with src and dst vertex primary keys. *EdgeApi* | [**updateEdge**](./EdgeApi.md#updateEdge) | **PUT** /v1/graph/{graph_id}/edge | Update edge's property +## Documentation for Utilities APIs + +- [Driver](./driver.rst) +- [Session](./session.rst) +- [Result](./result.rst) +- [Status](./status.rst) +- [Encoder&Decoder](./encoder.rst) ## Documentation for Data Structures diff --git a/docs/flex/interactive/development/python/result.rst b/docs/flex/interactive/development/python/result.rst new file mode 100644 index 000000000000..c7f9cdb50a58 --- /dev/null +++ b/docs/flex/interactive/development/python/result.rst @@ -0,0 +1,13 @@ +.. _result: + +Result +======= + +Result Class +-------------- +.. automodule:: gs_interactive.client.result +.. autoclass:: gs_interactive.client.result.Result + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + diff --git a/docs/flex/interactive/development/python/session.rst b/docs/flex/interactive/development/python/session.rst new file mode 100644 index 000000000000..b53f6c0b7595 --- /dev/null +++ b/docs/flex/interactive/development/python/session.rst @@ -0,0 +1,22 @@ +.. _default_session: + +Session +======= + +Session Interface +-------------- +.. automodule:: gs_interactive.client.session +.. autoclass:: gs_interactive.client.session.Session + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + + +DefaultSession Class +-------------- +.. automodule:: gs_interactive.client.session +.. autoclass:: gs_interactive.client.session.DefaultSession + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + diff --git a/docs/flex/interactive/development/python/status.rst b/docs/flex/interactive/development/python/status.rst new file mode 100644 index 000000000000..a2751cf98990 --- /dev/null +++ b/docs/flex/interactive/development/python/status.rst @@ -0,0 +1,13 @@ +.. _status: + +Status +======= + +Status Class +-------------- +.. automodule:: gs_interactive.client.status +.. autoclass:: gs_interactive.client.status.Status + :special-members: + :members: + :exclude-members: __repr__, __str__, __weakref__, run + diff --git a/docs/flex/interactive/development/stored_procedure/cpp_procedure.md b/docs/flex/interactive/development/stored_procedure/cpp_procedure.md index 063e38a0ff25..197f05837d61 100644 --- a/docs/flex/interactive/development/stored_procedure/cpp_procedure.md +++ b/docs/flex/interactive/development/stored_procedure/cpp_procedure.md @@ -367,4 +367,3 @@ print(f"vertices num: {num}") To create an efficient procedure that meets your needs, it's essential to understand the programming interface and the Interactive storage interface. We recommend reading the [source code](https://github.com/alibaba/GraphScope/tree/main/flex) of Interactive, and you can also access the generated API documentation [here](https://graphscope.io/docs/reference/flex/). - diff --git a/flex/interactive/sdk/generate_sdk_doc.sh b/flex/interactive/sdk/generate_sdk_doc.sh index 0059d734e52d..6c0e615cd06c 100644 --- a/flex/interactive/sdk/generate_sdk_doc.sh +++ b/flex/interactive/sdk/generate_sdk_doc.sh @@ -15,7 +15,7 @@ # This script is used to generate the Java SDK from the Flex Interactive API # It uses the Swagger Codegen tool to generate the SDK - +set -e GENERATED_ENDPOINT="https://virtserver.swaggerhub.com/GRAPHSCOPE/InteractiveAPI/1.0.0" ENDPOINT_PLACE_HOLDER="{INTERACTIVE_ADMIN_ENDPOINT}" @@ -29,6 +29,11 @@ function usage() { function do_gen() { echo "Generating SDK documentation" + if [ "$#" -ne 1 ]; then + echo "Invalid number of arguments" + usage + exit 1 + fi OUTPUT_PATH="$1" echo "Output path: ${OUTPUT_PATH}" # First check whether java/docs and python/docs exist @@ -59,6 +64,7 @@ function do_gen() { echo "SDK documentation generated successfully." } +SOURCE_FILE_OUTPUT_DIR="" while [[ $# -gt 0 ]]; do key="$1" @@ -69,9 +75,10 @@ while [[ $# -gt 0 ]]; do exit ;; -o | --output-dir) + # do_gen "$@" + shift + SOURCE_FILE_OUTPUT_DIR="$1" shift - do_gen "$@" - exit 0 ;; *) # unknown option err "unknown option $1" @@ -79,4 +86,6 @@ while [[ $# -gt 0 ]]; do exit 1 ;; esac -done \ No newline at end of file +done + +do_gen "${SOURCE_FILE_OUTPUT_DIR}" \ No newline at end of file diff --git a/flex/interactive/sdk/java/pom.xml b/flex/interactive/sdk/java/pom.xml index 7d2d4b07b146..45b0b2ae4f88 100644 --- a/flex/interactive/sdk/java/pom.xml +++ b/flex/interactive/sdk/java/pom.xml @@ -200,15 +200,22 @@ + + + GraphScope + com.alibaba.graphscope* + + ${java.home}/bin/javadoc none - - - http.response.details - a - Http Response Details: - - + + com/alibaba/graphscope/interactive/client/**/*.java + + ${javadoc.output.directory} + ${javadoc.output.destDir} + false + false + en_US @@ -525,5 +532,7 @@ 1.6.7 2.2.1 1.37.0 + ${project.build.directory}/javadoc + reference diff --git a/flex/interactive/sdk/python/gs_interactive/client/driver.py b/flex/interactive/sdk/python/gs_interactive/client/driver.py index 78539f157135..385748683bd8 100644 --- a/flex/interactive/sdk/python/gs_interactive/client/driver.py +++ b/flex/interactive/sdk/python/gs_interactive/client/driver.py @@ -32,6 +32,11 @@ class Driver: + """ + The main entry point for the Interactive SDK. With the Interactive endpoints provided, you can create a Interactive Session to interact with the Interactive service, + and create a Neo4j Session to interact with the Neo4j service. + """ + def __init__( self, admin_endpoint: str = None, @@ -40,7 +45,14 @@ def __init__( gremlin_endpoint: str = None, ): """ - Construct a new driver with the given endpoints. + Construct a new driver using the specified endpoints. + If no endpoints are provided, the driver will read them from environment variables. + You will receive the endpoints after starting the Interactive service. + + Args: + admin_endpoint: the endpoint for the admin service. + stored_proc_endpoint (str, optional): the endpoint for the stored procedure service. + cypher_endpoint (str, optional): the endpoint for the cypher service. """ if admin_endpoint is None: self.read_endpoints_from_env() @@ -54,10 +66,13 @@ def __init__( self._neo4j_driver = None def close(self): + """ + Close the driver and release resources. + """ if self._neo4j_driver is not None: self._neo4j_driver.close() - def __del(self): + def __del__(self): self.close() def init_host_and_port(self): @@ -77,7 +92,6 @@ def read_endpoints_from_env(self): INTERACTIVE_ADMIN_ENDPOINT: http://host:port INTERACTIVE_STORED_PROC_ENDPOINT: http://host:port INTERACTIVE_CYPHER_ENDPOINT: neo4j://host:port or bolt://host:port - INTERACTIVE_GREMLIN_ENDPOINT: ws://host:port/gremlin """ self._admin_endpoint = os.environ.get("INTERACTIVE_ADMIN_ENDPOINT") assert ( @@ -100,16 +114,27 @@ def read_endpoints_from_env(self): ) def session(self) -> Session: + """ + Create a session with the specified endpoints. + """ if self._stored_proc_endpoint is not None: return DefaultSession(self._admin_endpoint, self._stored_proc_endpoint) return DefaultSession(self._admin_endpoint) def getDefaultSession(self) -> Session: + """ + Get the default session. + """ if self._session is None: self._session = self.session() return self._session def getNeo4jSession(self, **config) -> Neo4jSession: + """ + Create a neo4j session with the specified endpoints. + Args: + config: a dictionary of configuration options. The same as the ones in neo4j.Driver.session + """ return self.getNeo4jSessionImpl(**config) def getGremlinClient(self) -> str: @@ -151,10 +176,6 @@ def getGremlinClientImpl(self): return Client(graph_url, "g") def getGremlinEndpoint(self): - """ - Get the gremlin endpoint from the service status endpoint. - Only works if the sdk was running in the same pod as the service. - """ service_status = self.getDefaultSession().get_service_status() if service_status.is_ok(): gremlin_port = service_status.get_value().gremlin_port diff --git a/flex/interactive/sdk/python/gs_interactive/client/result.py b/flex/interactive/sdk/python/gs_interactive/client/result.py index eee6405dd790..29e25cbe4bb9 100644 --- a/flex/interactive/sdk/python/gs_interactive/client/result.py +++ b/flex/interactive/sdk/python/gs_interactive/client/result.py @@ -28,9 +28,18 @@ T = TypeVar("T") -# Generate a python class Result, which has two field status and value. This class can be used to wrap the execution result for interface where exception may happen class Result(Generic[T]): + """ + This is a generic class that wraps the result of an operation. It contains the status of the operation and the value returned by the operation. + """ def __init__(self, status: Status, value: T): + """ + Construct a new Result object with the specified status and value. + + Args: + status: the status of the operation. + value: the value returned by the operation. + """ self.status = status self.value = value @@ -41,35 +50,59 @@ def __repr__(self): return f"Result: {self.status}, value: {self.value}" def is_ok(self): + """ + Whether the operation is successful. + """ return self.status.is_ok() def is_error(self): + """ + Whether the operation is failed. + """ return self.status.is_error() def get_value(self): + """ + Get the value returned by the operation. + """ return self.value def get_status(self): + """ + Get the status of the operation. + """ return self.status def get_status_message(self): + """ + Get the detail message of the status. + """ return self.status.message - - def get_status(self): - return self.status @staticmethod def ok(value): + """ + A static method to create a successful result. + """ return Result(Status.ok(), value) @staticmethod def error(status: Status, msg: str): + """ + A static method to create a failed result. + """ return Result(status, msg) @staticmethod def from_exception(exception: ApiException): + """ + A static method create a Result object from an ApiException. + """ return Result(Status.from_exception(exception), None) @staticmethod def from_response(response: ApiResponse): + """ + A static method create a Result object from an successful ApiResponse. + """ return Result(Status.from_response(response), response.data) diff --git a/flex/interactive/sdk/python/gs_interactive/client/session.py b/flex/interactive/sdk/python/gs_interactive/client/session.py index 36a1a85eb0a0..c69e1a19b647 100644 --- a/flex/interactive/sdk/python/gs_interactive/client/session.py +++ b/flex/interactive/sdk/python/gs_interactive/client/session.py @@ -18,12 +18,11 @@ from abc import ABCMeta, abstractmethod from enum import Enum -from typing import Annotated, Any, Dict, List, Optional, Union +from typing_extensions import Annotated +from typing import Any, Dict, List, Optional, Union from pydantic import Field, StrictBytes, StrictStr -from pydantic import Field, StrictStr, StrictBytes - from gs_interactive.client.status import Status, StatusCode from gs_interactive.api import * @@ -279,7 +278,20 @@ class Session( class DefaultSession(Session): + """ + The default session implementation for Interactive SDK. + It provides the implementation of all service APIs. + """ + def __init__(self, admin_uri: str, stored_proc_uri: str = None): + """ + Construct a new session using the specified admin_uri and stored_proc_uri. + + Args: + admin_uri (str): the uri for the admin service. + stored_proc_uri (str, optional): the uri for the stored procedure service. If not provided, + the uri will be read from the service status. + """ self._client = ApiClient(Configuration(host=admin_uri)) self._graph_api = AdminServiceGraphManagementApi(self._client) @@ -318,6 +330,9 @@ def add_vertex( graph_id: StrictStr, vertex_edge_request: VertexEdgeRequest, ) -> Result[StrictStr]: + """ + Add a vertex to the specified graph. + """ graph_id = self.ensure_param_str("graph_id", graph_id) try: api_response = self._vertex_api.add_vertex_with_http_info(graph_id, vertex_edge_request) @@ -344,6 +359,10 @@ def get_vertex( Any, Field(description="The primary key value of vertex.") ], ) -> Result[VertexRequest]: + """ + Get a vertex from the specified graph with primary key value. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: api_response = self._vertex_api.get_vertex_with_http_info(graph_id, label, primary_key_value) @@ -355,6 +374,10 @@ def get_vertex( def update_vertex( self, graph_id: StrictStr, vertex_request: VertexRequest ) -> Result[str]: + """ + Update a vertex in the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: api_response = self._vertex_api.update_vertex_with_http_info(graph_id, vertex_request) @@ -364,6 +387,10 @@ def update_vertex( ################ Edge Interfaces ########## def add_edge(self, graph_id: StrictStr, edge_request: List[EdgeRequest]) -> Result[str]: + """ + Add an edge to the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: api_response = self._edge_api.add_edge_with_http_info(graph_id, edge_request) @@ -408,6 +435,10 @@ def get_edge( Any, Field(description="The primary key value of dst vertex.") ], ) -> Result[Union[None, EdgeRequest]]: + """ + Get an edge from the specified graph with primary key value. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: api_response = self._edge_api.get_edge_with_http_info( @@ -420,6 +451,10 @@ def get_edge( def update_edge( self, graph_id: StrictStr, edge_request: EdgeRequest ) -> Result[str]: + """ + Update an edge in the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: api_response = self._edge_api.update_edge_with_http_info(graph_id, edge_request) @@ -429,6 +464,10 @@ def update_edge( ################ Graph Interfaces ########## def create_graph(self, graph: CreateGraphRequest) -> Result[CreateGraphResponse]: + """ + Create a new graph with the specified graph request. + """ + try: response = self._graph_api.create_graph_with_http_info(graph) return Result.from_response(response) @@ -440,6 +479,7 @@ def get_graph_schema( graph_id: Annotated[StrictStr, Field(description="The id of graph to get")], ) -> Result[GetGraphSchemaResponse]: """Get the schema of a specified graph. + Parameters: graph_id (str): The ID of the graph whose schema is to be retrieved. Returns: @@ -456,6 +496,10 @@ def get_graph_meta( self, graph_id: Annotated[StrictStr, Field(description="The id of graph to get")], ) -> Result[GetGraphResponse]: + """ + Get the meta information of a specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._graph_api.get_graph_with_http_info(graph_id) @@ -467,6 +511,10 @@ def get_graph_statistics( self, graph_id: Annotated[StrictStr, Field(description="The id of graph to get")], ) -> Result[GetGraphStatisticsResponse]: + """ + Get the statistics of a specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._graph_api.get_graph_statistic_with_http_info(graph_id) @@ -478,6 +526,10 @@ def delete_graph( self, graph_id: Annotated[StrictStr, Field(description="The id of graph to delete")], ) -> Result[str]: + """ + Delete a graph with the specified graph id. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._graph_api.delete_graph_with_http_info(graph_id) @@ -486,6 +538,10 @@ def delete_graph( return Result.from_exception(e) def list_graphs(self) -> Result[List[GetGraphResponse]]: + """ + List all graphs. + """ + try: response = self._graph_api.list_graphs_with_http_info() return Result.from_response(response) @@ -497,6 +553,10 @@ def bulk_loading( graph_id: Annotated[StrictStr, Field(description="The id of graph to load")], schema_mapping: SchemaMapping, ) -> Result[JobResponse]: + """ + Submit a bulk loading job to the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) # First try to upload the input files if they are specified with a starting @ # return a new schema_mapping with the uploaded files @@ -517,6 +577,10 @@ def bulk_loading( def create_procedure( self, graph_id: StrictStr, procedure: CreateProcedureRequest ) -> Result[CreateProcedureResponse]: + """ + Create a new procedure in the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._procedure_api.create_procedure_with_http_info( @@ -529,6 +593,9 @@ def create_procedure( def delete_procedure( self, graph_id: StrictStr, procedure_id: StrictStr ) -> Result[str]: + """ + Delete a procedure in the specified graph. + """ graph_id = self.ensure_param_str("graph_id", graph_id) procedure_id = self.ensure_param_str("procedure_id", procedure_id) try: @@ -542,6 +609,10 @@ def delete_procedure( def list_procedures( self, graph_id: StrictStr ) -> Result[List[GetProcedureResponse]]: + """ + List all procedures in the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._procedure_api.list_procedures_with_http_info(graph_id) @@ -552,6 +623,9 @@ def list_procedures( def update_procedure( self, graph_id: StrictStr, proc_id: StrictStr, procedure: UpdateProcedureRequest ) -> Result[str]: + """ + Update a procedure in the specified graph. + """ graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._procedure_api.update_procedure_with_http_info( @@ -564,6 +638,10 @@ def update_procedure( def get_procedure( self, graph_id: StrictStr, procedure_id: StrictStr ) -> Result[GetProcedureResponse]: + """ + Get a procedure in the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: response = self._procedure_api.get_procedure_with_http_info( @@ -576,6 +654,10 @@ def get_procedure( def call_procedure( self, graph_id: StrictStr, params: QueryRequest ) -> Result[CollectiveResults]: + """ + Call a procedure in the specified graph. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: # gs_interactive currently support four type of inputformat, see flex/engines/graph_db/graph_db_session.h @@ -594,6 +676,10 @@ def call_procedure( return Result.from_exception(e) def call_procedure_current(self, params: QueryRequest) -> Result[CollectiveResults]: + """ + Call a procedure in the current graph. + """ + try: # gs_interactive currently support four type of inputformat, see flex/engines/graph_db/graph_db_session.h # Here we add byte of value 1 to denote the input format is in json format @@ -610,6 +696,10 @@ def call_procedure_current(self, params: QueryRequest) -> Result[CollectiveResul return Result.from_exception(e) def call_procedure_raw(self, graph_id: StrictStr, params: bytes) -> Result[str]: + """ + Call a procedure in the specified graph with raw bytes. + """ + graph_id = self.ensure_param_str("graph_id", graph_id) try: # gs_interactive currently support four type of inputformat, see flex/engines/graph_db/graph_db_session.h @@ -623,6 +713,10 @@ def call_procedure_raw(self, graph_id: StrictStr, params: bytes) -> Result[str]: return Result.from_exception(e) def call_procedure_current_raw(self, params: bytes) -> Result[str]: + """ + Call a procedure in the current graph with raw bytes. + """ + try: # gs_interactive currently support four type of inputformat, see flex/engines/graph_db/graph_db_session.h # Here we add byte of value 1 to denote the input format is in encoder/decoder format @@ -635,6 +729,10 @@ def call_procedure_current_raw(self, params: bytes) -> Result[str]: ################ QueryService Interfaces ########## def get_service_status(self) -> Result[ServiceStatus]: + """ + Get the status of the service. + """ + try: response = self._service_api.get_service_status_with_http_info() return Result.from_response(response) @@ -648,6 +746,10 @@ def start_service( Field(description="Start service on a specified graph"), ] = None, ) -> Result[str]: + """ + Start the service on a specified graph. + """ + try: response = self._service_api.start_service_with_http_info( start_service_request @@ -657,6 +759,10 @@ def start_service( return Result.from_exception(e) def stop_service(self) -> Result[str]: + """ + Stop the service. + """ + try: response = self._service_api.stop_service_with_http_info() return Result.from_response(response) @@ -664,6 +770,10 @@ def stop_service(self) -> Result[str]: return Result.from_exception(e) def restart_service(self) -> Result[str]: + """ + Restart the service. + """ + try: response = self._service_api.restart_service_with_http_info() return Result.from_response(response) @@ -672,6 +782,10 @@ def restart_service(self) -> Result[str]: ################ Job Interfaces ########## def get_job(self, job_id: StrictStr) -> Result[JobStatus]: + """ + Get the status of a job with the specified job id. + """ + job_id = self.ensure_param_str("job_id", job_id) try: response = self._job_api.get_job_by_id_with_http_info(job_id) @@ -680,6 +794,10 @@ def get_job(self, job_id: StrictStr) -> Result[JobStatus]: return Result.from_exception(e) def list_jobs(self) -> Result[List[JobResponse]]: + """ + List all jobs. + """ + try: response = self._job_api.list_jobs_with_http_info() return Result.from_response(response) @@ -687,6 +805,10 @@ def list_jobs(self) -> Result[List[JobResponse]]: return Result.from_exception(e) def cancel_job(self, job_id: StrictStr) -> Result[str]: + """ + Cancel a job with the specified job id. + """ + job_id = self.ensure_param_str("job_id", job_id) try: response = self._job_api.delete_job_by_id_with_http_info(job_id) @@ -697,6 +819,10 @@ def cancel_job(self, job_id: StrictStr) -> Result[str]: def upload_file( self, filestorage: Optional[Union[StrictBytes, StrictStr]] ) -> Result[UploadFileResponse]: + """ + Upload a file to the server. + """ + try: print("uploading file: ", filestorage) response = self._utils_api.upload_file_with_http_info(filestorage) diff --git a/flex/interactive/sdk/python/gs_interactive/client/status.py b/flex/interactive/sdk/python/gs_interactive/client/status.py index 37f49611f1f6..83350afad440 100644 --- a/flex/interactive/sdk/python/gs_interactive/client/status.py +++ b/flex/interactive/sdk/python/gs_interactive/client/status.py @@ -26,14 +26,24 @@ ForbiddenException, NotFoundException, ServiceException, - UnauthorizedException, ) from gs_interactive.client.generated.interactive_pb2 import Code as StatusCode from gs_interactive.models.api_response_with_code import APIResponseWithCode class Status: + """ + This class represents the status of an operation. It contains the status code and the message. + """ + def __init__(self, status: StatusCode, message: str): + """ + Construct a new Status object with the specified status code and message. + + Args: + status (StatusCode): the returnd code of the operation. + message (str): the message returned by the operation. + """ self.status = status self.message = message @@ -44,25 +54,48 @@ def __repr__(self): return f"Status: {self.status}, message: {self.message}" def is_ok(self) -> bool: + """ + Whether the operation is successful. + """ + return self.status == StatusCode.OK def is_error(self) -> bool: + """ + Whether the operation is failed. + """ return self.status != StatusCode.OK def get_code(self): + """ + Get the status code returned by the operation. + """ + return self.status @property def get_message(self): + """ + Get the message returned by the operation. + """ + return self.message # static method create a server internal error object @staticmethod def server_internal_error(message: str): + """ + Create a server internal error object with the specified message. + """ + return Status(StatusCode.INTERNAL_ERROR, message) @staticmethod def from_exception(exception: ApiException): + """ + Create a Status object from an ApiException. + """ + # mapping from ApiException to StatusCode print("exception: ", exception) if isinstance(exception, BadRequestException): @@ -82,6 +115,10 @@ def from_exception(exception: ApiException): @staticmethod def from_response(response: ApiResponse): + """ + Create a Status object from an ApiResponse. + """ + # mapping from ApiResponse to StatusCode if response.status_code == 200: return Status(StatusCode.OK, "OK") @@ -94,4 +131,8 @@ def from_response(response: ApiResponse): @staticmethod def ok(): + """ + Create a successful status object. + """ + return Status(StatusCode.OK, "OK") diff --git a/flex/interactive/sdk/python/gs_interactive/client/utils.py b/flex/interactive/sdk/python/gs_interactive/client/utils.py index abdc78b4c39f..6bf3a4b89e72 100644 --- a/flex/interactive/sdk/python/gs_interactive/client/utils.py +++ b/flex/interactive/sdk/python/gs_interactive/client/utils.py @@ -19,72 +19,141 @@ class Encoder: + """ + A simple encoder to encode the data into bytes + """ + def __init__(self, endian = 'little') -> None: self.byte_array = bytearray() self.endian = endian def put_int(self, value: int): - # put the value in big endian, 4 bytes + """ + Put an integer into the byte array, 4 bytes + """ + self.byte_array.extend(value.to_bytes(4, byteorder=self.endian)) def put_long(self, value: int): + """ + Put a long integer into the byte array, 8 bytes + """ self.byte_array.extend(value.to_bytes(8, byteorder=self.endian)) def put_string(self, value: str): + """ + Put a string into the byte array, first put the length of the string, then the string + """ + self.put_int(len(value)) self.byte_array.extend(value.encode('utf-8')) def put_byte(self, value: int): + """ + Put a single byte into the byte array + """ + self.byte_array.extend(value.to_bytes(1, byteorder=self.endian)) def put_bytes(self, value: bytes): + """ + Put a byte array into the byte array + """ + self.byte_array.extend(value) def put_double(self, value: float): + """ + Put a double into the byte array, 8 bytes + """ + self.byte_array.extend(value.to_bytes(8, byteorder=self.endian)) def get_bytes(self): + """ + Get the bytes from the byte array + """ + # return bytes not bytearray return bytes(self.byte_array) class Decoder: + """ + A simple decoder to decode the bytes into data + """ + def __init__(self, byte_array: bytearray,endian = 'little') -> None: self.byte_array = byte_array self.index = 0 self.endian = endian def get_int(self) -> int: + """ + Get an integer from the byte array, 4 bytes + + returns: int + """ value = int.from_bytes(self.byte_array[self.index:self.index+4], byteorder=self.endian) self.index += 4 return value def get_long(self) -> int: + """ + Get a long integer from the byte array, 8 bytes + + returns: int + """ value = int.from_bytes(self.byte_array[self.index:self.index+8], byteorder=self.endian) self.index += 8 return value def get_double(self) -> float: + """ + Get a double from the byte array, 8 bytes + + returns: float + """ value = float.from_bytes(self.byte_array[self.index:self.index+8], byteorder=self.endian) self.index += 8 return value def get_byte(self) -> int: + """ + Get a single byte from the byte array + + returns: int + """ + value = int.from_bytes(self.byte_array[self.index:self.index+1], byteorder=self.endian) self.index += 1 return value def get_bytes(self, length: int) -> bytes: + """ + Get a byte array from the byte array + + returns: A byte array + """ value = self.byte_array[self.index:self.index+length] self.index += length return value def get_string(self) -> str: + """ + Get a string from the byte array, first get the length of the string, then the string + + returns: str + """ length = self.get_int() value = self.byte_array[self.index:self.index+length].decode('utf-8') self.index += length return value def is_empty(self) -> bool: + """ + Whether the byte array is empty + """ + return self.index == len(self.byte_array)