cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/cli/tests/utils.py

@@ -0,0 +1,52 @@
+import os
+from unittest import mock
+
+import click
+from click.testing import CliRunner
+
+from cumulusci.cli.cci import cli
+from cumulusci.core.tasks import BaseTask
+
+
+def run_click_command(cmd, *args, **kw):
+    """Run a click command with a mock context and injected CCI runtime object."""
+    runtime = kw.pop("runtime", mock.Mock())
+    with click.Context(command=mock.Mock(), obj=runtime):
+        return cmd.callback(*args, **kw)
+
+
+def run_cli_command(*args, runtime=None, input=None, **kw):
+    """Run a click command with arg parsing and injected CCI runtime object."""
+    if tuple(map(int, click.__version__.split("."))) >= (8, 1, 0):
+        runner = CliRunner()
+    else:
+        runner = CliRunner(mix_stderr=False)
+    result = runner.invoke(
+        cli,
+        args,
+        obj=runtime,
+        input=input,
+        catch_exceptions=False,
+        standalone_mode=False,
+    )
+    return result
+
+
+def recursive_list_files(d="."):
+    result = []
+    for d, subdirs, files in os.walk(d):
+        d = d.replace(os.path.sep, "/")
+        if d != ".":
+            result.append("/".join([d, ""])[2:])
+        for f in files:
+            result.append("/".join([d, f])[2:])
+    result.sort()
+    return result
+
+
+class DummyTask(BaseTask):
+    task_docs = "Some task docs."
+    task_options = {"color": {"description": "It's a color!", "required": True}}
+
+    def _run_task(self):
+        click.echo(f"<{self.__class__}>\n\tcolor: {self.options['color']}")

cumulusci/cli/ui.py

