Zengtudor/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2024-11-21 20:55:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation improvements

Browse Source
This commit is contained in:
Wenzel Jakob 2016-04-28 14:33:45 +02:00
parent 6ca6e82f7c
commit f64feaf3e4
9 changed files with 125 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/advanced.rst
View File

@ -41,15 +41,18 @@ in C++.
public: public:
Vector2(float x, float y) : x(x), y(y) { } 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+(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*(float value) const { return Vector2(x * value, y * value); }
Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; }
Vector2& operator*=(float v) { x *= v; y *= v; 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: private:
float x, y; 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` that can be passed to the :func:`module::def` and :func:`class_::def`
functions. The default policy is :enum:`return_value_policy::automatic`. functions. The default policy is :enum:`return_value_policy::automatic`.
.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
+--------------------------------------------------+----------------------------------------------------------------------------+ +--------------------------------------------------+----------------------------------------------------------------------------+
| Return value policy | Description | | 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 special exception classes that will map to different types of Python
exceptions: exceptions:
.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
+--------------------------------------+------------------------------+ +--------------------------------------+------------------------------+
| C++ exception type | Python exception type | | 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_`, Available types include :class:`handle`, :class:`object`, :class:`bool_`,
:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, :class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`,
:class:`list`, :class:`dict`, :class:`slice`, :class:`capsule`, :class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`,
:class:`function`, :class:`buffer`, :class:`array`, and :class:`array_t`. :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++ In this kind of mixed code, it is often necessary to convert arbitrary C++
types to Python, which can be done using :func:`cast`: types to Python, which can be done using :func:`cast`:

106
docs/basics.rst
View File

@ -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 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`. as arguments and return values, refer to the section on binding :ref:`classes`.
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| Data type | Description | Header file | | Data type | Description | Header file |
+============================+==========================+=======================+ +=================================+==========================+===============================+
| int8_t, uint8_t | 8-bit integers | pybind11/pybind11.h | | ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| int16_t, uint16_t | 16-bit integers | pybind11/pybind11.h | | ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| int32_t, uint32_t | 32-bit integers | pybind11/pybind11.h | | ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| int64_t, uint64_t | 64-bit integers | pybind11/pybind11.h | | ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| ssize_t, size_t | Platform-dependent size | pybind11/pybind11.h | | ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| float, double | Floating point types | pybind11/pybind11.h | | ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| bool | Two-state Boolean type | pybind11/pybind11.h | | ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| char | Character literal | pybind11/pybind11.h | | ``char`` | Character literal | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| wchar_t | Wide character literal | pybind11/pybind11.h | | ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| const char * | UTF-8 string literal | pybind11/pybind11.h | | ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| const wchar_t * | Wide string literal | pybind11/pybind11.h | | ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::string | STL dynamic UTF-8 string | pybind11/pybind11.h | | ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::wstring | STL dynamic wide string | pybind11/pybind11.h | | ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::pair<T1, T2> | Pair of two custom types | pybind11/pybind11.h | | ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::tuple<...> | Arbitrary tuple of types | pybind11/pybind11.h | | ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::reference_wrapper<...>| Reference type wrapper | pybind11/pybind11.h | | ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::complex<T> | Complex numbers | pybind11/complex.h | | ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::array<T, Size> | STL static array | pybind11/stl.h | | ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::vector<T> | STL dynamic array | pybind11/stl.h | | ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::list<T> | STL linked list | pybind11/stl.h | | ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::map<T1, T2> | STL ordered map | pybind11/stl.h | | ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::unordered_map<T1, T2> | STL unordered map | pybind11/stl.h | | ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::set<T> | STL ordered set | pybind11/stl.h | | ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::unordered_set<T> | STL unordered set | pybind11/stl.h | | ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
| std::function<...> | STL polymorphic function | pybind11/functional.h | | ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` |
+----------------------------+--------------------------+-----------------------+ +---------------------------------+--------------------------+-------------------------------+
.. [#f1] In practice, implementation and binding code will generally be located .. [#f1] In practice, implementation and binding code will generally be located

17
docs/benchmark.rst
View File

@ -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 modest **1.2x** speedup relative to Boost.Python, which required 116.35
seconds). 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 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 included here, hence the comparison is slightly shifted in Boost.Python's
favor. favor.
.. image:: pybind11_vs_boost_python2.svg .. only:: not latex
.. image:: pybind11_vs_boost_python2.svg
.. only:: latex
.. image:: pybind11_vs_boost_python2.png

20
docs/cmake.rst
View File

@ -29,11 +29,13 @@ subdirectory named :file:`pybind11`.
project(example) project(example)
# Add a CMake parameter for choosing a desired Python version # 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) 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) if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
message(STATUS "Setting build type to 'MinSizeRel' as none was specified.") message(STATUS "Setting build type to 'MinSizeRel' as none was specified.")
set(CMAKE_BUILD_TYPE MinSizeRel CACHE STRING "Choose the type of build." FORCE) 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) find_package(PythonLibs REQUIRED)
endif() 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}") string(REPLACE "+" "" PYTHONLIBS_VERSION_STRING "+${PYTHONLIBS_VERSION_STRING}")
# Uncomment the following line if you will also require a matching Python interpreter # 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 path for Python header files
include_directories(${PYTHON_INCLUDE_DIR}) 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) include_directories(${PROJECT_SOURCE_DIR}/pybind11/include)
# Create the binding library # Create the binding library
@ -143,11 +147,13 @@ subdirectory named :file:`pybind11`.
set_target_properties(example PROPERTIES MACOSX_RPATH ".") set_target_properties(example PROPERTIES MACOSX_RPATH ".")
set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup ") set_target_properties(example PROPERTIES LINK_FLAGS "-undefined dynamic_lookup ")
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) 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() endif()
else() else()
if (NOT ${U_CMAKE_BUILD_TYPE} MATCHES DEBUG) 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() endif()
endif() endif()

