| 1 |
Installation and use with setuptools |
| 2 |
==================================== |
| 3 |
|
| 4 |
Since Cppy is nothing else than a collection of header that are only compiled |
| 5 |
when used, installing it is extremely straightforward using pip:: |
| 6 |
|
| 7 |
$ pip install cppy |
| 8 |
|
| 9 |
If you want to run the development version, you can install directly from |
| 10 |
GitHub:: |
| 11 |
|
| 12 |
$ pip install git+https://github.com/nucleic/cppy |
| 13 |
|
| 14 |
|
| 15 |
Using Cppy in an extensions |
| 16 |
--------------------------- |
| 17 |
|
| 18 |
To use Cppy in your extension (written in C++), you simply need to include it. |
| 19 |
|
| 20 |
.. code:: c++ |
| 21 |
|
| 22 |
#include <cppy/cppy.h> |
| 23 |
|
| 24 |
Cppy includes Python.h so when including cppy.h you do not need to also include |
| 25 |
Python.h. |
| 26 |
|
| 27 |
Every functions, classes exposed by Cppy are stored in the `cppy` namespace. |
| 28 |
|
| 29 |
.. code:: c++ |
| 30 |
|
| 31 |
cppy::ptr obj_ptr( PyUnicode_FromString("test") ) |
| 32 |
|
| 33 |
|
| 34 |
Use with setuptools |
| 35 |
------------------- |
| 36 |
|
| 37 |
Cppy is only needed during the installation step of the projects using it. |
| 38 |
|
| 39 |
When using a PEP 517 compatible build system, one can simply specify cppy as a |
| 40 |
build requirement in ```pyproject.toml``:: |
| 41 |
|
| 42 |
[build-system] |
| 43 |
requires = ["setuptools>=42", "wheel", "cppy>=1.2"] |
| 44 |
|
| 45 |
Which will ensure that cppy is available in setup.py allowing to import it at the |
| 46 |
top level of the module. This allows in particular to import ``CppyBuildExt`` |
| 47 |
which enforces the use of C++11 and provide access to the cppy headers. On Windows, |
| 48 |
FH4 Exception Handling can be disabled by setting the CPPY_DISABLE_FH4 environment |
| 49 |
variable. This avoids requiring VCRUNTIME140_1.dll |
| 50 |
|
| 51 |
In one is not using a PEP 517 compatible install, the following example setup.py |
| 52 |
script illustrates how to use Cppy without requiring it to be installed before |
| 53 |
`setup.py` is run. |
| 54 |
|
| 55 |
.. code:: python |
| 56 |
|
| 57 |
from setuptools import setup, Extension |
| 58 |
from setuptools.command.build_ext import build_ext |
| 59 |
|
| 60 |
ext_modules = [ |
| 61 |
Extension( |
| 62 |
'project', |
| 63 |
['module.cpp'], |
| 64 |
include_dirs=['.'], |
| 65 |
language='c++', |
| 66 |
), |
| 67 |
] |
| 68 |
|
| 69 |
class BuildExt(build_ext): |
| 70 |
|
| 71 |
def build_extensions(self): |
| 72 |
|
| 73 |
# Delayed import of cppy to let setup_requires install it if |
| 74 |
# necessary |
| 75 |
import cppy |
| 76 |
|
| 77 |
ct = self.compiler.compiler_type |
| 78 |
for ext in self.extensions: |
| 79 |
# cppy.get_include() collect the path of the header files |
| 80 |
ext.include_dirs.insert(0, cppy.get_include()) |
| 81 |
build_ext.build_extensions(self) |
| 82 |
|
| 83 |
setup( |
| 84 |
name='project', |
| 85 |
python_requires='>=3.5', |
| 86 |
setup_requires=['cppy'], |
| 87 |
ext_modules=ext_modules, |
| 88 |
cmdclass={'build_ext': BuildExt}, |
| 89 |
) |