cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/__about__.py

@@ -0,0 +1 @@
+__version__ = "5.0.0"

cumulusci/__init__.py

@@ -0,0 +1,22 @@
+import os
+import sys
+import warnings
+from importlib.metadata import PackageNotFoundError, version
+
+# Suppress pkg_resources deprecation warnings from dependencies
+warnings.filterwarnings("ignore", message=".*pkg_resources.*", category=UserWarning)
+
+from simple_salesforce import api, bulk
+
+__location__ = os.path.dirname(os.path.realpath(__file__))
+
+try:
+    __version__ = version("cumulusci")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+if sys.version_info < (3, 8):  # pragma: no cover
+    raise Exception("CumulusCI requires Python 3.8+.")
+
+api.OrderedDict = dict
+bulk.OrderedDict = dict

cumulusci/__main__.py

@@ -0,0 +1,3 @@
+from cumulusci.cli.cci import main
+
+main()

cumulusci/cli/cci.py

@@ -0,0 +1,244 @@
+import code
+import contextlib
+import pdb
+import runpy
+import sys
+import traceback
+
+import click
+import requests
+import rich
+from rich.console import Console
+from rich.markup import escape
+
+import cumulusci
+from cumulusci.core.debug import set_debug_mode
+from cumulusci.core.exceptions import CumulusCIUsageError
+from cumulusci.utils import get_cci_upgrade_command
+from cumulusci.utils.http.requests_utils import init_requests_trust
+from cumulusci.utils.logging import tee_stdout_stderr
+
+from .error import error
+from .flow import flow
+from .logger import get_tempfile_logger, init_logger
+from .org import org
+from .plan import plan
+from .project import project
+from .robot import robot
+from .runtime import CliRuntime, pass_runtime
+from .service import service
+from .task import task
+from .utils import (
+    check_latest_version,
+    get_installed_version,
+    get_latest_final_version,
+    warn_if_no_long_paths,
+)
+
+SUGGEST_ERROR_COMMAND = (
+    """Run this command for more information about debugging errors: cci error --help"""
+)
+
+USAGE_ERRORS = (CumulusCIUsageError, click.UsageError)
+
+
+#
+# Root command
+#
+def main(args=None):
+    """Main CumulusCI CLI entry point.
+
+    This runs as the first step in processing any CLI command.
+
+    This wraps the `click` library in order to do some initialization and centralized error handling.
+    """
+    with contextlib.ExitStack() as stack:
+        args = args or sys.argv
+
+        # (If enabled) set up requests to validate certs using system CA certs instead of certifi
+        init_requests_trust()
+
+        # Check for updates _unless_ we've been asked to output JSON,
+        # or if we're going to check anyway as part of the `version` command.
+        is_version_command = len(args) > 1 and args[1] == "version"
+        if "--json" not in args and not is_version_command:
+            check_latest_version()
+
+        # Only create logfiles for commands that are not `cci error`
+        is_error_command = len(args) > 2 and args[1] == "error"
+        tempfile_path = None
+        if not is_error_command:
+            logger, tempfile_path = get_tempfile_logger()
+            stack.enter_context(tee_stdout_stderr(args, logger, tempfile_path))
+
+        debug = "--debug" in args
+        if debug:
+            args.remove("--debug")
+
+        with set_debug_mode(debug):
+            try:
+                runtime = CliRuntime(load_keychain=False)
+            except Exception as e:
+                handle_exception(e, is_error_command, tempfile_path, debug)
+                sys.exit(1)
+
+            runtime.check_cumulusci_version()
+            should_show_stacktraces = runtime.universal_config.cli__show_stacktraces
+
+            init_logger(debug=debug)
+            # Hand CLI processing over to click, but handle exceptions
+            try:
+                cli(args[1:], standalone_mode=False, obj=runtime)
+            except click.Abort:  # Keyboard interrupt
+                console = Console()
+                show_debug_info() if debug else console.print("\n[red bold]Aborted!")
+                sys.exit(1)
+            except Exception as e:
+                if debug:
+                    show_debug_info()
+                else:
+                    handle_exception(
+                        e,
+                        is_error_command,
+                        tempfile_path,
+                        should_show_stacktraces,
+                    )
+                sys.exit(1)
+
+
+def handle_exception(
+    error,
+    is_error_cmd,
+    logfile_path,
+    should_show_stacktraces=False,
+):
+    """Displays error of appropriate message back to user, prompts user to investigate further
+    with `cci error` commands, and writes the traceback to the latest logfile.
+    """
+    error_console = Console(stderr=True)
+    if isinstance(error, requests.exceptions.ConnectionError):
+        connection_error_message(error_console)
+    elif isinstance(error, click.ClickException):
+        error_console.print(f"[red bold]Error: {escape(error.format_message())}")
+    else:
+        # We call str ourselves to make Typeguard shut up.
+        error_console.print(f"[red bold]Error: {escape(str(error))}")
+    # Only suggest gist command if it wasn't run
+    if not is_error_cmd:
+        error_console.print(f"[yellow]{SUGGEST_ERROR_COMMAND}")
+
+    # This is None if we're handling an exception for a `cci error` command.
+    if logfile_path:
+        with open(logfile_path, "a") as log_file:
+            traceback.print_exc(file=log_file)  # log stacktrace silently
+
+    if should_show_stacktraces and not isinstance(error, USAGE_ERRORS):
+        error_console.print_exception()
+
+
+def connection_error_message(console: Console):
+    message = (
+        "We encountered an error with your internet connection. "
+        "Please check your connection and try the last cci command again."
+    )
+    console.print(f"[red bold]{message}")
+
+
+def show_debug_info():
+    """Displays the traceback and opens pdb"""
+    traceback.print_exc()
+    pdb.post_mortem()
+
+
+def show_version_info():
+    console = rich.get_console()
+    console.print(f"CumulusCI version: {cumulusci.__version__} ({sys.argv[0]})")
+    console.print(f"Python version: {sys.version.split()[0]} ({sys.executable})")
+    console.print()
+    warn_if_no_long_paths(console=console)
+
+    current_version = get_installed_version()
+    latest_version = get_latest_final_version()
+
+    if not latest_version > current_version:
+        console.print("You have the latest version of CumulusCI :sun_behind_cloud:\n")
+        display_release_notes_link(str(latest_version))
+        return
+
+    console.print(
+        f"[yellow]There is a newer version of CumulusCI available: {str(latest_version)}"
+    )
+    console.print(f"To upgrade, run `{get_cci_upgrade_command()}`")
+    display_release_notes_link(str(latest_version))
+
+
+def display_release_notes_link(latest_version: str) -> None:
+    """Provide a link to the latest CumulusCI Release Notes"""
+    release_notes_link = (
+        f"https://github.com/SFDO-Tooling/CumulusCI/releases/tag/v{latest_version}"
+    )
+    console = rich.get_console()
+    console.print(
+        f"See the latest CumulusCI Release Notes: [link={release_notes_link}]{release_notes_link}[/link]"
+    )
+
+
+def version_info_wrapper(
+    ctx: click.Context, param: click.Parameter, value: bool
+) -> None:
+    if not value:
+        return
+    show_version_info()
+    ctx.exit()
+
+
+@click.group("main", help="")
+@click.option(  # based on https://click.palletsprojects.com/en/8.1.x/options/#callbacks-and-eager-options
+    "--version",
+    is_flag=True,
+    expose_value=False,
+    is_eager=True,
+    help="Show the version and exit.",
+    callback=version_info_wrapper,
+)
+def cli():
+    """Top-level `click` command group."""
+
+
+@cli.command(name="version", help="Print the current version of CumulusCI")
+def version():
+    show_version_info()
+
+
+@cli.command(name="shell", help="Drop into a Python shell")
+@click.option("--script", help="Path to a script to run", type=click.Path())
+@click.option("--python", help="Python code to run directly")
+@pass_runtime(require_project=False, require_keychain=True)
+def shell(runtime, script=None, python=None):
+    # alias for backwards-compatibility
+    variables = {
+        "config": runtime,
+        "runtime": runtime,
+        "project_config": runtime.project_config,
+    }
+
+    if script:
+        if python:
+            raise click.UsageError("Cannot specify both --script and --python")
+        runpy.run_path(script, init_globals=variables)
+    elif python:
+        exec(python, variables)
+    else:
+        code.interact(local=variables)
+
+
+# Top Level Groups
+
+cli.add_command(error)
+cli.add_command(project)
+cli.add_command(org)
+cli.add_command(service)
+cli.add_command(task)
+cli.add_command(flow)
+cli.add_command(plan)
+cli.add_command(robot)

