feat: setup.py redesign and helpers

Author: henryiii

.github/workflows/ci.yml

@@ -332,28 +332,34 @@ jobs:
   doxygen:
     name: "Documentation build test"
     runs-on: ubuntu-latest
-    container: alpine:3.12
 
     steps:
     - uses: actions/checkout@v2
 
-    - name: Install system requirements
-      run: apk add doxygen python3-dev
+    - uses: actions/setup-python@v2
 
-    - name: Ensure pip
-      run: python3 -m ensurepip
+    - name: Install Doxygen
+      run: sudo apt install -y doxygen
 
     - name: Install docs & setup requirements
-      run: python3 -m pip install -r docs/requirements.txt pytest setuptools
+      run: python3 -m pip install -r docs/requirements.txt
 
     - name: Build docs
       run: python3 -m sphinx -W -b html docs docs/.build
 
     - name: Make SDist
       run: python3 setup.py sdist
 
+    - run: git status --ignored
+
+    - name: Check local include dir
+      run: >
+        ls pybind11;
+        python3 -c "import pybind11, pathlib; assert (a := pybind11.get_include()) == (b := str(pathlib.Path('include').resolve())), f'{a} != {b}'"
+
     - name: Compare Dists (headers only)
+      working-directory: include
       run: |
-        python3 -m pip install --user -U ./dist/*
-        installed=$(python3 -c "import pybind11; print(pybind11.get_include(True) + '/pybind11')")
-        diff -rq $installed ./include/pybind11
+        python3 -m pip install --user -U ../dist/*
+        installed=$(python3 -c "import pybind11; print(pybind11.get_include() + '/pybind11')")
+        diff -rq $installed ./pybind11

.github/workflows/format.yml

@@ -17,3 +17,5 @@ jobs:
     - uses: actions/checkout@v2
     - uses: actions/setup-python@v2
     - uses: pre-commit/action@v2.0.0
+      with:
+        extra_args: --hook-stage manual

.gitignore

@@ -39,3 +39,5 @@ pybind11Config*.cmake
 pybind11Targets.cmake
 /*env*
 /.vscode
+/pybind11/include/*
+/pybind11/share/*

.pre-commit-config.yaml

@@ -14,6 +14,12 @@ repos:
   - id: trailing-whitespace
   - id: fix-encoding-pragma
 
+- repo: https://github.com/psf/black
+  rev: 19.10b0
+  hooks:
+  - id: black
+    files: ^(setup.py|pybind11)
+
 - repo: https://github.com/Lucas-C/pre-commit-hooks
   rev: v1.1.9
   hooks:
@@ -34,6 +40,13 @@ repos:
     types: [file]
     files: (\.cmake|CMakeLists.txt)(.in)?$
 
+- repo: https://github.com/mgedmin/check-manifest
+  rev: "0.42"
+  hooks:
+  - id: check-manifest
+    stages: [manual]
+    additional_dependencies: [cmake, ninja]
+
 - repo: local
   hooks:
   - id: check-style

MANIFEST.in

@@ -1,2 +1,7 @@
 recursive-include include/pybind11 *.h
-include LICENSE README.md .github/CONTRIBUTING.md
+recursive-include pybind11 *.h
+recursive-include pybind11 *.cmake
+recursive-include pybind11 *.py
+recursive-include tools *.cmake
+recursive-include tools *.in
+include CMakeLists.txt LICENSE README.md .github/CONTRIBUTING.md

docs/compiling.rst

@@ -13,6 +13,51 @@ the [python_example]_ repository.
 
 .. [python_example] https://github.com/pybind/python_example
 
+A helper file is provided with pybind11 that can simplify usage with setuptools
+if you have pybind11 installed as a Python package; the file is also standalone,
+if you want to copy it to your package. If use use PEP518's ``pyproject.toml``
+file:
+
+.. code-block:: toml
+
+    [build-system]
+    requires = ["setuptools", "wheel", "pybind11==2.6.0"]
+    build-backend = "setuptools.build_meta"
+
+you can ensure that pybind11 is available during the building of your project
+(pip 10+ required).
+
+An example of a ``setup.py`` using pybind11's helpers:
+
+.. code-block:: python
+
+    from setuptools import setup, Extension
+    from pybind11.setup_helpers import BuildExt
+
+    ext_modules = [
+        Extension(
+            "python_example",
+            sorted(["src/main.cpp"]),
+            language="c++",
+        ),
+    ]
+
+    setup(
+        ...,
+        cmdclass={"build_ext": BuildExt},
+        ext_modules=ext_modules
+    )
+
+
+If you copy ``setup_helpers.py`` into your local project to try to support the
+classic build procedure, then you will need to use the deprecated
+``setup_requires=["pybind11>=2.6.0"]`` keyword argument to setup;
+``setup_helpers`` tries to support this as well.
+
+.. versionchanged:: 2.6
+
+    Added support file.
+
 Building with cppimport
 ========================
 

pybind11/__init__.py

@@ -1,13 +1,12 @@
 # -*- coding: utf-8 -*-
-from ._version import version_info, __version__  # noqa: F401 imported but unused
 
+from ._version import version_info, __version__
+from .commands import get_include, get_cmake_dir
 
-def get_include(user=False):
-    import os
-    d = os.path.dirname(__file__)
-    if os.path.exists(os.path.join(d, "include")):
-        # Package is installed
-        return os.path.join(d, "include")
-    else:
-        # Package is from a source directory
-        return os.path.join(os.path.dirname(d), "include")
+
+__all__ = (
+    "version_info",
+    "__version__",
+    "get_include",
+    "get_cmake_dir",
+)

pybind11/__main__.py

@@ -9,29 +9,34 @@
 
 
 def print_includes():
-    dirs = [sysconfig.get_path('include'),
-            sysconfig.get_path('platinclude'),
-            get_include()]
+    dirs = [
+        sysconfig.get_path("include"),
+        sysconfig.get_path("platinclude"),
+        get_include(),
+    ]
 
     # Make unique but preserve order
     unique_dirs = []
     for d in dirs:
         if d not in unique_dirs:
             unique_dirs.append(d)
 
-    print(' '.join('-I' + d for d in unique_dirs))
+    print(" ".join("-I" + d for d in unique_dirs))
 
 
 def main():
-    parser = argparse.ArgumentParser(prog='python -m pybind11')
-    parser.add_argument('--includes', action='store_true',
-                        help='Include flags for both pybind11 and Python headers.')
+    parser = argparse.ArgumentParser(prog="python -m pybind11")
+    parser.add_argument(
+        "--includes",
+        action="store_true",
+        help="Include flags for both pybind11 and Python headers.",
+    )
     args = parser.parse_args()
     if not sys.argv[1:]:
         parser.print_help()
     if args.includes:
         print_includes()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

pybind11/_version.py

@@ -1,3 +1,4 @@
 # -*- coding: utf-8 -*-
-version_info = (2, 5, 'dev1')
-__version__ = '.'.join(map(str, version_info))
+
+version_info = (2, 6, 0, "dev1")
+__version__ = ".".join(map(str, version_info))

pybind11/commands.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+import os
+
+
+DIR = os.path.abspath(os.path.dirname(__file__))
+
+
+def get_include(user=False):
+    installed_path = os.path.join(DIR, "include")
+    source_path = os.path.join(os.path.dirname(DIR), "include")
+    return installed_path if os.path.exists(installed_path) else source_path
+
+
+def get_cmake_dir():
+    cmake_installed_path = os.path.join(DIR, "share", "cmake", "pybind11")
+    if os.path.exists(cmake_installed_path):
+        return cmake_installed_path
+    else:
+        raise ImportError(
+            "pybind11 not installed, installation required to access the CMake files"
+        )