0
# Core C++ Binding API
1

2
The core C++ binding API provides the fundamental classes and macros for creating Python modules and binding C++ code to Python. This is the primary interface for pybind11 users.
3

4
## Capabilities
5

6
### Module Definition
7

8
Create and configure Python modules from C++ code.
9

10
```cpp { .api }
11
PYBIND11_MODULE(name, variable) {
12
    // Module definition macro
13
    // name: Python module name (identifier)
14
    // variable: C++ variable name for the module (pybind11::module_ instance)
15
}
16
```
17

18
```cpp { .api }
19
class module_ : public object {
20
public:
21
    // Create Python binding for a new function within the module scope
22
    template <typename Func, typename... Extra>
23
    module_ &def(const char *name_, Func &&f, const Extra &...extra);
24
    
25
    // Create and return a new Python submodule
26
    module_ def_submodule(const char *name, const char *doc = nullptr);
27
    
28
    // Add an object to the module
29
    module_ &add_object(const char *name, handle obj, bool overwrite = false);
30
    
31
    // Set module docstring
32
    module_ &doc(const char *doc);
33
    
34
    // Define module-level attributes
35
    template <typename T>
36
    module_ &attr(const char *name) const;
37
};
38
```
39

40
### Function Binding
41

42
Bind C++ functions to Python, with support for overloading, default arguments, and various calling conventions.
43

44
```cpp { .api }
45
class cpp_function : public function {
46
    // Internal class for representing bound C++ functions
47
    // Created automatically by module_::def() and class_::def()
48
};
49

50
// Function binding attributes (used with module_::def and class_::def)
51
namespace pybind11 {
52
    // Function naming and documentation
53
    auto name(const char *name);
54
    auto doc(const char *doc);
55
    
56
    // Argument specification
57
    auto arg(const char *name);
58
    template<typename T>
59
    auto arg_v(const char *name, T &&value, const char *doc = nullptr);
60
    
61
    // Function relationships
62
    auto sibling(handle other);
63
    auto is_method(handle self);
64
    auto is_operator();
65
    
66
    // Call policies
67
    enum class return_value_policy {
68
        automatic,                // Automatic policy selection
69
        copy,                     // Copy the return value
70
        move,                     // Move the return value
71
        reference,                // Return a reference
72
        reference_internal,       // Return a reference, keep object alive
73
        take_ownership           // Transfer ownership to Python
74
    };
75
}
76
```
77

78
### Class Binding
79

80
Bind C++ classes to Python, including constructors, methods, properties, and inheritance.
81

82
```cpp { .api }
83
template<typename type_, typename... options>
84
class class_ : public detail::generic_type {
85
public:
86
    // Constructor - create a new Python class binding
87
    template <typename... Extra>
88
    class_(handle scope, const char *name, const Extra &...extra);
89
    
90
    // Bind member functions
91
    template <typename Func, typename... Extra>
92
    class_ &def(const char *name_, Func &&f, const Extra &...extra);
93
    
94
    // Bind static functions
95
    template <typename Func, typename... Extra>
96
    class_ &def_static(const char *name_, Func &&f, const Extra &...extra);
97
    
98
    // Bind constructors
99
    template <typename... Args>
100
    class_ &def(const detail::initimpl::constructor<Args...> &init, const Extra &...extra);
101
    
102
    // Bind properties with getter/setter
103
    template <typename Getter, typename Setter, typename... Extra>
104
    class_ &def_property(const char *name, const Getter &fget, const Setter &fset, const Extra& ...extra);
105
    
106
    // Bind read-only properties
107
    template <typename Getter, typename... Extra>
108
    class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra);
109
    
110
    // Bind data members for read/write access
111
    template <typename D>
112
    class_ &def_readwrite(const char *name, D C::*pm, const Extra& ...extra);
113
    
114
    // Bind data members for read-only access
115
    template <typename D>
116
    class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra);
117
    
118
    // Bind special methods
119
    template <typename... Args>
120
    class_ &def(const detail::initimpl::pickle_factory<GetState, SetState> &pf, const Extra &...extra);
121
};
122
```
123

124
### Constructor Binding
125

126
Specify how C++ constructors should be exposed to Python.
127

128
```cpp { .api }
129
namespace detail::initimpl {
130
    // Standard constructor binding
131
    template<typename... Args>
132
    constructor<Args...> init();
133
    
134
    // Alias constructor for trampoline classes
135
    template<typename... Args>  
136
    alias_constructor<Args...> init_alias();
137
    
138
    // Custom initialization function
139
    template<typename Func>
140
    auto init(Func &&f);
141
    
142
    // Constructor with both base and alias versions
143
    template<typename CFunc, typename AFunc>
144
    auto init(CFunc &&c, AFunc &&a);
145
    
146
    // Pickle support
147
    template<typename GetState, typename SetState>
148
    pickle_factory<GetState, SetState> pickle(GetState &&g, SetState &&s);
149
}
150
```
151

152
### Object System
153

154
Core object types for interacting with Python objects from C++.
155

156
```cpp { .api }
157
class handle {
158
    // Non-owning reference to a Python object
159
public:
160
    PyObject *ptr() const;
161
    explicit operator bool() const;
162
    bool is_none() const;
163
    
164
    template<typename T> T cast() const;
165
    template<typename... Args> object operator()(Args &&...args) const;
166
};
167

168
class object : public handle {
169
    // Owning reference to a Python object
170
public:
171
    object() = default;
172
    object(const object &o);
173
    object(object &&o) noexcept;
174
    object(handle h, borrowed_t);
175
    object(handle h, stolen_t);
176
    ~object();
177
    
178
    object& operator=(const object &other);
179
    object& operator=(object &&other) noexcept;
180
};
181
```
182

183
### Global Functions
184

185
Module-level utility functions.
186

187
```cpp { .api }
188
// Get global dictionary
189
dict globals();
190

191
// Module registration (used internally by PYBIND11_MODULE)
192
module_ create_extension_module(const char *name, const char *doc, PyModuleDef *def);
193
```
194

195
## Usage Examples
196

197
### Basic Module Definition
198

199
```cpp
200
#include <pybind11/pybind11.h>
201

202
namespace py = pybind11;
203

204
// Simple function
205
int add(int i, int j) { return i + j; }
206

207
PYBIND11_MODULE(example, m) {
208
    m.doc() = "pybind11 example plugin";
209
    m.def("add", &add, "A function that adds two numbers");
210
}
211
```
212

213
### Function with Default Arguments
214

215
```cpp
216
int add_with_default(int i, int j = 1) { return i + j; }
217

218
PYBIND11_MODULE(example, m) {
219
    m.def("add_with_default", &add_with_default, 
220
          "Add two numbers", py::arg("i"), py::arg("j") = 1);
221
}
222
```
223

224
### Class Binding
225

226
```cpp
227
class Pet {
228
public:
229
    Pet(const std::string &name) : name(name) { }
230
    void setName(const std::string &name_) { name = name_; }
231
    const std::string &getName() const { return name; }
232
    
233
private:
234
    std::string name;
235
};
236

237
PYBIND11_MODULE(example, m) {
238
    py::class_<Pet>(m, "Pet")
239
        .def(py::init<const std::string &>())
240
        .def("setName", &Pet::setName)
241
        .def("getName", &Pet::getName)
242
        .def_readwrite("name", &Pet::name);
243
}
244
```
245

246
### Class with Properties
247

248
```cpp
249
class Person {
250
    std::string name_;
251
    int age_;
252
public:
253
    Person(const std::string& name, int age) : name_(name), age_(age) {}
254
    
255
    const std::string& name() const { return name_; }
256
    void set_name(const std::string& name) { name_ = name; }
257
    
258
    int age() const { return age_; }
259
    void set_age(int age) { age_ = age; }
260
};
261

262
PYBIND11_MODULE(example, m) {
263
    py::class_<Person>(m, "Person")
264
        .def(py::init<const std::string&, int>())
265
        .def_property("name", &Person::name, &Person::set_name)
266
        .def_property("age", &Person::age, &Person::set_age);
267
}
268
```
269

270
### Submodules
271

272
```cpp 
273
PYBIND11_MODULE(example, m) {
274
    m.doc() = "pybind11 example plugin";
275
    
276
    // Create submodule
277
    auto math_module = m.def_submodule("math", "Math operations");
278
    math_module.def("add", &add, "Add two numbers");
279
    
280
    auto string_module = m.def_submodule("strings", "String operations");
281
    // ... bind string functions
282
}
283
```
284

285
## Types
286

287
```cpp { .api }
288
namespace pybind11 {
289
    // Core handle types
290
    class handle;        // Non-owning Python object reference
291
    class object;        // Owning Python object reference
292
    
293
    // Module and class types
294
    class module_;       // Python module wrapper
295
    template<typename T, typename... Options> 
296
    class class_;        // Python class wrapper
297
    
298
    // Special reference types
299
    struct borrowed_t {};   // Tag for borrowed references
300
    struct stolen_t {};     // Tag for stolen references
301
    
302
    constexpr borrowed_t borrowed{};
303
    constexpr stolen_t stolen{};
304
    
305
    // Template options for class binding
306
    class multiple_inheritance;  // Enable multiple inheritance support
307
    class dynamic_attr;         // Enable dynamic attribute access
308
    template<typename T> class base;  // Specify base class
309
}
310
```