Core C++ Binding API

PYBIND11_MODULE(name, variable) {
    // Module definition macro
    // name: Python module name (identifier)
    // variable: C++ variable name for the module (pybind11::module_ instance)
}

class module_ : public object {
public:
    // Create Python binding for a new function within the module scope
    template <typename Func, typename... Extra>
    module_ &def(const char *name_, Func &&f, const Extra &...extra);
    
    // Create and return a new Python submodule
    module_ def_submodule(const char *name, const char *doc = nullptr);
    
    // Add an object to the module
    module_ &add_object(const char *name, handle obj, bool overwrite = false);
    
    // Set module docstring
    module_ &doc(const char *doc);
    
    // Define module-level attributes
    template <typename T>
    module_ &attr(const char *name) const;
};

class cpp_function : public function {
    // Internal class for representing bound C++ functions
    // Created automatically by module_::def() and class_::def()
};

// Function binding attributes (used with module_::def and class_::def)
namespace pybind11 {
    // Function naming and documentation
    auto name(const char *name);
    auto doc(const char *doc);
    
    // Argument specification
    auto arg(const char *name);
    template<typename T>
    auto arg_v(const char *name, T &&value, const char *doc = nullptr);
    
    // Function relationships
    auto sibling(handle other);
    auto is_method(handle self);
    auto is_operator();
    
    // Call policies
    enum class return_value_policy {
        automatic,                // Automatic policy selection
        copy,                     // Copy the return value
        move,                     // Move the return value
        reference,                // Return a reference
        reference_internal,       // Return a reference, keep object alive
        take_ownership           // Transfer ownership to Python
    };
}

template<typename type_, typename... options>
class class_ : public detail::generic_type {
public:
    // Constructor - create a new Python class binding
    template <typename... Extra>
    class_(handle scope, const char *name, const Extra &...extra);
    
    // Bind member functions
    template <typename Func, typename... Extra>
    class_ &def(const char *name_, Func &&f, const Extra &...extra);
    
    // Bind static functions
    template <typename Func, typename... Extra>
    class_ &def_static(const char *name_, Func &&f, const Extra &...extra);
    
    // Bind constructors
    template <typename... Args>
    class_ &def(const detail::initimpl::constructor<Args...> &init, const Extra &...extra);
    
    // Bind properties with getter/setter
    template <typename Getter, typename Setter, typename... Extra>
    class_ &def_property(const char *name, const Getter &fget, const Setter &fset, const Extra& ...extra);
    
    // Bind read-only properties
    template <typename Getter, typename... Extra>
    class_ &def_property_readonly(const char *name, const Getter &fget, const Extra& ...extra);
    
    // Bind data members for read/write access
    template <typename D>
    class_ &def_readwrite(const char *name, D C::*pm, const Extra& ...extra);
    
    // Bind data members for read-only access
    template <typename D>
    class_ &def_readonly(const char *name, const D C::*pm, const Extra& ...extra);
    
    // Bind special methods
    template <typename... Args>
    class_ &def(const detail::initimpl::pickle_factory<GetState, SetState> &pf, const Extra &...extra);
};

namespace detail::initimpl {
    // Standard constructor binding
    template<typename... Args>
    constructor<Args...> init();
    
    // Alias constructor for trampoline classes
    template<typename... Args>  
    alias_constructor<Args...> init_alias();
    
    // Custom initialization function
    template<typename Func>
    auto init(Func &&f);
    
    // Constructor with both base and alias versions
    template<typename CFunc, typename AFunc>
    auto init(CFunc &&c, AFunc &&a);
    
    // Pickle support
    template<typename GetState, typename SetState>
    pickle_factory<GetState, SetState> pickle(GetState &&g, SetState &&s);
}

class handle {
    // Non-owning reference to a Python object
public:
    PyObject *ptr() const;
    explicit operator bool() const;
    bool is_none() const;
    
    template<typename T> T cast() const;
    template<typename... Args> object operator()(Args &&...args) const;
};

class object : public handle {
    // Owning reference to a Python object
public:
    object() = default;
    object(const object &o);
    object(object &&o) noexcept;
    object(handle h, borrowed_t);
    object(handle h, stolen_t);
    ~object();
    
    object& operator=(const object &other);
    object& operator=(object &&other) noexcept;
};

// Get global dictionary
dict globals();

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

#include <pybind11/pybind11.h>

namespace py = pybind11;

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

PYBIND11_MODULE(example, m) {
    m.doc() = "pybind11 example plugin";
    m.def("add", &add, "A function that adds two numbers");
}

int add_with_default(int i, int j = 1) { return i + j; }

PYBIND11_MODULE(example, m) {
    m.def("add_with_default", &add_with_default, 
          "Add two numbers", py::arg("i"), py::arg("j") = 1);
}

class Pet {
public:
    Pet(const std::string &name) : name(name) { }
    void setName(const std::string &name_) { name = name_; }
    const std::string &getName() const { return name; }
    
private:
    std::string name;
};

PYBIND11_MODULE(example, m) {
    py::class_<Pet>(m, "Pet")
        .def(py::init<const std::string &>())
        .def("setName", &Pet::setName)
        .def("getName", &Pet::getName)
        .def_readwrite("name", &Pet::name);
}

class Person {
    std::string name_;
    int age_;
public:
    Person(const std::string& name, int age) : name_(name), age_(age) {}
    
    const std::string& name() const { return name_; }
    void set_name(const std::string& name) { name_ = name; }
    
    int age() const { return age_; }
    void set_age(int age) { age_ = age; }
};

PYBIND11_MODULE(example, m) {
    py::class_<Person>(m, "Person")
        .def(py::init<const std::string&, int>())
        .def_property("name", &Person::name, &Person::set_name)
        .def_property("age", &Person::age, &Person::set_age);
}

PYBIND11_MODULE(example, m) {
    m.doc() = "pybind11 example plugin";
    
    // Create submodule
    auto math_module = m.def_submodule("math", "Math operations");
    math_module.def("add", &add, "Add two numbers");
    
    auto string_module = m.def_submodule("strings", "String operations");
    // ... bind string functions
}

namespace pybind11 {
    // Core handle types
    class handle;        // Non-owning Python object reference
    class object;        // Owning Python object reference
    
    // Module and class types
    class module_;       // Python module wrapper
    template<typename T, typename... Options> 
    class class_;        // Python class wrapper
    
    // Special reference types
    struct borrowed_t {};   // Tag for borrowed references
    struct stolen_t {};     // Tag for stolen references
    
    constexpr borrowed_t borrowed{};
    constexpr stolen_t stolen{};
    
    // Template options for class binding
    class multiple_inheritance;  // Enable multiple inheritance support
    class dynamic_attr;         // Enable dynamic attribute access
    template<typename T> class base;  // Specify base class
}