Python C/C++ API Professional Template

A professional template for creating high-performance Python extension modules using the native Python C API (<Python.h>). This template avoids heavy dependencies like SWIG or pybind11, giving you full control over the binding process.

Features

• Native Binding: Pure <Python.h> usage for maximum performance and minimum overhead.
• Modern C++: Support for C++20 features in your extension logic.
• Robust Makefile: Automated virtual environment management, compilation, and testing.
• Complex Examples Included:
  • Keyword argument handling (PyArg_ParseTupleAndKeywords).
  • Python sequence processing (List to std::vector).
  • Dictionary creation and mapping.
  • Custom Exception handling.
• Standardized Structure: Clear separation between C++ source, headers, and Python tests.

Directory Structure

• cppmodule/: The C++ extension source code.
  • src/: Implementation files (.cpp).
  • include/: Header files (.h).
• lib/: Third-party C/C++ libraries (gitkept).
• tests/: Python unit tests using pytest.
• main.py: Entry point for quick demonstration and manual testing.
• Makefile: The heart of the build system.

Getting Started

1. Prerequisites

Ensure you have Python development headers installed (e.g., python3-dev or python3.x-dev). The Makefile is configured to detect these automatically.

2. Configure Virtual Environment

The Makefile handles virtual environment creation and dependency installation:

make venv

3. Compile the Extension

Build the shared object (.so) directly:

make compile

4. Run Demonstration

Compile and execute main.py:

make run

5. Run Unit Tests

make tests

Environment Variables & Customization

To change the module name, update the MODULE_NAME variable in the Makefile and rename the cppmodule/ directory and its references in setup.py and tests/.

API Examples

Keyword Arguments

import cppmodule
cppmodule.hello(name="Panda", repeat=3)

List Processing & Dictionaries

import cppmodule
stats = cppmodule.stats([1.0, 2.0, 3.0])
print(stats['mean']) # 2.0

Author

nguyenpanda
Email: [email protected]
Website: https://nguyenpanda.com

License

MIT License