Merge pull request #42 from EricCousineau-TRI/feature-2020-06-21-upst…

…ream

Merge 'upstream/master' (8c0cd94) from previous merge-base (07e2259)

.gitignore

@@ -10,6 +10,7 @@ cmake_install.cmake
 *.sdf
 *.opensdf
 *.vcxproj
+*.vcxproj.user
 *.filters
 example.dir
 Win32

.travis.yml

@@ -17,7 +17,8 @@ matrix:
     - $PY_CMD -m pip install --user --upgrade pip wheel setuptools
     install:
     # breathe 4.14 doesn't work with bit fields. See https://github.com/michaeljones/breathe/issues/462
-    - $PY_CMD -m pip install --user --upgrade sphinx sphinx_rtd_theme breathe==4.13.1 flake8 pep8-naming pytest
+    # Latest breathe + Sphinx causes warnings and errors out
+    - $PY_CMD -m pip install --user --upgrade "sphinx<3" sphinx_rtd_theme breathe==4.13.1 flake8 pep8-naming pytest
     - curl -fsSL https://sourceforge.net/projects/doxygen/files/rel-1.8.15/doxygen-1.8.15.linux.bin.tar.gz/download | tar xz
     - export PATH="$PWD/doxygen-1.8.15/bin:$PATH"
     script:
@@ -112,7 +113,7 @@ matrix:
   - os: linux
     dist: xenial
     env: PYTHON=3.8 CPP=17 GCC=7
-    name: Python 3.8, c++17, gcc 7 (w/o numpy/scipy) # TODO: update build name when the numpy/scipy wheels become available
+    name: Python 3.8, c++17, gcc 7
     addons:
       apt:
         sources:
@@ -122,13 +123,21 @@ matrix:
           - g++-7
           - python3.8-dev
           - python3.8-venv
-    # Currently there is no numpy/scipy wheels available for python3.8
-    # TODO: remove next before_install, install and script clause when the wheels become available
-    before_install:
-      - pyenv global $(pyenv whence 2to3)  # activate all python versions
-      - PY_CMD=python3.8
-      - $PY_CMD -m ensurepip --user
-      - $PY_CMD -m pip install --user --upgrade pip wheel setuptools
+  - os: linux
+    dist: xenial
+    env: PYTHON=3.9 CPP=17 GCC=7
+    name: Python 3.9 beta, c++17, gcc 7 (w/o numpy/scipy) # TODO: update build name when the numpy/scipy wheels become available
+    addons:
+      apt:
+        sources:
+          - deadsnakes
+          - ubuntu-toolchain-r-test
+        packages:
+          - g++-7
+          - python3.9-dev
+          - python3.9-venv
+    # Currently there are no numpy/scipy wheels available for python3.9
+    # TODO: remove next install and script clause when the wheels become available
     install:
       - $PY_CMD -m pip install --user --upgrade pytest
     script:
@@ -145,18 +154,28 @@ matrix:
     name: Python 3.7, c++14, AppleClang 9, Debug build
     osx_image: xcode9.4
     env: PYTHON=3.7 CPP=14 CLANG DEBUG=1
-  # WARNING: This current fails on download. Should try to upgrade OS + Python version?
-  # # Test a PyPy 2.7 build
-  # - os: linux
-  #   dist: trusty
-  #   env: PYPY=5.8 PYTHON=2.7 CPP=11 GCC=4.8
-  #   name: PyPy 5.8, Python 2.7, c++11, gcc 4.8
-  #   addons:
-  #     apt:
-  #       packages:
-  #         - libblas-dev
-  #         - liblapack-dev
-  #         - gfortran
+  # Test a PyPy 2.7 build
+  - os: linux
+    dist: trusty
+    env: PYPY=7.3.1 PYTHON=2.7 CPP=11 GCC=4.8
+    name: PyPy 7.3, Python 2.7, c++11, gcc 4.8
+    addons:
+      apt:
+        packages:
+          - libblas-dev
+          - liblapack-dev
+          - gfortran
+  - os: linux
+    dist: xenial
+    env: PYPY=7.3.1 PYTHON=3.6 CPP=11 GCC=5
+    name: PyPy 7.3, Python 3.6, c++11, gcc 5
+    addons:
+      apt:
+        packages:
+          - libblas-dev
+          - liblapack-dev
+          - gfortran
+          - g++-5
   # Build in 32-bit mode and tests against the CMake-installed version
   - os: linux
     dist: trusty