cumulusci/cli/error.py

@@ -0,0 +1,125 @@
+import platform
+import sys
+import webbrowser
+from datetime import datetime
+from pathlib import Path
+
+import click
+import github3
+
+import cumulusci
+from cumulusci.cli.utils import warn_if_no_long_paths, win32_long_paths_enabled
+from cumulusci.core.exceptions import CumulusCIException
+from cumulusci.core.github import check_github_scopes, create_gist, get_github_api
+
+from .runtime import pass_runtime
+
+GIST_404_ERR_MSG = """A 404 error code was returned when trying to create your gist.
+Please ensure that your GitHub personal access token has the 'Create gists' scope."""
+
+
+@click.group("error", short_help="Get or share information about an error")
+def error():
+    """
+    Get or share information about an error
+
+    If you'd like to dig into an error more yourself,
+    you can get the last few lines of context about it
+    from `cci error info`.
+
+    If you'd like to submit it to a developer for conversation,
+    you can use the `cci error gist` command. Just make sure
+    that your GitHub access token has the 'create gist' scope.
+
+    If you'd like to regularly see stack traces, set the `show_stacktraces`
+    option to `True` in the "cli" section of `~/.cumulusci/cumulusci.yml`, or to
+    see a stack-trace (and other debugging information) just once, use the `--debug`
+    command line option.
+
+    For more information on working with errors in CumulusCI visit:
+    https://cumulusci.readthedocs.io/en/latest/features.html#working-with-errors
+    """
+
+
+def get_logfile_path():
+    return Path.home() / ".cumulusci" / "logs" / "cci.log"
+
+
+@error.command(
+    name="info",
+    help="Outputs the most recent traceback (if one exists in the most recent log)",
+)
+def error_info():
+    warn_if_no_long_paths()
+    logfile_path = get_logfile_path()
+    if not logfile_path.is_file():
+        click.echo(f"No logfile found at: {logfile_path}")
+        return
+
+    traceback = get_traceback(logfile_path.read_text(encoding="utf-8"))
+    click.echo(traceback)
+
+
+def get_traceback(log_content: str) -> str:
+    """Returns the the traceback in a logfile if it exists."""
+    stacktrace_start = "Traceback (most recent call last):"
+    if stacktrace_start not in log_content:
+        return f"\nNo stacktrace found in: {get_logfile_path()}\n"
+
+    stacktrace = ""
+    for i, line in enumerate(reversed(log_content.split("\n")), 1):
+        stacktrace = "\n" + line + stacktrace
+        if stacktrace_start in line:
+            break
+
+    return stacktrace
+
+
+@error.command(name="gist", help="Creates a GitHub gist from the latest logfile")
+@pass_runtime(require_project=False, require_keychain=True)
+def error_gist(runtime):
+    logfile_path = get_logfile_path()
+    if logfile_path.is_file():
+        log_content = logfile_path.read_text(encoding="utf-8")
+    else:
+        log_not_found_msg = """No logfile to open at path: {}
+        Please ensure you're running this command from the same directory you were experiencing an issue."""
+        error_msg = log_not_found_msg.format(logfile_path)
+        click.echo(error_msg)
+        raise CumulusCIException(error_msg)
+
+    last_cmd_header = "\n\n\nLast Command Run\n================================\n"
+    filename = f"cci_output_{datetime.utcnow()}.txt"
+    files = {
+        filename: {"content": f"{get_context_info()}{last_cmd_header}{log_content}"}
+    }
+
+    try:
+        gh = runtime.keychain.get_service("github")
+        gist = create_gist(
+            get_github_api(gh.username, gh.password or gh.token),
+            "CumulusCI Error Output",
+            files,
+        )
+    except github3.exceptions.NotFoundError as exc:
+        scope_warning = check_github_scopes(exc)
+        raise CumulusCIException(GIST_404_ERR_MSG + f"\n\n{scope_warning}")
+    except Exception as e:
+        raise CumulusCIException(
+            f"An error occurred attempting to create your gist:\n{e}"
+        )
+    else:
+        click.echo(f"Gist created: {gist.html_url}")
+        webbrowser.open(gist.html_url)
+
+
+def get_context_info():
+    host_info = platform.uname()
+
+    info = []
+    info.append(f"CumulusCI version: {cumulusci.__version__}")
+    info.append(f"Python version: {sys.version.split()[0]} ({sys.executable})")
+    info.append(f"Environment Info: {host_info.system} / {host_info.machine}")
+    if host_info.system == "Windows":
+        info.append(f"Windows long path support enabled: {win32_long_paths_enabled()}")
+    return "\n".join(info)

