cumulusci 3.68.0.dev1__tar.gz → 3.68.0.dev2__tar.gz

{cumulusci-3.68.0.dev1 → cumulusci-3.68.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cumulusci
-Version: 3.68.0.dev1
+Version: 3.68.0.dev2
 Summary: Build and release tools for Salesforce developers
 Home-page: https://github.com/SFDO-Tooling/CumulusCI
 Author: Salesforce.org

{cumulusci-3.68.0.dev1 → cumulusci-3.68.0.dev2}/cumulusci/core/config/base_task_flow_config.py

@@ -1,4 +1,5 @@
 from difflib import get_close_matches
+from typing import Any, Dict, List
 
 from cumulusci.core.config import BaseConfig, FlowConfig, TaskConfig
 from cumulusci.core.exceptions import (
@@ -8,10 +9,9 @@ from cumulusci.core.exceptions import (
 )
 
 
-def list_infos(infos):
+def list_infos(infos: dict) -> List[Dict[str, str]]:
     rv = []
-    for info_name in infos:
-        info = infos[info_name]
+    for info_name, info in infos.items():
         if not info:
             info = {}
         rv.append(
@@ -21,6 +21,7 @@ def list_infos(infos):
                 "group": info.get("group"),
             }
         )
+
     return rv
 
 
@@ -30,11 +31,11 @@ class BaseTaskFlowConfig(BaseConfig):
     tasks: dict
     flows: dict
 
-    def list_tasks(self):
+    def list_tasks(self) -> List[Dict[str, str]]:
         """Returns a list of task info dictionaries with keys 'name' and 'description'"""
         return list_infos(self.tasks)
 
-    def get_task(self, name):
+    def get_task(self, name: str) -> TaskConfig:
         """Returns a TaskConfig"""
         config = self.lookup(f"tasks__{name}")
         if not config and name not in self.tasks:
@@ -53,11 +54,11 @@ class BaseTaskFlowConfig(BaseConfig):
 
         return TaskConfig(config)
 
-    def list_flows(self):
+    def list_flows(self) -> List[Dict[str, str]]:
         """Returns a list of flow info dictionaries with keys 'name' and 'description'"""
         return list_infos(self.flows)
 
-    def get_flow(self, name):
+    def get_flow(self, name: str) -> FlowConfig:
         """Returns a FlowConfig"""
         config = self.lookup(f"flows__{name}")
         if not config:
@@ -66,7 +67,7 @@ class BaseTaskFlowConfig(BaseConfig):
             raise FlowNotFoundError(error_msg + suggestion)
         return FlowConfig(config)
 
-    def get_suggested_name(self, name, steps):
+    def get_suggested_name(self, name: str, steps: Dict[str, Any]) -> str:
         """
         Given a name that cannot be resolved and a list of tasks/flow dicts, returns the nearest match.
         """

{cumulusci-3.68.0.dev1 → cumulusci-3.68.0.dev2}/cumulusci/core/flowrunner.py

@@ -51,26 +51,35 @@ Option values/overrides can be passed in at a number of levels, in increasing or
 
 """
 
-# we don't actually use this set of imports, they're just in type
-# comments, which require explicit runtime import when checking...
-try:
-    from typing import List
-except ImportError:  # pragma: no cover
-    pass
-
 import copy
 import logging
-from collections import defaultdict, namedtuple
+from collections import defaultdict
 from distutils.version import LooseVersion
 from operator import attrgetter
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    DefaultDict,
+    Dict,
+    List,
+    NamedTuple,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
 
 from jinja2.sandbox import ImmutableSandboxedEnvironment
 
 from cumulusci.core.config import FlowConfig, TaskConfig
+from cumulusci.core.config.org_config import OrgConfig
+from cumulusci.core.config.project_config import BaseProjectConfig
 from cumulusci.core.exceptions import FlowConfigError, FlowInfiniteLoopError
 from cumulusci.core.utils import import_global
 
-# TODO: define exception types: flowfailure, taskimporterror, etc?
+if TYPE_CHECKING:
+    from cumulusci.core.tasks import BaseTask
+
 
 RETURN_VALUE_OPTION_PREFIX = "^^"
 
@@ -85,32 +94,44 @@ class StepVersion(LooseVersion):
         self.version = tuple(-1 if x == "/" else x for x in self.version)
 
 
-class StepSpec(object):
+class StepSpec:
     """simple namespace to describe what the flowrunner should do each step"""
 
     __slots__ = (
-        "step_num",  # type: str
-        "task_name",  # type: str
-        "task_config",  # type: dict
-        "task_class",  # type: str
+        "step_num",
+        "task_name",
+        "task_config",
+        "task_class",
         "project_config",
-        "allow_failure",  # type: bool
-        "path",  # type: str
-        "skip",  # type: bool
-        "when",  # type: str
+        "allow_failure",
+        "path",
+        "skip",
+        "when",
     )
 
+    step_num: StepVersion
+    task_name: str
+    task_config: dict
+    task_class: Optional[
+        Type["BaseTask"]
+    ]  # None means this step was skipped by setting task: None
+    project_config: BaseProjectConfig
+    allow_failure: bool
+    path: str
+    skip: bool
+    when: Optional[str]
+
     def __init__(
         self,
         step_num: StepVersion,
-        task_name,
-        task_config,
-        task_class,
-        project_config,
-        allow_failure=False,
-        from_flow=None,
-        skip=None,
-        when=None,
+        task_name: str,
+        task_config: dict,
+        task_class: Optional[Type["BaseTask"]],
+        project_config: BaseProjectConfig,
+        allow_failure: bool = False,
+        from_flow: Optional[str] = None,
+        skip: bool = False,
+        when: Optional[str] = None,
     ):
         self.step_num = step_num
         self.task_name = task_name
@@ -140,13 +161,16 @@ class StepSpec(object):
         )
 
 
-StepResult = namedtuple(
-    "StepResult",
-    ["step_num", "task_name", "path", "result", "return_values", "exception"],
-)
+class StepResult(NamedTuple):
+    step_num: StepVersion
+    task_name: str
+    path: str
+    result: Any
+    return_values: Any
+    exception: Optional[Exception]
 
 
-class FlowCallback(object):
+class FlowCallback:
     """A subclass of FlowCallback allows code running a flow
     to inject callback methods to run during the flow. Anything you
     would like the FlowCallback to have access to can be passed to the
@@ -181,24 +205,24 @@ class FlowCallback(object):
 
     """
 
-    def pre_flow(self, coordinator):
+    def pre_flow(self, coordinator: "FlowCoordinator"):
         """This is passed an instance of FlowCoordinator,
         that pertains to the flow which is about to run."""
         pass
 
-    def post_flow(self, coordinator):
+    def post_flow(self, coordinator: "FlowCoordinator"):
         """This is passed an instance of FlowCoordinator,
         that pertains to the flow just finished running.
         This step executes whether or not the flow completed
         successfully."""
         pass
 
-    def pre_task(self, step):
+    def pre_task(self, step: StepSpec):
         """This is passed an instance StepSpec, that
         pertains to the task which is about to run."""
         pass
 
-    def post_task(self, step, result):
+    def post_task(self, step: StepSpec, result: StepResult):
         """This method is called after a task has executed.
 
         :param step: Instance of StepSpec that relates to the task which executed
@@ -208,19 +232,28 @@ class FlowCallback(object):
         pass
 
 
-class TaskRunner(object):
+class TaskRunner:
     """TaskRunner encapsulates the job of instantiating and running a task."""
 
-    def __init__(self, step, org_config, flow=None):
+    step: StepSpec
+    org_config: Optional[OrgConfig]
+    flow: Optional["FlowCoordinator"]
+
+    def __init__(
+        self,
+        step: StepSpec,
+        org_config: Optional[OrgConfig],
+        flow: Optional["FlowCoordinator"] = None,
+    ):
         self.step = step
         self.org_config = org_config
         self.flow = flow
 
     @classmethod
-    def from_flow(cls, flow, step):
+    def from_flow(cls, flow: "FlowCoordinator", step: StepSpec) -> "TaskRunner":
         return cls(step, flow.org_config, flow=flow)
 
-    def run_step(self, **options):
+    def run_step(self, **options) -> StepResult:
         """
         Run a step.
 
@@ -258,7 +291,7 @@ class TaskRunner(object):
             exc,
         )
 
-    def _log_options(self, task):
+    def _log_options(self, task: "BaseTask"):
         if not task.task_options:
             task.logger.info("No task options present")
             return
@@ -275,21 +308,31 @@ class TaskRunner(object):
                         v = self._obfuscate_if_sensitive(v, info)
                         task.logger.info(f"    - {v}")
 
-    def _obfuscate_if_sensitive(self, value, info):
+    def _obfuscate_if_sensitive(self, value: str, info: dict) -> str:
         if info.get("sensitive"):
             value = 8 * "*"
         return value
 
 
-class FlowCoordinator(object):
+class FlowCoordinator:
+    org_config: Optional[OrgConfig]
+    steps: List[StepSpec]
+    callbacks: FlowCallback
+    logger: logging.Logger
+    skip: List[str]
+    flow_config: FlowConfig
+    runtime_options: dict
+    name: Optional[str]
+    results: List[StepResult]
+
     def __init__(
         self,
-        project_config,
-        flow_config,
-        name=None,
-        options=None,
-        skip=None,
-        callbacks=None,
+        project_config: BaseProjectConfig,
+        flow_config: FlowConfig,
+        name: Optional[str] = None,
+        options: Optional[dict] = None,
+        skip: Optional[List[str]] = None,
+        callbacks: Optional[FlowCallback] = None,
     ):
         self.project_config = project_config
         self.flow_config = flow_config
@@ -302,17 +345,20 @@ class FlowCoordinator(object):
 
         self.runtime_options = options or {}
 
-        if not skip:
-            skip = []
-        self.skip = skip
-
+        self.skip = skip or []
         self.results = []
 
         self.logger = self._init_logger()
-        self.steps = self._init_steps()  # type: List[StepSpec]
+        self.steps = self._init_steps()
 
     @classmethod
-    def from_steps(cls, project_config, steps, name=None, callbacks=None):
+    def from_steps(
+        cls,
+        project_config: BaseProjectConfig,
+        steps: List[StepSpec],
+        name: Optional[str] = None,
+        callbacks: Optional[FlowCallback] = None,
+    ):
         instance = cls(
             project_config,
             flow_config=FlowConfig({"steps": {}}),
@@ -341,7 +387,9 @@ class FlowCoordinator(object):
 
         return "\n".join(lines)
 
-    def get_flow_steps(self, for_docs=False, verbose=False):
+    def get_flow_steps(
+        self, for_docs: bool = False, verbose: bool = False
+    ) -> List[str]:
         """Returns a list of flow steps (tasks and sub-flows) for the given flow.
         For docs, indicates whether or not we want to use the string for use in a code-block
         of an rst file. If True, will omit output of source information."""
@@ -405,7 +453,7 @@ class FlowCoordinator(object):
 
         return lines
 
-    def run(self, org_config):
+    def run(self, org_config: OrgConfig):
         self.org_config = org_config
         line = f"Initializing flow: {self.__class__.__name__}"
         if self.name:
@@ -446,7 +494,7 @@ class FlowCoordinator(object):
         finally:
             self.callbacks.post_flow(self)
 
-    def _run_step(self, step):
+    def _run_step(self, step: StepSpec):
         if step.skip:
             self._rule(fill="*")
             self.logger.info(f"Skipping task: {step.task_name}")
@@ -481,7 +529,7 @@ class FlowCoordinator(object):
         if result.exception and not step.allow_failure:
             raise result.exception  # PY3: raise an exception type we control *from* this exception instead?
 
-    def _init_logger(self):
+    def _init_logger(self) -> logging.Logger:
         """
         Returns a logging.Logger-like object to use for the duration of the flow. Tasks will receive this logger
         and getChild(class_name) to get a child logger.
@@ -490,7 +538,7 @@ class FlowCoordinator(object):
         """
         return logging.getLogger("cumulusci.flows").getChild(self.__class__.__name__)
 
-    def _init_steps(self):
+    def _init_steps(self) -> List[StepSpec]:
         """
         Given the flow config and everything else, create a list of steps to run, sorted by step number.
 
@@ -509,14 +557,14 @@ class FlowCoordinator(object):
 
     def _visit_step(
         self,
-        number,
-        step_config,
-        project_config,
-        visited_steps=None,
-        parent_options=None,
-        parent_ui_options=None,
-        from_flow=None,
-    ):
+        number: Union[str, int],
+        step_config: dict,
+        project_config: BaseProjectConfig,
+        visited_steps: Optional[List[StepSpec]] = None,
+        parent_options: Optional[dict] = None,
+        parent_ui_options: Optional[dict] = None,
+        from_flow: Optional[str] = None,
+    ) -> List[StepSpec]:
         """
         for each step (as defined in the flow YAML), _visit_step is called with only
         the first two parameters. this takes care of validating the step, collating the
@@ -532,7 +580,7 @@ class FlowCoordinator(object):
         :param from_flow: used when called recursively for nested steps, name of parent flow
         :return: List[StepSpec] a list of all resolved steps including/under the one passed in
         """
