cocoindex 0.1.40__cp313-cp313-macosx_11_0_arm64.whl → 0.1.42__cp313-cp313-macosx_11_0_arm64.whl

cocoindex/__init__.py

@@ -2,14 +2,15 @@
 Cocoindex is a framework for building and running indexing pipelines.
 """
 from . import functions, query, sources, storages, cli, utils
-from .flow import FlowBuilder, DataScope, DataSlice, Flow, flow_def, transform_flow
+
+from .auth_registry import AuthEntryReference, add_auth_entry, ref_auth_entry
+from .flow import FlowBuilder, DataScope, DataSlice, Flow, transform_flow
+from .flow import flow_def, flow_def as flow
 from .flow import EvaluateAndDumpOptions, GeneratedField
 from .flow import update_all_flows_async, FlowLiveUpdater, FlowLiveUpdaterOptions
+from .lib import init, start_server, stop, main_fn
 from .llm import LlmSpec, LlmApiType
 from .index import VectorSimilarityMetric, VectorIndexDef, IndexOptions
-from .auth_registry import AuthEntryReference, add_auth_entry, ref_auth_entry
-from .lib import *
 from .setting import DatabaseConnectionSpec, Settings, ServerSettings
 from .setting import get_app_namespace
-from ._engine import OpArgSchema
 from .typing import Float32, Float64, LocalDateTime, OffsetDateTime, Range, Vector, Json

cocoindex/cli.py

@@ -1,89 +1,234 @@
 import click
 import datetime
+import sys
+import importlib.util
+import os
+import atexit
+import types
 
+from dotenv import load_dotenv, find_dotenv
 from rich.console import Console
 from rich.table import Table
 
-from . import flow, lib, setting
+from . import flow, lib, setting, query
 from .setup import sync_setup, drop_setup, flow_names_with_setup, apply_setup_changes
 
+# Create ServerSettings lazily upon first call, as environment variables may be loaded from files, etc.
+COCOINDEX_HOST = 'https://cocoindex.io'
+
+def _parse_app_flow_specifier(specifier: str) -> tuple[str, str | None]:
+    """Parses 'module_or_path[:flow_name]' into (module_or_path, flow_name | None)."""
+    parts = specifier.split(":", 1)  # Split only on the first colon
+    app_ref = parts[0]
+
+    if not app_ref:
+        raise click.BadParameter(
+            f"Application module/path part is missing or invalid in specifier: '{specifier}'. "
+            "Expected format like 'myapp.py' or 'myapp:MyFlow'.",
+            param_hint="APP_SPECIFIER"
+        )
+
+    if len(parts) == 1:
+        return app_ref, None
+
+    flow_ref_part = parts[1]
+
+    if not flow_ref_part: # Handles empty string after colon
+        return app_ref, None
+
+    if not flow_ref_part.isidentifier():
+        raise click.BadParameter(
+            f"Invalid format for flow name part ('{flow_ref_part}') in specifier '{specifier}'. "
+            "If a colon separates the application from the flow name, the flow name should typically be "
+            "a valid identifier (e.g., alphanumeric with underscores, not starting with a number).",
+            param_hint="APP_SPECIFIER"
+        )
+    return app_ref, flow_ref_part
+
+def _get_app_ref_from_specifier(
+    specifier: str,
+) -> str:
+    """
+    Parses the APP_TARGET to get the application reference (path or module).
+    Issues a warning if a flow name component is also provided in it.
+    """
+    app_ref, flow_ref = _parse_app_flow_specifier(specifier)
+
+    if flow_ref is not None:
+        click.echo(
+            click.style(
+                f"Ignoring flow name '{flow_ref}' in '{specifier}': "
+                f"this command operates on the entire app/module '{app_ref}'.",
+                fg='yellow'
+            ),
+            err=True
+        )
+    return app_ref
+
+def _load_user_app(app_target: str) -> types.ModuleType:
+    """
+    Loads the user's application, which can be a file path or an installed module name.
+    Exits on failure.
+    """
+    if not app_target:
+        raise click.ClickException("Application target not provided.")
+
+    looks_like_path = os.sep in app_target or app_target.lower().endswith(".py")
+
+    if looks_like_path:
+        if not os.path.isfile(app_target):
+            raise click.ClickException(f"Application file path not found: {app_target}")
+        app_path = os.path.abspath(app_target)
+        app_dir = os.path.dirname(app_path)
+        module_name = os.path.splitext(os.path.basename(app_path))[0]
+        
+        if app_dir not in sys.path:
+            sys.path.insert(0, app_dir)
+        try:
+            spec = importlib.util.spec_from_file_location(module_name, app_path)
+            if spec is None:
+                raise ImportError(f"Could not create spec for file: {app_path}")
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[spec.name] = module 
+            spec.loader.exec_module(module)
+            return module
+        except (ImportError, FileNotFoundError, PermissionError) as e:
+            raise click.ClickException(f"Failed importing file '{app_path}': {e}")
+        finally:
+            if app_dir in sys.path and sys.path[0] == app_dir:
+                sys.path.pop(0)
+
+    # Try as module
+    try:
+        return importlib.import_module(app_target)
+    except ImportError as e:
+        raise click.ClickException(f"Failed to load module '{app_target}': {e}")
+    except Exception as e:
+        raise click.ClickException(f"Unexpected error importing module '{app_target}': {e}")
+
 @click.group()
-def cli():
+@click.version_option(package_name="cocoindex", message="%(prog)s version %(version)s")
+@click.option(
+    "--env-file",
+    type=click.Path(exists=True, file_okay=True, dir_okay=False, readable=True, resolve_path=True),
+    help="Path to a .env file to load environment variables from. "
+         "If not provided, attempts to load '.env' from the current directory.",
+    default=None,
+    show_default=False
+)
+def cli(env_file: str | None):
     """
     CLI for Cocoindex.
     """
+    dotenv_path = env_file or find_dotenv(usecwd=True)
+
+    if load_dotenv(dotenv_path=dotenv_path):
+        loaded_env_path = os.path.abspath(dotenv_path)
+        click.echo(f"Loaded environment variables from: {loaded_env_path}", err=True)
+
+    try:
+        settings = setting.Settings.from_env()
+        lib.init(settings)
+        atexit.register(lib.stop)
+    except Exception as e:
+        raise click.ClickException(f"Failed to initialize CocoIndex library: {e}")
 
 @cli.command()
-@click.option(
-    "-a", "--all", "show_all", is_flag=True, show_default=True, default=False,
-    help="Also show all flows with persisted setup under the current app namespace, even if not defined in the current process.")
-def ls(show_all: bool):
+@click.argument("app_target", type=str, required=False)
+def ls(app_target: str | None):
     """
     List all flows.
