Skip to main content

pycpp-tools

A command-line utility to initialize basic CMake C++ / pybind11 / Godot GDExtension projects, and to manage Python projects with mamba (pymamba).

Features

  • Initialize a CMake C++ project (CMake 3.30, C++23, Ninja, Conan)
  • Initialize a pure C project (--pure-c)
  • Initialize a pybind11 project (--pybind11)
  • Initialize a Godot GDExtension project (--godot)
  • Generate VS Code tasks.json / launch.json (CodeLLDB + clangd workflow)
  • Manage Python app/lib projects with mamba (pymamba: init / add / remove / sync)

Installation

pip install .
# or editable mode
pip install -e .

After installation, the pycpp, pymamba, and lpip commands are available.

Build workflow (CMake / pure-c / pybind11)

These project types use Conan 2 for C++ dependencies and CMake presets for configure.

Typical flow (VS Code tasks or equivalent CLI):

  1. conan — install Debug and Release dependencies
  2. config-debug or config-release — configure with the matching preset (run conan yourself first if needed)
  3. build — cmake --build build
  4. run — depends on build
# after editing conanfile.py requirements, refresh deps:
# VS Code task: conan

cmake --preset conan-debug    # or: conan-release
cmake --build build

Add C++ packages in conanfile.py (requirements()). For pybind11 projects, pybind11 itself still comes from the current Python environment ([tool.pycpp].pybind11_dir in pyproject.toml); Conan is for other C++ deps.

Usage

CMake C++ Project

pycpp init --name myproject

Creates a minimal C++23 app with Conan + VS Code tasks (conan, config-debug, config-release, build, run).

Pure C Project

pycpp init --name myproject --pure-c

Same Conan / tasks workflow as the CMake C++ template.

Godot GDExtension Project

Run in an empty extension source directory (init writes into the current working directory):

pycpp init --name demo --godot

Defaults (override via CLI or cmake -D):

  • GODOT_CPP_DIR: E:/work_data/third_libs/godot-cpp-10.0.0-rc1
  • GODOTCPP_API_VERSION: 4.6
pycpp init --name demo --godot \
  --godot-cpp-dir "E:/work_data/third_libs/godot-cpp-10.0.0-rc1" \
  --godot-api-version "4.6"

Build with the VS Code cmake: configure & build (debug) or (release) tasks. Output goes under bin/.

Godot projects do not use the Conan workflow above.

Attach to an existing Godot project (--attach)

pycpp init --name gdes_demo --godot --attach "../my-godot-project"

--attach accepts a relative path (from the extension directory). This also writes a .code-workspace and .gdextension into the Godot project, and points build output at that project's bin/.

If .gdextension already exists, you are asked whether to overwrite (default no).

Example outputs:

  • debug: <project>/bin/libgdes_demo.windows.template_debug.x86_64.dll
  • release: <project>/bin/libgdes_demo.windows.template_release.x86_64.dll

Open <project>/gdes_demo.code-workspace in VS Code to edit the Godot project and extension together.

Pybind11 Project

pycpp init --name demo --pybind11

Naming:

  • --name: C++ extension module name (default: demo)
  • Python package: py + name (e.g. pydemo → src/pydemo/)
  • Import: from pydemo import demo

Useful files after init:

  • cpp-src/ — C++ sources
  • src/<package>/ — Python package (extension binary is built here)
  • pyproject.toml — package metadata and [tool.pycpp] paths
  • scripts/cmake-config.py — debug / release configure helpers
  • scripts/clear.py / scripts/package.py — clean and package
  • VS Code tasks: conan, config-debug, config-release, build, run, clear, package

[tool.pycpp] (set at init from the current environment):

[tool.pycpp]
python_dir = "..."
pybind11_dir = "..."
python_version = "3.13"
cxx_standard = 23

After changing toml, re-run config-debug / config-release (or package).

Develop and debug

# VS Code: conan → config-debug (or config-release) → build → run
python scripts/cmake-config.py debug
cmake --build build
pip install -e .
python test.py

Use pip install -e . so imports and IDE hints work without sys.path hacks.

Package

python scripts/package.py
# or VS Code task: package

This clears, refreshes Conan deps, configures release, builds, then runs python -m build with the interpreter from [tool.pycpp].python_dir (so wheel tags match). Requires the build package in that environment.

CLI options

  • --name <name>: project / module name
  • --pybind11: pybind11 project
  • --pure-c: pure C project
  • --godot: Godot GDExtension project
  • --godot-cpp-dir: path to godot-cpp (with --godot)
  • --godot-api-version: target Godot API version (with --godot)
  • --attach <dir>: link to an existing Godot project (with --godot)
  • --inplace-vscode: overwrite existing .vscode tasks/launch files