@@ -0,0 +1,234 @@
+# -*- coding: utf-8 -*-
+"""Format and display CLI output.
+
+Classes:
+    CliTable: Pretty prints tabular data to stdout, via Rich's Console API
+"""
+import os
+from typing import Any, List, Union
+
+import rich
+from rich import box, print
+from rich.console import Console
+from rich.style import Style
+from rich.table import Column, Table
+
+CHECKMARK = "[green]:heavy_check_mark:" if os.name == "posix" else "+"
+CROSSMARK = "[red]:cross_mark:" if os.name == "posix" else "-"
+
+
+class CliTable:
+    """Format and print data to the command line in tabular form.
+    Attributes:
+
+    * PICTOGRAM_TRUE: True boolean values are replaced with this string.
+    * PICTOGRAM_FALSE = False boolean values are replaced with this string.
+
+    Methods:
+    * echo: Print the table data to stdout using rich.Console.print
+    Class Methods:
+    * columnify_headers: Convert a list of strs to Columns
+    """
+
+    PICTOGRAM_TRUE = CHECKMARK
+    PICTOGRAM_FALSE = " "
+
+    def __init__(
+        self,
+        data: List[List[Any]],
+        title: str = None,
+        dim_rows: List[int] = None,
+        **kwargs,
+    ):
+        """Constructor.
+        Args:
+            data: Required. List[List] of data to format, with the heading as 0-th member.
+            title: String to use as the table's title.
+            dim_rows: List[int] of row indices to dim.
+        """
+
+        headers: List[Column] = self.columnify_headers(data[0])
+        rows = [self._stringify_row(r) for r in data[1:]]
+        self._table: Table = Table(*headers, title=title, box=box.SIMPLE, **kwargs)
+
+        for idx, row in enumerate(rows):
+            dim_row = idx + 1 in dim_rows if dim_rows else False
+            self._table.add_row(*row, style=Style(dim=dim_row))
+
+    def _stringify_row(self, row: list) -> List[str]:
+        return [self._stringify_cell(cell) for cell in row]
+
+    def _stringify_cell(self, cell: Any) -> str:
+        if isinstance(cell, bool):
+            cell = self.PICTOGRAM_TRUE if cell else self.PICTOGRAM_FALSE
+        elif cell is None:
+            cell = ""
+        else:
+            cell = str(cell)
+        return cell
+
+    def __rich__(self) -> str:
+        return self._table
+
+    def columnify_headers(self, headers: List[Union[str, Column]]) -> List[Column]:
+        """
+        Given a List[str, Column], return a list of Columns.
+
+        Strings are instantiated with default styles, Columns are unchanged.
+        """
+        cols: List[Column] = []
+
+        for header in headers:
+            if isinstance(header, Column):
+                cols.append(header)
+            else:
+                header: str = self._stringify_cell(header)
+                cols.append(Column(header=header, overflow="fold"))
+        return cols
+
+    def echo(self, plain=False, box_style: box.Box = None):
+        """
+        Print this table to the global Console using console.print().
+        """
+        orig_box = self._table.box
+        if plain:
+            self._table.box = box.ASCII2
+        else:
+            self._table.box = box_style or orig_box
+        console = rich.get_console()
+        console.print(self._table)
+        self._table.box = orig_box
+
+    @property
+    def table(self):
+        return self._table
+
+    def __str__(self):
+        from io import StringIO
+
+        console = Console(file=StringIO())
+        tab_width = console.size.width - 21
+        console.print(self._table, width=tab_width)
+        return console.file.getvalue()
+
+
+def _soql_table(results, truncated):
+    if results:
+        if truncated:
+            assert results[-1] == truncated
+            first_row = results[0]
+            fake_row = {k: "" for k, v in first_row.items()}
+            first_column = list(first_row)[0]
+            fake_row[first_column] = truncated
+
+            results[-1] = fake_row
+
+        headings = list(results[0].keys())
+        return CliTable(
+            [headings] + [list(map(str, r.values())) for r in results],
+        ).echo()
+    else:
+        return CliTable([["No results"]]).echo()
+
+
+def _summarize(field):
+    if field["referenceTo"]:
+        allowed = field["referenceTo"]
+    elif field["picklistValues"]:
+        allowed = [value["value"] for value in field["picklistValues"]]
+    else:
+        allowed = field["type"]
+    return (field["name"], allowed)
+
+
+class SimpleSalesforceUIHelpers:
+    def __init__(self, sf):
+        self._sf = sf
+
+    def query(self, query, format="table", include_deleted=False, max_rows=100):
+        """Return the result of a Salesforce SOQL query.
+
+        Arguments:
+
+            * query -- the SOQL query to send to Salesforce, e.g.
+                    SELECT Id FROM Lead WHERE Email = "waldo@somewhere.com"
+            * include_deleted -- True if deleted records should be included
+            * format -- one of these values:
+                - "table" -- printable ASCII table (the default)
+                - "obj" -- ordinary Python objects
+                - "pprint" -- string in easily readable Python dict shape
+                - "json" -- JSON
+            * max_rows -- maximum rows to output, defaults to 100
+
+        For example:
+            query("select Name, Id from Account", format="pprint")
+            contact_ids = query("select count(Id) from Contact", format="obj")
+        """
+        results = self._sf.query_all(query, include_deleted=include_deleted)["records"]
+
+        if len(results) > max_rows:
+            truncated = f"... truncated {len(results) - max_rows} rows"
+            results = results[0:max_rows]
+        else:
+            truncated = False
+
+        for result in results:
+            if result.get("attributes"):
+                del result["attributes"]
+
+        if truncated:
+            results.append(truncated)
+
+        if format == "table":
+            help_message = "Type help(query) to learn about other return formats or assigning the result."
+            print(_soql_table(results, truncated))
+            print()
+            print(help_message)
+            rc = None
+        elif format == "obj":
+            rc = results
+        elif format == "pprint":
+            from rich.pretty import pprint
+
+            pprint(results)
+            rc = None
+        elif format == "json":
+            from json import dumps
+
+            rc = dumps(results, indent=2)
+        else:
+            raise TypeError(f"Unknown format `{format}`")
+
+        return rc
+
+    def describe(self, sobj_name, detailed=False, format="pprint"):
+        """Describe an sobject.
+
+        Arguments:
+
+            sobj_name - sobject name to describe. e.g. "Account", "Contact"
+            detailed - set to `True` to get detailed information about object
+            format -- one of these values:
+            - "pprint" -- string in easily readable Python dict shape (default)
+            - "obj" -- ordinary Python objects
+
+        For example:
+
+            >>> describe("Account")
+            >>> data = describe("Account", detailed=True, format=obj)
+        """
+        from pprint import pprint
+
+        data = getattr(self._sf, sobj_name).describe()
+
+        if detailed:
+            rc = data
+        else:
+            rc = dict(_summarize(field) for field in data["fields"])
+
+        if format == "pprint":
+            pprint(rc)
+        elif format == "obj":
+            return rc
+        else:
+            raise TypeError(f"Unknown format {format}")

