0
# Python Package API
1

2
The pybind11 Python package provides build system integration, path discovery utilities, and helpers for building C++ extensions. This package is typically used during the build process rather than at runtime.
3

4
## Capabilities
5

6
### Path Discovery Functions
7

8
Functions to locate pybind11 installation paths for build systems and compilers.
9

10
```python { .api }
11
def get_include(user: bool = False) -> str:
12
    """
13
    Return the path to the pybind11 include directory.
14
    
15
    Args:
16
        user: Unused historical parameter, may be removed
17
        
18
    Returns:
19
        str: Path to pybind11 C++ headers
20
    """
21

22
def get_cmake_dir() -> str:
23
    """
24
    Return the path to the pybind11 CMake module directory.
25
    
26
    Returns:
27
        str: Path to CMake modules
28
        
29
    Raises:
30
        ImportError: If pybind11 is not properly installed
31
    """
32

33
def get_pkgconfig_dir() -> str:
34
    """
35
    Return the path to the pybind11 pkgconfig directory.
36
    
37
    Returns:
38
        str: Path to pkgconfig files
39
        
40
    Raises:
41
        ImportError: If pybind11 is not properly installed
42
    """
43
```
44

45
### Version Information
46

47
Package version information for compatibility checking.
48

49
```python { .api }
50
__version__: str  # Version string (e.g., "3.0.1")
51
version_info: tuple  # Version tuple (major, minor, patch)
52
```
53

54
### Extension Building Classes
55

56
Classes for building C++ extensions with proper pybind11 integration.
57

58
```python { .api }
59
class Pybind11Extension:
60
    """
61
    Build a C++11+ Extension module with pybind11.
62
    
63
    Automatically adds recommended flags and assumes C++ sources.
64
    Inherits from setuptools.Extension or distutils.Extension.
65
    """
66
    
67
    def __init__(self, *args, cxx_std: int = 0, include_pybind11: bool = True, **kwargs):
68
        """
69
        Initialize Pybind11Extension.
70
        
71
        Args:
72
            *args: Arguments passed to Extension
73
            cxx_std: C++ standard level (11, 14, 17, etc.) - 0 for auto-detection
74
            include_pybind11: Whether to automatically include pybind11 headers
75
            **kwargs: Additional keyword arguments passed to Extension
76
        """
77
    
78
    @property
79
    def cxx_std(self) -> int:
80
        """The C++ standard level."""
81
    
82
    @cxx_std.setter
83
    def cxx_std(self, level: int) -> None:
84
        """Set the C++ standard level."""
85
```
86

87
```python { .api }
88
class build_ext:
89
    """
90
    Customized build_ext that allows auto-search for the highest supported
91
    C++ level for Pybind11Extension.
92
    
93
    Inherits from setuptools.command.build_ext.build_ext or
94
    distutils.command.build_ext.build_ext.
95
    """
96
    
97
    def build_extensions(self) -> None:
98
        """Build extensions, injecting C++ std for Pybind11Extension if needed."""
99
```
100

101
### Parallel Compilation Utilities
102

103
Utilities for accelerating compilation of C++ extensions.
104

105
```python { .api }
106
class ParallelCompile:
107
    """
108
    Make a parallel compile function for faster builds.
109
    """
110
    
111
    def __init__(
112
        self,
113
        envvar: str | None = None,
114
        default: int = 0,
115
        max: int = 0,
116
        needs_recompile: Callable[[str, str], bool] = no_recompile
117
    ):
118
        """
119
        Initialize parallel compilation.
120
        
121
        Args:
122
            envvar: Environment variable to control compilation threads
123
            default: Default number of threads (0 for auto)
124
            max: Maximum number of threads (0 for no limit)
125
            needs_recompile: Function to determine if recompilation is needed
126
        """
127
    
128
    def function(self) -> CCompilerMethod:
129
        """Build a function object usable as distutils.ccompiler.CCompiler.compile."""
130
    
131
    def install(self) -> ParallelCompile:
132
        """Install the compile function into distutils.ccompiler.CCompiler.compile."""
133
    
134
    def __enter__(self) -> ParallelCompile:
135
        """Context manager entry."""
136
    
137
    def __exit__(self, *args) -> None:
138
        """Context manager exit."""
139
```
140

