feat(api): rename add_flow_def() to open_flow() (#830)

Author: georgeh0

docs/docs/core/flow_def.mdx

@@ -33,14 +33,14 @@ It takes two arguments:
 *   `flow_builder`: a `FlowBuilder` object to help build the flow.
 *   `data_scope`: a `DataScope` object, representing the top-level data scope. Any data created by the flow should be added to it.
 
-Alternatively, for more flexibility (e.g. you want to do this conditionally or generate dynamic name), you can explicitly call the `cocoindex.add_flow_def()` method:
+Alternatively, for more flexibility (e.g. you want to do this conditionally or generate dynamic name), you can explicitly call the `cocoindex.open_flow()` method:
 
 ```python
 def demo_flow_def(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope):
     ...
 
 # Add the flow definition to the flow registry.
-demo_flow = cocoindex.add_flow_def("DemoFlow", demo_flow_def)
+demo_flow = cocoindex.open_flow("DemoFlow", demo_flow_def)
 ```
 
 In both cases, `demo_flow` will be an object with `cocoindex.Flow` class type.

python/cocoindex/__init__.py

@@ -11,7 +11,8 @@
 from .flow import flow_def
 from .flow import EvaluateAndDumpOptions, GeneratedField
 from .flow import FlowLiveUpdater, FlowLiveUpdaterOptions, FlowUpdaterStatusUpdates
-from .flow import add_flow_def, remove_flow
+from .flow import open_flow
+from .flow import add_flow_def, remove_flow  # DEPRECATED
 from .flow import update_all_flows_async, setup_all_flows, drop_all_flows
 from .lib import init, start_server, stop
 from .llm import LlmSpec, LlmApiType
@@ -57,8 +58,9 @@
     "FlowLiveUpdater",
     "FlowLiveUpdaterOptions",
     "FlowUpdaterStatusUpdates",
-    "add_flow_def",
-    "remove_flow",
+    "open_flow",
+    "add_flow_def",  # DEPRECATED
+    "remove_flow",  # DEPRECATED
     "update_all_flows_async",
     "setup_all_flows",
     "drop_all_flows",

python/cocoindex/flow.py

@@ -857,14 +857,24 @@ def get_flow_full_name(name: str) -> str:
     return f"{setting.get_app_namespace(trailing_delimiter='.')}{name}"
 
 
-def add_flow_def(name: str, fl_def: Callable[[FlowBuilder, DataScope], None]) -> Flow:
+def open_flow(name: str, fl_def: Callable[[FlowBuilder, DataScope], None]) -> Flow:
+    """
+    Open a flow, with the given name and definition.
+    """
     with _flows_lock:
         if name in _flows:
             raise KeyError(f"Flow with name {name} already exists")
         fl = _flows[name] = _create_lazy_flow(name, fl_def)
     return fl
 
 
+def add_flow_def(name: str, fl_def: Callable[[FlowBuilder, DataScope], None]) -> Flow:
+    """
+    DEPRECATED: Use `open_flow()` instead.
+    """
+    return open_flow(name, fl_def)
+
+
 def remove_flow(fl: Flow) -> None:
     """
     DEPRECATED: Use `Flow.close()` instead.
@@ -878,7 +888,7 @@ def flow_def(
     """
     A decorator to wrap the flow definition.
     """
-    return lambda fl_def: add_flow_def(name or fl_def.__name__, fl_def)
+    return lambda fl_def: open_flow(name or fl_def.__name__, fl_def)
 
 
 def flow_names() -> list[str]: