Add C API for adapters

.github/actions/setup-rust/action.yml

@@ -0,0 +1,65 @@
+name: Setup Rust
+description: 'Ensure Rust compiler and utilities are available, and setup caching'
+
+inputs:
+  kind:
+    description: "Targets to install: 'runner' for the host only, 'full' for cross targets (e.g. wheel building), or 'wasm'"
+    default: "runner"
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Validate kind
+      shell: bash
+      env:
+        KIND: ${{ inputs.kind }}
+      run: |
+        case "$KIND" in
+          runner|full|wasm) ;;
+          *) echo "::error::invalid kind '$KIND' (expected runner, full or wasm)"; exit 1 ;;
+        esac
+
+    - name: Set up Rust
+      uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+      with:
+        toolchain: stable
+        components: clippy, rustfmt
+
+    - name: Setup Rust cache
+      uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+      with:
+        key: ${{ runner.os }}
+
+    - run: rustup target add x86_64-unknown-linux-gnu
+      shell: bash
+      if: ${{ inputs.kind == 'runner' && runner.os == 'Linux' }}
+
+    - run: |
+        rustup target add aarch64-unknown-linux-gnu
+        rustup target add x86_64-unknown-linux-gnu
+      shell: bash
+      if: ${{ inputs.kind == 'full' && runner.os == 'Linux' }}
+
+    - run: rustup target add aarch64-apple-darwin
+      shell: bash
+      if: ${{ inputs.kind == 'runner' && runner.os == 'macOS' }}
+
+    - run: |
+        rustup target add aarch64-apple-darwin
+        rustup target add x86_64-apple-darwin
+      shell: bash
+      if: ${{ inputs.kind == 'full' && runner.os == 'macOS' }}
+
+    - run: rustup target add x86_64-pc-windows-msvc
+      shell: bash
+      if: ${{ inputs.kind == 'runner' && runner.os == 'Windows' }}
+
+    - run: |
+        rustup target add x86_64-pc-windows-msvc
+        rustup target add aarch64-pc-windows-msvc
+      shell: bash
+      if: ${{ inputs.kind == 'full' && runner.os == 'Windows' }}
+
+    - run: rustup target add wasm32-unknown-unknown
+      shell: bash
+      if: ${{ inputs.kind == 'wasm' }}

.github/workflows/build.yml

@@ -212,29 +212,40 @@ jobs:
             # Things to exclude if not a full matrix run #
             ##############################################
             - is-full-run: false
-              os: windows-2022
+              os: ubuntu-24.04
               cibuildwheel: "cp310"
 
+            - is-full-run: false
+              os: ubuntu-24.04
+              cibuildwheel: "cp312"
+
+            - is-full-run: false
+              os: ubuntu-24.04
+              cibuildwheel: "cp313"
+
             - is-full-run: false
               os: windows-2022
-              cibuildwheel: "cp311"
+              cibuildwheel: "cp310"
 
             - is-full-run: false
               os: windows-2022
               cibuildwheel: "cp312"
 
-            # avoid unnecessary use of mac resources
+            - is-full-run: false
+              os: windows-2022
+              cibuildwheel: "cp313"
+
             - is-full-run: false
               os: macos-14
               cibuildwheel: "cp310"
 
             - is-full-run: false
               os: macos-14
-              cibuildwheel: "cp311"
+              cibuildwheel: "cp312"
 
             - is-full-run: false
               os: macos-14
-              cibuildwheel: "cp312"
+              cibuildwheel: "cp313"
 
       runs-on: ${{ matrix.os }}
 
@@ -427,31 +438,43 @@ jobs:
             # Things to exclude if not a full matrix run #
             ##############################################
 
+            # Avoid extra resources for linux build
+            - is-full-run: false
+              os: ubuntu-24.04
+              python-version: "3.10"
+
+            - is-full-run: false
+              os: ubuntu-24.04
+              python-version: "3.12"
+
+            - is-full-run: false
+              os: ubuntu-24.04
+              python-version: "3.13"
+
             # Avoid extra resources for windows build
             - is-full-run: false
               os: windows-2022
               python-version: "3.10"
 
             - is-full-run: false
               os: windows-2022
-              python-version: "3.11"
+              python-version: "3.12"
 
             - is-full-run: false
               os: windows-2022
-              python-version: "3.12"
+              python-version: "3.13"
 
-            # avoid unnecessary use of mac resources
             - is-full-run: false
               os: macos-14
               python-version: "3.10"
 
             - is-full-run: false
               os: macos-14
-              python-version: "3.11"
+              python-version: "3.12"
 
             - is-full-run: false
               os: macos-14
-              python-version: "3.12"
+              python-version: "3.13"
 
       runs-on: ${{ matrix.os }}
 
@@ -524,6 +547,127 @@ jobs:
         - name: Python Test Steps
           run: make test
 
+    ####################################################################################################################
+    #..................................................................................................................#
+    #..|########|..|########|..../####\....|########|.............../####\...|########\..|########\....................#
+    #..|########|..|##|......../##/..\##\..|########|............./##/.\##\..|##|../##/..|##|../##/....................#
+    #.....|##|.....|##|.........\##\..........|##|...............|##|........|##|./##/...|##|./##/.....................#
+    #.....|##|.....|########|.....\##\........|##|...............|##|........|##||##/....|##||##/......................#
+    #.....|##|.....|##|.............\##\......|##|...............|##|........|##|........|##|..........................#
+    #.....|##|.....|##|........\##\../##/.....|##|................\##\./##/..|##|........|##|..........................#
+    #.....|##|.....|########|...\####/........|##|.................\####/....|##|........|##|..........................#
+    #..................................................................................................................#
+    #...|########|...\##\..../##/...../#####\......./|\........./|\....|########\..|##|........|########|..../####\....#
+    #...|##|..........\##\../##/...../##/.\##\...../#|#\......./#|#\...|##|../##/..|##|........|##|......../##/..\##\..#
+    #...|##|...........\##\/##/...../##/...\##\...|##|\#\...../#/|##|..|##|./##/...|##|........|##|.........\##\.......#
+    #...|########|......|####|...../###########\..|##|.\#\.../#/.|##|..|##||##/....|##|........|########|.....\##\.....#
+    #...|##|.........../##/\##\....|##|.....|##|..|##|..\#\./#/..|##|..|##|........|##|........|##|.............\##\...#
+    #...|##|........../##/..\##\...|##|.....|##|..|##|...\#|#/...|##|..|##|........|########|..|##|........\##\./##/...#
+    #...|########|.../##/....\##\..|##|.....|##|..|##|....\|/....|##|..|##|........|########|..|########|...\####/.....#
+    #.........................................................................................................#
+    ##############################################################
+    # Build / test C++ examples (05_cpp)                         #
+    ##############################################################
+    test_cpp_examples:
+      needs:
+        - initialize
+        - build
+
+      strategy:
+        matrix:
+          os:
+            - ubuntu-24.04
+            - macos-14
+            - windows-2022
+          example:
+            - 1_cpp_node
+            - 2_cpp_node_with_struct
+            - 3_cpp_adapter
+            - 4_c_api_adapter
+            - 5_c_api_adapter_rust
+          python-version:
+            - 3.11
+          exclude:
+            # The Rust example resolves CSP symbols with dlsym, which has no Windows equivalent
+            - os: windows-2022
+              example: 5_c_api_adapter_rust
+
+      runs-on: ${{ matrix.os }}
+
+      steps:
+        - name: Checkout
+          uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+          with:
+              submodules: recursive
+
+        - name: Set up Python ${{ matrix.python-version }}
+          uses: ./.github/actions/setup-python
+          with:
+            version: '${{ matrix.python-version }}'
+            cibuildwheel: false
+
+        - name: Set up Caches
+          uses: ./.github/actions/setup-caches
+
+        - name: Install python dependencies
+          run: make requirements
+
+        - name: Download wheel
+          uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+          with:
+            name: csp-dist-${{ runner.os }}-${{ runner.arch }}-${{ matrix.python-version }}
+
+        ########
+        # Linux
+        - name: Install wheel (Linux)
+          run: |
+            python -m pip install -U *manylinux*.whl
+          if: ${{ runner.os == 'Linux' }}
+
+        - name: Install build tools (Linux)
+          run: sudo apt-get install -y cmake build-essential
+          if: ${{ runner.os == 'Linux' }}
+
+        ########
+        # MacOS
+        - name: Install wheel (OSX arm)
+          run: |
+            python -m pip install -U *arm64*.whl
+          if: ${{ runner.os == 'macOS' && runner.arch == 'ARM64' }}
+
+        - name: Install wheel (OSX x86)
+          run: |
+            python -m pip install -U *x86*.whl
+          if: ${{ runner.os == 'macOS' && runner.arch == 'X64' }}
+
+        ##########
+        # Windows
+        - name: Install wheel (Windows)
+          shell: bash
+          run: |
+            python -m pip install -U *win_amd64*.whl
+          if: ${{ runner.os == 'Windows' }}
+
+        ##########
+        # Steps for Rust depend C API Rust Example (5_c_api_adapter_rust)
+        - name: Setup Rust
+          uses: ./.github/actions/setup-rust
+          if: ${{ matrix.example == '5_c_api_adapter_rust' }}
+
+        - name: Build example ${{ matrix.example }} and run tests
+          shell: bash
+          run: |
+            cd examples/05_cpp/${{ matrix.example }}
+            hatch-build --hooks-only -t wheel
+            python -m pytest -vvv .
+
+        # Guards against declarations that were never implemented, and against symbols that fail
+        # to export on a given platform (notably the Windows dllexport path).
+        - name: Check C API surface
+          shell: bash
+          run: python ci/scripts/check_c_api.py all
+          if: ${{ matrix.example == '4_c_api_adapter' }}
+
     ################################################################
     #..............................................................#
     #..|########|..|########|..../####\....|########|..............#
@@ -633,15 +777,11 @@ jobs:
           os:
             - ubuntu-24.04
           python-version:
-            - "3.10"
+            - "3.11"
           package:
             - sqlalchemy<2
             - perspective-python<3
-            # - pandas<3
-            # uncomment the pandas pin once we move off Python 3.10 to ensure we maintain pandas 2.x compatibility
-            # pandas 3.0 does not support 3.10 so we currently get free coverage, but won't after 3.10 goes EOL
-            # Min supported version of pandas 2.2
-            - numpy==1.22.4
+            - pandas<3
 
       runs-on: ${{ matrix.os }}
 
@@ -740,6 +880,7 @@ jobs:
         - test
         - test_sdist
         - test_dependencies
+        - test_cpp_examples
 
       if: startsWith(github.ref, 'refs/tags/v')
       runs-on: ubuntu-24.04

.gitignore

@@ -99,6 +99,7 @@ target/
 lib/
 lib64/
 csp/bin/
+csp/cmake/
 csp/include/
 csp/lib/
 *.so

CMakeLists.txt

@@ -52,6 +52,9 @@ if(NOT DEFINED CSP_CMAKE_MODULE_PATH)
 endif()
 list(PREPEND CMAKE_MODULE_PATH "${CSP_CMAKE_MODULE_PATH}")
 
+# Install the modules with the package. The trailing slash installs the directory contents.
+install(DIRECTORY "${CSP_CMAKE_MODULE_PATH}/" DESTINATION "cmake/modules")
+
 ###################################################################################################################################################
 # Build Configuration #
 #######################

Makefile

@@ -44,7 +44,7 @@ lint-cpp:
 
 lint-docs:
 	python -m mdformat --check docs/wiki/ README.md examples/
-	python -m codespell_lib docs/wiki/ README.md examples/ --skip "*.cpp,*.h"
+	python -m codespell_lib docs/wiki/ README.md examples/ --skip "*.cpp,*.h,*/build/*,*/target/*,*/_skbuild/*"
 
 # lint: lint-py lint-cpp  ## run lints
 lint: lint-py lint-docs ## run lints
@@ -62,7 +62,7 @@ fix-cpp:
 
 fix-docs:
 	python -m mdformat docs/wiki/ README.md examples/
-	python -m codespell_lib --write docs/wiki/ README.md examples/ --skip "*.cpp,*.h"
+	python -m codespell_lib --write docs/wiki/ README.md examples/ --skip "*.cpp,*.h,*/build/*,*/target/*,*/_skbuild/*"
 
 fix: fix-py fix-cpp fix-docs ## run autofixers
 

README.md

@@ -23,7 +23,7 @@ Here is a very simple example of a small `csp` program to calculate a [bid-ask s
 ```python
 import csp
 from csp import ts
-from datetime import datetime
+from csp.utils.datetime import utc_now
 
 
 @csp.node
@@ -44,7 +44,7 @@ def my_graph():
 
 
 if __name__ == '__main__':
-    csp.run(my_graph, starttime=datetime.utcnow())
+    csp.run(my_graph, starttime=utc_now())
 ```
 
 Running this, our output should look like (with some slight variations for current time):