update document

core/dbt/cli/example.py

@@ -1,35 +1,21 @@
-import click
-import os
-import sys
+from dbt.cli.main import dbtRunner
+from dbt.config.runtime import load_profile, load_project
 
-from dbt.cli import dbt_cli
-from dbt.cli.context import make_context
-from dbt.adapters.factory import adapter_management
-from dbt.profiler import profiler
-from dbt.config.runtime import load_project
-
-# python core/dbt/cli/example.py deps --project-dir <project-dir-path>
-# python core/dbt/cli/example.py run --project-dir <project-dir-path>
 if __name__ == "__main__":
+    project_dir = "/Users/chenyuli/git/jaffle_shop"
+    # Bypass cli group context configuration entirely and invoke deps directly
+    cli_args = ["run", "--project-dir", project_dir]
 
-    # currently this would not construct params properly
-    # Use cli group to configure context + call arbitrary command
-    # ctx = make_context(cli_args)
-    # if ctx:
-    #     dbt.invoke(ctx)
+    # initialize the dbt runner
+    dbt = dbtRunner()
+    # run the command
+    res, success = dbt.invoke(cli_args)
 
-    # Bypass cli group context configuration entirely and invoke deps directly
-    # Note: This only really works because of the prior global initializations (logging, tracking) from dbt.invoke(ctx)
-    input_args = sys.argv[1:]
-    # we are not supporting --version, --help in this example for now.
-    command = input_args[0]
-    cli_args = input_args[1:]
-    click.echo(f"\n`dbt {command}` called")
-    ctx = make_context(cli_args, dbt_cli.commands[command])
-    assert ctx is not None
+    # preload profile and project
+    profile = load_profile(project_dir, {}, "testing-postgres")
+    project = load_project(project_dir, False, profile, {})
 
-    ctx.with_resource(adapter_management())
-    ctx.with_resource(profiler(enable=True, outfile="output.profile"))
-    project_dir = os.path.expanduser(ctx.params.get("project_dir"))  # type: ignore
-    ctx.obj["project"] = load_project(project_dir, True, None, None)  # type: ignore
-    dbt_cli.commands[command].invoke(ctx)
+    # initialize the runner with pre-loaded profile and project, you can also pass in a preloaded manifest
+    dbt = dbtRunner(profile=profile, project=project)
+    # run the command, this will use the pre-loaded profile and project instead of loading
+    res, success = dbt.invoke(cli_args)

core/dbt/docs/source/index.rst

@@ -3,68 +3,32 @@ dbt-core's API documentation
 How to invoke dbt commands in python runtime
 --------------------------------------------
 
-All dbt commands are under the root group `dbt_cli`, we can import the `dbt_cli` group and access the commands under it.
+Right now the best way to invoke a command from python runtime is to use the `dbtRunner` we exposed
 
 .. code-block:: python
+    from dbt.cli.main import dbtRunner
+    cli_args = ['run', '--project-dir', 'jaffle_shop']
 
-    from pprint import pprint
-    from dbt.cli import dbt_cli
-
-    pprint(dbt_cli.commands)
-
-this would show us all of the dbt commands that are currently implemented.
-
-.. code-block:: python
-
-    {'build': <Command build>,
-    'clean': <Command clean>,
-    'compile': <Command compile>,
-    'debug': <Command debug>,
-    'deps': <Command deps>,
-    'docs': <Group docs>,
-    'init': <Command init>,
-    'list': <Command list>,
-    'parse': <Command parse>,
-    'run': <Command run>,
-    'run-operation': <Command run-operation>,
-    'seed': <Command seed>,
-    'snapshot': <Command snapshot>,
-    'source': <Group source>,
-    'test': <Command test>}
-
-
-Right now the best way to invoke a command from python runtime is to use the `make_context` function from `dbt.cli.context` to create a context for the command we are running, then do the setup that would normally happen in the `cli` group, and involke the dbt command with that click context we just built.
-
-For make context, We would need to pass in the arguments that we want to invoke the command with, also the command that we are building this context for.
+    # initialize the dbt runner
+    dbt = dbtRunner()
+    # run the command
+    res, success = dbt.invoke(args)
 
+You can also pass in pre constructed object into dbtRunner, and we will use those objects instead of loading up from the disk.
 
 .. code-block:: python
 
-    from dbt.cli import dbt_cli
-    from dbt.cli.context import make_context
-    from dbt.tracking import track_run
-    from dbt.adapters.factory import adapter_management
-    from dbt.profiler import profiler
-    from dbt.config.runtime import load_project
-
-    command = 'run'
-    cli_args = ['--project-dir', 'jaffle_shop']
-    # make context
-    ctx = make_context(cli_args, dbt_cli.commands[command])
-
-    # do the setup that would normally happen in the cli group
-    # for this step we are looking to provide proper api soon
-    ctx.with_resource(track_run(run_command=command))
-    ctx.with_resource(adapter_management())
-    ctx.with_resource(profiler(enable=True, outfile="output.profile"))
-    project_dir = os.path.expanduser(ctx.params.get('project_dir'))
-    ctx.obj["project"] = load_project(project_dir, True, None, None)
+    # preload profile and project
+    profile = load_profile(project_dir, {}, 'testing-postgres')
+    project = load_project(project_dir, False, profile, {})
 
-    # invoke the command
-    dbt_cli.commands[command].invoke(ctx)
+    # initialize the runner with pre-loaded profile and project
+    dbt = dbtRunner(profile=profile, project=project)
+    # run the command, this will use the pre-loaded profile and project instead of loading
+    res, success = dbt.invoke(cli_args)
 
 
-For the full code example, you can refer to `example.py <https://github.com/dbt-labs/dbt-core/blob/feature/click-cli/core/dbt/cli/example.py>`_
+For the full example code, you can refer to `core/dbt/cli/example.py`
 
 API documentation
 -----------------