diff --git a/docs/advanced.rst b/docs/advanced.rst index 1c6f6e0a9..b70c593f4 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -41,15 +41,18 @@ in C++. public: Vector2(float x, float y) : x(x), y(y) { } - std::string toString() const { return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; } - Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } Vector2 operator*(float value) const { return Vector2(x * value, y * value); } Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } Vector2& operator*=(float v) { x *= v; y *= v; return *this; } - friend Vector2 operator*(float f, const Vector2 &v) { return Vector2(f * v.x, f * v.y); } + friend Vector2 operator*(float f, const Vector2 &v) { + return Vector2(f * v.x, f * v.y); + } + std::string toString() const { + return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; + } private: float x, y; }; @@ -411,6 +414,8 @@ For this reason, pybind11 provides a several `return value policy` annotations that can be passed to the :func:`module::def` and :func:`class_::def` functions. The default policy is :enum:`return_value_policy::automatic`. +.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| + +--------------------------------------------------+----------------------------------------------------------------------------+ | Return value policy | Description | +==================================================+============================================================================+ @@ -746,6 +751,8 @@ automatically converted into a Python ``Exception``. pybind11 defines multiple special exception classes that will map to different types of Python exceptions: +.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| + +--------------------------------------+------------------------------+ | C++ exception type | Python exception type | +======================================+==============================+ @@ -1034,8 +1041,9 @@ For instance, the following statement iterates over a Python ``dict``: Available types include :class:`handle`, :class:`object`, :class:`bool_`, :class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, -:class:`list`, :class:`dict`, :class:`slice`, :class:`capsule`, -:class:`function`, :class:`buffer`, :class:`array`, and :class:`array_t`. +:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, +:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, +:class:`array`, and :class:`array_t`. In this kind of mixed code, it is often necessary to convert arbitrary C++ types to Python, which can be done using :func:`cast`: diff --git a/docs/basics.rst b/docs/basics.rst index a2a608488..f81c103b3 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -222,59 +222,59 @@ The following basic data types are supported out of the box (some may require an additional extension header to be included). To pass other data structures as arguments and return values, refer to the section on binding :ref:`classes`. -+----------------------------+--------------------------+-----------------------+ -| Data type | Description | Header file | -+============================+==========================+=======================+ -| int8_t, uint8_t | 8-bit integers | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| int16_t, uint16_t | 16-bit integers | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| int32_t, uint32_t | 32-bit integers | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| int64_t, uint64_t | 64-bit integers | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| ssize_t, size_t | Platform-dependent size | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| float, double | Floating point types | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| bool | Two-state Boolean type | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| char | Character literal | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| wchar_t | Wide character literal | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| const char * | UTF-8 string literal | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| const wchar_t * | Wide string literal | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| std::string | STL dynamic UTF-8 string | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| std::wstring | STL dynamic wide string | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| std::pair | Pair of two custom types | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| std::tuple<...> | Arbitrary tuple of types | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| std::reference_wrapper<...>| Reference type wrapper | pybind11/pybind11.h | -+----------------------------+--------------------------+-----------------------+ -| std::complex | Complex numbers | pybind11/complex.h | -+----------------------------+--------------------------+-----------------------+ -| std::array | STL static array | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::vector | STL dynamic array | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::list | STL linked list | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::map | STL ordered map | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::unordered_map | STL unordered map | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::set | STL ordered set | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::unordered_set | STL unordered set | pybind11/stl.h | -+----------------------------+--------------------------+-----------------------+ -| std::function<...> | STL polymorphic function | pybind11/functional.h | -+----------------------------+--------------------------+-----------------------+ ++---------------------------------+--------------------------+-------------------------------+ +| Data type | Description | Header file | ++=================================+==========================+===============================+ +| ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``char`` | Character literal | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::pair`` | Pair of two custom types | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::complex`` | Complex numbers | :file:`pybind11/complex.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::array`` | STL static array | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::vector`` | STL dynamic array | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::list`` | STL linked list | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::map`` | STL ordered map | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::unordered_map`` | STL unordered map | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::set`` | STL ordered set | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::unordered_set`` | STL unordered set | :file:`pybind11/stl.h` | ++---------------------------------+--------------------------+-------------------------------+ +| ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` | ++---------------------------------+--------------------------+-------------------------------+ .. [#f1] In practice, implementation and binding code will generally be located diff --git a/docs/benchmark.rst b/docs/benchmark.rst index c31e2902d..365919756 100644 --- a/docs/benchmark.rst +++ b/docs/benchmark.rst @@ -65,7 +65,13 @@ the largest largest file with 2048 classes and a total of 8192 methods -- a modest **1.2x** speedup relative to Boost.Python, which required 116.35 seconds). -.. image:: pybind11_vs_boost_python1.svg +.. only:: not latex + + .. image:: pybind11_vs_boost_python1.svg + +.. only:: latex + + .. image:: pybind11_vs_boost_python1.png Module size ----------- @@ -79,5 +85,12 @@ that it stores many definitions in an external library, whose size was not included here, hence the comparison is slightly shifted in Boost.Python's favor. -.. image:: pybind11_vs_boost_python2.svg +.. only:: not latex + + .. image:: pybind11_vs_boost_python2.svg + +.. only:: latex + + .. image:: pybind11_vs_boost_python2.png + diff --git a/docs/cmake.rst b/docs/cmake.rst index ace216758..7236ea8b8 100644 --- a/docs/cmake.rst +++ b/docs/cmake.rst @@ -29,11 +29,13 @@ subdirectory named :file:`pybind11`. project(example) # Add a CMake parameter for choosing a desired Python version - set(EXAMPLE_PYTHON_VERSION "" CACHE STRING "Python version to use for compiling the example library") - + set(EXAMPLE_PYTHON_VERSION "" CACHE STRING + "Python version to use for compiling the example library") + include(CheckCXXCompilerFlag) - # Set a default build configuration if none is specified. 'MinSizeRel' produces the smallest binaries + # Set a default build configuration if none is specified. + # 'MinSizeRel' produces the smallest binaries if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES) message(STATUS "Setting build type to 'MinSizeRel' as none was specified.") set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Choose the type of build." FORCE) @@ -53,7 +55,8 @@ subdirectory named :file:`pybind11`. find_package(PythonLibs REQUIRED) endif() - # The above sometimes returns version numbers like "3.4.3+"; the "+" must be removed for the next lines to work + # The above sometimes returns version numbers like "3.4.3+"; + # the "+" must be removed for the next lines to work string(REPLACE "+" "" PYTHONLIBS_VERSION_STRING "+${PYTHONLIBS_VERSION_STRING}") # Uncomment the following line if you will also require a matching Python interpreter @@ -88,7 +91,8 @@ subdirectory named :file:`pybind11`. # Include path for Python header files include_directories(${PYTHON_INCLUDE_DIR}) - # Include path for pybind11 header files -- this may need to be changed depending on your setup + # Include path for pybind11 header files -- this may need to be + # changed depending on your setup include_directories(${PROJECT_SOURCE_DIR}/pybind11/include) # Create the binding library @@ -143,11 +147,13 @@ subdirectory named :file:`pybind11`. set_target_properties(example PROPERTIES MACOSX_RPATH ".") set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup ") if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) - add_custom_command(TARGET example POST_BUILD COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so) + add_custom_command(TARGET example POST_BUILD + COMMAND strip -u -r ${PROJECT_BINARY_DIR}/example.so) endif() else() if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) - add_custom_command(TARGET example POST_BUILD COMMAND strip ${PROJECT_BINARY_DIR}/example.so) + add_custom_command(TARGET example POST_BUILD + COMMAND strip ${PROJECT_BINARY_DIR}/example.so) endif() endif() endif() diff --git a/docs/conf.py b/docs/conf.py index ca76e196e..9d25838d2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -233,7 +233,7 @@ latex_elements = { #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. -#'preamble': '', +'preamble': '\DeclareUnicodeCharacter{00A0}{}', # Latex figure (float) alignment #'figure_align': 'htbp', @@ -249,7 +249,7 @@ latex_documents = [ # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = 'pybind11-logo.png' # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. diff --git a/docs/faq.rst b/docs/faq.rst index 255610597..4badaf6c0 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -120,15 +120,16 @@ the included file :file:`example/example.cpp`. return m.ptr(); } -The various ``init_ex`` functions are contained in separate files that can be -compiled independently from another. Following this approach will +The various ``init_ex`` functions should be contained in separate files that +can be compiled independently from another. Following this approach will -1. enable parallel builds (if desired). +1. reduce memory requirements per compilation unit. -2. allow for faster incremental builds (e.g. if a single class definiton is - changed, only a subset of the binding code may need to be recompiled). +2. enable parallel builds (if desired). -3. reduce memory requirements. +3. allow for faster incremental builds. For instance, when a single class + definiton is changed, only a subset of the binding code will generally need + to be recompiled. How can I create smaller binaries? ================================== @@ -142,9 +143,17 @@ phase. However, due to the nested nature of these types, the resulting symbol names in the compiled extension library can be extremely long. For instance, the included test suite contains the following symbol: -.. code-block:: cpp +.. only:: html - __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS​3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_ + .. code-block:: none + + _​_​Z​N​8​p​y​b​i​n​d​1​1​1​2​c​p​p​_​f​u​n​c​t​i​o​n​C​1​I​v​8​E​x​a​m​p​l​e​2​J​R​N​S​t​3​_​_​1​6​v​e​c​t​o​r​I​N​S​3​_​1​2​b​a​s​i​c​_​s​t​r​i​n​g​I​w​N​S​3​_​1​1​c​h​a​r​_​t​r​a​i​t​s​I​w​E​E​N​S​3​_​9​a​l​l​o​c​a​t​o​r​I​w​E​E​E​E​N​S​8​_​I​S​A​_​E​E​E​E​E​J​N​S​_​4​n​a​m​e​E​N​S​_​7​s​i​b​l​i​n​g​E​N​S​_​9​i​s​_​m​e​t​h​o​d​E​A​2​8​_​c​E​E​E​M​T​0​_​F​T​_​D​p​T​1​_​E​D​p​R​K​T​2​_​ + +.. only:: not html + + .. code-block:: cpp + + __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_ which is the mangled form of the following function type: @@ -152,12 +161,12 @@ which is the mangled form of the following function type: pybind11::cpp_function::cpp_function, std::__1::allocator >, std::__1::allocator, std::__1::allocator > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector, std::__1::allocator >, std::__1::allocator, std::__1::allocator > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28]) -The memory needed to store just the name of this function (196 bytes) is larger -than the actual piece of code (111 bytes) it represents! On the other hand, -it's silly to even give this function a name -- after all, it's just a tiny -cog in a bigger piece of machinery that is not exposed to the outside world. -So we'll generally only want to export symbols for those functions which are -actually called from the outside. +The memory needed to store just the mangled name of this function (196 bytes) +is larger than the actual piece of code (111 bytes) it represents! On the other +hand, it's silly to even give this function a name -- after all, it's just a +tiny cog in a bigger piece of machinery that is not exposed to the outside +world. So we'll generally only want to export symbols for those functions which +are actually called from the outside. This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC and Clang, which sets the default symbol visibility to *hidden*. It's best to diff --git a/docs/index.rst b/docs/index.rst index 56a9c0cfa..511517102 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,13 @@ -.. image:: pybind11-logo.png +.. only: not latex + + .. image:: pybind11-logo.png pybind11 --- Seamless operability between C++11 and Python ========================================================== -Contents: +.. only: not latex + + Contents: .. toctree:: :maxdepth: 2 diff --git a/docs/pybind11_vs_boost_python1.png b/docs/pybind11_vs_boost_python1.png new file mode 100644 index 000000000..833231f24 Binary files /dev/null and b/docs/pybind11_vs_boost_python1.png differ diff --git a/docs/pybind11_vs_boost_python2.png b/docs/pybind11_vs_boost_python2.png new file mode 100644 index 000000000..9f17272c5 Binary files /dev/null and b/docs/pybind11_vs_boost_python2.png differ