@@ -176,6 +195,10 @@ matrix:
           cmake ../pybind11-tests ${CMAKE_EXTRA_ARGS} -DPYBIND11_WERROR=ON
           make pytest -j 2"
         set +ex
+  allow_failures:
+    - name: PyPy 7.3, Python 2.7, c++11, gcc 4.8
+    - name: PyPy 7.3, Python 3.6, c++11, gcc 5
+    - name: Python 3.9 beta, c++17, gcc 7 (w/o numpy/scipy)
 cache:
   directories:
   - $HOME/.local/bin
@@ -217,9 +240,9 @@ before_install:
     SCRIPT_RUN_PREFIX="docker exec --tty $containerid"
     $SCRIPT_RUN_PREFIX sh -c 'for s in 0 15; do sleep $s; apt-get update && apt-get -qy dist-upgrade && break; done'
   else
-    if [ "$PYPY" = "5.8" ]; then
-      curl -fSL https://bitbucket.org/pypy/pypy/downloads/pypy2-v5.8.0-linux64.tar.bz2 | tar xj
-      PY_CMD=$(echo `pwd`/pypy2-v5.8.0-linux64/bin/pypy)
+    if [ -n "$PYPY" ]; then
+      curl -fSL https://bitbucket.org/pypy/pypy/downloads/pypy$PYTHON-v$PYPY-linux64.tar.bz2 | tar xj
+      PY_CMD=$(echo `pwd`/pypy$PYTHON-v$PYPY-linux64/bin/pypy$PY)
       CMAKE_EXTRA_ARGS+=" -DPYTHON_EXECUTABLE:FILEPATH=$PY_CMD"
     else
       PY_CMD=python$PYTHON
@@ -261,11 +284,12 @@ install:
     export NPY_NUM_BUILD_JOBS=2
     echo "Installing pytest, numpy, scipy..."
     local PIP_CMD=""
-    if [ -n $PYPY ]; then
+    if [ -n "$PYPY" ]; then
       # For expediency, install only versions that are available on the extra index.
       travis_wait 30 \
-        $PY_CMD -m pip install --user --upgrade --extra-index-url https://imaginary.ca/trusty-pypi \
-          pytest numpy==1.15.4 scipy==1.2.0
+        $PY_CMD -m pip install --user --upgrade --extra-index-url https://antocuni.github.io/pypy-wheels/manylinux2010 \
+          numpy scipy
+        $PY_CMD -m pip install --user --upgrade pytest
     else
       $PY_CMD -m pip install --user --upgrade pytest numpy scipy
     fi

docs/advanced/classes.rst

@@ -784,13 +784,17 @@ An instance can now be pickled as follows:
     p.setExtra(15)
     data = pickle.dumps(p, 2)
 
-Note that only the cPickle module is supported on Python 2.7. The second
-argument to ``dumps`` is also crucial: it selects the pickle protocol version
-2, since the older version 1 is not supported. Newer versions are also fine—for
-instance, specify ``-1`` to always use the latest available version. Beware:
-failure to follow these instructions will cause important pybind11 memory
-allocation routines to be skipped during unpickling, which will likely lead to
-memory corruption and/or segmentation faults.
+
+.. note::
+    Note that only the cPickle module is supported on Python 2.7.
+
+    The second argument to ``dumps`` is also crucial: it selects the pickle
+    protocol version 2, since the older version 1 is not supported. Newer
+    versions are also fine—for instance, specify ``-1`` to always use the
+    latest available version. Beware: failure to follow these instructions
+    will cause important pybind11 memory allocation routines to be skipped
+    during unpickling, which will likely lead to memory corruption and/or
+    segmentation faults.
 
 .. seealso::
 