4
docs/conf.py
View File

@ -233,7 +233,7 @@ latex_elements = {
#'pointsize': '10pt', #'pointsize': '10pt',
# Additional stuff for the LaTeX preamble. # Additional stuff for the LaTeX preamble.
#'preamble': '', 'preamble': '\DeclareUnicodeCharacter{00A0}{}',
# Latex figure (float) alignment # Latex figure (float) alignment
#'figure_align': 'htbp', #'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 name of an image file (relative to this directory) to place at the top of
# the title page. # the title page.
#latex_logo = None # latex_logo = 'pybind11-logo.png'
# For "manual" documents, if this is true, then toplevel headings are parts, # For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters. # not chapters.

37
docs/faq.rst
View File

@ -120,15 +120,16 @@ the included file :file:`example/example.cpp`.
return m.ptr(); return m.ptr();
} }
The various ``init_ex`` functions are contained in separate files that can be The various ``init_ex`` functions should be contained in separate files that
compiled independently from another. Following this approach will 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 2. enable parallel builds (if desired).
changed, only a subset of the binding code may need to be recompiled).
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? 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, names in the compiled extension library can be extremely long. For instance,
the included test suite contains the following symbol: 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: 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<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28]) pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), 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 The memory needed to store just the mangled name of this function (196 bytes)
than the actual piece of code (111 bytes) it represents! On the other hand, is larger than the actual piece of code (111 bytes) it represents! On the other
it's silly to even give this function a name -- after all, it's just a tiny hand, it's silly to even give this function a name -- after all, it's just a
cog in a bigger piece of machinery that is not exposed to the outside world. tiny cog in a bigger piece of machinery that is not exposed to the outside
So we'll generally only want to export symbols for those functions which are world. So we'll generally only want to export symbols for those functions which
actually called from the outside. are actually called from the outside.
This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC 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 and Clang, which sets the default symbol visibility to *hidden*. It's best to

8
docs/index.rst
View File

@ -1,9 +1,13 @@
.. image:: pybind11-logo.png .. only: not latex
.. image:: pybind11-logo.png
pybind11 --- Seamless operability between C++11 and Python pybind11 --- Seamless operability between C++11 and Python
========================================================== ==========================================================
Contents: .. only: not latex
Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

BIN
docs/pybind11_vs_boost_python1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
docs/pybind11_vs_boost_python2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB