Repository: SFDO-Tooling/CumulusCI
Pull request #3451 (2022-11-29 01:47:55)

Vendor LooseVersion
For a year or more, the Python interpreter has warned us that they intend to remove the module distutils.version. We use the class LooseVersion from that module. This has two consequences:

1. At some point CCI will break because it depends on a module that will disappear (probably Python 3.12).
2. In the meantime, our Python 3.10 and 3.11 test output is [dominated by warnings](https://github.com/SFDO-Tooling/CumulusCI/actions/runs/3536227946/jobs/5994878911#step:5:257). This hides other warnings which might be more urgent.

The class we need has no dependencies and is licensed with one of the most [liberal licences](https://en.wikipedia.org/wiki/Python_Software_Foundation_License) available. We already depend on this license to be able to deploy many PSF-licensed modules with CCI.

W-12132460


jstvz: I noticed we have an [approved 3PP request](https://gus.lightning.force.com/lightning/r/ADM_Third_Party_Software__c/a0qEE0000000p49YAA/view) from your installer work last year. By my reading of the Open Source Policy we're in compliance.

Patch:
diff --git a/cumulusci/core/config/org_config.py b/cumulusci/core/config/org_config.py
index e8072cc49..b3f191d17 100644
--- a/cumulusci/core/config/org_config.py
+++ b/cumulusci/core/config/org_config.py
@@ -3,7 +3,6 @@ import re
 from collections import defaultdict, namedtuple
 from contextlib import contextmanager
 from datetime import date, datetime
-from distutils.version import StrictVersion
 from urllib.parse import urlparse
 
 import requests
@@ -21,6 +20,7 @@ from cumulusci.oauth.salesforce import SANDBOX_LOGIN_URL, jwt_session
 from cumulusci.utils import parse_api_datetime
 from cumulusci.utils.fileutils import open_fs_resource
 from cumulusci.utils.http.requests_utils import safe_json_from_response
+from cumulusci.utils.version_strings import StrictVersion
 
 SKIP_REFRESH = os.environ.get("CUMULUSCI_DISABLE_REFRESH")
 SANDBOX_MYDOMAIN_RE = re.compile(r"\.cs\d+\.my\.(.*)salesforce\.com")
diff --git a/cumulusci/core/config/project_config.py b/cumulusci/core/config/project_config.py
index 2fc74f9b7..2b4cf2bc2 100644
--- a/cumulusci/core/config/project_config.py
+++ b/cumulusci/core/config/project_config.py
@@ -4,7 +4,6 @@ import pathlib
 import re
 from configparser import ConfigParser
 from contextlib import contextmanager
-from distutils.version import LooseVersion
 from io import StringIO
 from itertools import chain
 from pathlib import Path
@@ -15,6 +14,7 @@ from github3.repos.repo import Repository
 
 from cumulusci.core.config.base_config import BaseConfig
 from cumulusci.core.versions import PackageVersionNumber
+from cumulusci.utils.version_strings import LooseVersion
 
 API_VERSION_RE = re.compile(r"^\d\d+\.0$")
 
diff --git a/cumulusci/core/flowrunner.py b/cumulusci/core/flowrunner.py
index 760cd00cd..a8c5b9751 100644
--- a/cumulusci/core/flowrunner.py
+++ b/cumulusci/core/flowrunner.py
@@ -54,7 +54,6 @@ Option values/overrides can be passed in at a number of levels, in increasing or
 import copy
 import logging
 from collections import defaultdict
-from distutils.version import LooseVersion
 from operator import attrgetter
 from typing import (
     TYPE_CHECKING,
@@ -76,6 +75,7 @@ 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
+from cumulusci.utils.version_strings import LooseVersion
 
 if TYPE_CHECKING:
     from cumulusci.core.tasks import BaseTask
diff --git a/cumulusci/tasks/datadictionary.py b/cumulusci/tasks/datadictionary.py
index daa390eca..4a8773260 100644
--- a/cumulusci/tasks/datadictionary.py
+++ b/cumulusci/tasks/datadictionary.py
@@ -1,6 +1,5 @@
 import csv
 from collections import defaultdict
-from distutils.version import LooseVersion
 from pathlib import PurePosixPath
 from typing import List, Optional, Union
 from unittest.mock import Mock
@@ -24,6 +23,7 @@ from cumulusci.core.exceptions import TaskOptionsError
 from cumulusci.core.utils import process_bool_arg
 from cumulusci.tasks.github.base import BaseGithubTask
 from cumulusci.utils import download_extract_github_from_repo
+from cumulusci.utils.version_strings import LooseVersion
 from cumulusci.utils.xml import metadata_tree
 
 
diff --git a/cumulusci/tasks/metadata/ee_src.py b/cumulusci/tasks/metadata/ee_src.py
index 8d0f8c708..5d2bfc1a8 100644
--- a/cumulusci/tasks/metadata/ee_src.py
+++ b/cumulusci/tasks/metadata/ee_src.py
@@ -1,4 +1,6 @@
 import os
+
+# TODO: Replace this with shutils
 from distutils.dir_util import copy_tree, remove_tree
 
 from cumulusci.core.exceptions import TaskOptionsError
diff --git a/cumulusci/tasks/metadata/managed_src.py b/cumulusci/tasks/metadata/managed_src.py
index bccac64ef..d51a75ff0 100644
--- a/cumulusci/tasks/metadata/managed_src.py
+++ b/cumulusci/tasks/metadata/managed_src.py
@@ -1,3 +1,4 @@
+# TODO: Replace this with shutils
 from distutils.dir_util import copy_tree, remove_tree
 from pathlib import Path
 
diff --git a/cumulusci/tasks/release_notes/provider.py b/cumulusci/tasks/release_notes/provider.py
index e249c0958..da0bb182d 100644
--- a/cumulusci/tasks/release_notes/provider.py
+++ b/cumulusci/tasks/release_notes/provider.py
@@ -1,11 +1,11 @@
 import os
 import time
 from datetime import datetime
-from distutils.version import LooseVersion
 
 import pytz
 
 from cumulusci.core.github import get_tag_by_name
+from cumulusci.utils.version_strings import LooseVersion
 
 
 class BaseChangeNotesProvider(object):
diff --git a/cumulusci/utils/version_strings.py b/cumulusci/utils/version_strings.py
new file mode 100644
index 000000000..a216cd78e
--- /dev/null
+++ b/cumulusci/utils/version_strings.py
@@ -0,0 +1,391 @@
+#
+# From https://github.com/python/cpython/blob/b07f546ea3a574bc3016fb023c157c65a47f4849/Lib/distutils/version.py
+#
+# PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+# --------------------------------------------
+
+# 1. This LICENSE AGREEMENT is between the Python Software Foundation
+# ("PSF"), and the Individual or Organization ("Licensee") accessing and
+# otherwise using this software ("Python") in source or binary form and
+# its associated documentation.
+
+# 2. Subject to the terms and conditions of this License Agreement, PSF hereby
+# grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
+# analyze, test, perform and/or display publicly, prepare derivative works,
+# distribute, and otherwise use Python alone or in any derivative version,
+# provided, however, that PSF's License Agreement and PSF's notice of copyright,
+# i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+# 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Python Software Foundation;
+# All Rights Reserved" are retained in Python alone or in any derivative version
+# prepared by Licensee.
+
+# 3. In the event Licensee prepares a derivative work that is based on
+# or incorporates Python or any part thereof, and wants to make
+# the derivative work available to others as provided herein, then
+# Licensee hereby agrees to include in any such work a brief summary of
+# the changes made to Python.
+
+# 4. PSF is making Python available to Licensee on an "AS IS"
+# basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+# IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
+# DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+# FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
+# INFRINGE ANY THIRD PARTY RIGHTS.
+
+# 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
+# FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
+# A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
+# OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+
+# 6. This License Agreement will automatically terminate upon a material
+# breach of its terms and conditions.
+
+# 7. Nothing in this License Agreement shall be deemed to create any
+# relationship of agency, partnership, or joint venture between PSF and
+# Licensee.  This License Agreement does not grant permission to use PSF
+# trademarks or trade name in a trademark sense to endorse or promote
+# products or services of Licensee, or any third party.
+
+# 8. By copying, installing or otherwise using Python, Licensee
+# agrees to be bound by the terms and conditions of this License
+# Agreement.
+
+#
+# distutils/version.py
+#
+# Implements multiple version numbering conventions for the
+# Python Module Distribution Utilities.
+#
+# $Id$
+#
+
+"""Provides classes to represent module version numbers (one class for
+each style of version numbering).  There are currently two such classes
+implemented: StrictVersion and LooseVersion.
+
+Every version number class implements the following interface:
+  * the 'parse' method takes a string and parses it to some internal
+    representation; if the string is an invalid version number,
+    'parse' raises a ValueError exception
+  * the class constructor takes an optional string argument which,
+    if supplied, is passed to 'parse'
+  * __str__ reconstructs the string that was passed to 'parse' (or
+    an equivalent string -- ie. one that will generate an equivalent
+    version number instance)
+  * __repr__ generates Python code to recreate the version number instance
+  * _cmp compares the current instance with either another instance
+    of the same class or a string (which will be parsed to an instance
+    of the same class, thus must follow the same rules)
+"""
+
+import re
+
+
+class Version:
+    """Abstract base class for version numbering classes.  Just provides
+    constructor (__init__) and reproducer (__repr__), because those
+    seem to be the same for all version numbering classes; and route
+    rich comparisons to _cmp.
+    """
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def __repr__(self):
+        return "%s ('%s')" % (self.__class__.__name__, str(self))
+
+    def __eq__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c == 0
+
+    def __lt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c < 0
+
+    def __le__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c <= 0
+
+    def __gt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c > 0
+
+    def __ge__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c >= 0
+
+
+# Interface for version-number classes -- must be implemented
+# by the following classes (the concrete ones -- Version should
+# be treated as an abstract class).
+#    __init__ (string) - create and take same action as 'parse'
+#                        (string parameter is optional)
+#    parse (string)    - convert a string representation to whatever
+#                        internal representation is appropriate for
+#                        this style of version numbering
+#    __str__ (self)    - convert back to a string; should be very similar
+#                        (if not identical to) the string supplied to parse
+#    __repr__ (self)   - generate Python code to recreate
+#                        the instance
+#    _cmp (self, other) - compare two version numbers ('other' may
+#                        be an unparsed version string, or another
+#                        instance of your version class)
+
+
+class StrictVersion(Version):
+
+    """Version numbering for anal retentives and software idealists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of two or three
+    dot-separated numeric components, with an optional "pre-release" tag
+    on the end.  The pre-release tag consists of the letter 'a' or 'b'
+    followed by a number.  If the numeric components of two version
+    numbers are equal, then one with a pre-release tag will always
+    be deemed earlier (lesser) than one without.
+
+    The following are valid version numbers (shown in the order that
+    would be obtained by sorting according to the supplied cmp function):
+
+        0.4       0.4.0  (these two are equivalent)
+        0.4.1
+        0.5a1
+        0.5b3
+        0.5
+        0.9.6
+        1.0
+        1.0.4a3
+        1.0.4b1
+        1.0.4
+
+    The following are examples of invalid version numbers:
+
+        1
+        2.7.2.2
+        1.3.a4
+        1.3pl1
+        1.3c4
+
+    The rationale for this version numbering system will be explained
+    in the distutils documentation.
+    """
+
+    version_re = re.compile(
+        r"^(\d+) \. (\d+) (\. (\d+))? ([ab](\d+))?$", re.VERBOSE | re.ASCII
+    )
+
+    def parse(self, vstring):
+        match = self.version_re.match(vstring)
+        if not match:
+            raise ValueError("invalid version number '%s'" % vstring)
+
+        (major, minor, patch, prerelease, prerelease_num) = match.group(1, 2, 4, 5, 6)
+
+        if patch:
+            self.version = tuple(map(int, [major, minor, patch]))
+        else:
+            self.version = tuple(map(int, [major, minor])) + (0,)
+
+        if prerelease:
+            self.prerelease = (prerelease[0], int(prerelease_num))
+        else:
+            self.prerelease = None
+
+    def __str__(self):
+
+        if self.version[2] == 0:
+            vstring = ".".join(map(str, self.version[0:2]))
+        else:
+            vstring = ".".join(map(str, self.version))
+
+        if self.prerelease:
+            vstring = vstring + self.prerelease[0] + str(self.prerelease[1])
+
+        return vstring
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = StrictVersion(other)
+        elif not isinstance(other, StrictVersion):
+            return NotImplemented
+
+        if self.version != other.version:
+            # numeric versions don't match
+            # prerelease stuff doesn't matter
+            if self.version < other.version:
+                return -1
+            else:
+                return 1
+
+        # have to compare prerelease
+        # case 1: neither has prerelease; they're equal
+        # case 2: self has prerelease, other doesn't; other is greater
+        # case 3: self doesn't have prerelease, other does: self is greater
+        # case 4: both have prerelease: must compare them!
+
+        if not self.prerelease and not other.prerelease:
+            return 0
+        elif self.prerelease and not other.prerelease:
+            return -1
+        elif not self.prerelease and other.prerelease:
+            return 1
+        elif self.prerelease and other.prerelease:
+            if self.prerelease == other.prerelease:
+                return 0
+            elif self.prerelease < other.prerelease:
+                return -1
+            else:
+                return 1
+        else:
+            assert False, "never get here"
+
+
+# end class StrictVersion
+
+
+# The rules according to Greg Stein:
+# 1) a version number has 1 or more numbers separated by a period or by
+#    sequences of letters. If only periods, then these are compared
+#    left-to-right to determine an ordering.
+# 2) sequences of letters are part of the tuple for comparison and are
+#    compared lexicographically
+# 3) recognize the numeric components may have leading zeroes
+#
+# The LooseVersion class below implements these rules: a version number
+# string is split up into a tuple of integer and string components, and
+# comparison is a simple tuple comparison.  This means that version
+# numbers behave in a predictable and obvious way, but a way that might
+# not necessarily be how people *want* version numbers to behave.  There
+# wouldn't be a problem if people could stick to purely numeric version
+# numbers: just split on period and compare the numbers as tuples.
+# However, people insist on putting letters into their version numbers;
+# the most common purpose seems to be:
+#   - indicating a "pre-release" version
+#     ('alpha', 'beta', 'a', 'b', 'pre', 'p')
+#   - indicating a post-release patch ('p', 'pl', 'patch')
+# but of course this can't cover all version number schemes, and there's
+# no way to know what a programmer means without asking him.
+#
+# The problem is what to do with letters (and other non-numeric
+# characters) in a version number.  The current implementation does the
+# obvious and predictable thing: keep them as strings and compare
+# lexically within a tuple comparison.  This has the desired effect if
+# an appended letter sequence implies something "post-release":
+# eg. "0.99" < "0.99pl14" < "1.0", and "5.001" < "5.001m" < "5.002".
+#
+# However, if letters in a version number imply a pre-release version,
+# the "obvious" thing isn't correct.  Eg. you would expect that
+# "1.5.1" < "1.5.2a2" < "1.5.2", but under the tuple/lexical comparison
+# implemented here, this just isn't so.
+#
+# Two possible solutions come to mind.  The first is to tie the
+# comparison algorithm to a particular set of semantic rules, as has
+# been done in the StrictVersion class above.  This works great as long
+# as everyone can go along with bondage and discipline.  Hopefully a
+# (large) subset of Python module programmers will agree that the
+# particular flavour of bondage and discipline provided by StrictVersion
+# provides enough benefit to be worth using, and will submit their
+# version numbering scheme to its domination.  The free-thinking
+# anarchists in the lot will never give in, though, and something needs
+# to be done to accommodate them.
+#
+# Perhaps a "moderately strict" version class could be implemented that
+# lets almost anything slide (syntactically), and makes some heuristic
+# assumptions about non-digits in version number strings.  This could
+# sink into special-case-hell, though; if I was as talented and
+# idiosyncratic as Larry Wall, I'd go ahead and implement a class that
+# somehow knows that "1.2.1" < "1.2.2a2" < "1.2.2" < "1.2.2pl3", and is
+# just as happy dealing with things like "2g6" and "1.13++".  I don't
+# think I'm smart enough to do it right though.
+#
+# In any case, I've coded the test suite for this module (see
+# ../test/test_version.py) specifically to fail on things like comparing
+# "1.2a2" and "1.2".  That's not because the *code* is doing anything
+# wrong, it's because the simple, obvious design doesn't match my
+# complicated, hairy expectations for real-world version numbers.  It
+# would be a snap to fix the test suite to say, "Yep, LooseVersion does
+# the Right Thing" (ie. the code matches the conception).  But I'd rather
+# have a conception that matches common notions about version numbers.
+
+
+class LooseVersion(Version):
+
+    """Version numbering for anarchists and software realists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of a series of numbers,
+    separated by either periods or strings of letters.  When comparing
+    version numbers, the numeric components will be compared
+    numerically, and the alphabetic components lexically.  The following
+    are all valid version numbers, in no particular order:
+
+        1.5.1
+        1.5.2b2
+        161
+        3.10a
+        8.02
+        3.4j
+        1996.07.12
+        3.2.pl0
+        3.1.1.6
+        2g6
+        11g
+        0.960923
+        2.2beta29
+        1.13++
+        5.5.kw
+        2.0b1pl0
+
+    In fact, there is no such thing as an invalid version number under
+    this scheme; the rules for comparison are simple and predictable,
+    but may not always give the results you want (for some definition
+    of "want").
+    """
+
+    component_re = re.compile(r"(\d+ | [a-z]+ | \.)", re.VERBOSE)
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def parse(self, vstring):
+        # I've given up on thinking I can reconstruct the version string
+        # from the parsed tuple -- so I just store the string here for
+        # use by __str__
+        self.vstring = vstring
+        components = [x for x in self.component_re.split(vstring) if x and x != "."]
+        for i, obj in enumerate(components):
+            try:
+                components[i] = int(obj)
+            except ValueError:
+                pass
+
+        self.version = components
+
+    def __str__(self):
+        return self.vstring
+
+    def __repr__(self):
+        return "LooseVersion ('%s')" % str(self)
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = LooseVersion(other)
+        elif not isinstance(other, LooseVersion):
+            return NotImplemented
+
+        if self.version == other.version:
+            return 0
+        if self.version < other.version:
+            return -1
+        if self.version > other.version:
+            return 1


Test patch:
diff --git a/cumulusci/core/config/tests/test_config.py b/cumulusci/core/config/tests/test_config.py
index e833b962e..74b2104bb 100644
--- a/cumulusci/core/config/tests/test_config.py
+++ b/cumulusci/core/config/tests/test_config.py
@@ -2,7 +2,6 @@
 import json
 import os
 import pathlib
-from distutils.version import StrictVersion
 from pathlib import Path
 from tempfile import TemporaryDirectory
 from unittest import mock
@@ -44,6 +43,7 @@ from cumulusci.core.keychain.base_project_keychain import (
 from cumulusci.core.source import LocalFolderSource
 from cumulusci.tests.util import DummyKeychain
 from cumulusci.utils import temporary_dir, touch
+from cumulusci.utils.version_strings import StrictVersion
 from cumulusci.utils.yaml.cumulusci_yml import GitHubSourceModel, LocalFolderSourceModel
 
 
diff --git a/cumulusci/core/dependencies/tests/test_dependencies.py b/cumulusci/core/dependencies/tests/test_dependencies.py
index 862254583..c3eb329d8 100644
--- a/cumulusci/core/dependencies/tests/test_dependencies.py
+++ b/cumulusci/core/dependencies/tests/test_dependencies.py
@@ -1,6 +1,5 @@
 import io
 import os
-from distutils.version import StrictVersion
 from typing import List, Optional, Tuple
 from unittest import mock
 from zipfile import ZipFile
@@ -30,6 +29,7 @@ from cumulusci.salesforce_api.package_install import (
     DEFAULT_PACKAGE_RETRY_OPTIONS,
     PackageInstallOptions,
 )
+from cumulusci.utils.version_strings import StrictVersion
 from cumulusci.utils.ziputils import zip_subfolder
 
 
diff --git a/cumulusci/tasks/apex/tests/test_apex_tasks.py b/cumulusci/tasks/apex/tests/test_apex_tasks.py
index e06393f25..8f7f65484 100644
--- a/cumulusci/tasks/apex/tests/test_apex_tasks.py
+++ b/cumulusci/tasks/apex/tests/test_apex_tasks.py
@@ -4,7 +4,6 @@ import os
 import shutil
 import tempfile
 from copy import deepcopy
-from distutils.version import StrictVersion
 from unittest.mock import MagicMock, Mock, patch
 
 import pytest
@@ -31,6 +30,7 @@ from cumulusci.core.tests.utils import MockLoggerMixin
 from cumulusci.tasks.apex.anon import AnonymousApexTask
 from cumulusci.tasks.apex.batch import BatchApexWait
 from cumulusci.tasks.apex.testrunner import RunApexTests
+from cumulusci.utils.version_strings import StrictVersion
 
 
 @patch(
diff --git a/cumulusci/tasks/tests/test_datadictionary.py b/cumulusci/tasks/tests/test_datadictionary.py
index 3da39b251..6d9877062 100644
--- a/cumulusci/tasks/tests/test_datadictionary.py
+++ b/cumulusci/tasks/tests/test_datadictionary.py
@@ -1,6 +1,5 @@
 import io
 from collections import defaultdict
-from distutils.version import LooseVersion
 from unittest.mock import Mock, call, mock_open, patch
 
 import pytest
@@ -26,6 +25,7 @@ from cumulusci.tasks.datadictionary import (
 from cumulusci.tasks.salesforce.tests.util import create_task
 from cumulusci.tests.util import create_project_config
 from cumulusci.utils import temporary_dir
+from cumulusci.utils.version_strings import LooseVersion
 from cumulusci.utils.xml import metadata_tree
 from cumulusci.utils.yaml.cumulusci_yml import cci_safe_load