+
+    If APP_TARGET (path/to/app.py or a module) is provided, lists flows
+    defined in the app and their backend setup status.
+
+    If APP_TARGET is omitted, lists all flows that have a persisted
+    setup in the backend.
     """
-    current_flow_names = flow.flow_names()
-    persisted_flow_names = flow_names_with_setup()
-    remaining_persisted_flow_names = set(persisted_flow_names)
+    if app_target:
+        app_ref = _get_app_ref_from_specifier(app_target)
+        _load_user_app(app_ref)
 
-    has_missing_setup = False
-    has_extra_setup = False
+        current_flow_names = set(flow.flow_names())
+        persisted_flow_names = set(flow_names_with_setup())
 
-    for name in current_flow_names:
-        if name in remaining_persisted_flow_names:
-            remaining_persisted_flow_names.remove(name)
-            suffix = ''
-        else:
-            suffix = ' [+]'
-            has_missing_setup = True
-        click.echo(f'{name}{suffix}')
+        if not current_flow_names:
+            click.echo(f"No flows are defined in '{app_ref}'.")
+            return
 
-    if show_all:
-        for name in persisted_flow_names:
-            if name in remaining_persisted_flow_names:
-                click.echo(f'{name} [?]')
-                has_extra_setup = True
-
-    if has_missing_setup or has_extra_setup:
-        click.echo('')
-        click.echo('Notes:')
-        if has_missing_setup:
+        has_missing = False
+        for name in sorted(current_flow_names):
+            if name in persisted_flow_names:
+                click.echo(name)
+            else:
+                click.echo(f"{name} [+]")
+                has_missing = True
+
+        if has_missing:
+            click.echo('')
+            click.echo('Notes:')
             click.echo('  [+]: Flows present in the current process, but missing setup.')
-        if has_extra_setup:
-            click.echo('  [?]: Flows with persisted setup, but not in the current process.')
+
+    else:
+        persisted_flow_names = sorted(flow_names_with_setup())
+
+        if not persisted_flow_names:
+            click.echo("No persisted flow setups found in the backend.")
+            return
+
+        for name in persisted_flow_names:
+            click.echo(name)
 
 @cli.command()
-@click.argument("flow_name", type=str, required=False)
+@click.argument("app_flow_specifier", type=str)
 @click.option("--color/--no-color", default=True, help="Enable or disable colored output.")
 @click.option("--verbose", is_flag=True, help="Show verbose output with full details.")
-def show(flow_name: str | None, color: bool, verbose: bool):
+def show(app_flow_specifier: str, color: bool, verbose: bool):
     """
