0
# SIP
1

2
A comprehensive tool for creating Python bindings for C and C++ libraries. SIP originally developed to create PyQt but is applicable to any C/C++ library, providing build tools that process specification files and generate optimized C/C++ code compiled into extension modules.
3

4
## Package Information
5

6
- **Package Name**: sip
7
- **Language**: Python
8
- **Installation**: `pip install sip`
9
- **Requirements**: Python 3.5.1+, packaging, toml
10

11
## Core Imports
12

13
```python
14
import sipbuild
15
```
16

17
For specific functionality:
18

19
```python
20
from sipbuild import Project, Bindings, Builder
21
from sipbuild import AbstractProject, AbstractBuilder
22
from sipbuild import Buildable, BuildableBindings, BuildableExecutable
23
from sipbuild import BuildableFromSources, BuildableModule
24
from sipbuild import Installable, Option
25
from sipbuild import UserException, UserParseException, handle_exception
26
from sipbuild import import_callable, resolve_abi_version
27
from sipbuild import SIP_VERSION, SIP_VERSION_STR
28
```
29

30
## Basic Usage
31

32
```python
33
from sipbuild import Project, Bindings
34

35
# Create a project for building Python bindings
36
project = Project()
37

38
# Configure bindings
39
bindings = Bindings(
40
    sip_files=['mymodule.sip'],
41
    include_dirs=['/usr/include'],
42
    libraries=['mylib']
43
)
44

45
# Build the project
46
project.build()
47
```
48

49
Command-line usage:
50

51
```bash
52
# Build project in current directory
53
sip-build
54

55
# Install the project
56
sip-install
57

58
# Create wheel distribution
59
sip-wheel
60

61
# Generate legacy SIP v5 compatible bindings
62
sip5 -c . mymodule.sip
63
```
64

65
## Architecture
66

67
SIP follows a configurable build pipeline architecture:
68

69
- **Projects**: Top-level containers managing build configuration and coordination
70
- **Bindings**: Specification-to-code generators that process .sip files into C/C++ source
71
- **Builders**: Platform-specific build orchestrators handling compilation and linking
72
- **Buildables**: Individual build targets (modules, executables, libraries)
73
- **Tools**: Command-line interfaces wrapping the core functionality
74

75
This design enables creation of Python wheels that are version-independent (compatible with Python 3.5+), supports multiple extension modules within the same package, and provides sophisticated configuration and build management capabilities.
76

77
## Capabilities
78

79
### Core Python API
80

81
The primary programmatic interface for creating and managing Python binding projects, including project configuration, bindings generation, and build orchestration.
82

83
```python { .api }
84
class Project:
85
    def build(self): ...
86
    def build_sdist(self, sdist_directory): ...
87
    def build_wheel(self, wheel_directory): ...
88
    def install(self): ...
89

90
class Bindings:
91
    def generate(self): ...
92
    def is_buildable(self): ...
93
    def verify_configuration(self): ...
94

95
class Builder:
96
    def build(self): ...
97
    def install(self): ...
98
```
99

100
[Core Python API](./core-api.md)
101

102
### Command-Line Tools
103

104
Seven command-line tools for building, installing, and managing SIP projects from the shell, providing complete project lifecycle management without requiring Python code.
105

106
```bash { .api }
107
sip-build           # Build project in-situ
108
sip-install         # Build and install project
109
sip-wheel           # Build wheel distribution
110
sip-sdist           # Build source distribution
111
sip-module          # Generate sip module source
112
sip-distinfo        # Create .dist-info directories
113
sip5                # Legacy SIP v5 compatibility
114
```
115

116
[Command-Line Tools](./cli-tools.md)
117

118
### Configuration System
119

120
Comprehensive configuration management supporting pyproject.toml files, command-line overrides, and environment markers for flexible project setup.
121

122
```python { .api }
123
class Option:
124
    def __init__(self, name, option_type, default=None, choices=None): ...
125

126
class Configurable:
127
    def add_options(self, parser): ...
128
    def apply_options(self, options): ...
129
```
130

131
[Configuration System](./configuration.md)
132

133
### Build System Integration
134

135
PEP 517 build backend support and integration with modern Python packaging workflows, enabling seamless integration with pip and other build tools.
136

137
```python { .api }
138
def build_sdist(sdist_directory, config_settings=None): ...
139
def build_wheel(wheel_directory, config_settings=None, metadata_directory=None): ...
140
```
141

142
[Build System Integration](./build-integration.md)
143

144
## Types
145

146
```python { .api }
147
class UserException(Exception):
148
    """Base exception for user-friendly errors."""
149
    pass
150

151
class UserFileException(UserException):
152
    """Base class for file-related user errors."""
153
    pass
154

155
class UserParseException(UserException):
156
    """Exception for parsing errors in specification files."""
157
    pass
158

159
class PyProjectException(UserFileException):
160
    """Exception related to pyproject.toml files."""
161
    pass
162

163
class PyProjectOptionException(PyProjectException):
164
    """Configuration option errors in pyproject.toml."""
165
    pass
166

167
class PyProjectUndefinedOptionException(PyProjectOptionException):
168
    """Exception for undefined required options."""
169
    pass
170

171
def handle_exception(exception):
172
    """Standard exception handler for SIP tools."""
173
    pass
174

175
class Installable:
176
    """Manages file installation to target directories."""
177
    def install(self): ...
178
    def get_full_target_dir(self): ...
179

180
def import_callable(callable_name, expected_type):
181
    """
182
    Import callable from module for factory pattern support.
183
    
184
    Args:
185
        callable_name (str): Name of callable to import
186
        expected_type (type): Expected type of the callable
187
        
188
    Returns:
189
        callable: Imported callable
190
    """
191
    pass
192

193
def resolve_abi_version(version_spec):
194
    """
195
    Resolve ABI version specification to actual version.
196
    
197
    Args:
198
        version_spec (str): Version specification (e.g., '12.8')
199
        
200
    Returns:
201
        tuple: (major, minor) version numbers
202
    """
203
    pass
204

205
SIP_VERSION: int
206
"""Numeric version identifier."""
207

208
SIP_VERSION_STR: str  
209
"""String version identifier (e.g., '5.5.0')."""
210
```