chore: include more files in sdist (to make it self-sufficient) (#2139

)

* chore: include more files in `sdist` (to make it self-sufficient)

* chore: change the mintest workflow to use sdist instead

* docs: add a newsfragment

* chore: revert `mintest.yaml` to only run on `master` merges
(now that it has passed for demonstration purposes).

* chore: remove temp dir when done

.github/workflows/mintest.yaml

@@ -41,5 +41,6 @@ jobs:
         run: |
           tools/sed_coverage_rc.py
 
-      - name: Run tox
-        run: tox
+      - name: Run tox inside sdist
+        run: |
+          tools/tox_sdist.py

MANIFEST.in

@@ -1,11 +1,16 @@
+recursive-include docs *.rst *.html *.ico *.png *.py *.svg
+recursive-include examples *.py
 recursive-include falcon *.pyx
-recursive-include tests *.py
-recursive-include docs *.rst
+recursive-include tests *.py *.pyx
 include .coveragerc
 include tox.ini
+include CONTRIBUTING.md
 include README.rst
+include AUTHORS
 include LICENSE
 include docs/conf.py docs/Makefile
 graft docs/_static
 graft docs/_templates
+graft requirements
 graft tools
+prune docs/_build

README.rst

@@ -1027,7 +1027,7 @@ See also: `CONTRIBUTING.md <https://github.com/falconry/falcon/blob/master/CONTR
 Legal
 -----
 
-Copyright 2013-2022 by Individual and corporate contributors as
+Copyright 2013-2023 by Individual and corporate contributors as
 noted in the individual source files.
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may

docs/_newsfragments/2051.bugfix.rst

@@ -0,0 +1,4 @@
+Some essential files were unintentionally omitted from the source distribution
+archive, rendering it unsuitable to run the test suite off.
+This has been fixed, and the ``sdist`` tarball should now be usable as a base
+for packaging Falcon in OS distributions.

tools/tox_sdist.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+
+import argparse
+import atexit
+import logging
+import pathlib
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+
+logging.basicConfig(
+    format='[tox_sdist.py] %(asctime)s [%(levelname)s] %(message)s', level=logging.INFO
+)
+HERE = pathlib.Path(__file__).resolve().parent
+DIST = HERE.parent / 'dist'
+
+
+def build_sdist():
+    subprocess.check_call((sys.executable, 'setup.py', 'sdist'))
+    archives = sorted(DIST.glob('*.tar.gz'), key=lambda p: p.stat().st_mtime)
+    assert archives, 'no sdist archives found, something is wrong!'
+    archive = archives[-1]
+    logging.info(f'Built sdist: {archive}.')
+    return archive
+
+
+def extract_sdist(archive, target):
+    with tarfile.open(archive) as targz:
+        targz.extractall(target)
+
+    content = target / archive.with_suffix('').stem
+    assert content.is_dir, 'no extracted directory found, something is wrong!'
+    logging.info(f'Extracted {archive} to {content}.')
+    return content
+
+
+def exec_tox(tox_ini_dir):
+    logging.info(f'Running tox in {tox_ini_dir}...')
+    subprocess.check_call(('tox', '--version'))
+    subprocess.check_call(('tox',), cwd=tox_ini_dir)
+
+
+def _cleanup(target):
+    shutil.rmtree(target)
+    logging.info(f'Removed temporary directory {target}.')
+
+
+def main():
+    description = 'Build, extract sdist to a temp path, and run tox within.'
+
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument(
+        '-p', '--path', help='path to extract sdist to (default: create temp)'
+    )
+    args = parser.parse_args()
+
+    target = args.path
+    if not target:
+        target = tempfile.mkdtemp(prefix='falcon-')
+        atexit.register(_cleanup, target)
+    target = pathlib.Path(target)
+    logging.info(f'Using target path: {target}.')
+
+    archive = build_sdist()
+    extracted = extract_sdist(archive, target)
+    exec_tox(extracted)
+
+
+if __name__ == '__main__':
+    main()