-    Show the flow spec and schema in a readable format with colored output.
+    Show the flow spec and schema.
+
+    APP_FLOW_SPECIFIER: Specifies the application and optionally the target flow.
+    Can be one of the following formats:
+
+    \b
+      - path/to/your_app.py
+      - an_installed.module_name
+      - path/to/your_app.py:SpecificFlowName
+      - an_installed.module_name:SpecificFlowName
+
+    :SpecificFlowName can be omitted only if the application defines a single flow.
     """
-    flow = _flow_by_name(flow_name)
-    console = Console(no_color=not color)
-    console.print(flow._render_spec(verbose=verbose))
+    app_ref, flow_ref = _parse_app_flow_specifier(app_flow_specifier)
+    _load_user_app(app_ref)
 
+    fl = _flow_by_name(flow_ref)
+    console = Console(no_color=not color)
+    console.print(fl._render_spec(verbose=verbose))
     console.print()
     table = Table(
-        title=f"Schema for Flow: {flow.full_name}",
-        show_header=True,
+        title=f"Schema for Flow: {fl.name}",
+        title_style="cyan",
         header_style="bold magenta"
     )
     table.add_column("Field", style="cyan")
     table.add_column("Type", style="green")
     table.add_column("Attributes", style="yellow")
-
-    for field_name, field_type, attr_str in flow._get_schema():
+    for field_name, field_type, attr_str in fl._get_schema():
         table.add_row(field_name, field_type, attr_str)
-
     console.print(table)
 
 @cli.command()
-def setup():
+@click.argument("app_target", type=str)
+def setup(app_target: str):
     """
     Check and apply backend setup changes for flows, including the internal and target storage
     (to export).
+
+    APP_TARGET: path/to/app.py or installed_module.
     """
+    app_ref = _get_app_ref_from_specifier(app_target)
+    _load_user_app(app_ref)
+
     setup_status = sync_setup()
     click.echo(setup_status)
     if setup_status.is_up_to_date():
@@ -94,80 +239,125 @@ def setup():
         return
     apply_setup_changes(setup_status)
 
-@cli.command()
+@cli.command("drop")
+@click.argument("app_target", type=str, required=False)
 @click.argument("flow_name", type=str, nargs=-1)
 @click.option(
     "-a", "--all", "drop_all", is_flag=True, show_default=True, default=False,
     help="Drop the backend setup for all flows with persisted setup, "
-         "even if not defined in the current process.")
-def drop(flow_name: tuple[str, ...], drop_all: bool):
+         "even if not defined in the current process."
+         "If used, APP_TARGET and any listed flow names are ignored.")
+def drop(app_target: str | None, flow_name: tuple[str, ...], drop_all: bool):
     """
