IncludeCPP 2.5.1

Professional C++ Python bindings with type-generic templates, pystubs and native threading

IncludeCPP - C++ Performance in Python, Zero Hassle

Write performance-critical code in C++, use it in Python like native modules. No boilerplate, no manual bindings, no complexity.

Installation

pip install IncludeCPP

Quick Start

1. Initialize Project

python -m includecpp init

Creates:

• cpp.proj - Configuration
• include/ - C++ source files
• plugins/ - Module definitions

First-time Setup: When you run init for the first time on your system, IncludeCPP automatically registers the global includecpp command. After that, you can use includecpp <command> instead of python -m includecpp <command> (restart your terminal for Windows).

2. Auto-Generate Plugin Definition

python -m includecpp plugin fast_list include/fast_list.cpp include/fast_list.h

Automatically generates plugins/fast_list.cp by analyzing your C++ code. Detects classes, methods, constructors (including parametrized ones), functions, and structs.

3. Build

python -m includecpp rebuild

4. Use in Python

from includecpp import CppApi

api = CppApi()
fast_list = api.include("fast_list")

my_list = fast_list.FastList()
my_list.append(42)

CLI Commands

init

Initialize new IncludeCPP project.

includecpp init

plugin

Auto-generate .cp plugin definition from C++ files.

includecpp plugin <name> <file1.cpp> [file2.h] [...]

Options:

• -p, --private <func> - Exclude function from public API

Example:

includecpp plugin math_tools include/math.cpp include/math.h -p InternalHelper

rebuild

Build or rebuild C++ modules.

includecpp rebuild [OPTIONS]

Options:

• --clean - Force clean rebuild (ignore incremental cache)
• --full - Complete rebuild including generator and all caches
• --verbose - Detailed build output
• --no-incremental - Disable incremental builds
• --parallel/--no-parallel - Enable/disable parallel compilation (default: enabled)
• -j, --jobs <N> - Max parallel jobs (default: 4)
• -m, --modules <name> - Rebuild specific modules only

Examples:

includecpp rebuild --full --verbose
includecpp rebuild -m crypto -m networking

install / minstall

Install community modules from GitHub.

includecpp install <module_name>
includecpp install --list-all

Downloads from https://github.com/liliassg/IncludeCPP/tree/main/minstall/<module_name>

update

Update IncludeCPP to latest version or manage versions.

includecpp update              # Upgrade to latest version
includecpp update --version    # Show installed version
includecpp update --all        # List all available PyPI versions
includecpp update 2.4.0        # Install specific version

reboot

Reinstall current IncludeCPP version (uninstall + install).

includecpp reboot

Useful for fixing corrupted installations.

get

Display detailed module API information.

includecpp get <module_name>

Shows classes, methods, functions, structs with type information.

bug

Report bugs to GitHub or view existing issues.

includecpp bug                 # Report a new bug
includecpp bug --get           # List open bugs from GitHub

--doc

Show documentation with color highlighting.

includecpp --doc

Fetches and displays the latest README from PyPI.

Plugin Definition Syntax (.cp files)

Classes with Constructors

module CLASS(MyClass) {
    CONSTRUCTOR()                    # Default constructor
    CONSTRUCTOR(int, double)         # Parametrized constructor
    METHOD(doSomething)
    FIELD(value)
}

Functions

module FUNCTION(calculate)

Methods with Overload Support (v2.5+)

For overloaded methods (same name, different parameters):

module CLASS(Circle) {
    CONSTRUCTOR()
    METHOD_CONST(intersects, const Circle&)
    METHOD_CONST(intersects, const Rect&)
    METHOD(setRadius, double)
}

• METHOD(name) - Simple method (no overloads)
• METHOD(name, type1, type2) - Method with parameter types for overload resolution
• METHOD_CONST(name, types...) - Const method with overload support

The plugin generator auto-detects overloads and generates the correct format.

Template Functions

module TEMPLATE_FUNC(maximum) TYPES(int, float, double)

Structs

module STRUCT(Point) TYPES(int, float) {
    FIELD(T, x)
    FIELD(T, y)
}

Dependencies

DEPENDS(math_utils, geometry)

Multi-File Modules

SOURCE(module.cpp helpers.cpp utils.cpp) my_module

Features

VSCode IntelliSense Support

Automatic .pyi stub generation for full IDE autocomplete.

Enable/Disable in cpp.proj:

{
  "CPI-IntelliSense": true
}

Provides:

• Function signatures with types
• Class methods and attributes
• Constructor overloads
• Module-level exports
• Full VSCode/PyCharm autocomplete

Parametrized Constructors (v2.4.3+)

C++ constructors with parameters are automatically bound:

class Vector2D {
public:
    Vector2D();                      // Default
    Vector2D(double x, double y);    // Parametrized
};

geometry CLASS(Vector2D) {
    CONSTRUCTOR()
    CONSTRUCTOR(double, double)
    METHOD(length)
}

v = geometry.Vector2D(3.0, 4.0)  # Works!

Incremental Builds

SHA256-based change detection. Only rebuilds modified modules.

Cross-Platform

• Windows (MSVC, MinGW, g++)
• Linux (g++, clang++)
• macOS (clang++)

Type Support

• Basic: int, float, double, bool, string
• STL: vector, map, set, array, pair
• Custom: Structs, classes, templates

Configuration

cpp.proj:

{
  "project": "MyProject",
  "version": "1.0.0",
  "include": "/include",
  "plugins": "/plugins",
  "compiler": {
    "standard": "c++17",
    "optimization": "O3",
    "flags": ["-Wall", "-pthread"]
  },
  "types": {
    "common": ["int", "float", "double", "string"]
  },
  "threading": {
    "enabled": true,
    "max_workers": 8
  },
  "CPI-IntelliSense": true
}

Python API

from includecpp import CppApi

api = CppApi(auto_update=True)
module = api.include("my_module")

# API Methods
api.need_update("module_name")  # Check if rebuild needed
api.update("module_name")       # Rebuild single module
api.list_modules()              # List available modules
api.exists("module_name")       # Check if module exists

Requirements

• Python: 3.8+
• C++ Compiler: g++, clang++, or MSVC
• CMake: 3.15+ (optional, falls back to direct compilation)
• pybind11: Installed automatically

Build System

• AppData Storage: Builds stored in %APPDATA%\IncludeCPP (Windows) or ~/.local/share/includecpp (Linux)
• Clean Projects: Source directory stays clean
• Incremental: SHA256-based change detection
• Parallel: Multi-threaded compilation
• Caching: Reuses unchanged binaries

---

License: MIT Version: 2.5.1 Repository: https://github.com/liliassg/IncludeCPP