IncludeCPP 2.4.0

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).

Example:

includecpp rebuild
includecpp plugin my_module include/module.cpp

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.

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.

python -m includecpp init

plugin

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

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

Options:

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

Example:

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

rebuild

Build or rebuild C++ modules.

python -m 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:

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

install

Install community modules from GitHub.

python -m includecpp install <module_name>

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

Example:

python -m includecpp install fast_list
python -m includecpp rebuild

Features

VSCode IntelliSense Support

Automatic type hint generation for full IDE autocomplete.

Enable/Disable in cpp.proj:

{
  "CPI-IntelliSense": true
}

When enabled, .pyi stub files are generated during rebuild, providing:

• Function signatures
• Class methods and attributes
• Module-level exports
• Full VSCode autocomplete

Template Structs (v2.0+)

template<typename T>
struct Point {
    T x;
    T y;
};

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

Auto-generates:

• .to_dict() method
• .from_dict() static method
• Full type hints

Module Dependencies

DEPENDS(math_utils, geometry)

Build system handles dependency order automatically.

Multi-File Modules

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

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
}

Advanced Examples

Class with Methods

class Crypto {
public:
    std::string md5(const std::string& data);
    std::string sha256(const std::string& data);
};

crypto CLASS(Crypto) {
    METHOD(md5)
    METHOD(sha256)
}

crypto = api.include("crypto")
hash = crypto.Crypto().md5("hello")

Template Functions

template<typename T>
T maximum(T a, T b) {
    return a > b ? a : b;
}

math TEMPLATE_FUNC(maximum) TYPES(int, float, string)

math.maximum(10, 20)        # 20
math.maximum(1.5, 2.3)      # 2.3
math.maximum("a", "z")      # "z"

Python API

Selective Module Updates

from includecpp import CppApi

api = CppApi()

if api.need_update("crypto"):
    api.update("crypto")

crypto = api.include("crypto")

Auto-Update on Include

api = CppApi(auto_update=True)
crypto = api.include("crypto")

API Methods

• need_update(module_name) -> bool - Check if source is newer than build
• update(module_name) - Rebuild single module
• include(module_name, auto_update=None) - Load module with optional auto-rebuild
• list_modules() - List all available modules
• 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

Why IncludeCPP?

For developers who:

• Need C++ performance with Python productivity
• Don't want complex build configurations
• Value fast iteration and simple workflows
• Want production-ready bindings without boilerplate

Not for:

• Pure Python projects
• When CPython extensions are overkill
• Projects requiring custom build pipelines

---

License: MIT Version: 2.2.1 Status: Production Ready Repository: https://github.com/liliassg/IncludeCPP