0
# Cython
1

2
A Python compiler that transforms Python code into C/C++ extensions, making it as easy to write C extensions as Python itself. Cython provides a superset of the Python language with optional static typing capabilities, enabling developers to achieve significant performance improvements while maintaining Python's ease of use.
3

4
## Package Information
5

6
- **Package Name**: Cython
7
- **Language**: Python
8
- **Installation**: `pip install Cython`
9
- **Documentation**: https://cython.readthedocs.io/
10
- **Repository**: https://github.com/cython/cython
11

12
## Core Imports
13

14
```python
15
import cython
16
```
17

18
For the build system:
19

20
```python
21
from Cython.Build import cythonize
22
```
23

24
For import hooks:
25

26
```python
27
import pyximport
28
pyximport.install()
29
```
30

31
For distutils integration:
32

33
```python
34
from Cython.Distutils import build_ext, Extension
35
```
36

37
## Basic Usage
38

39
### Simple Cython Code with Type Annotations
40

41
```python
42
import cython
43

44
@cython.cfunc
45
@cython.locals(x=cython.int, y=cython.int)
46
def add_numbers(x, y):
47
    return x + y
48

49
# Using Cython types with declare
50
def fibonacci(n):
51
    n_typed = cython.declare(cython.int, n)
52
    if n_typed <= 1:
53
        return n_typed
54
    return fibonacci(n_typed-1) + fibonacci(n_typed-2)
55
```
56

57
### Building Extensions with cythonize
58

59
```python
60
from setuptools import setup
61
from Cython.Build import cythonize
62

63
setup(
64
    ext_modules = cythonize("my_module.pyx")
65
)
66
```
67

68
### Using Import Hooks
69

70
```python
71
import pyximport
72
pyximport.install()
73

74
# Now you can import .pyx files directly
75
import my_cython_module
76
```
77

78
## Architecture
79

80
Cython operates through a multi-stage compilation process:
81

82
- **Parser**: Converts Cython code (.pyx) into an Abstract Syntax Tree
83
- **Compiler**: Transforms the AST into optimized C/C++ code
84
- **Builder**: Compiles the generated C/C++ code into Python extension modules
85
- **Runtime**: Provides runtime support for Cython features and Python interoperability
86

87
The core language extensions include static typing for variables, function parameters, and return values, as well as direct C function calls, C data structures, and seamless integration with existing C/C++ libraries.
88

89
## Capabilities
90

91
### Core Language Features
92

93
Cython's language constructs, type system, decorators, and compiler directives that extend Python with static typing and C-level performance. Includes primitive types, pointer operations, memory management, and GIL control.
94

95
```python { .api }
96
# Type declarations
97
def declare(t=None, value=_Unspecified, **kwds): ...
98
def cast(t, *args, **kwargs): ...
99
def sizeof(arg): ...
100
def typeof(arg): ...
101

102
# Decorators
103
def locals(**arg_types): ...
104
def cfunc(f): ...
105
def ccall(f): ...
106
def inline(f, *args, **kwds): ...
107

108
# Compiler directives
109
def boundscheck(flag): ...
110
def wraparound(flag): ...
111
def cdivision(flag): ...
112
```
113

114
[Core Language](./core-language.md)
115

116
### Build System
117

118
The cythonize function and build infrastructure for converting .pyx files into compiled extension modules. Supports setuptools integration, parallel compilation, and advanced build configuration.
119

120
```python { .api }
121
def cythonize(module_list, exclude=None, nthreads=0, aliases=None, 
122
              quiet=False, force=None, language=None, 
123
              exclude_failures=False, show_all_warnings=False, **options): ...
124
```
125

126
[Build System](./build-system.md)
127

128
### Import System
129

130
Import hooks that allow importing .pyx files directly as Python modules without explicit compilation. Provides automatic compilation and caching of Cython modules at import time.
131

132
```python { .api }
133
def install(pyximport=True, pyimport=False, build_dir=None, 
134
            build_in_temp=True, setup_args=None, reload_support=False,
135
            load_py_module_on_import_failure=False, inplace=False,
136
            language_level=None): ...
137
def uninstall(py_importer, pyx_importer): ...
138
```
139

140
[Import System](./import-system.md)
141

142
### Command Line Tools
143

144
Command line interfaces for compiling Cython code, building extensions, and debugging. Includes the cython compiler, cythonize build tool, and cygdb debugger.
145

146
```bash { .api }
147
cython [options] sourcefile.pyx
148
cythonize [options] sourcefile.pyx
149
cygdb [options] [path-to-project-directory]
150
```
151

152
[Command Line Tools](./command-line-tools.md)
153

154
### IPython/Jupyter Integration
155

156
Magic commands and extensions for interactive Cython development in IPython and Jupyter notebooks. Enables inline compilation, execution, and debugging of Cython code.
157

158
```python { .api }
159
def load_ipython_extension(ip): ...
160

161
%%cython [options]
162
%%cython_inline
163
%%cython_pyximport module_name
164
```
165

166
[IPython/Jupyter Integration](./ipython-integration.md)
167

168
### Debugging and Profiling
169

170
Comprehensive debugging and profiling tools for analyzing and optimizing Cython code. Includes source-level debugging, performance analysis, and bottleneck identification.
171

172
```bash { .api }
173
cygdb [options] [path-to-project-directory] [gdb-args...]
174
```
175

176
```python { .api }
177
@cython.profile(True)
178
@cython.linetrace(True)
179
def profiled_function(): ...
180
```
181

182
[Debugging and Profiling](./debugging-profiling.md)
183