pymamba

pymamba manages a Python project’s pyproject.toml and a matching mamba environment. It calls mamba only (no conda fallback).

Existing files are not overwritten on init (skipped with a message). After sync, activate the env yourself in the current shell (mamba activate <venv>).

Typical workflow

mkdir myapp && cd myapp
pymamba init --name myapp
pymamba sync
mamba activate myapp
pymamba add requests
# edit / run src/main.py

init

Create project files in the current directory:

# application (default)
pymamba init --name myapp

# library layout
pymamba init --name mylib --lib

# optional: Python version and mamba env name
pymamba init -n myapp --python 3.13 --venv myapp-env
Option Default Meaning
--name / -n demo Project name (and default mamba env name)
--lib off Library layout under src/<name>/
--python current interpreter major.minor Stored as requires-python / env Python version
--venv same as --name Mamba env name in [tool.pymamba]

App layout

  • pyproject.toml
  • .gitignore
  • src/main.py

Lib layout (--lib)

  • pyproject.toml (includes [tool.setuptools.packages.find])
  • .gitignore
  • src/<name>/__init__.py
  • tests/test.py

[tool.pymamba] example:

[tool.pymamba]
venv = "myapp"
python_version = "3.13"
venv_ready = false

venv_ready is set to true after a successful sync / add (env created or reused).

sync

Create or reuse the mamba env from [tool.pymamba], then pip install everything in [project].dependencies:

pymamba sync
pymamba sync -i https://pypi.tuna.tsinghua.edu.cn/simple
pymamba sync --lpip   # install via lpip (download on cache miss)

If the env already exists (or venv_ready is true), you are prompted: [r]euse or [c]reate (rebuild). Rebuild removes the env and creates it again.

add

Resolve package versions, pin them in pyproject.toml (name==version), ensure the env exists, then install:

pymamba add requests
pymamba add "rich==13.9.4" httpx
pymamba add torch --lpip -i https://download.pytorch.org/whl/cpu
  • Without ==, the latest version is looked up on PyPI and pinned.
  • With ==, that version is checked on PyPI (unless --lpip) and pinned.
  • --lpip: install via lpip first, then pin whatever pip show reports (skips PyPI lookup).
  • -i / --index-url: passed through to pip / lpip download.

remove

Remove a package from [project].dependencies, uninstall it from the env, and clean orphan dependencies that are no longer required by remaining deps:

pymamba remove requests

If the env does not exist and is not marked ready, only pyproject.toml is updated.

CLI summary

Command Purpose
pymamba init Scaffold app or lib project + [tool.pymamba]
pymamba sync Create/update mamba env and install deps
pymamba add … Pin + install dependencies
pymamba remove <pkg> Unpin + uninstall (with orphan cleanup)

Requirements

  • Python 3.13+ (for this tool)
  • Conan 2 (for cmake / pure-c / pybind11 projects)
  • CMake 3.30+ (3.23+ recommended for presets)
  • C++23-capable compiler (default: clang-cl)
  • Ninja
  • mamba (for pymamba)
  • VS Code extensions:

License

MIT License

Author

R.E. (redelephant@foxmail.com)

Metadata

Release files for pycpp-tools 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycpp-tools 0.8.0
File Size Uploaded Provenance Actions
pycpp_tools-0.8.0.tar.gz 26.0 kB Without provenance Details for pycpp_tools-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pycpp-tools 0.8.0
File Interpreter ABI Platform Actions
pycpp_tools-0.8.0-py3-none-any.whl Python 3 none any Details for pycpp_tools-0.8.0-py3-none-any.whl

Total release size: 54.0 kB

Release files / pycpp_tools-0.8.0.tar.gz

Download URL pycpp_tools-0.8.0.tar.gz
Size 26.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e40d235edf1affe2327dfcc75ebff96e46c4acec78a251e80b284a76616a2791
BLAKE2b-256 checksum
How to use checksums
592be1a0c1397a9775d05da951a33e81dfc32831db4cd74c43f27779cd8530e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / pycpp_tools-0.8.0-py3-none-any.whl

Download URL pycpp_tools-0.8.0-py3-none-any.whl
Size 28.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79068104e6bcce127edd7e22d0dc52b97b19c434cd0d9b9781d4012fcedebb6d
BLAKE2b-256 checksum
How to use checksums
4e91bb2efee0244011894e1522f281ddd38205cf6fa244fc4ba4fe60c7c646b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for pycpp-tools 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page