Cython

Table of contents

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