@@ -800,6 +804,38 @@ memory corruption and/or segmentation faults.
 
 .. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances
 
+Deepcopy support
+================
+
+Python normally uses references in assignments. Sometimes a real copy is needed
+to prevent changing all copies. The ``copy`` module [#f5]_ provides these
+capabilities.
+
+On Python 3, a class with pickle support is automatically also (deep)copy
+compatible. However, performance can be improved by adding custom
+``__copy__`` and ``__deepcopy__`` methods. With Python 2.7, these custom methods
+are mandatory for (deep)copy compatibility, because pybind11 only supports
+cPickle.
+
+For simple classes (deep)copy can be enabled by using the copy constructor,
+which should look as follows:
+
+.. code-block:: cpp
+
+    py::class_<Copyable>(m, "Copyable")
+        .def("__copy__",  [](const Copyable &self) {
+            return Copyable(self);
+        })
+        .def("__deepcopy__", [](const Copyable &self, py::dict) {
+            return Copyable(self);
+        }, "memo"_a);
+
+.. note::
+
+    Dynamic attributes will not be copied in this example.
+
+.. [#f5] https://docs.python.org/3/library/copy.html
+
 Multiple Inheritance
 ====================
 
@@ -1058,6 +1094,32 @@ described trampoline:
     ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));``
     where ``int (A::*)() const`` is the type of ``A::foo``.
 
+Binding final classes
+=====================
+
+Some classes may not be appropriate to inherit from. In C++11, classes can
+use the ``final`` specifier to ensure that a class cannot be inherited from.
+The ``py::is_final`` attribute can be used to ensure that Python classes 
+cannot inherit from a specified type. The underlying C++ type does not need
+to be declared final.
+
+.. code-block:: cpp
+
+    class IsFinal final {};
+
+    py::class_<IsFinal>(m, "IsFinal", py::is_final());
+
+When you try to inherit from such a class in Python, you will now get this
+error:
+
+.. code-block:: pycon
+
+    >>> class PyFinalChild(IsFinal):
+    ...     pass
+    TypeError: type 'IsFinal' is not an acceptable base type
+
+.. note:: This attribute is currently ignored on PyPy
+
 Custom automatic downcasters
 ============================
 

docs/advanced/functions.rst

@@ -362,6 +362,34 @@ like so:
     py::class_<MyClass>("MyClass")
         .def("myFunction", py::arg("arg") = (SomeType *) nullptr);
 
+Keyword-only arguments
+======================
+
+Python 3 introduced keyword-only arguments by specifying an unnamed ``*``
+argument in a function definition:
+
+.. code-block:: python
+
+    def f(a, *, b):  # a can be positional or via keyword; b must be via keyword
+        pass
+
+    f(a=1, b=2)  # good
+    f(b=2, a=1)  # good
+    f(1, b=2)    # good
+    f(1, 2)      # TypeError: f() takes 1 positional argument but 2 were given
+
+Pybind11 provides a ``py::kwonly`` object that allows you to implement
+the same behaviour by specifying the object between positional and keyword-only
+argument annotations when registering the function:
+
+.. code-block:: cpp
+
+    m.def("f", [](int a, int b) { /* ... */ },
+          py::arg("a"), py::kwonly(), py::arg("b"));
+
+Note that, as in Python, you cannot combine this with a ``py::args`` argument.
+This feature does *not* require Python 3 to work.
+
 .. _nonconverting_arguments:
 
 Non-converting arguments

docs/changelog.rst

@@ -6,6 +6,51 @@ Changelog
 Starting with version 1.8.0, pybind11 releases use a `semantic versioning
 <http://semver.org>`_ policy.
 
+v2.5.0 (Mar 31, 2020)
+-----------------------------------------------------
+
+* Use C++17 fold expressions in type casters, if available. This can
+  improve performance during overload resolution when functions have
+  multiple arguments.
+  `#2043 <https://github.com/pybind/pybind11/pull/2043>`_.
+
+* Changed include directory resolution in ``pybind11/__init__.py``
+  and installation in ``setup.py``. This fixes a number of open issues
+  where pybind11 headers could not be found in certain environments.
+  `#1995 <https://github.com/pybind/pybind11/pull/1995>`_.
+
+* C++20 ``char8_t`` and ``u8string`` support. `#2026
+  <https://github.com/pybind/pybind11/pull/2026>`_.
+
+* CMake: search for Python 3.9. `bb9c91
+  <https://github.com/pybind/pybind11/commit/bb9c91>`_.
+
+* Fixes for MSYS-based build environments.
+  `#2087 <https://github.com/pybind/pybind11/pull/2087>`_,
+  `#2053 <https://github.com/pybind/pybind11/pull/2053>`_.
+
+* STL bindings for ``std::vector<...>::clear``. `#2074
+  <https://github.com/pybind/pybind11/pull/2074>`_.
+
+* Read-only flag for ``py::buffer``. `#1466
+  <https://github.com/pybind/pybind11/pull/1466>`_.
+
+* Exception handling during module initialization.
+  `bf2b031 <https://github.com/pybind/pybind11/commit/bf2b031>`_.
+
+* Support linking against a CPython debug build.
+  `#2025 <https://github.com/pybind/pybind11/pull/2025>`_.
+
+* Fixed issues involving the availability and use of aligned ``new`` and
+  ``delete``. `#1988 <https://github.com/pybind/pybind11/pull/1988>`_,
+  `759221 <https://github.com/pybind/pybind11/commit/759221>`_.
+
+* Fixed a resource leak upon interpreter shutdown.
+  `#2020 <https://github.com/pybind/pybind11/pull/2020>`_.
+
+* Fixed error handling in the boolean caster.
+  `#1976 <https://github.com/pybind/pybind11/pull/1976>`_.
+
 v2.4.3 (Oct 15, 2019)
 -----------------------------------------------------
 

docs/compiling.rst

@@ -105,18 +105,14 @@ on the target compiler, falling back to C++11 if C++14 support is not
 available.  Note, however, that this default is subject to change: future
 pybind11 releases are expected to migrate to newer C++ standards as they become
 available.  To override this, the standard flag can be given explicitly in
-``PYBIND11_CPP_STANDARD``:
+`CMAKE_CXX_STANDARD <https://cmake.org/cmake/help/v3.17/variable/CMAKE_CXX_STANDARD.html>`_:
 
 .. code-block:: cmake
 
     # Use just one of these:
-    # GCC/clang:
-    set(PYBIND11_CPP_STANDARD -std=c++11)
-    set(PYBIND11_CPP_STANDARD -std=c++14)
-    set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support
-    # MSVC:
-    set(PYBIND11_CPP_STANDARD /std:c++14)
-    set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features
+    set(CMAKE_CXX_STANDARD 11)
+    set(CMAKE_CXX_STANDARD 14)
+    set(CMAKE_CXX_STANDARD 17) # Experimental C++17 support
 
     add_subdirectory(pybind11)  # or find_package(pybind11)
 
@@ -292,3 +288,11 @@ code by introspecting existing C++ codebases using LLVM/Clang. See the
 [binder]_ documentation for details.
 
 .. [binder] http://cppbinder.readthedocs.io/en/latest/about.html
+
+[AutoWIG]_ is a Python library that wraps automatically compiled libraries into
+high-level languages. It parses C++ code using LLVM/Clang technologies and
+generates the wrappers using the Mako templating engine. The approach is automatic,
+extensible, and applies to very complex C++ libraries, composed of thousands of
+classes or incorporating modern meta-programming constructs.
+
+.. [AutoWIG] https://github.com/StatisKit/AutoWIG

docs/conf.py

@@ -61,9 +61,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.4'
+version = '2.5'
 # The full version, including alpha/beta/rc tags.
-release = '2.4.dev4'
+release = '2.5.dev1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.