cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/vcs/utils/__init__.py

@@ -0,0 +1,31 @@
+from cumulusci.core.exceptions import CumulusCIException
+
+
+class AbstractCommitDir(object):
+    """
+    Abstract class for commit directories.
+    """
+
+    pass
+
+
+def get_ref_from_options(project_config, options: dict) -> str:
+    if "ref" in options:
+        return options["ref"]
+
+    elif "version" in options:
+        get_beta = options.get("version") == "latest_beta"
+        tag_name = project_config.get_latest_tag(beta=get_beta)
+        return f"tags/{tag_name}"
+
+    elif "tag_name" in options:
+        if options["tag_name"] in ("latest", "latest_beta"):
+            get_beta = options["tag_name"] == "latest_beta"
+            tag_name = project_config.get_latest_tag(beta=get_beta)
+        else:
+            tag_name = options["tag_name"]
+
+        return f"tags/{tag_name}"
+
+    else:
+        raise CumulusCIException("No ref, version, or tag_name present")

cumulusci/vcs/vcs_source.py

@@ -0,0 +1,287 @@
+import os
+import shutil
+from abc import ABC, abstractmethod
+from typing import Type
+
+import fs
+
+from cumulusci.core.exceptions import DependencyResolutionError, VcsNotFoundError
+from cumulusci.core.utils import import_global
+from cumulusci.utils import download_extract_vcs_from_repo
+from cumulusci.utils.yaml.cumulusci_yml import VCSSourceModel, VCSSourceRelease
+
+# To avoid circular dependency error
+# from cumulusci.core.config import BaseProjectConfig
+# from cumulusci.vcs.base import VCSService
+# from cumulusci.vcs.models import AbstractRepo
+
+
+class VCSSource(ABC):
+    """Abstract base class for VCS sources.
+    This class defines the interface for VCS sources and provides
+    common functionality for working with VCS sources.
+    Subclasses should implement the methods and properties defined here.
+    """
+
+    _registry = {}
+    # project_config : BaseProjectConfig
+    spec: VCSSourceModel
+    vcs: str
+    url: str
+    location: str
+    # repo: AbstractRepo
+    repo_owner: str
+    repo_name: str
+    # vcs_service: VCSService
+
+    def __init__(self, project_config, spec: VCSSourceModel):
+        self.project_config = project_config
+        self.spec = spec
+        self.vcs = spec.vcs
+        self.url = spec.url
+        self.location = self.url
+
+        if self.url.endswith(".git"):
+            self.url = self.url[:-4]
+
+        self._resolve_repo()
+
+    def _resolve_repo(self):
+        from cumulusci.vcs.base import VCSService
+
+        self.vcs_service: VCSService = self.get_vcs_service()
+
+        try:
+            from cumulusci.vcs.models import AbstractRepo
+
+            self.repo: AbstractRepo = self.vcs_service.get_repository(
+                options={"repository_url": self.url}
+            )
+        except VcsNotFoundError:
+            raise DependencyResolutionError(
+                f"We are unable to find the repository at {self.url}. Please make sure the URL is correct, that your GitHub user has read access to the repository, and that your GitHub personal access token includes the “repo” scope."
+            )
+
+        self._set_additional_repo_config()
+
+        self.resolve()
+
+    @classmethod
+    def register(cls, vcs_type: str, subclass: str):
+        """Register a subclass of VCSSource with a specific type name.
+        This allows the VCSSource class to create instances of the subclass
+        based on the type name specified in the VCSSourceModel.
+        Args:
+            vcs_type (str): The vcs type name to register the subclass with, ex: 'github'.
+            subclass (str): The subclass to register, ex: 'cumulusci.core.source.GitHubSource'.
+        """
+        cls._registry[vcs_type] = subclass
+
+    @classmethod
+    def registered_source_models(cls):
+        """Returns a list of registered classes.
+        return:
+            [GitHubSource, ...].
+        """
+        return_list = []
+        for source_klass_path in cls._registry.values():
+            if source_klass_path:
+                source_klass = import_global(source_klass_path)
+                if issubclass(source_klass, VCSSource):
+                    return_list.append(source_klass.source_model())
+        return return_list
+
+    @classmethod
+    def create(cls, project_config, spec: VCSSourceModel):
+        source_klass_path = cls._registry.get(spec.vcs, None)
+        if source_klass_path:
+            source_klass = import_global(source_klass_path)
+            if issubclass(source_klass, VCSSource):
+                return source_klass(project_config, spec)
+
+        raise ValueError(f"No child class found for type_name={spec.vcs}")
+
+    @classmethod
+    @abstractmethod
+    def source_model(self) -> Type[VCSSourceModel]:
+        raise NotImplementedError("Subclasses should implement source_model")
+
+    @abstractmethod
+    def get_vcs_service(self):
+        raise NotImplementedError("Subclasses should implement get_vcs_service")
+
+    @abstractmethod
+    def __repr__(self):
+        raise NotImplementedError(
+            "Subclasses should implement __repr__ to provide a string representation of the VCS source."
+        )
+
+    @abstractmethod
+    def __str__(self):
+        raise NotImplementedError(
+            "Subclasses should implement __str__ to provide a string representation of the VCS source."
+        )
+
+    @abstractmethod
+    def __hash__(self):
+        raise NotImplementedError(
+            "Subclasses should implement __hash__ to provide a hash value for the VCS source."
+        )
+
+    @abstractmethod
+    def get_ref(self):
+        raise NotImplementedError(
+            "Subclasses should implement get_ref to retrieve the reference information."
+        )
+
+    @abstractmethod
+    def get_tag(self):
+        raise NotImplementedError(
+            "Subclasses should implement get_tag to retrieve the tag information."
+        )
+
+    @abstractmethod
+    def get_branch(self):
+        raise NotImplementedError(
+            "Subclasses should implement get_branch to retrieve the branch information."
+        )
+
+    @abstractmethod
+    def get_release_tag(self):
+        raise NotImplementedError(
+            "Subclasses should implement get_release_tag to retrieve the release tag information."
+        )
+
+    def _set_additional_repo_config(self):
+        ### Subclasses can override this method to set additional configuration on the repo.
+        """Set additional configuration on the repo."""
+        pass
+
+    def resolve(self):
+        from cumulusci.vcs.bootstrap import find_latest_release, find_previous_release
+
+        """Resolve a VCS source into a specific commit.
+
+        The spec must include:
+        - vcs: the VCS repository type (e.g., GitHub, Bitbucket, ADO)
+        - url: the URL of the VCS repository
+
+        It's recommended that the source include:
+        - resolution_strategy: [production | preproduction | <strategy-name>]
+
+        The spec may instead be specific about the desired ref or release:
+        - commit: a commit hash
+        - ref: a Git ref
+        - branch: a Git branch
+        - tag: a Git tag
+        - release: "latest" | "previous" | "latest_beta"
+
+        If none of these are specified, CumulusCI will use the resolution strategy "production"
+        to locate the appropriate release or ref.
+        """
+        ref = None
+        self.branch = None
+        # These branches preserve some existing behavior: when a source is set to
+        # a specific tag or release, there's no fallback, as there would be
+        # if we were subsumed within the dependency resolution machinery.
+
+        # If the user was _not_ specific, we will use the full resolution stack,
+        # including fallback behaviors.
+        if self.spec.commit:
+            self.commit = self.description = self.spec.commit
+            return
+        elif self.spec.ref:
+            ref = self.get_ref()
+        elif self.spec.tag:
+            ref = self.get_tag()
+        elif self.spec.branch:
+            self.branch = self.spec.branch
+            ref = self.get_branch()
+        elif self.spec.release:
+            release = None
+            if self.spec.release is VCSSourceRelease.LATEST:
+                release = find_latest_release(self.repo, include_beta=False)
+            elif self.spec.release is VCSSourceRelease.LATEST_BETA:
+                release = find_latest_release(self.repo, include_beta=True)
+            elif self.spec.release is VCSSourceRelease.PREVIOUS:
+                release = find_previous_release(self.repo)
+            if release is None:
+                raise DependencyResolutionError(
+                    f"Could not find release {self.spec.release}."
+                )
+            ref = release.tag_ref_name
+        else:
+            # Avoid circular import issues
+            from cumulusci.core.dependencies.resolvers import (
+                get_resolver_stack,
+                resolve_dependency,
+            )
+
+            dynamic_dependency_cls = self.vcs_service.dynamic_dependency_class
+
+            # Use resolution strategies to find the right commit.
+            dep = dynamic_dependency_cls(url=self.spec.url)
+            dep.set_repo(self.repo)
+
+            resolve_dependency(
+                dep,
+                self.project_config,
+                get_resolver_stack(self.project_config, self.spec.resolution_strategy),
+            )
+
+            self.commit = self.description = dep.ref
+            return
+
+        self.description = ref[6:] if ref.startswith("heads/") else ref
+        self.commit = self.repo.get_ref(ref).sha
+
+    def fetch(self):
+        """Fetch the archive of the specified commit and construct its project config."""
+        with self.project_config.open_cache(
+            fs.path.join("projects", self.repo.repo_name, self.commit)
+        ) as path:
+            zf = download_extract_vcs_from_repo(self.repo, ref=self.commit)
+            try:
+                zf.extractall(path)
+            except Exception:
+                # make sure we don't leave an incomplete cache
+                shutil.rmtree(path)
+                raise
+
+        project_config = self.project_config.construct_subproject_config(
+            repo_info={
+                "root": os.path.realpath(path),
+                "owner": self.repo.repo_owner,
+                "name": self.repo.repo_name,
+                "url": self.url,
+                "commit": self.commit,
+                # Note: we currently only pass the branch if it was explicitly
+                # included in the source spec. If the commit was found another way,
+                # we aren't looking up what branches have that commit as their head.
+                "branch": self.branch,
+            }
+        )
+        return project_config
+
+    @property
+    def frozenspec(self):
+        """Return a spec to reconstruct this source at the current commit"""
+        # TODO: The branch name is lost when freezing the source for MetaDeploy.
+        # We could include it here, but it would fail validation when GitHubSourceModel
+        # parses it due to having both commit and branch.
+        return {
+            "vcs": self.vcs,
+            "url": self.url,
+            "commit": self.commit,
+            "description": self.description,
+        }
+
+    @property
+    def allow_remote_code(self) -> bool:
+        return self.spec.allow_remote_code
+
+
+VCSSource.register("github", "cumulusci.core.source.github.GitHubSource")
+VCSSource.register(
+    "github_enterprise", "cumulusci.core.source.github.GitHubEnterpriseSource"
+)

