0
# Core Python API
1
2
The primary programmatic interface for creating and managing Python binding projects. This API provides complete control over the binding generation process, from project configuration to final build output.
3
4
## Capabilities
5
6
### Project Management
7
8
The Project class serves as the main entry point for managing SIP binding projects, coordinating all aspects of the build process.
9
10
```python { .api }
11
class Project:
12
"""Main project implementation with 37+ configurable options."""
13
14
def build(self):
15
"""Build the project in-situ."""
16
pass
17
18
def build_sdist(self, sdist_directory):
19
"""
20
Build source distribution.
21
22
Args:
23
sdist_directory (str): Target directory for source distribution
24
25
Returns:
26
str: Path to created source distribution
27
"""
28
pass
29
30
def build_wheel(self, wheel_directory):
31
"""
32
Build wheel distribution.
33
34
Args:
35
wheel_directory (str): Target directory for wheel
36
37
Returns:
38
str: Path to created wheel
39
"""
40
pass
41
42
def install(self):
43
"""Build and install the project."""
44
pass
45
```
46
47
### Abstract Base Classes
48
49
Foundation classes that define the core interfaces for extensible project and builder implementations.
50
51
```python { .api }
52
class AbstractProject:
53
"""Base class for projects containing bindings."""
54
55
@classmethod
56
def bootstrap(cls, tool, tool_description=''):
57
"""
58
Bootstrap project from configuration.
59
60
Args:
61
tool (str): Tool name for specialized bootstrap (required)
62
tool_description (str, optional): Description of the tool
63
64
Returns:
65
AbstractProject: Configured project instance
66
"""
67
pass
68
69
def build(self):
70
"""Build the project."""
71
pass
72
73
def build_sdist(self, sdist_directory):
74
"""Build source distribution."""
75
pass
76
77
def build_wheel(self, wheel_directory):
78
"""Build wheel distribution."""
79
pass
80
81
def install(self):
82
"""Install the project."""
83
pass
84
85
def import_callable(self, callable_name, expected_type):
86
"""
87
Import callable from module.
88
89
Args:
90
callable_name (str): Name of callable to import
91
expected_type (type): Expected type of the callable
92
93
Returns:
94
callable: Imported callable
95
"""
96
pass
97
98
def setup(self):
99
"""Setup project configuration."""
100
pass
101
102
class AbstractBuilder:
103
"""Base class for project builders."""
104
105
def build(self):
106
"""Build the project."""
107
pass
108
109
def build_sdist(self):
110
"""Build source distribution."""
111
pass
112
113
def build_wheel(self):
114
"""Build wheel distribution."""
115
pass
116
117
def install(self):
118
"""Install the project."""
119
pass
120
```
121
122
### Bindings Generation
123
124
The Bindings class manages the transformation of .sip specification files into C/C++ source code for compilation into Python extension modules.
125
126
```python { .api }
127
class Bindings:
128
"""Encapsulates a module's bindings with 18+ configurable options."""
129
130
def generate(self):
131
"""
132
Generate binding code from .sip specification files.
133
134
Processes specification files and creates optimized C/C++ source code
135
for compilation into Python extension modules.
136
"""
137
pass
138
139
def is_buildable(self):
140
"""
141
Check if bindings can be built.
142
143
Returns:
144
bool: True if bindings are buildable, False otherwise
145
"""
146
pass
147
148
def verify_configuration(self, tool):
149
"""
150
Verify configuration validity.
151
152
Args:
153
tool (str): Tool name for context-specific validation
154
155
Raises:
156
UserException: If configuration is invalid
157
"""
158
pass
159
```
160
161
### Build Orchestration
162
163
Builder classes handle the platform-specific compilation and linking process for generated binding code.
164
165
```python { .api }
166
class Builder:
167
"""Default base implementation of project builder."""
168
169
def build(self):
170
"""
171
Build the project.
172
173
Handles bindings generation, script creation, and build management.
174
"""
175
pass
176
177
def install(self):
178
"""Install the built project."""
179
pass
180
181
class DistutilsBuilder:
182
"""Distutils-based implementation of Builder."""
183
184
def build(self):
185
"""
186
Build using distutils.
187
188
Note: Cannot build executables or static modules.
189
"""
190
pass
191
192
def install(self):
193
"""Install using distutils."""
194
pass
195
```
196
197
### Buildable Components
198
199
Classes representing individual build targets within a project.
200
201
```python { .api }
202
class Buildable:
203
"""Base class for buildable components."""
204
def build(self): ...
205
def install(self): ...
206
def is_buildable(self): ...
207
208
class BuildableBindings(Buildable):
209
"""Builds extension modules for bindings from .sip files."""
210
def generate(self): ...
211
def verify_configuration(self, tool): ...
212
213
class BuildableExecutable(Buildable):
214
"""Builds standalone executables."""
215
def get_executable_name(self): ...
216
217
class BuildableFromSources(Buildable):
218
"""Base class for components built from C/C++ source files."""
219
def get_sources(self): ...
220
def get_include_dirs(self): ...
221
def get_libraries(self): ...
222
223
class BuildableModule(BuildableFromSources):
224
"""Builds Python extension modules from C/C++ sources."""
225
def get_module_name(self): ...
226
```
227
228
### Installation Management
229
230
The Installable class manages file installation to target directories.
231
232
```python { .api }
233
class Installable:
234
"""Manages file installation to target directories."""
235
236
def install(self):
237
"""
238
Install files to target locations.
239
240
Copies files from build directory to installation directory
241
with proper permissions and directory structure.
242
"""
243
pass
244
245
def get_full_target_dir(self):
246
"""
247
Get full target directory path.
248
249
Returns:
250
str: Complete path to target directory
251
"""
252
pass
253
```
254
255
### Exception Classes
256
257
Exception hierarchy for user-friendly error handling throughout the SIP system.
258
259
```python { .api }
260
class UserException(Exception):
261
"""Base exception for user-friendly errors."""
262
pass
263
264
class UserFileException(UserException):
265
"""Base class for file-related user errors."""
266
pass
267
268
class UserParseException(UserException):
269
"""Exception for parsing errors."""
270
pass
271
272
class PyProjectException(UserFileException):
273
"""Exception related to pyproject.toml files."""
274
pass
275
276
class PyProjectOptionException(PyProjectException):
277
"""Configuration option errors in pyproject.toml."""
278
pass
279
280
class PyProjectUndefinedOptionException(PyProjectOptionException):
281
"""Exception for undefined required options in pyproject.toml."""
282
pass
283
284
def handle_exception(exception):
285
"""
286
Standard exception handler for SIP tools.
287
288
Args:
289
exception (Exception): Exception to handle
290
291
Provides user-friendly error messages and appropriate exit codes.
292
"""
293
pass
294
```
295
296
### Version Information
297
298
```python { .api }
299
SIP_VERSION: int
300
"""Numeric version identifier."""
301
302
SIP_VERSION_STR: str
303
"""String version identifier (e.g., '5.5.0')."""
304
```
305
306
## Usage Examples
307
308
### Basic Project Setup
309
310
```python
311
from sipbuild import Project, Bindings
312
313
# Create and configure a project
314
project = Project()
315
316
# Add bindings configuration
317
bindings = Bindings(
318
sip_files=['mymodule.sip'],
319
include_dirs=['/usr/include/mylib'],
320
libraries=['mylib'],
321
library_dirs=['/usr/lib']
322
)
323
324
# Verify configuration
325
bindings.verify_configuration()
326
327
# Generate and build
328
if bindings.is_buildable():
329
bindings.generate()
330
project.build()
331
```
332
333
### Custom Builder
334
335
```python
336
from sipbuild import AbstractProject, AbstractBuilder
337
338
class CustomProject(AbstractProject):
339
def setup(self):
340
# Custom setup logic
341
super().setup()
342
343
class CustomBuilder(AbstractBuilder):
344
def build(self):
345
# Custom build logic
346
super().build()
347
348
# Bootstrap with custom classes
349
project = CustomProject.bootstrap()
350
project.build()
351
```