cumulusci/cli/utils.py

@@ -0,0 +1,150 @@
+import contextlib
+import os
+import re
+import sys
+import time
+from collections import defaultdict
+from typing import Optional
+
+import click
+import requests
+from packaging import version as packaging_version
+from rich.console import Console
+
+from cumulusci import __version__
+from cumulusci.core.config import UniversalConfig
+from cumulusci.utils import get_cci_upgrade_command
+from cumulusci.utils.http.requests_utils import safe_json_from_response
+
+LOWEST_SUPPORTED_VERSION = (3, 8, 0)
+WIN_LONG_PATH_WARNING = """
+WARNING: Long path support is not enabled. This can lead to errors with some
+tasks. Your administrator will need to activate the "Enable Win32 long paths"
+group policy, or set LongPathsEnabled to 1 in the registry key
+HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\FileSystem.
+"""
+
+
+def group_items(items):
+    """Given a list of dicts with 'group' keys,
+    returns those items in lists categorized group"""
+    groups = defaultdict(list)
+    for item in items:
+        group_name = item["group"] or "Other"
+        groups[group_name].append([item["name"], item["description"]])
+
+    return groups
+
+
+@contextlib.contextmanager
+def timestamp_file(
+    config_dir: Optional[str] = None, timestamp_file: str = "cumulus_timestamp"
+):
+    """Opens a file for tracking the time of the last version check"""
+
+    config_dir = (
+        UniversalConfig.default_cumulusci_dir() if config_dir is None else config_dir
+    )
+    timestamp_file = os.path.join(config_dir, timestamp_file)
+
+    try:
+        with open(timestamp_file, "r+") as f:
+            yield f
+    except IOError:  # file does not exist
+        with open(timestamp_file, "w+") as f:
+            yield f
+
+
+FINAL_VERSION_RE = re.compile(r"^[\d\.]+$")
+
+
+def is_final_release(version: str) -> bool:
+    """Returns bool whether version string should be considered a final release.
+
+    cumulusci versions are considered final if they contain only digits and periods.
+    e.g. 1.0.1 is final but 2.0b1 and 2.0.dev0 are not.
+    """
+    return bool(FINAL_VERSION_RE.match(version))
+
+
+def get_latest_final_version():
+    """return the latest version of cumulusci in pypi, be defensive"""
+    # use the pypi json api https://wiki.python.org/moin/PyPIJSON
+    res = safe_json_from_response(
+        requests.get("https://pypi.org/pypi/cumulusci/json", timeout=5)
+    )
+    with timestamp_file() as f:
+        f.write(str(time.time()))
+    versions = []
+    for versionstring in res["releases"].keys():
+        if not is_final_release(versionstring):
+            continue
+        versions.append(packaging_version.parse(versionstring))
+    versions.sort(reverse=True)
+    return versions[0]
+
+
+def check_latest_version():
+    """checks for the latest version of cumulusci from pypi, max once per hour"""
+    check = True
+
+    with timestamp_file() as f:
+        timestamp = float(f.read() or 0)
+    delta = time.time() - timestamp
+    check = delta > 3600
+
+    if check:
+        try:
+            latest_version = get_latest_final_version()
+        except requests.exceptions.RequestException as e:
+            click.echo("Error checking cci version:", err=True)
+            click.echo(str(e), err=True)
+            return
+
+        result = latest_version > get_installed_version()
+        if result:
+            click.echo(
+                f"""An update to CumulusCI is available. To install the update, run this command: {get_cci_upgrade_command()}""",
+                err=True,
+            )
+
+        if sys.version_info < LOWEST_SUPPORTED_VERSION:
+            click.echo(
+                "Sorry! Your Python version is not supported. Please upgrade to Python 3.9.",
+                err=True,
+            )
+
+
+def parse_version(versionstring: str) -> packaging_version.Version:
+    """Parse a version string into a Version object."""
+    return packaging_version.parse(versionstring)
+
+
+def get_installed_version() -> packaging_version.Version:
+    """Get the installed version of CumulusCI."""
+    return parse_version(__version__)
+
+
+def win32_long_paths_enabled() -> bool:
+    """Boolean indicating whether long paths are available on Windows systems.
+
+    Reads the Windows Registry the running platform. Throws ModuleNotFoundError
+    if run on non-Windows platforms.
+    """
+    # Only present on windows, so import it here instead
+    import winreg
+
+    access_registry = winreg.ConnectRegistry(None, winreg.HKEY_LOCAL_MACHINE)
+    access_key = winreg.OpenKey(
+        access_registry, r"SYSTEM\CurrentControlSet\Control\FileSystem"
+    )
+
+    is_enabled, _ = winreg.QueryValueEx(access_key, "LongPathsEnabled")
+
+    return is_enabled == 1
+
+
+def warn_if_no_long_paths(console: Console = Console()) -> None:
+    """Print a warning to the user if long paths are not enabled."""
+    if sys.platform.startswith("win") and not win32_long_paths_enabled():
+        console.print(WIN_LONG_PATH_WARNING)