cumulusci/cli/flow.py

@@ -0,0 +1,185 @@
+import json
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+
+import click
+
+from cumulusci.core.exceptions import FlowNotFoundError
+from cumulusci.core.utils import format_duration
+from cumulusci.utils import document_flow, flow_ref_title_and_intro
+from cumulusci.utils.yaml.safer_loader import load_yaml_data
+
+from .runtime import pass_runtime
+from .ui import CliTable
+from .utils import group_items
+
+
+@click.group("flow", help="Commands for finding and running flows for a project")
+def flow():
+    pass
+
+
+@flow.command(name="doc", help="Exports RST format documentation for all flows")
+@click.option(
+    "--project", "project", is_flag=True, help="Include project-specific flows only"
+)
+@pass_runtime(require_project=False, require_keychain=True)
+def flow_doc(runtime, project=False):
+    flow_info_path = Path(__file__, "..", "..", "..", "docs", "flows.yml").resolve()
+    with open(flow_info_path, "r", encoding="utf-8") as f:
+        flow_info = load_yaml_data(f)
+    click.echo(flow_ref_title_and_intro(flow_info["intro_blurb"]))
+    flow_info_groups = list(flow_info["groups"].keys())
+
+    universal_flows = runtime.universal_config.list_flows()
+    if project:
+        flows = [
+            flow
+            for flow in runtime.project_config.list_flows()
+            if flow not in universal_flows
+        ]
+    else:
+        flows = universal_flows
+    flows_by_group = group_items(flows)
+    flow_groups = sorted(
+        flows_by_group.keys(),
+        key=lambda group: flow_info_groups.index(group)
+        if group in flow_info_groups
+        else 100,
+    )
+
+    for group in flow_groups:
+        click.echo(f"{group}\n{'-' * len(group)}")
+        if group in flow_info["groups"]:
+            click.echo(flow_info["groups"][group]["description"])
+
+        for flow in sorted(flows_by_group[group]):
+            flow_name, flow_description = flow
+            try:
+                flow_coordinator = runtime.get_flow(flow_name)
+            except FlowNotFoundError as e:
+                raise click.UsageError(str(e))
+
+            additional_info = None
+            if flow_name in flow_info.get("flows", {}):
+                additional_info = flow_info["flows"][flow_name]["rst_text"]
+
+            click.echo(
+                document_flow(
+                    flow_name,
+                    flow_description,
+                    flow_coordinator,
+                    additional_info=additional_info,
+                )
+            )
+            click.echo("")
+
+
+@flow.command(name="list", help="List available flows for the current context")
+@click.option("--plain", is_flag=True, help="Print the table using plain ascii.")
+@click.option("--json", "print_json", is_flag=True, help="Print a json string")
+@pass_runtime(require_project=False)
+def flow_list(runtime, plain, print_json):
+    plain = plain or runtime.universal_config.cli__plain_output
+    flows = runtime.get_available_flows()
+    if print_json:
+        click.echo(json.dumps(flows))
+        return None
+
+    flow_groups = group_items(flows)
+    for group, flows in flow_groups.items():
+        data = [["Flow", "Description"]]
+        data.extend(sorted(flows))
+        table = CliTable(
+            data,
+            group,
+        )
+        table.echo(plain)
+
+    click.echo(
+        "Use "
+        + click.style("cci flow info <flow_name>", bold=True)
+        + " to get more information about a flow."
+    )
+
+
+@flow.command(name="info", help="Displays information for a flow")
+@click.argument("flow_name")
+@pass_runtime(require_keychain=True)
+def flow_info(runtime, flow_name):
+    try:
+        coordinator = runtime.get_flow(flow_name)
+        output = coordinator.get_summary(verbose=True)
+        click.echo(output)
+    except FlowNotFoundError as e:
+        raise click.UsageError(str(e))
+
+
+@flow.command(name="run", help="Runs a flow")
+@click.argument("flow_name")
+@click.option(
+    "--org",
+    help="Specify the target org.  By default, runs against the current default org",
+)
+@click.option(
+    "--delete-org",
+    is_flag=True,
+    help="If set, deletes the scratch org after the flow completes",
+)
+@click.option(
+    "--debug", is_flag=True, help="Drops into pdb, the Python debugger, on an exception"
+)
+@click.option(
+    "-o",
+    nargs=2,
+    multiple=True,
+    help="Pass task specific options for the task as '-o taskname__option value'.  You can specify more than one option by using -o more than once.",
+)
+@click.option(
+    "--no-prompt",
+    is_flag=True,
+    help="Disables all prompts.  Set for non-interactive mode use such as calling from scripts or CI systems",
+)
+@pass_runtime(require_keychain=True)
+def flow_run(runtime, flow_name, org, delete_org, debug, o, no_prompt):
+
+    # Get necessary configs
+    org, org_config = runtime.get_org(org)
+    if delete_org and not org_config.scratch:
+        raise click.UsageError("--delete-org can only be used with a scratch org")
+
+    # Parse command line options
+    options = defaultdict(dict)
+    if o:
+        for key, value in o:
+            if "__" in key:
+                task_name, option_name = key.split("__")
+                options[task_name][option_name] = value
+            else:
+                raise click.UsageError(
+                    "-o option for flows should contain __ to split task name from option name."
+                )
+
+    # Create the flow and handle initialization exceptions
+    try:
+        coordinator = runtime.get_flow(flow_name, options=options)
+        start_time = datetime.now()
+        coordinator.run(org_config)
+        duration = datetime.now() - start_time
+        click.echo(f"Ran {flow_name} in {format_duration(duration)}")
+    except Exception:
+        runtime.alert(f"Flow error: {flow_name}")
+        raise
+    finally:
+        # Delete the scratch org if --delete-org was set
+        if delete_org:
+            try:
+                org_config.delete_org()
+            except Exception as e:
+                click.echo(
+                    "Scratch org deletion failed.  Ignoring the error below to complete the flow:"
+                )
+                click.echo(str(e))
+
+    runtime.alert(f"Flow Complete: {flow_name}")