184
### C/C++ Interoperability
185

186
Extensive capabilities for interfacing with C and C++ libraries, including standard library bindings, external library interfaces, and tools for wrapping existing codebases.
187

188
```python { .api }
189
# Standard library bindings
190
from cpython.object cimport PyObject, Py_INCREF, Py_DECREF
191
from libc.stdlib cimport malloc, free
192
from libcpp.vector cimport vector
193
from posix.unistd cimport getpid
194

195
# External library declaration
196
cdef extern from "library.h":
197
    int external_function(int arg)
198
```
199

200
[C/C++ Interoperability](./c-cpp-interoperability.md)
201

202
### Compiler Interface
203

204
Direct access to Cython's compilation pipeline for advanced use cases and tooling integration.
205

206
```python { .api }
207
def compile(source, options=None, full_module_name=None, **kwds):
208
    """Compile Cython source code to C/C++ extensions.
209
    
210
    Args:
211
        source: Source code string or sequence of source files
212
        options: CompilationOptions instance
213
        full_module_name: Full module name for compilation
214
        **kwds: Additional compilation options
215
    
216
    Returns:
217
        CompilationResult or CompilationResultSet
218
    """
219

220
def compile_single(source, options, full_module_name, cache=None):
221
    """Compile a single source file."""
222

223
def compile_multiple(sources, options, cache=None):
224
    """Compile multiple source files with dependency tracking."""
225
```
226

227
## Types
228

229
### Core Types
230

231
```python { .api }
232
# Fundamental types
233
class typedef:
234
    def __init__(self, type, name=None): ...
235
    def __call__(self, *arg): ...
236

237
# Primitive types (available as module attributes)
238
int = typedef(int, "int")
239
long = typedef(int, "long") 
240
float = typedef(float, "float")
241
double = typedef(float, "double")
242
char = typedef(int, "char")
243
bint = typedef(bool, "bint")
244
void = typedef(None, "void")
245

246
# Pointer and array types
247
def pointer(basetype): ...
248
def array(basetype, n): ...
249

250
# Structure types
251
def struct(**members): ...
252
def union(**members): ...
253

254
# Type modifiers
255
class const:
256
    def __class_getitem__(cls, base_type): ...
257

258
class volatile:
259
    def __class_getitem__(cls, base_type): ...
260
```
261

262
### Fused Types
263

264
```python { .api }
265
def fused_type(*args): ...
266

267
# Pre-defined fused types
268
integral: _FusedType
269
floating: _FusedType
270
numeric: _FusedType
271
```
272

273
### Parallel Computing Types
274

275
```python { .api }
276
class CythonDotParallel:
277
    """The cython.parallel module for parallel computing."""
278
    
279
    def parallel(self, num_threads=None):
280
        """Context manager for parallel regions.
281
        
282
        Args:
283
            num_threads: Number of threads to use (default: system maximum)
284
        
285
        Returns:
286
            Context manager for parallel execution
287
        """
288
    
289
    def prange(self, start=0, stop=None, step=1, nogil=False, 
290
               schedule=None, chunksize=None, num_threads=None):
291
        """Parallel range loop with OpenMP support.
292
        
293
        Args:
294
            start: Loop start value (default: 0)
295
            stop: Loop end value (required if start is provided)
296
            step: Loop step size (default: 1)
297
            nogil: Execute without GIL (default: False)
298
            schedule: OpenMP scheduling policy ('static', 'dynamic', 'guided')
299
            chunksize: Chunk size for scheduling
300
            num_threads: Number of threads to use
301
        
302
        Returns:
303
            Range iterator for parallel execution
304
        """
305
    
306
    def threadid(self):
307
        """Get current thread ID in parallel region.
308
        
309
        Returns:
310
            Integer thread ID (0-based)
311
        """
312
```
313

314
### Threading and Synchronization Types
315

316
```python { .api }
317
class critical_section:
318
    """Context manager and decorator for thread-safe critical sections."""
319
    
320
    def __init__(self, arg0, arg1=None):
321
        """Initialize critical section with lock objects."""
322
    
323
    def __call__(self, *args, **kwargs):
324
        """Use as decorator for functions."""
325
    
326
    def __enter__(self):
327
        """Enter critical section context."""
328
    
329
    def __exit__(self, exc_class, exc, tb):
330
        """Exit critical section context."""
331

332
class pymutex:
333
    """Python threading mutex implementation."""
334
    
335
    def __init__(self):
336
        """Initialize mutex using threading.Lock."""
337
    
338
    def acquire(self):
339
        """Acquire the mutex lock."""
340
    
341
    def release(self):
342
        """Release the mutex lock."""
343
    
344
    def __enter__(self):
345
        """Context manager entry."""
346
    
347
    def __exit__(self, exc_type, exc_value, traceback):
348
        """Context manager exit."""
349

350
pythread_type_lock = pymutex  # Alias for pymutex
351
```
352

353
### Inline Compilation Functions
354

355
```python { .api }
356
def inline(f, *args, **kwargs):
357
    """Inline compile Cython code or mark function for inlining.
358
    
359
    Args:
360
        f: Function to inline or C code string
361
        *args: Additional arguments for inline compilation
362
        **kwargs: Keyword arguments for compilation options
363
    
364
    Returns:
365
        Compiled inline function or result
366
    """
367

368
def compile(f):
369
    """Runtime compile a function with Cython.
370
    
371
    Args:
372
        f: Function to compile at runtime
373
    
374
    Returns:
375
        RuntimeCompiledFunction instance
376
    """
377
```