-    Drop the backend setup for specified flows.
-    If no flow is specified, all flows defined in the current process will be dropped.
+    Drop the backend setup for flows.
+
+    Modes of operation:\n
+    1. Drop ALL persisted setups: `cocoindex drop --all`\n
+    2. Drop all flows defined in an app: `cocoindex drop <APP_TARGET>`\n
+    3. Drop specific named flows: `cocoindex drop <APP_TARGET> [FLOW_NAME...]`
     """
+    app_ref = None
+    flow_names = []
+
     if drop_all:
+        if app_target or flow_name:
+            click.echo("Warning: When --all is used, APP_TARGET and any individual flow names are ignored.", err=True)
         flow_names = flow_names_with_setup()
-    elif len(flow_name) == 0:
-        flow_names = flow.flow_names()
+    elif app_target:
+        app_ref = _get_app_ref_from_specifier(app_target)
+        _load_user_app(app_ref)
+        if flow_name:
+            flow_names = list(flow_name)
+            click.echo(f"Preparing to drop specified flows: {', '.join(flow_names)} (in '{app_ref}').", err=True)
+        else:
+            flow_names = [fl.name for fl in flow.flows()]
+            if not flow_names:
+                click.echo(f"No flows found defined in '{app_ref}' to drop.")
+                return
+            click.echo(f"Preparing to drop all flows defined in '{app_ref}': {', '.join(flow_names)}.", err=True)
     else:
-        flow_names = list(flow_name)
+        raise click.UsageError(
+            "Missing arguments. You must either provide an APP_TARGET (to target app-specific flows) "
+            "or use the --all flag."
+        )
+
+    if not flow_names:
+        click.echo("No flows identified for the drop operation.")
+        return
+
     setup_status = drop_setup(flow_names)
     click.echo(setup_status)
     if setup_status.is_up_to_date():
         click.echo("No flows need to be dropped.")
         return
     if not click.confirm(
-        "Changes need to be pushed. Continue? [yes/N]", default=False, show_default=False):
+        f"\nThis will apply changes to drop setup for: {', '.join(flow_names)}. Continue? [yes/N]",
+        default=False, show_default=False):
+        click.echo("Drop operation aborted by user.")
         return
     apply_setup_changes(setup_status)
 
 @cli.command()
-@click.argument("flow_name", type=str, required=False)
+@click.argument("app_flow_specifier", type=str)
 @click.option(
     "-L", "--live", is_flag=True, show_default=True, default=False,
     help="Continuously watch changes from data sources and apply to the target index.")
 @click.option(
     "-q", "--quiet", is_flag=True, show_default=True, default=False,
     help="Avoid printing anything to the standard output, e.g. statistics.")
-def update(flow_name: str | None, live: bool, quiet: bool):
+def update(app_flow_specifier: str, live: bool, quiet: bool):
     """
     Update the index to reflect the latest data from data sources.
+
+    APP_FLOW_SPECIFIER: path/to/app.py, module, path/to/app.py:FlowName, or module:FlowName.
+    If :FlowName is omitted, updates all flows.
     """
+    app_ref, flow_ref = _parse_app_flow_specifier(app_flow_specifier)
+    _load_user_app(app_ref)
+
     options = flow.FlowLiveUpdaterOptions(live_mode=live, print_stats=not quiet)
-    if flow_name is None:
+    if flow_ref is None:
         return flow.update_all_flows(options)
     else:
-        with flow.FlowLiveUpdater(_flow_by_name(flow_name), options) as updater:
+        with flow.FlowLiveUpdater(_flow_by_name(flow_ref), options) as updater:
             updater.wait()
             return updater.update_stats()
 
 @cli.command()
-@click.argument("flow_name", type=str, required=False)
+@click.argument("app_flow_specifier", type=str)
 @click.option(
     "-o", "--output-dir", type=str, required=False,
     help="The directory to dump the output to.")
 @click.option(
     "--cache/--no-cache", is_flag=True, show_default=True, default=True,
-    help="Use already-cached intermediate data if available. "
-         "Note that we only reuse existing cached data without updating the cache "
-         "even if it's turned on.")
-def evaluate(flow_name: str | None, output_dir: str | None, cache: bool = True):
+    help="Use already-cached intermediate data if available.")
+def evaluate(app_flow_specifier: str, output_dir: str | None, cache: bool = True):
     """
     Evaluate the flow and dump flow outputs to files.
 
     Instead of updating the index, it dumps what should be indexed to files.
     Mainly used for evaluation purpose.