cumulusci/cli/logger.py

@@ -0,0 +1,72 @@
+""" CLI logger """
+import logging
+import os
+import sys
+import tempfile
+
+import requests
+from rich.logging import RichHandler
+
+try:
+    import colorama
+except ImportError:
+    # coloredlogs only installs colorama on Windows
+    pass
+
+
+def init_logger(debug=False):
+    """Initialize the logger"""
+
+    logger = logging.getLogger(__name__.split(".")[0])
+    for handler in logger.handlers:  # pragma: no cover
+        logger.removeHandler(handler)
+
+    if os.name == "nt" and "colorama" in sys.modules:  # pragma: no cover
+        colorama.init()
+
+    logger.addHandler(
+        RichHandler(
+            rich_tracebacks=True,
+            show_level=debug,
+            show_path=debug,
+            tracebacks_show_locals=debug,
+        )
+    )
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+
+    if debug:  # pragma: no cover
+        # Referenced from:
+        # https://github.com/urllib3/urllib3/blob/cd55f2fe98df4d499ab5c826433ee4995d3f6a60/src/urllib3/__init__.py#L48
+        def add_rich_logger(
+            module: str, level: int = logging.DEBUG
+        ) -> logging.StreamHandler:
+            """Retrieve the logger for the given module.
+            Remove all handlers from it, and add a single RichHandler."""
+            logger = logging.getLogger(module)
+            for handler in logger.handlers:
+                logger.removeHandler(handler)
+
+            handler = RichHandler()
+            logger.addHandler(handler)
+            logger.setLevel(level)
+            logger.debug(f"Added rich.logging.RichHandler to logger: {module}")
+            return handler
+
+        # monkey patch urllib3 logger
+        requests.packages.urllib3.add_stderr_logger = add_rich_logger
+        requests.packages.urllib3.add_stderr_logger("urllib3")
+
+
+def get_tempfile_logger():
+    """Creates a logger that writes to a temporary
+    logfile. Returns the logger and path to tempfile"""
+    logger = logging.getLogger("tempfile_logger")
+    file_handle, filepath = tempfile.mkstemp()
+    # close the file as it will be opened again by FileHandler
+    os.close(file_handle)
+    handler = logging.FileHandler(filepath, encoding="utf-8")
+    handler.terminator = ""
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG)
+    return logger, filepath