Skip to main content

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

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cpyextpatt-0.3.0.tar.gz (682.4 kB view details)

Uploaded Source

Built Distributions

cpyextpatt-0.3.0-cp313-cp313-macosx_10_13_universal2.whl (345.0 kB view details)

Uploaded CPython 3.13macOS 10.13+ universal2 (ARM64, x86-64)

cpyextpatt-0.3.0-cp312-cp312-macosx_10_13_universal2.whl (339.1 kB view details)

Uploaded CPython 3.12macOS 10.13+ universal2 (ARM64, x86-64)

cpyextpatt-0.3.0-cp311-cp311-macosx_10_9_universal2.whl (321.3 kB view details)

Uploaded CPython 3.11macOS 10.9+ universal2 (ARM64, x86-64)

cpyextpatt-0.3.0-cp310-cp310-macosx_10_9_universal2.whl (316.2 kB view details)

Uploaded CPython 3.10macOS 10.9+ universal2 (ARM64, x86-64)

cpyextpatt-0.3.0-cp39-cp39-macosx_10_9_universal2.whl (313.7 kB view details)

Uploaded CPython 3.9macOS 10.9+ universal2 (ARM64, x86-64)

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

Hashes for cpyextpatt-0.3.0.tar.gz
Algorithm Hash digest
SHA256 2d1927b904898f5af25e67f5a3014048dbe0183225e49de44242e0a9ef5c896d
MD5 145f3c6280326967868c6a21a80f9ae5
BLAKE2b-256 98cf7a5d3d249c2aed795836f2ee07c72e19d8420a643f2bc680139dd25d4d91

See more details on using hashes here.

File details

Details for the file cpyextpatt-0.3.0-cp313-cp313-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for cpyextpatt-0.3.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 afd4dfe24bf42ff079512e1f5ea0351504c5c7d35ec1f1802382214a070dd1b8
MD5 545d55c48f7046996cec1ff87f4d8565
BLAKE2b-256 171d91584c2d67da4c6d19b24671e94245567386375ffff8da350d5887e77230

See more details on using hashes here.

File details

Details for the file cpyextpatt-0.3.0-cp312-cp312-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for cpyextpatt-0.3.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 ce6454a7e5b7a3e4fd7360088d0eba1651426ccd4e6460e0ae51aae697b873e6
MD5 9569b41dc76bc854674b45a8420999f5
BLAKE2b-256 d443f5b618d0795379bc04e0bf7ce235fe9cf3edd96bad5270379945fb9257ab

See more details on using hashes here.

File details

Details for the file cpyextpatt-0.3.0-cp311-cp311-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for cpyextpatt-0.3.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 1a4d2da68432fe2bfd7edbba3751308fe83ffe88c5a0e84cae95f3b4412cfb6d
MD5 7a768f68a363bdf9858e1ded7ff6cdbc
BLAKE2b-256 d7cae0f7a312699ffebcb9cb6f018cd2fd14dee765610a5cc7a61ca926d704ff

See more details on using hashes here.

File details

Details for the file cpyextpatt-0.3.0-cp310-cp310-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for cpyextpatt-0.3.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 d433d37a73c37d6cde113fd68c688e6f612953626da3697f6ccfcd47125ab10f
MD5 9b1736618c6142085ac3eca3b37e9caa
BLAKE2b-256 e6fd7cf2717e0a0dcd0cd717ef59f0e76f74ab7b54e80e63a830a6087500b34a

See more details on using hashes here.

File details

Details for the file cpyextpatt-0.3.0-cp39-cp39-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for cpyextpatt-0.3.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 7eeae2932b61ff3e45364efe7f747e7ec17ca89307eba20fc3bc20ff2a058f7e
MD5 7777069532e4107d2b8499423727b6a0
BLAKE2b-256 08ea28fb15f0eca22e5931e0bb6d44c6861ebf1c313b91fbb65aca6c31ac1742

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page