cumulusci_plus-5.0.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: cumulusci-plus
+Version: 5.0.0
+Summary: Build and release tools for Salesforce developers
+Project-URL: Homepage, https://github.com/SFDO-Tooling/CumulusCI
+Project-URL: Changelog, https://cumulusci.readthedocs.io/en/stable/history.html
+Project-URL: Bug Tracker, https://github.com/SFDO-Tooling/CumulusCI/issues
+Author-email: "Salesforce.org" <sfdo-mrbelvedere@salesforce.com>
+License: BSD 3-Clause License
+License-File: AUTHORS.rst
+License-File: LICENSE
+Keywords: cumulusci,salesforce
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography
+Requires-Dist: defusedxml
+Requires-Dist: docutils>=0.21.2
+Requires-Dist: faker
+Requires-Dist: fs
+Requires-Dist: github3-py
+Requires-Dist: jinja2
+Requires-Dist: keyring<=23.0.1
+Requires-Dist: lxml
+Requires-Dist: markupsafe
+Requires-Dist: packaging>=23.0
+Requires-Dist: psutil
+Requires-Dist: pydantic<2
+Requires-Dist: pyjwt
+Requires-Dist: python-dateutil
+Requires-Dist: pytz
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: requests-futures
+Requires-Dist: rich>=13.9.4
+Requires-Dist: robotframework
+Requires-Dist: robotframework-pabot
+Requires-Dist: robotframework-requests
+Requires-Dist: robotframework-seleniumlibrary<6
+Requires-Dist: rst2ansi>=0.1.5
+Requires-Dist: salesforce-bulk
+Requires-Dist: sarge
+Requires-Dist: selenium<4
+Requires-Dist: simple-salesforce==1.11.4
+Requires-Dist: snowfakery>=4.0.0
+Requires-Dist: sqlalchemy<2
+Requires-Dist: xmltodict
+Provides-Extra: select
+Requires-Dist: annoy; extra == 'select'
+Requires-Dist: numpy; extra == 'select'
+Requires-Dist: pandas; extra == 'select'
+Requires-Dist: scikit-learn; extra == 'select'
+Description-Content-Type: text/markdown
+
+# CumulusCI
+
+[![Code Coverage](https://coveralls.io/repos/github/SFDO-Tooling/CumulusCI/badge.svg?branch=main)](https://coveralls.io/github/SFDO-Tooling/CumulusCI?branch=main)
+[![PyPI](https://img.shields.io/pypi/v/cumulusci)](https://pypi.org/project/cumulusci/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cumulusci)
+![PyPI - License](https://img.shields.io/pypi/l/cumulusci)
+[![Documentation Status](https://readthedocs.org/projects/cumulusci/badge/?version=latest)](https://cumulusci.readthedocs.io/en/latest/?badge=latest)
+
+CumulusCI helps build great applications on the Salesforce platform by
+automating org setup, testing, and deployment for everyone --- from
+developers and admins to testers and product managers.
+
+**Best practices, proven at scale.** CumulusCI provides a complete
+development and release process created by Salesforce.org to build and
+release applications to thousands of users on the Salesforce platform.
+It\'s easy to start new projects with a standard set of tasks (single
+actions) and flows (sequences of tasks), or customize by adding your
+own.
+
+**Batteries included.** Out-of-the-box features help you quickly:
+
+-   Build sophisticated orgs with automatic installation of
+    dependencies.
+-   Load and capture sample datasets to make your orgs feel real.
+-   Apply transformations to existing metadata to tailor orgs to your
+    specific requirements.
+-   Run builds in continuous integration systems.
+-   Create end-to-end browser tests and setup automation using [Robot
+    Framework](https://cumulusci.readthedocs.io/en/latest/robotframework.html).
+-   Generate synthetic data on any scale, from a single record to a
+    million, using
+    [Snowfakery](https://cumulusci.readthedocs.io/en/latest/cookbook.html#large-volume-data-synthesis-with-snowfakery).
+
+**Build anywhere.** Automation defined using CumulusCI is portable. It
+is stored in a source repository and can be run from your local command
+line, from a continuous integration system, or from a customer-facing
+MetaDeploy installer. CumulusCI can run automation on scratch orgs
+created using the Salesforce CLI, or on persistent orgs like sandboxes,
+production orgs, and Developer Edition orgs.
+
+## Learn more
+
+For a tutorial introduction to CumulusCI, complete the [Build
+Applications with
+CumulusCI](https://trailhead.salesforce.com/en/content/learn/trails/build-applications-with-cumulusci)
+trail on Trailhead.
+
+To go in depth, read the [full
+documentation](https://cumulusci.readthedocs.io/en/latest/).
+
+If you just want a quick intro, watch [these screencast
+demos](https://cumulusci.readthedocs.io/en/latest/demos.html) of using
+CumulusCI to configure a Salesforce project from a GitHub repository.
+
+For a live demo with voiceover, please see Jason Lantz\'s [PyCon 2020
+presentation](https://www.youtube.com/watch?v=XL77lRTVF3g) from minute
+36 through minute 54.
+
+## Questions?
+
+Ask in the [CumulusCI (CCI) group in the Trailblazer
+Community](https://success.salesforce.com/_ui/core/chatter/groups/GroupProfilePage?g=0F9300000009M9ZCAU).
+
+_Please note:_ CumulusCI is distributed under an [open source
+license](https://github.com/SFDO-Tooling/CumulusCI/blob/main/LICENSE)
+and is not covered by the Salesforce Master Subscription Agreement.
+
+<!-- Changelog -->
+## v4.4.0 (2025-05-05)
+
+<!-- Release notes generated using configuration in .github/release.yml at main -->
+
+## What's Changed
+
+### Changes
+
+-   Add new tasks get_assignable_permission_sets and get_assignable_licenses by [@vsbharath](https://github.com/vsbharath) in [#3892](https://github.com/SFDO-Tooling/CumulusCI/pull/3892)
+
+### Issues Fixed
+
+-   fix: Make get permset licenses return active only by [@jstvz](https://github.com/jstvz) in [#3888](https://github.com/SFDO-Tooling/CumulusCI/pull/3888)
+-   fix: Read the docs configuration by LaTeX into PDF by [@dcinzona](https://github.com/dcinzona) in [#3891](https://github.com/SFDO-Tooling/CumulusCI/pull/3891)
+
+**Full Changelog**: https://github.com/SFDO-Tooling/CumulusCI/compare/v4.3.0.dev0...v4.4.0