cumulusci/conftest.py

@@ -0,0 +1,181 @@
+import io
+import os
+from contextlib import contextmanager, nullcontext
+from http.client import HTTPMessage
+from logging import getLogger
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest import mock
+
+import pytest
+import yaml
+from pytest import fixture
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from cumulusci.core.dependencies.utils import TaskContext
+from cumulusci.core.github import get_github_api
+from cumulusci.salesforce_api.org_schema_models import Base
+from cumulusci.tasks.bulkdata.tests.integration_test_utils import (
+    ensure_accounts,
+    ensure_records,
+)
+from cumulusci.tasks.salesforce.tests.util import create_task_fixture
+from cumulusci.tests.pytest_plugins.pytest_sf_vcr import salesforce_vcr, vcr_config
+from cumulusci.tests.util import DummyKeychain, DummyOrgConfig, mock_env
+
+ensure_accounts = ensure_accounts
+ensure_records = ensure_records
+
+
+@fixture(scope="session", autouse=True)
+def mock_sleep():
+    """Patch time.sleep to avoid delays in unit tests"""
+    with mock.patch("time.sleep"):
+        yield
+
+
+class MockHttpResponse(mock.Mock):
+    def __init__(self, status):
+        super(MockHttpResponse, self).__init__()
+        self.status = status
+        self.strict = 0
+        self.version = 0
+        self.reason = None
+        self.msg = HTTPMessage(io.BytesIO())
+        self.closed = True
+
+    def read(self):  # pragma: no cover
+        return b""
+
+    def isclosed(self):
+        return self.closed
+
+
+@fixture
+def gh_api():
+    return get_github_api("TestOwner", "TestRepo")
+
+
+@fixture(scope="class", autouse=True)
+def restore_cwd():
+    d = os.getcwd()
+    try:
+        yield
+    finally:
+        os.chdir(d)
+
+
+@fixture
+def mock_http_response():
+    def _make_response(status):
+        return MockHttpResponse(status)
+
+    return _make_response
+
+
+@fixture(scope="function")
+def fallback_org_config():
+    def fallback_org_config():
+        return DummyOrgConfig(
+            name="pytest_sf_orgconnect_dummy_org_config", keychain=DummyKeychain()
+        )
+
+    return fallback_org_config
+
+
+vcr_config = fixture(vcr_config, scope="module")
+vcr = fixture(salesforce_vcr, scope="module")
+
+create_task_fixture = fixture(create_task_fixture, scope="function")
+
+
+# TODO: This should also chdir to a temp directory which
+#       can represent the repo-root, but that will require
+#       test case changes.
+@pytest.fixture(autouse=True)
+def patch_home_and_env(request):
+    "Patch the default home directory and $HOME environment for all tests at once."
+
+    use_real_env = request.node.get_closest_marker("use_real_env")
+
+    with TemporaryDirectory(prefix="fake_home_") as home:
+        if use_real_env:
+            mock_env_cm = nullcontext()
+        else:
+            mock_env_cm = mock_env(home)
+
+        with mock_env_cm:
+            Path(home, ".cumulusci").mkdir()
+            Path(home, ".cumulusci/cumulusci.yml").touch()
+            yield
+
+
+@pytest.fixture()
+def temp_db():
+    with TemporaryDirectory() as t:
+
+        @contextmanager
+        def open_db():
+            engine = create_engine(f"sqlite:///{t}/tempfile.db")
+            with engine.connect() as connection:
+                Session = sessionmaker(bind=connection)
+                Base.metadata.bind = engine
+                Base.metadata.create_all()
+                session = Session()
+                yield connection, Base.metadata, session
+
+        yield open_db
+
+
+@pytest.fixture()
+def delete_data_from_org(create_task):
+    def delete_data_from_org(object_names):
+        from cumulusci.tasks.bulkdata.delete import DeleteData
+
+        t = create_task(DeleteData, {"objects": object_names})
+        assert t.org_config.scratch
+        t()
+
+    return delete_data_from_org
+
+
+@pytest.fixture(scope="session")
+def cumulusci_test_repo_root():
+    return Path(__file__).parent.parent
+
+
+@pytest.fixture(scope="session")
+def global_describe(cumulusci_test_repo_root):
+    global_describe_file = (
+        cumulusci_test_repo_root
+        / "cumulusci/tests/shared_cassettes/GET_sobjects_Global_describe.yaml"
+    )
+    with global_describe_file.open() as f:
+        data = yaml.safe_load(yaml.safe_load(f)["response"]["body"]["string"])
+
+    def global_describe_specific_sobjects(sobjects: int = None):
+        if sobjects is None:  # pragma: no cover
+            subset = data.copy()
+        elif isinstance(sobjects, int):
+            subset = data.copy()
+            subset["sobjects"] = subset["sobjects"][0:sobjects]
+        elif isinstance(sobjects, (list, tuple)):  # pragma: no cover
+            raise NotImplementedError(
+                "We could implement a by-name subsetting here when we need it."
+            )
+        return subset
+
+    return global_describe_specific_sobjects
+
+
+@pytest.fixture(scope="session")
+def shared_vcr_cassettes(cumulusci_test_repo_root):
+    return Path(cumulusci_test_repo_root / "cumulusci/tests/shared_cassettes")
+
+
+@pytest.fixture
+def task_context(org_config, project_config):
+    return TaskContext(
+        org_config=org_config, project_config=project_config, logger=getLogger()
+    )

cumulusci/core/config/BaseConfig.py

@@ -0,0 +1,5 @@
+from cumulusci.utils.deprecation import warn_moved
+
+from .base_config import *  # noqa
+
+warn_moved(".base_config", ".BaseConfig")

cumulusci/core/config/BaseTaskFlowConfig.py

@@ -0,0 +1,5 @@
+from cumulusci.utils.deprecation import warn_moved
+
+from .base_task_flow_config import *  # noqa
+
+warn_moved(".base_task_flow_config", ".BaseTaskFlowConfig")

cumulusci/core/config/OrgConfig.py

@@ -0,0 +1,5 @@
+from cumulusci.utils.deprecation import warn_moved
+
+from .org_config import *  # noqa
+
+warn_moved(".org_config", ".OrgConfig")

cumulusci/core/config/ScratchOrgConfig.py

@@ -0,0 +1,5 @@
+from cumulusci.utils.deprecation import warn_moved
+
+from .scratch_org_config import *  # noqa
+
+warn_moved(".scratch_org_config", ".ScratchOrgConfig")