Cython: A Guide for Python Programmers

Copyright
Table of Contents
Preface
Who Should Read This Book?
Prerequisites
Who Should Not Read This Book?
Outline
Conventions Used in This Book
Using Code Examples
Safari® Books Online
How to Contact Us
Acknowledgments
Chapter 1. Cython Essentials
Comparing Python, C, and Cython
Function Call Overhead
Looping
Math Operations
Stack Versus Heap Allocation
Tempering Our Enthusiasm
Wrapping C Code with Cython
Summary
Chapter 2. Compiling and Running Cython Code
The Cython Compilation Pipeline
Installing and Testing Our Setup
The Standard Way: Using distutils with cythonize
Our distutils Script
Compiling with distutils on Mac OS X and Linux
Compiling with distutils on Windows
Using Our Extension Module
Interactive Cython with IPython’s %%cython Magic
Compiling On-the-Fly with pyximport
Controlling pyximport and Managing Dependencies
pyximport Example with External Dependencies
Rolling Our Own and Compiling by Hand
Using Cython with Other Build Systems
CMake and Cython
SCons and Cython
Make and Cython
Compiler Directives
Summary
Chapter 3. Cython in Depth
Interpreted Versus Compiled Execution
Dynamic Versus Static Typing
Static Type Declaration with cdef
Automatic Type Inference in Cython
C Pointers in Cython
Mixing Statically and Dynamically Typed Variables
Statically Declaring Variables with a Python Type
Static Typing for Speed
Reference Counting and Static String Types
Cython’s Three Kinds of Functions
Python Functions in Cython with the def Keyword
C Functions in Cython with the cdef Keyword
Combining def and cdef Functions with cpdef
Functions and Exception Handling
Functions and the embedsignature Compiler Directive
Type Coercion and Casting
Declaring and Using structs, unions, and enums
Type Aliasing with ctypedef
Cython for Loops and while Loops
Guidelines for Efficient Loops
Loop Example
The Cython Preprocessor
Bridging the Python 2 and Python 3 Divide
str, unicode, bytes, and All That
Summary
Chapter 4. Cython in Practice: N-Body Simulation
Overview of the N-Body Python Code
Converting to Cython
Python Data Structures and Organization
Converting Data Structures to structs
Running the Cythonized Version
Summary
Chapter 5. Cython and Extension Types
Comparing Python Classes and Extension Types
Extension Types in Cython
Type Attributes and Access Control
C-Level Initialization and Finalization
cdef and cpdef Methods
Inheritance and Subclassing
Casting and Subclasses
Extension Type Objects and None
Extension Type Properties in Cython
Special Methods Are Even More Special
Arithmetic Methods
Rich Comparisons
Iterator Support
Summary
Chapter 6. Organizing Cython Code
Cython Implementation (.pyx) and Declaration (.pxd) Files
The cimport Statement
Predefined Definition Files
Include Files and the include Statement
Organizing and Compiling Cython Modules Inside Python Packages
Summary
Chapter 7. Wrapping C Libraries with Cython
Declaring External C Code in Cython
Cython Does Not Automate Wrapping
Declaring External C Functions and typedefs
Declaring and Wrapping C structs, unions, and enums
Wrapping C Functions
Wrapping C structs with Extension Types
Constants, Other Modifiers, and Controlling What Cython Generates
Error Checking and Raising Exceptions
Callbacks
Callbacks and Exception Propagation
Summary
Chapter 8. Wrapping C++ Libraries with Cython
Simple Example: MT_RNG Class
The Wrapper Extension Type
Compiling with C++
Using Our Wrapper from Python
Overloaded Methods and Functions
Operator Overloading
C++ Exceptions
Stack and Heap Allocation of C++ Instances
Working with C++ Class Hierarchies
C++ Templates
Templated Functions and Cython’s Fused Types
Templated Classes
Iterators and Nested Classes
Included STL Container Class Declarations
Memory Management and Smart Pointers
Summary
Chapter 9. Cython Profiling Tools
Cython Runtime Profiling
Performance Profiling and Annotations
Summary
Chapter 10. Cython, NumPy, and Typed Memoryviews
The Power of the New Buffer Protocol
The memoryview Type
Typed Memoryviews
Typed Memoryview Example
C-Level Access to Typed Memoryview Data
Trading Safety for Performance
Declaring Typed Memoryviews
Using Typed Memoryviews
Beyond Buffers
Wrapping C and C++ Arrays
Correct (and Automatic) Memory Management with Cython and C Arrays
Summary
Chapter 11. Cython in Practice: Spectral Norm
Overview of the Spectral Norm Python Code
Performance Profiling
Cythonizing Our Code
Adding Static Type Information
Using Typed Memoryviews
Comparing to the C Implementation
Summary
Chapter 12. Parallel Programming with Cython
Thread-Based Parallelism and the Global Interpreter Lock
The nogil Function Attribute
The with nogil Context Manager
Using prange to Parallelize Loops
Using prange
prange Options
Using prange for Reductions
Parallel Programming Pointers and Pitfalls
Summary
Chapter 13. Cython in Context
Cython Versus Project X
Other Ahead-of-Time Compilers for Python
Python Wrapper Projects
Just-in-Time Compilers for Python
Summary
Index
About the Author