ci-helper 0.1.0__py3-none-any.whl

ci_helper/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from .__version__ import __version__
+except ImportError:
+    __version__ = None

ci_helper/__main__.py

@@ -0,0 +1,120 @@
+import sys
+from pathlib import Path
+import argparse
+import json
+import subprocess
+import requests
+
+from .__version__ import __version__
+
+
+# Command line args that can be used in place of "setup.py" for projects that lack a
+# setup.py, runs a minimal setup.py similar to what pip does for projects with no
+# setup.py.
+_SETUP_PY_STUB = [
+    "-c",
+    'import sys, setuptools; sys.argv[0] = __file__ = "setup.py"; setuptools.setup()',
+]
+
+
+def setup_py(project_dir):
+    """Returns a list of command line arguments to be used in place of ["setup.py"]. If
+    setup.py exists, then this is just ["setup.py"]. Otherwise, if setup.cfg or
+    pyproject.toml exists, returns args that pass a code snippet to Python with "-c" to
+    execute a minimal setup.py calling setuptools.setup(). If none of pyproject.toml,
+    setup.cfg, or setup.py exists, raises an exception."""
+    if Path(project_dir, 'setup.py').exists():
+        return ['setup.py']
+    elif any(Path(project_dir, s).exists() for s in ['setup.cfg', 'pyproject.toml']):
+        return _SETUP_PY_STUB
+    msg = f"""{project_dir} does not look like a python project directory: contains no
+        setup.py, setup.cfg, or pyproject.toml"""
+    raise RuntimeError(' '.join(msg.split()))
+
+
+def get_pythons():
+    """Return stable, non-end-of-life Python versions in X.Y format"""
+    URL = "https://raw.githubusercontent.com/python/devguide/refs/heads/main/include/release-cycle.json"
+    response = requests.get(URL, timeout=30)
+    if not response.ok:
+        raise ValueError(f"{response.status_code} {response.reason}")
+    pythons = response.json()
+    pythons = [p for p in pythons if pythons[p]['status'] in ('bugfix', 'security')]
+    pythons.sort(key=lambda ver: [int(part) for part in ver.split('.')])
+    return pythons
+
+
+def main():
+    # Since setuptools_conda is self-hosting, it needs toml and distlib to read its own
+    # requirements just to know that it needs to install toml and distlib! So bootstrap
+    # that up if necessary.
+
+    parser = argparse.ArgumentParser(prog='ci-helper')
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=__version__,
+    )
+    subparsers = parser.add_subparsers(
+        dest="command", required=True, help="Action to perform"
+    )
+    parser_pythons = subparsers.add_parser(
+        "pythons",
+        help="Output list of stable Python versions that have not yet reached end of "
+        + "life, see `ci-helper pythons -h`",
+    )
+    parser_pythons.add_argument(
+        "--cibw",
+        action="store_true",
+        help="Output as a space-separated list in the format "
+        + "`cpXY-* cpXY-*` as appropriate for the  CIBW_BUILD environment variable "
+        + "to build for all stable CPython versions, otherwise versions are output as "
+        "a comma-separated list in the format X.Y,X.Y",
+    )
+    _ = subparsers.add_parser(
+        "defaultpython",
+        help="Output the second-latest stable Python version in X.Y format, "
+        "useful as a good choice for a default python version",
+    )
+    parser_distinfo = subparsers.add_parser(
+        "distinfo",
+        help="Output info about the distribution, see `ci-helper distinfo -h`",
+    )
+    parser_distinfo.add_argument(
+        "field",
+        choices=['name', 'version', 'is_pure', 'has_env_markers'],
+        nargs="?",
+        help="Name of field to output as a single json value, "
+        + "if not given, all info is output as json",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == 'distinfo':
+        # distinfo_args = parser_distinfo.parse_args()
+        cmd = [sys.executable, *setup_py('.'), '-q', 'ci_distinfo']
+        result = subprocess.run(cmd, check=True, capture_output=True)
+        info = result.stdout.decode('utf8')
+        if args.field is not None:
+            info = json.loads(info)
+            value = info[args.field]
+            if isinstance(value, str):
+                print(value)
+            else:
+                print(json.dumps(value))
+        else:
+            print(info)
+    elif args.command == 'pythons':
+        pythons = get_pythons()
+        if args.cibw:
+            print(' '.join([f"cp{p.replace('.', '')}-*" for p in pythons]))
+        else:
+            print(','.join(pythons))
+    elif args.command == 'defaultpython':
+        pythons = get_pythons()
+        print(pythons[-2])
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

ci_helper/__version__.py

@@ -0,0 +1,21 @@
+import os
+from pathlib import Path
+try:
+    import importlib.metadata as importlib_metadata
+except ImportError:
+    import importlib_metadata
+
+VERSION_SCHEME = {
+    "version_scheme": os.getenv("SCM_VERSION_SCHEME", "guess-next-dev"),
+    "local_scheme": os.getenv("SCM_LOCAL_SCHEME", "node-and-date"),
+}
+
+root = Path(__file__).parent.parent
+if (root / '.git').is_dir():
+    from setuptools_scm import get_version
+    __version__ = get_version(root, **VERSION_SCHEME)
+else:
+    try:
+        __version__ = importlib_metadata.version(__package__)
+    except importlib_metadata.PackageNotFoundError:
+        __version__ = None

ci_helper/ci_distinfo.py

@@ -0,0 +1,66 @@
+from setuptools import Command
+import json
+from pathlib import Path
+
+
+def get_pyproject_toml_entry(proj, *keys):
+    """Return [build-system] requires as read from proj/pyproject.toml, if any"""
+    # this import is here to avoid bootstrapping issues when building wheels for this
+    # package itself
+    import toml
+    pyproject_toml = Path(proj, 'pyproject.toml')
+    if not pyproject_toml.exists():
+        return None
+    config = toml.load(pyproject_toml)
+    try:
+        for key in keys:
+            config = config[key]
+        return config
+    except KeyError:
+        return None
+
+
+def has_environment_markers(setup_requires, install_requires, extras_requires):
+    """Given a list of install_requires and a dict of extras_requires, return if there
+    are any environment markers"""
+    for item in install_requires:
+        if ';' in item:
+            return True
+    for key in extras_requires:
+        if key.startswith(':'):
+            # an extras_requires item being used as an environment marker, an old
+            # pattern allowed by setuptools
+            return True
+    return False
+
+
+class ci_distinfo(Command):
+    description = "Get package info useful for building on CI"
+    user_options = []
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+
+        setup_requires = get_pyproject_toml_entry('.', 'build-system', 'requires')
+        if setup_requires is None:
+            setup_requires = self.distribution.setup_requires
+
+        info = {
+            'name': self.distribution.get_name(),
+            'version': self.distribution.get_version(),
+            'is_pure': not (
+                self.distribution.has_ext_modules()
+                or self.distribution.has_c_libraries()
+            ),
+            'has_env_markers': has_environment_markers(
+                setup_requires,
+                self.distribution.install_requires,
+                self.distribution.extras_require,
+            ),
+        }
+        print(json.dumps(info, indent=4))

ci_helper-0.1.0.data/data/lib/python3.12/site-packages/setuptools/_distutils/command/ci_distinfo.py

@@ -0,0 +1 @@
+from ci_helper.ci_distinfo import ci_distinfo

ci_helper-0.1.0.dist-info/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Christopher Billington
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ci_helper-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.1
+Name: ci-helper
+Version: 0.1.0
+Summary: Get info on how a package should be built on CI
+Home-page: http://github.com/chrisjbillington/ci-helper
+Author: Christopher Billington
+Author-email: chrisjbillington@gmail.com
+License: MIT
+Project-URL: Source Code, https://github.com/chrisjbillington/ci-helper
+Project-URL: Download, https://github.com/chrisjbillington/ci-helper/releases
+Project-URL: Tracker, https://github.com/chrisjbillington/ci-helper/issues
+Keywords: build setuptools conda
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: setuptools_scm
+Requires-Dist: importlib_metadata
+Requires-Dist: toml
+Requires-Dist: requests
+
+# ci-helper
+
+Output information to help build a Python package in CI
+
+## Motivation
+
+This tool exists to address certain issues of bit-rot and deployment of GitHub Actions
+workflows (though the problem exists for CI generally) that build Python packages.
+
+It looks up what current Python versions are supported so you can target them in your
+builds without having to maintain a curated list. It determines whether building on
+multiple OSs or Python versions is needed for a Python package, allowing you to deploy a
+generic CI configuration for different types of packages without having to modify it for
+each one specifically when they only vary in this way.
+
+Specifically:
+
+* It lists all stable and supported Python versions so your CI can target all supported
+versions of Python without having to curate a manual list.
+
+* It tells you what the second-most-recent minor version of Python is, so you can use that
+as a sensible default for tools that require a recent-ish Python but are likely not to
+work immediately after a new Python is released.
+
+* It tells you whether a Python package is pure Python or not, so that your CI knows
+whether it needs to build on multiple OSs/Python versions.
+
+* It tells you whether a Python package's dependencies have environment markers or not, so
+that your CI knows whether it needs to build on multiple OSs/Python versions, for
+package formats that don't support environment markers in dependencies (e.g. conda
+packages).
+
+These functions are all serving the goals of:
+
+* Minimising how often you need to modify your CI configs just because a new version of
+  Python came our or an old version reached end-of-life
+* Minimising (ideally to zero) how much you need to customise an otherwise generic CI
+  config when you re-use it for different types of Python packages (e.g. pure vs impure)
+
+## Installation
+
+This package is available on PyPI, install it to your current Python environemnt with
+```bash 
+pip install ci-helper
+```
+
+## Usage:
+
+```bash
+# The second-most recent minor Python release, a good choice for the version to run
+# tools from:
+$ ci-helper defaultpython
+3.12
+
+# All stable, non-end-of-life Python versions:
+$ ci-helper pythons
+3.9,3.10,3.11,3.12,3.13
+
+# Same but in the format used by `cibuildwheel`'s `CIBW_BUILD` environment variable (cpython-only for now):
+$ ci-helper pythons --cibw
+cp39-* cp310-* cp311-* cp312-* cp313-*
+
+# Info about the source Python project in the current working directory - name, version,
+# whether it's a pure Python package, and whether its build or run requirements contain
+# any # environment markers (that is, whether its requirements vary by platform or
+# Python version):
+$ ci-helper distinfo
+{
+    "name": "ci-helper",
+    "version": "0.1.dev1+g5043fb5.d20241202",
+    "is_pure": true,
+    "has_env_markers": false
+}
+
+# Same but one field at a time, more convenient for assigning to environment variables:
+$ ci-helper distinfo name
+ci-helper
+$ ci-helper distinfo version
+0.1.0
+$ ci-helper distinfo is_pure
+true
+$ ci-helper distinfo has_env_markers
+false 
+```
+
+## Full help text
+
+```shell
+$ ci-helper -h
+usage: ci-helper [-h] [--version] {pythons,defaultpython,distinfo} ...
+
+positional arguments:
+  {pythons,defaultpython,distinfo}
+                        Action to perform
+    pythons             Output list of stable Python versions that have not yet reached end of life, see `ci-helper pythons -h`
+    defaultpython       Output the second-latest stable Python version in X.Y format, useful as a good choice for a default python version
+    distinfo            Output info about the distribution, see `ci-helper distinfo -h`
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+```
+
+```shell
+$ ci-helper pythons -h
+usage: ci-helper pythons [-h] [--cibw]
+
+options:
+  -h, --help  show this help message and exit
+  --cibw      Output as a space-separated list in the format `cpXY-* cpXY-*` as appropriate for the CIBW_BUILD environment variable to build for all
+              stable CPython versions, otherwise versions are output as a comma-separated list in the format X.Y,X.Y
+```
+
+```shell
+$ ci-helper defaultpython -h
+usage: ci-helper defaultpython [-h]
+
+options:
+  -h, --help  show this help message and exit
+```
+
+```shell
+$ ci-helper distinfo -h
+usage: ci-helper distinfo [-h] [{name,version,is_pure,has_env_markers}]
+
+positional arguments:
+  {name,version,is_pure,has_env_markers}
+                        Name of field to output as a single json value, if not given, all info is output as json
+
+options:
+  -h, --help            show this help message and exit
+```
+

