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 conda/mamba (pyconda).

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 conda/mamba (pyconda: init / add / remove / sync)

Installation

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

After installation, the pycpp, pyconda, 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

pyconda

pyconda manages a Python project’s pyproject.toml and a matching conda/mamba environment. It prefers mamba if available, otherwise conda.

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
pyconda init --name myapp
pyconda sync
mamba activate myapp
pyconda add requests
# edit / run src/main.py

init

Create project files in the current directory:

# application (default)
pyconda init --name myapp

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

# optional: Python version and conda env name
pyconda init -n myapp --python 3.13 --venv myapp-env
Option Default Meaning
--name / -n demo Project name (and default conda 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 Conda env name in [tool.pyconda]

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.pyconda] example:

[tool.pyconda]
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 conda env from [tool.pyconda], then pip install everything in [project].dependencies:

pyconda sync
pyconda sync -i https://pypi.tuna.tsinghua.edu.cn/simple
pyconda 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:

pyconda add requests
pyconda add "rich==13.9.4" httpx
pyconda 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:

pyconda remove requests

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

CLI summary

Command Purpose
pyconda init Scaffold app or lib project + [tool.pyconda]
pyconda sync Create/update conda env and install deps
pyconda add … Pin + install dependencies
pyconda 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 or conda (for pyconda)
  • VS Code extensions:

License

MIT License

Author

R.E. (redelephant@foxmail.com)

Metadata

Release files for pycpp-tools 0.7.11

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.7.11
File Size Uploaded Provenance Actions
pycpp_tools-0.7.11.tar.gz 26.5 kB Without provenance Details for pycpp_tools-0.7.11.tar.gz

Built distribution (wheel)

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

Total release size: 54.8 kB

Release files / pycpp_tools-0.7.11.tar.gz

Download URL pycpp_tools-0.7.11.tar.gz
Size 26.5 kB
Tags Source
SHA-256 checksum
How to use checksums
bce68ce18da33f03e94cdd41aa1c7673b79d4847a15fc47798b960580b3998ce
BLAKE2b-256 checksum
How to use checksums
f65ab083fc2b445859deacb7885da93398b2256f68508fc3002a7424f9833d53
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.7.11-py3-none-any.whl

Download URL pycpp_tools-0.7.11-py3-none-any.whl
Size 28.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a00de1fdafccfc08e5d23f7ac0b251e5a305ba26627481045caa1b8fdeef6fc
BLAKE2b-256 checksum
How to use checksums
0bf7889b849c135224f4e8d4e48ec323ef192340bce8aa281015528f04106c8a
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.7.11

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