-        number = StepVersion(str(number))
+        step_number = StepVersion(str(number))
 
         if visited_steps is None:
             visited_steps = []
@@ -555,7 +603,7 @@ class FlowCoordinator(object):
         ):
             visited_steps.append(
                 StepSpec(
-                    step_num=number,
+                    step_num=step_number,
                     task_name=step_config.get("task", step_config.get("flow")),
                     task_config=step_config.get("options", {}),
                     task_class=None,
@@ -572,7 +620,7 @@ class FlowCoordinator(object):
             # get the base task_config from the project config, as a dict for easier manipulation.
             # will raise if the task doesn't exist / is invalid
             task_config = project_config.get_task(name)
-            task_config_dict = copy.deepcopy(task_config.config)
+            task_config_dict: dict = copy.deepcopy(task_config.config)
             if "options" not in task_config_dict:
                 task_config_dict["options"] = {}
 
@@ -605,7 +653,7 @@ class FlowCoordinator(object):
 
             visited_steps.append(
                 StepSpec(
-                    step_num=number,
+                    step_num=step_number,
                     task_name=name,
                     task_config=task_config_dict,
                     task_class=task_class,
@@ -712,7 +760,10 @@ class FlowCoordinator(object):
 class PreflightFlowCoordinator(FlowCoordinator):
     """Coordinates running preflight checks instead of the actual flow steps."""
 
-    def run(self, org_config):
+    preflight_results: DefaultDict[Optional[str], List[dict]]
+    _task_caches: Dict[BaseProjectConfig, "TaskCache"]
+
+    def run(self, org_config: OrgConfig):
         self.org_config = org_config
         self.callbacks.pre_flow(self)
 
@@ -759,7 +810,9 @@ class PreflightFlowCoordinator(FlowCoordinator):
         finally:
             self.callbacks.post_flow(self)
 
-    def evaluate_check(self, check, jinja2_context):
+    def evaluate_check(
+        self, check: dict, jinja2_context: Dict[str, Any]
+    ) -> Optional[dict]:
         self.logger.info(f"Evaluating check: {check['when']}")
         expr = jinja2_env.compile_expression(check["when"])
         value = bool(expr(**jinja2_context))
@@ -768,7 +821,7 @@ class PreflightFlowCoordinator(FlowCoordinator):
             return {"status": check["action"], "message": check.get("message")}
 
 
-class TaskCache(object):
+class TaskCache:
     """Provides access to named tasks and caches their results.
 
     This is intended for use in a jinja2 expression context
@@ -776,25 +829,31 @@ class TaskCache(object):
     can avoid running a task more than once with the same options.
     """
 
-    def __init__(self, flow, project_config):
+    project_config: BaseProjectConfig
+    results: Dict[Tuple[str, Tuple[Any]], Any]
+
+    def __init__(self, flow: FlowCoordinator, project_config: BaseProjectConfig):
         self.flow = flow
         # Cross-project flows may include preflight checks
         # that depend on their local context.
         self.project_config = project_config
         self.results = {}
 
-    def __getattr__(self, task_name):
+    def __getattr__(self, task_name: str):
         return CachedTaskRunner(self, task_name)
 
 
-class CachedTaskRunner(object):
+class CachedTaskRunner:
     """Runs a task and caches the result in a TaskCache"""
 
-    def __init__(self, cache, task_name):
+    cache: TaskCache
+    task_name: str
+
+    def __init__(self, cache: TaskCache, task_name: str):
         self.cache = cache
         self.task_name = task_name
 
-    def __call__(self, **options):
+    def __call__(self, **options: dict) -> Any:
         cache_key = (self.task_name, tuple(sorted(options.items())))
         if cache_key in self.cache.results:
             return self.cache.results[cache_key].return_values

{cumulusci-3.68.0.dev1 → cumulusci-3.68.0.dev2}/cumulusci/core/runtime.py

@@ -1,5 +1,6 @@
 import sys
 from abc import abstractmethod
+from typing import Optional, Type
 
 from cumulusci.core.config import BaseProjectConfig, UniversalConfig
 from cumulusci.core.debug import DebugMode, get_debug_mode
@@ -9,15 +10,15 @@ from cumulusci.core.keychain import BaseProjectKeychain
 
 
 # pylint: disable=assignment-from-none
-class BaseCumulusCI(object):
+class BaseCumulusCI:
     universal_config_class = UniversalConfig
     project_config_class = BaseProjectConfig
     keychain_class = BaseProjectKeychain
     callback_class = FlowCallback
 
     universal_config: UniversalConfig
-    project_config: BaseProjectConfig
-    keychain: BaseProjectKeychain
+    project_config: Optional[BaseProjectConfig]
+    keychain: Optional[BaseProjectKeychain]
     debug_mode: DebugMode
     project_config_error: Exception
 
@@ -37,30 +38,30 @@ class BaseCumulusCI(object):
             self._load_keychain()
 
     @property
-    def universal_config_cls(self):
+    def universal_config_cls(self) -> Type:
         klass = self.get_universal_config_class()
         return klass or self.universal_config_class
 
     @abstractmethod
-    def get_universal_config_class(self):
+    def get_universal_config_class(self) -> Optional[Type]:
         return None
 
     @property
-    def project_config_cls(self):
+    def project_config_cls(self) -> Type:
         klass = self.get_project_config_class()
         return klass or self.project_config_class
 
     @abstractmethod
-    def get_project_config_class(self):
+    def get_project_config_class(self) -> Optional[Type]:
         return None
 
     @property
-    def keychain_cls(self):
+    def keychain_cls(self) -> Type:
         klass = self.get_keychain_class()
         return klass or self.keychain_class
 
     @abstractmethod
-    def get_keychain_class(self):
+    def get_keychain_class(self) -> Optional[Type]:
         return None
 
     @property
@@ -72,7 +73,7 @@ class BaseCumulusCI(object):
         return None
 
     def _add_repo_to_path(self):
-        if self.project_config:
+        if self.project_config and self.project_config.repo_root:
             sys.path.append(self.project_config.repo_root)
 
     def _load_universal_config(self):
@@ -95,8 +96,10 @@ class BaseCumulusCI(object):
             self.keychain = self.keychain_cls(self.project_config, keychain_key)
             self.project_config.keychain = self.keychain
 
-    def get_flow(self, name, options=None):
-        """Get a primed and readytogo flow coordinator."""
+    def get_flow(self, name: str, options: Optional[dict] = None) -> FlowCoordinator:
+        """Get a primed and ready-to-go flow coordinator."""
+        if not self.project_config:
+            raise ProjectConfigNotFound
         flow_config = self.project_config.get_flow(name)
         callbacks = self.callback_class()
         coordinator = FlowCoordinator(