141
### Helper Functions
142

143
Utility functions for extension building and compilation.
144

145
```python { .api }
146
def intree_extensions(
147
    paths: Iterable[str], 
148
    package_dir: dict[str, str] | None = None
149
) -> list[Pybind11Extension]:
150
    """
151
    Generate Pybind11Extensions from source files in a Python source tree.
152
    
153
    Args:
154
        paths: Source file paths
155
        package_dir: Package directory mapping (behaves like setuptools.setup)
156
        
157
    Returns:
158
        List of Pybind11Extension objects
159
    """
160

161
def has_flag(compiler, flag: str) -> bool:
162
    """
163
    Return True if a flag is supported by the specified compiler.
164
    
165
    Args:
166
        compiler: Compiler instance
167
        flag: Compiler flag to test
168
        
169
    Returns:
170
        bool: True if flag is supported
171
    """
172

173
def auto_cpp_level(compiler) -> str | int:
174
    """
175
    Return the max supported C++ std level (17, 14, or 11).
176
    
177
    Args:
178
        compiler: Compiler instance
179
        
180
    Returns:
181
        str | int: Latest supported C++ standard ("latest" on Windows, int elsewhere)
182
    """
183

184
def naive_recompile(obj: str, src: str) -> bool:
185
    """
186
    Simple recompile check based on modification times.
187
    
188
    Args:
189
        obj: Object file path
190
        src: Source file path
191
        
192
    Returns:
193
        bool: True if recompilation is needed
194
    """
195

196
def no_recompile(obj: str, src: str) -> bool:
197
    """
198
    Always recompile strategy (safest but slowest).
199
    
200
    Args:
201
        obj: Object file path (unused)
202
        src: Source file path (unused)
203
        
204
    Returns:
205
        bool: Always True
206
    """
207
```
208

209
### Command Line Interface
210

211
The package provides a command-line interface for configuration queries.
212

213
```python { .api }
214
# Entry point: pybind11-config
215
# Usage: pybind11-config --includes
216
#        pybind11-config --cmakedir
217
#        pybind11-config --pkgconfigdir
218
```
219

220
## Usage Examples
221

222
### Basic Extension Setup
223

224
```python
225
from pybind11.setup_helpers import Pybind11Extension, build_ext
226
from setuptools import setup
227

228
ext_modules = [
229
    Pybind11Extension(
230
        "my_extension",
231
        ["src/main.cpp", "src/helper.cpp"],
232
        cxx_std=14,
233
        include_pybind11=True,
234
    ),
235
]
236

237
setup(
238
    name="my_package",
239
    ext_modules=ext_modules,
240
    cmdclass={"build_ext": build_ext},
241
)
242
```
243

244
### Using Parallel Compilation
245

246
```python
247
from pybind11.setup_helpers import ParallelCompile
248

249
# Enable parallel compilation
250
ParallelCompile("NPY_NUM_BUILD_JOBS").install()
251

252
# Or use as context manager
253
with ParallelCompile("NPY_NUM_BUILD_JOBS"):
254
    setup(...)
255
```
256

257
### Path Discovery in Build Scripts
258

259
```python
260
import pybind11
261

262
# Get include path for compiler
263
include_dirs = [pybind11.get_include()]
264

265
# Get CMake directory for CMake-based builds
266
cmake_dir = pybind11.get_cmake_dir()
267

268
# Get pkgconfig directory
269
pkgconfig_dir = pybind11.get_pkgconfig_dir()
270
```
271

272
## Types
273

274
```python { .api }
275
from typing import Callable, Iterable
276

277
# Type aliases used in the API
278
CCompilerMethod = Callable[..., list[str]]
279
CompilerType = Any  # distutils.ccompiler.CCompiler type
280
```