ci_helper-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ci_helper/__init__.py,sha256=npB_KdSACjRyJBy26TlLH10bIQfUOiuSsY3qfbOPsrE,89
+ci_helper/__main__.py,sha256=fbOQhtWVfi4kBLd4d9YJT158NDZ_fgn_23uiA3RQ5gk,4421
+ci_helper/__version__.py,sha256=PKz6bKiuM7wAkBz7aPv3HGZ4P_H59_GqQ8O4b7vSYTg,624
+ci_helper/ci_distinfo.py,sha256=aTfWgQ1mq2dNBW7IYv0Tv0DBogMyb5zgV2nf7sayc8M,2052
+ci_helper-0.1.0.data/data/lib/python3.12/site-packages/setuptools/_distutils/command/ci_distinfo.py,sha256=wv41yjVJHfhgcplPzgA0SHRZjoGyiApDwJrI_9DK7tw,46
+ci_helper-0.1.0.dist-info/LICENSE.txt,sha256=3mgN7gts5RUJpaxp4BZ8quNCSpZGbtsFib10aRfwGHc,1079
+ci_helper-0.1.0.dist-info/METADATA,sha256=SDSACFVsEsgryXWDzg844UMN2v_rs60RTc1jZ87A1nY,5457
+ci_helper-0.1.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+ci_helper-0.1.0.dist-info/entry_points.txt,sha256=9elbjJQ006m9owk3zYufl-CMqaL9F5cgHVDeJcNFxwE,54
+ci_helper-0.1.0.dist-info/top_level.txt,sha256=hDnJJ-LWQDv6CsxZ0T4b69G4yfSND5EofhlgMu8QrfU,10
+ci_helper-0.1.0.dist-info/RECORD,,

ci_helper-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ci_helper-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ci-helper = ci_helper.__main__:main

ci_helper-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ci_helper