Python C Extension Patterns.
Project description
If you need to write C extension for Python then this is the place for you.
The full documentation is on Read the Docs.
Code examples and documentation source are on GitHub. The example and test code is available on PyPi.
Subjects Covered
Introduction
A Simple Example
PyObjects and Reference Counting
Containers and Reference Counts
Struct Sequence Objects (a namedtuple in C)
Exception Raising
A Pythonic Coding Pattern for C Functions
Parsing Python Arguments
Creating New Types
Setting and Getting Module Globals
Logging and Frames
File Paths and Files
Subclassing and Using super()
Capsules
Iterators and Generators
Context Managers
Pickling C Extension Types
Watchers [Python 3.12+]
Setting Compiler Flags
Debugging
Memory Leaks
Thread Safety
Source Code Layout
Using C++ With CPython Code
Miscellaneous
Installation
Further Reading
TODO
History
Index
Project Links
Source is on GitHub.
Documentation on Read the Docs.
Project is on PyPi.
Videos
I have presented some of this, well mostly the chapter “PyObjects and Reference Counting”, at Python conferences so if you prefer videos they are here:
Installation
This is primarily a documentation project hosted on Read the Docs. However all the example code is buildable and testable so if you want to examine that then here is how to get the project.
From PyPi
pip install cPyExtPatt
From Source
Choose a directory of your choice, in this case: ~/dev/tmp.
mkdir -p ~/dev/tmp
cd ~/dev/tmp
git clone https://github.com/paulross/PythonExtensionPatterns.git
cd PythonExtensionPatterns
Virtual Environment
Create a Python environment in the directory of your choice, in this case: ~/dev/tmp/PythonExtensionPatterns/venv_3.11 and activate it:
python3.11 -m venv venv_3.11
source venv_3.11/bin/activate
Install the Dependencies
pip install -r requirements.txt
Running the Tests
You now should be able to run the following commands successfully in ~/dev/tmp/PythonExtensionPatterns with your environment activated:
pytest tests/
Building the Documentation
This will build the html and PDF documentation (requires a latex installation):
cd doc/sphinx
make html latexpdf
History
0.3.0 (2025-03-20)
Added Chapters
“Containers and Reference Counts” which corrects the Python documentation where that is wrong, misleading or missing.
“Struct Sequences (namedtuple in C)” which corrects the Python documentation where that is wrong, misleading or missing.
“Context Managers” with practical C code examples.
“Watchers” with practical examples for dictionary watchers (Python 3.12+).
“Installation” for the project.
“Source Code Layout” for the project.
Changed Chapters
Update the “Homogeneous Python Containers and C++” chapter.
Expand the “Memory Leaks” chapter.
Extended the “Logging” chapter to show how to access the CPython Frame from C.
Add “Emulating Sequence Types” to the “Creating New Types” chapter.
Expand the Index.
Other
Python versions supported: 3.9, 3.10, 3.11, 3.12, 3.13.
Development Status :: 5 - Production/Stable
The documentation content, example and test code has roughly doubled since version 0.2.2.
PDF Documentation is 339 pages.
TODO
Add “Debugging Python with CLion”.
0.2.2 (2024-10-21)
Expand note on PyDict_SetItem(), PySet_Add() with code in src/cpy/RefCount/cRefCount.c and tests.
0.2.1 (2024-07-29)
Python versions supported: 3.9, 3.10, 3.11, 3.12, 3.13 (possibly backwards compatible with Python 3.6, 3.7, 3.8)
Almost all example code is built and tested against these Python versions.
Added a chapter on managing file paths and files between Python and C.
Added a chapter on subclassing from your classes or builtin classes.
Added a chapter on pickling from C.
Added a chapter on Capsules.
Added a chapter on Iterators and Generators.
Added a chapter on memory leaks and how to detect them.
Added a chapter on thread safety.
Update “Homogeneous Python Containers and C++” to refer to https://github.com/paulross/PyCppContainers
All the documentation has been extensively reviewed and corrected where necessary.
Development Status :: 5 - Production/Stable
Contributors
Many thanks!
Pull Requests
Issues
0.1.0 (2014-09-09)
First release.
Originally “Examples of reliable coding of Python ‘C’ extensions by Paul Ross.”.
Development Status :: 3 - Alpha
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
File details
Details for the file cpyextpatt-0.3.0.tar.gz
.
File metadata
- Download URL: cpyextpatt-0.3.0.tar.gz
- Upload date:
- Size: 682.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
2d1927b904898f5af25e67f5a3014048dbe0183225e49de44242e0a9ef5c896d
|
|
MD5 |
145f3c6280326967868c6a21a80f9ae5
|
|
BLAKE2b-256 |
98cf7a5d3d249c2aed795836f2ee07c72e19d8420a643f2bc680139dd25d4d91
|
File details
Details for the file cpyextpatt-0.3.0-cp313-cp313-macosx_10_13_universal2.whl
.
File metadata
- Download URL: cpyextpatt-0.3.0-cp313-cp313-macosx_10_13_universal2.whl
- Upload date:
- Size: 345.0 kB
- Tags: CPython 3.13, macOS 10.13+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
afd4dfe24bf42ff079512e1f5ea0351504c5c7d35ec1f1802382214a070dd1b8
|
|
MD5 |
545d55c48f7046996cec1ff87f4d8565
|
|
BLAKE2b-256 |
171d91584c2d67da4c6d19b24671e94245567386375ffff8da350d5887e77230
|
File details
Details for the file cpyextpatt-0.3.0-cp312-cp312-macosx_10_13_universal2.whl
.
File metadata
- Download URL: cpyextpatt-0.3.0-cp312-cp312-macosx_10_13_universal2.whl
- Upload date:
- Size: 339.1 kB
- Tags: CPython 3.12, macOS 10.13+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
ce6454a7e5b7a3e4fd7360088d0eba1651426ccd4e6460e0ae51aae697b873e6
|
|
MD5 |
9569b41dc76bc854674b45a8420999f5
|
|
BLAKE2b-256 |
d443f5b618d0795379bc04e0bf7ce235fe9cf3edd96bad5270379945fb9257ab
|
File details
Details for the file cpyextpatt-0.3.0-cp311-cp311-macosx_10_9_universal2.whl
.
File metadata
- Download URL: cpyextpatt-0.3.0-cp311-cp311-macosx_10_9_universal2.whl
- Upload date:
- Size: 321.3 kB
- Tags: CPython 3.11, macOS 10.9+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
1a4d2da68432fe2bfd7edbba3751308fe83ffe88c5a0e84cae95f3b4412cfb6d
|
|
MD5 |
7a768f68a363bdf9858e1ded7ff6cdbc
|
|
BLAKE2b-256 |
d7cae0f7a312699ffebcb9cb6f018cd2fd14dee765610a5cc7a61ca926d704ff
|
File details
Details for the file cpyextpatt-0.3.0-cp310-cp310-macosx_10_9_universal2.whl
.
File metadata
- Download URL: cpyextpatt-0.3.0-cp310-cp310-macosx_10_9_universal2.whl
- Upload date:
- Size: 316.2 kB
- Tags: CPython 3.10, macOS 10.9+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
d433d37a73c37d6cde113fd68c688e6f612953626da3697f6ccfcd47125ab10f
|
|
MD5 |
9b1736618c6142085ac3eca3b37e9caa
|
|
BLAKE2b-256 |
e6fd7cf2717e0a0dcd0cd717ef59f0e76f74ab7b54e80e63a830a6087500b34a
|
File details
Details for the file cpyextpatt-0.3.0-cp39-cp39-macosx_10_9_universal2.whl
.
File metadata
- Download URL: cpyextpatt-0.3.0-cp39-cp39-macosx_10_9_universal2.whl
- Upload date:
- Size: 313.7 kB
- Tags: CPython 3.9, macOS 10.9+ universal2 (ARM64, x86-64)
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
7eeae2932b61ff3e45364efe7f747e7ec17ca89307eba20fc3bc20ff2a058f7e
|
|
MD5 |
7777069532e4107d2b8499423727b6a0
|
|
BLAKE2b-256 |
08ea28fb15f0eca22e5931e0bb6d44c6861ebf1c313b91fbb65aca6c31ac1742
|