0
# pybind11
1

2
A lightweight header-only library that exposes C++ types in Python and vice versa, primarily designed for creating Python bindings of existing C++ code. It provides seamless interoperability between C++11 and Python by enabling developers to map C++ features to Python including functions, classes, instance and static methods, overloaded functions, enumerations, STL data structures, smart pointers, and virtual methods.
3

4
## Package Information
5

6
- **Package Name**: pybind11
7
- **Language**: C++ with Python integration
8
- **Installation**: `pip install pybind11`
9
- **Package Type**: Library (header-only C++ with Python build support)
10

11
## Core Imports
12

13
C++ usage (header includes):
14

15
```cpp
16
#include <pybind11/pybind11.h>
17
```
18

19
For specific functionality:
20

21
```cpp
22
#include <pybind11/stl.h>     // STL container support
23
#include <pybind11/numpy.h>   // NumPy array support
24
#include <pybind11/embed.h>   // Python embedding
25
```
26

27
Python usage (build/configuration access):
28

29
```python
30
import pybind11
31
from pybind11.setup_helpers import Pybind11Extension, build_ext, ParallelCompile
32
```
33

34
## Basic Usage
35

36
### Creating a Simple Python Module
37

38
```cpp
39
#include <pybind11/pybind11.h>
40

41
int add(int i, int j) {
42
    return i + j;
43
}
44

45
namespace py = pybind11;
46

47
PYBIND11_MODULE(example, m) {
48
    m.doc() = "pybind11 example plugin";
49
    m.def("add", &add, "Add two numbers");
50
}
51
```
52

53
### Building with setup.py
54

55
```python
56
from pybind11.setup_helpers import Pybind11Extension, build_ext
57
from pybind11 import get_cmake_dir
58

59
ext_modules = [
60
    Pybind11Extension(
61
        "example",
62
        ["src/main.cpp"],
63
        cxx_std=14,
64
    ),
65
]
66

67
setup(
68
    name="example",
69
    ext_modules=ext_modules,
70
    cmdclass={"build_ext": build_ext},
71
)
72
```
73

74
## Architecture
75

76
pybind11 consists of two main components:
77

78
- **C++ Header Library**: Template-based framework for creating Python bindings, with no runtime dependencies beyond Python and the C++ standard library
79
- **Python Package**: Build system integration, path discovery utilities, and installation helpers
80

81
The header library uses compile-time introspection to automatically infer type information, eliminating much of the boilerplate code typically required for Python extension modules.
82

83
## Capabilities
84

85
### Python Package API
86

87
Core Python package functionality for build system integration, path discovery, and extension building utilities.
88

89
```python { .api }
90
def get_include(user: bool = False) -> str: ...
91
def get_cmake_dir() -> str: ...
92
def get_pkgconfig_dir() -> str: ...
93
```
94

95
[Python Package](./python-package.md)
96

97
### Core C++ Binding API
98

99
Essential C++ classes and functions for creating Python modules, binding functions, and managing the module lifecycle.
100

101
```cpp { .api }
102
class module_;
103
template<typename... Options> class class_;
104
class cpp_function;
105
PYBIND11_MODULE(name, variable);
106
```
107

108
[Core Binding](./core-binding.md)
109

110
### Type System and Conversion
111

112
Automatic type conversion system between C++ and Python types, including custom type casters and casting policies.
113

114
```cpp { .api }
115
template<typename T> T cast(const handle &obj);
116
template<typename T> handle cast(T &&value);
117
enum class return_value_policy;
118
```
119

120
[Type System](./type-system.md)
121

122
### STL Integration
123

124
Built-in support for automatic conversion of standard C++ containers to Python equivalents, plus utilities for binding container types.
125

126
```cpp { .api }
127
template<typename Vector> void bind_vector(module_ &m, const char *name);
128
template<typename Map> void bind_map(module_ &m, const char *name);
129
```
130

131
[STL Integration](./stl-integration.md)
132

133
### NumPy Integration
134

135
Integration with NumPy arrays for high-performance numerical computing, including buffer protocol support and vectorization.
136

137
```cpp { .api }
138
class array;
139
template<typename T> class array_t;
140
template<typename Func> auto vectorize(Func &&f);
141
```
142

143
[NumPy Integration](./numpy-integration.md)
144

145
### Exception Handling
146

147
Seamless translation between C++ exceptions and Python exceptions, with support for custom exception types.
148

149
```cpp { .api }
150
class error_already_set;
151
template<typename T> void register_exception();
152
```
153

154
[Exception Handling](./exception-handling.md)
155

156
### Advanced Features
157

158
Advanced binding features including inheritance, virtual methods, operators, enumerations, and smart pointer integration.
159

160
```cpp { .api }
161
template<typename T> class enum_;
162
template<typename... Args> detail::initimpl::constructor<Args...> init();
163
class trampoline_self_life_support;
164
```
165

166
[Advanced Features](./advanced-features.md)
167

168
## Types
169

170
```cpp { .api }
171
namespace pybind11 {
172
    // Core object types
173
    class object;
174
    class handle;
175
    class module_;
176
    
177
    // Python type wrappers
178
    class str;
179
    class bytes;
180
    class int_;
181
    class float_;
182
    class bool_;
183
    class list;
184
    class tuple;
185
    class dict;
186
    class set;
187
    class slice;
188
    
189
    // Special argument types
190
    class args;
191
    class kwargs;
192
    
193
    // Version information (Python side)
194
    extern const char* __version__;
195
    extern const std::tuple<int, int, int> version_info;
196
}
197
```