+
+    APP_FLOW_SPECIFIER: Specifies the application and optionally the target flow.
+    Can be one of the following formats:\n
+      - path/to/your_app.py\n
+      - an_installed.module_name\n
+      - path/to/your_app.py:SpecificFlowName\n
+      - an_installed.module_name:SpecificFlowName
+
+    :SpecificFlowName can be omitted only if the application defines a single flow.
     """
-    fl = _flow_by_name(flow_name)
+    app_ref, flow_ref = _parse_app_flow_specifier(app_flow_specifier)
+    _load_user_app(app_ref)
+
+    fl = _flow_by_name(flow_ref)
     if output_dir is None:
         output_dir = f"eval_{setting.get_app_namespace(trailing_delimiter='_')}{flow_name}_{datetime.datetime.now().strftime('%y%m%d_%H%M%S')}"
     options = flow.EvaluateAndDumpOptions(output_dir=output_dir, use_cache=cache)
     fl.evaluate_and_dump(options)
 
-# Create ServerSettings lazily upon first call, as environment variables may be loaded from files, etc.
-COCOINDEX_HOST = 'https://cocoindex.io'
-
 @cli.command()
+@click.argument("app_target", type=str)
 @click.option(
     "-a", "--address", type=str,
     help="The address to bind the server to, in the format of IP:PORT. "
@@ -190,13 +380,18 @@ COCOINDEX_HOST = 'https://cocoindex.io'
 @click.option(
     "-q", "--quiet", is_flag=True, show_default=True, default=False,
     help="Avoid printing anything to the standard output, e.g. statistics.")
-def server(address: str | None, live_update: bool, quiet: bool, cors_origin: str | None,
-           cors_cocoindex: bool, cors_local: int | None):
+def server(app_target: str, address: str | None, live_update: bool, quiet: bool,
+           cors_origin: str | None, cors_cocoindex: bool, cors_local: int | None):
     """
     Start a HTTP server providing REST APIs.
 
     It will allow tools like CocoInsight to access the server.
+
+    APP_TARGET: path/to/app.py or installed_module.
     """
+    app_ref = _get_app_ref_from_specifier(app_target)
+    _load_user_app(app_ref)
+
     server_settings = setting.ServerSettings.from_env()
     cors_origins: set[str] = set(server_settings.cors_origins or [])
     if cors_origin is not None:
@@ -223,16 +418,20 @@ def server(address: str | None, live_update: bool, quiet: bool, cors_origin: str
 
 def _flow_name(name: str | None) -> str:
     names = flow.flow_names()
+    available = ', '.join(sorted(names))
     if name is not None:
         if name not in names:
-            raise click.BadParameter(f"Flow {name} not found")
+            raise click.BadParameter(f"Flow '{name}' not found.\nAvailable: {available if names else 'None'}")
         return name
     if len(names) == 0:
-        raise click.UsageError("No flows available")
+        raise click.UsageError("No flows available in the loaded application.")
     elif len(names) == 1:
         return names[0]
     else:
-        raise click.UsageError("Multiple flows available, please specify --name")
+        raise click.UsageError(f"Multiple flows available, please specify which flow to target by appending :FlowName to the APP_TARGET.\nAvailable: {available}")
 
 def _flow_by_name(name: str | None) -> flow.Flow:
     return flow.flow_by_name(_flow_name(name))
+
+if __name__ == "__main__":
+    cli()

cocoindex/flow.py

@@ -489,7 +489,7 @@ class Flow:
         tree = Tree(f"Flow: {self.full_name}", style="cyan")
 
         def build_tree(label: str, lines: list):
-            node = Tree(label, style="bold magenta" if lines else "cyan")
+            node = Tree(label=label if lines else label + " None", style="cyan")
             for line in lines:
                 child_node = node.add(Text(line.content, style="yellow"))
                 child_node.children = build_tree("", line.children).children
@@ -657,7 +657,7 @@ async def update_all_flows_async(options: FlowLiveUpdaterOptions) -> dict[str, _
 
 def _get_data_slice_annotation_type(data_slice_type: Type[DataSlice[T]]) -> Type[T] | None:
     type_args = get_args(data_slice_type)
-    if data_slice_type is DataSlice:
+    if data_slice_type is inspect.Parameter.empty or data_slice_type is DataSlice:
         return None
     if get_origin(data_slice_type) != DataSlice or len(type_args) != 1:
         raise ValueError(f"Expect a DataSlice[T] type, but got {data_slice_type}")
@@ -718,9 +718,11 @@ class TransformFlow(Generic[T]):
         for (param_name, param), param_type in zip(sig.parameters.items(), self._flow_arg_types):
             if param.kind not in (inspect.Parameter.POSITIONAL_OR_KEYWORD,
                                   inspect.Parameter.KEYWORD_ONLY):
-                raise ValueError(f"Parameter {param_name} is not a parameter can be passed by name")
-            engine_ds = flow_builder_state.engine_flow_builder.add_direct_input(
-                param_name, encode_enriched_type(param_type))
+                raise ValueError(f"Parameter `{param_name}` is not a parameter can be passed by name")
+            encoded_type = encode_enriched_type(param_type)
+            if encoded_type is None:
+                raise ValueError(f"Parameter `{param_name}` has no type annotation")
+            engine_ds = flow_builder_state.engine_flow_builder.add_direct_input(param_name, encoded_type)
             kwargs[param_name] = DataSlice(_DataSliceState(flow_builder_state, engine_ds))
 
         output = self._flow_fn(**kwargs)
@@ -780,8 +782,13 @@ def transform_flow() -> Callable[[Callable[..., DataSlice[T]]], TransformFlow[T]
         for (param_name, param) in sig.parameters.items():
             if param.kind not in (inspect.Parameter.POSITIONAL_OR_KEYWORD,
                                   inspect.Parameter.KEYWORD_ONLY):
-                raise ValueError(f"Parameter {param_name} is not a parameter can be passed by name")
-            arg_types.append(_get_data_slice_annotation_type(param.annotation))
+                raise ValueError(f"Parameter `{param_name}` is not a parameter can be passed by name")
+            value_type_annotation = _get_data_slice_annotation_type(param.annotation)
+            if value_type_annotation is None:
+                raise ValueError(
+                    f"Parameter `{param_name}` for {fn} has no value type annotation. "
+                    "Please use `cocoindex.DataSlice[T]` where T is the type of the value.")
+            arg_types.append(value_type_annotation)
 
         _transform_flow = TransformFlow(fn, arg_types)
         functools.update_wrapper(_transform_flow, fn)

cocoindex/lib.py

@@ -1,19 +1,20 @@
 """
 Library level functions and states.
 """
-import sys
-import functools
-import inspect
+import warnings
+from typing import Callable, Any
 
-from typing import Callable
-
-from . import _engine
-from . import flow, query, cli, setting
+from . import _engine, flow, query, setting
 from .convert import dump_engine_object
 
 
-def init(settings: setting.Settings):
-    """Initialize the cocoindex library."""
+def init(settings: setting.Settings | None = None):
+    """
+    Initialize the cocoindex library.
+
+    If the settings are not provided, they are loaded from the environment variables.
+    """
+    settings = settings or setting.Settings.from_env()
     _engine.init(dump_engine_object(settings))
     setting.set_app_namespace(settings.app_namespace)
 
@@ -29,50 +30,42 @@ def stop():
     _engine.stop()
 
 def main_fn(
-        settings: setting.Settings | None = None,
-        cocoindex_cmd: str = 'cocoindex',
+        settings: Any | None = None,
+        cocoindex_cmd: str | None = None,
         ) -> Callable[[Callable], Callable]:
     """
-    A decorator to wrap the main function.
-    If the python binary is called with the given command, it yields control to the cocoindex CLI.
+    DEPRECATED: The @cocoindex.main_fn() decorator is obsolete and has no effect.
+    It will be removed in a future version, which will cause an AttributeError.
 
-    If the settings are not provided, they are loaded from the environment variables.
+    Please remove this decorator from your code and use the standalone 'cocoindex' CLI.
+    See the updated CLI usage examples in the warning message.
     """
-
-    def _pre_init() -> None:
-        effective_settings = settings or setting.Settings.from_env()
-        init(effective_settings)
-
-    def _should_run_cli() -> bool:
-        return len(sys.argv) > 1 and sys.argv[1] == cocoindex_cmd
-
-    def _run_cli():
-        return cli.cli.main(sys.argv[2:], prog_name=f"{sys.argv[0]} {sys.argv[1]}")
+    warnings.warn(
+        "\n\n"
+        "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n"
+        "CRITICAL DEPRECATION NOTICE from CocoIndex:\n"
+        "The @cocoindex.main_fn() decorator in your script is DEPRECATED and IGNORED.\n"
+        "It provides NO functionality and will be REMOVED entirely in a future version.\n"
+        "If not removed, your script will FAIL with an AttributeError in the future.\n\n"
+        "ACTION REQUIRED: Please REMOVE @cocoindex.main_fn() from your Python script.\n\n"
+        "To use CocoIndex, invoke the standalone 'cocoindex' CLI."
+        " Examples of new CLI usage:\n\n"
+        "  To list flows from 'main.py' (previously 'python main.py cocoindex ls'):\n"
+        "    cocoindex ls main.py\n\n"
+        "  To list all persisted flows (previously 'python main.py cocoindex ls --all'):\n"
+        "    cocoindex ls\n\n"
+        "  To show 'MyFlow' defined in 'main.py' (previously 'python main.py cocoindex show MyFlow'):\n"
+        "    cocoindex show main.py:MyFlow\n\n"
+        "  To update all flows in 'my_package.flows_module':\n"
+        "    cocoindex update my_package.flows_module\n\n"
+        "  To update 'SpecificFlow' in 'my_package.flows_module':\n"
+        "    cocoindex update my_package.flows_module:SpecificFlow\n\n"
+        "See cocoindex <command> --help for more details.\n"
+        "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n\n",
+        DeprecationWarning,
+        stacklevel=2
+    )
 
     def _main_wrapper(fn: Callable) -> Callable:
-        if inspect.iscoroutinefunction(fn):
-            @functools.wraps(fn)
-            async def _inner(*args, **kwargs):
-                _pre_init()
-                try:
-                    if _should_run_cli():
-                        # Schedule to a separate thread as it invokes nested event loop.
-                        # return await asyncio.to_thread(_run_cli)
-                        return _run_cli()
-                    return await fn(*args, **kwargs)
-                finally:
-                    stop()
-            return _inner
-        else:
-            @functools.wraps(fn)
-            def _inner(*args, **kwargs):
-                _pre_init()
-                try:
-                    if _should_run_cli():
-                        return _run_cli()
-                    return fn(*args, **kwargs)
-                finally:
-                    stop()
-            return _inner
-
+        return fn
     return _main_wrapper

cocoindex/typing.py

@@ -168,6 +168,8 @@ def analyze_type_info(t) -> AnalyzedTypeInfo:
             kind = 'Time'
         elif t is datetime.datetime:
             kind = 'OffsetDateTime'
+        elif t is datetime.timedelta:
+            kind = 'TimeDelta'
         else:
             raise ValueError(f"type unsupported yet: {t}")
 

{cocoindex-0.1.40.dist-info → cocoindex-0.1.42.dist-info}/METADATA

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.1.40
+Version: 0.1.42
 Requires-Dist: sentence-transformers>=3.3.1
 Requires-Dist: click>=8.1.8
 Requires-Dist: rich>=14.0.0
+Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: pytest ; extra == 'test'
 Provides-Extra: test
 License-File: LICENSE

{cocoindex-0.1.40.dist-info → cocoindex-0.1.42.dist-info}/RECORD

@@ -1,15 +1,16 @@
-cocoindex-0.1.40.dist-info/METADATA,sha256=k_dUmyVymd4d0TmoRNrOnQAf8r9bOgLzqQU5MWTFZe8,9790
-cocoindex-0.1.40.dist-info/WHEEL,sha256=UPfJ7S-gMCqCJ6cj5sliE010L87pWgiShNoxmys5TN4,104
-cocoindex-0.1.40.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-cocoindex/__init__.py,sha256=NIOdQAQ2nMgLgMdfGsWj4YnmC6sFWDUE1-33hkS63T4,799
-cocoindex/_engine.cpython-313-darwin.so,sha256=qM1UrYG6Sa4ssujab96aoUvA6hnu_2E6_Meb7gd9HGI,56853264
+cocoindex-0.1.42.dist-info/METADATA,sha256=-ukEQ2NadNRsjsH5WOnIQ4RuPN8oDBlLc2DJ4NyLilg,9826
+cocoindex-0.1.42.dist-info/WHEEL,sha256=UPfJ7S-gMCqCJ6cj5sliE010L87pWgiShNoxmys5TN4,104
+cocoindex-0.1.42.dist-info/entry_points.txt,sha256=_NretjYVzBdNTn7dK-zgwr7YfG2afz1u1uSE-5bZXF8,46
+cocoindex-0.1.42.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+cocoindex/__init__.py,sha256=0iO3lM8w35zhVDPsvCGBAXwUQZsCWRRqjt2wFdtJhME,834
+cocoindex/_engine.cpython-313-darwin.so,sha256=3J5U0Twf2TYRTTyXAHc5ELPlxHgaZw-7mUCy5yAOJNs,56872480
 cocoindex/auth_registry.py,sha256=NsALZ3SKsDG9cPdrlTlalIqUvgbgFOaFGAbWJNedtJE,692
-cocoindex/cli.py,sha256=Ac3ybnQW-HGVGJeUwIOHd1qhjs0KC5wCsemWuyouEfU,8999
+cocoindex/cli.py,sha256=1FvpeLjLHSu4EC3Ds7eeSDjBNTtAc06nsuORkNjv_NQ,16569
 cocoindex/convert.py,sha256=75HSBie7DokM0RJyUBqeveZRl5y_Fl8lzByoRF0yb2M,6915
-cocoindex/flow.py,sha256=QRbbYwHCpOvjAah33gbuVLgu1ML_ea0HReHHOFDTHxQ,27888
+cocoindex/flow.py,sha256=0otFFqO8XVv-uc1Qbya9BBCK1orv7CGI52TiB5v63xk,28409
 cocoindex/functions.py,sha256=F79dNmGE127LaU67kF5Oqtf_tIzebFQH7MkyceMX4-s,1830
 cocoindex/index.py,sha256=LssEOuZi6AqhwKtZM3QFeQpa9T-0ELi8G5DsrYKECvc,534
-cocoindex/lib.py,sha256=OqTMuOHicdyX9PRA7fmTzznK8HZMrzxpUDbqxAEF--Q,2383
+cocoindex/lib.py,sha256=JiLIV5Fi-FNKMlH-6JMoe-UQsvirnFkkOLcoEQk9WkE,2903
 cocoindex/llm.py,sha256=_3rtahuKcqcEHPkFSwhXOSrekZyGxVApPoYtlU_chcA,348
 cocoindex/op.py,sha256=yyB3gYYj6uIeoGW9FXuj9Ludaz50QYDeqGgi3dKG1_I,10739
 cocoindex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -21,6 +22,6 @@ cocoindex/sources.py,sha256=7lpwYLsFCRfbURKf79Vu0JZZoXjAYY0DxNHzUb-VHBY,1327
 cocoindex/storages.py,sha256=MFMsfyOCYMggTWeWrOi82miqOXQmiUuqq828x5htBr0,2207
 cocoindex/tests/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 cocoindex/tests/test_convert.py,sha256=7jc--I3frrg7DB5MPr4JFzE7DSCznJuWyHdlDLQJ_fM,15516
-cocoindex/typing.py,sha256=369ABRtnpbaVSQVIBc2ZDutXW8jUmncvNJd9CHEWT3Q,8962
+cocoindex/typing.py,sha256=RMJXdey5_vd7JbPTEdUw1DeQ4Uu4MicdiaXjzQHFNRA,9031
 cocoindex/utils.py,sha256=eClhMdjBjcXaDkah-rPUmE7Y5Ncd7S1goUe2qTETR08,456
-cocoindex-0.1.40.dist-info/RECORD,,
+cocoindex-0.1.42.dist-info/RECORD,,

cocoindex-0.1.42.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cocoindex=cocoindex.cli:cli