python-cxx 0.1.0b20

C++ DSP Extensions for Python.

python-cxx

C/C++ DSP Extensions for Python.

Building the foundation for a fast, reliable, easy-to-use signal processing toolset.

This package is about real-world utility, learning, and most of all fun!

Installation & Usage

pip install python-cxx

Once the package has been installed you can run the example with

python-cxx-example

If successful, you should see something like this

---------------------------------------------------------
Hello from python_cxx!!!
A C++ compiled extension that can operate in Python.
For example, given a list [1, 2, 3]...one can use:
---------------------------------------------------------
* Typecasting to e.g. square: python_cxx.IntVector([1, 4, 9])
* Binding to e.g. double: python_cxx.IntVector([2, 4, 6])
* Or wrap an operation like decrement: [0, 1, 2]!
Executing a C++ class method on [1. 1. 1. 1. 1.] gives:
Exponential average: [0.9     0.99    0.999   0.9999  0.99999]

Benchmark Results
-----------------
* Ran 100 trials 5 times.
* Time of one independent trial: 2.92 msec
* Best time of subsequent trials: 2.7 msec
* Worst time of subsequent trials: 2.92 msec
* Best speed: 152 Mitems / sec
* Worst speed: 140 Mitems / sec

Experiment with the example script (python-cxx/example.py), use with the interpreter, or get the source and add your own features!

>>> import numpy as np
>>> from python_cxx import decrement_it
>>> x = [1, 2, 3]
>>> decrement_it(x)
[0, 1, 2]

Source Installation & Development

Install

Get uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Get the code and go to the project directory

git clone https://github.com/hunterdsp/python-cxx.git && cd python-cxx

Synchronize dependencies and install

uv sync

Develop

• Edit the code
• Add testing
• Commit!
• Synchronize: uv sync
• Run scripts e.g.: uv run --no-editable python-cxx-example
• Ensure ALL tests pass: uvx pytest
• Repeat until you make it here with no failures
• Submit a pull-request

... more coming soon ... Have Fun!!!

Debugging

Create a debug environment and install ALL dependencies adding meson-python

uv venv .venv.debug --clear
. .venv.debug/bin/activate
uv pip install . meson-python

Build the extension with debug symbols

uv pip install --editable . --no-build-isolation \
    -Csetup-args=-Dbuildtype=debug \
    -Cbuild-dir=build-dbg

Attach to the example with gdb and set a breakpoint on the step method

gdb --args python3.12 -c "from python_cxx_example import main; main()"
break step
run

You should see the debugger stop on the first call to step() like so

[New Thread 0x7fffcddf26c0 (LWP 612534)]
[New Thread 0x7fffcd5f16c0 (LWP 612539)]
Downloading separate debug info for ...

---------------------------------------------------------
Hello from python_cxx!!!
A C++ compiled extension that can operate in Python.
For example, given a list [1, 2, 3]...one can use:
---------------------------------------------------------
* Typecasting to e.g. square: python_cxx.IntVector([1, 4, 9])
* Binding to e.g. double: python_cxx.IntVector([2, 4, 6])
* Or wrap an operation like decrement: [0, 1, 2]!
Executing a C++ class method on [1. 1. 1. 1. 1.] gives:

Thread 1 "python3.12" hit Breakpoint 1.1, ExpAverage::step (this=0x7ffff49cd708, x=...) at ../src/array.cpp:18
18           void step(nanobind::ndarray<nanobind::c_contig, nanobind::device::cpu> x) {
(gdb)