pact-foundation · JP-Ellis · Jul 29, 2025 · Jul 25, 2025
diff --git a/.github/workflows/build-ffi.yml b/.github/workflows/build-ffi.yml
@@ -0,0 +1,198 @@
+---
+name: build ffi
+
+on:
+  push:
+    tags:
+      - pact-python-ffi/*
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  STABLE_PYTHON_VERSION: '39'
+  HATCH_VERBOSE: '1'
+  FORCE_COLOR: '1'
+  CIBW_BUILD_FRONTEND: build
+
+jobs:
+  complete:
+    name: Build FFI completion check
+    if: always()
+
+    permissions:
+      contents: none
+
+    runs-on: ubuntu-latest
+    needs:
+      - build-sdist
+      - build-wheels
+
+    steps:
+      - name: Failed
+        run: exit 1
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+
+  build-sdist:
+    name: Build FFI source distribution
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc  # v6.4.3
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install ${{ env.STABLE_PYTHON_VERSION }}
+
+      - name: Install hatch
+        run: uv tool install hatch
+
+      - name: Create source distribution
+        working-directory: pact-python-ffi
+        run: hatch build --target sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: wheels-sdist
+          path: pact-python-ffi/dist/*.tar*
+          if-no-files-found: error
+          compression-level: 0
+
+  build-wheels:
+    name: Build FFI wheels on ${{ matrix.os }}
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-13
+          - os: macos-latest
+          - os: ubuntu-24.04-arm
+          - os: ubuntu-latest
+          - os: windows-11-arm
+          - os: windows-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Create wheels
+        uses: pypa/cibuildwheel@95d2f3a92fbf80abe066b09418bbf128a8923df2  # v3.0.1
+        with:
+          package-dir: pact-python-ffi
+        env:
+          CIBW_BUILD: cp${{ env.STABLE_PYTHON_VERSION }}-*
+          HATCH_VERBOSE: '1'
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+          compression-level: 0
+
+  publish:
+    name: Publish FFI wheels and sdist
+
+    if: >-
+      github.event_name == 'push' &&
+      startsWith(github.event.ref, 'refs/tags/pact-python-ffi/')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pact-python-ffi
+
+    needs:
+      - build-sdist
+      - build-wheels
+
+    permissions:
+      # Required for creating the release
+      contents: write
+      # Required for trusted publishing
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Install git cliff and typos
+        uses: taiki-e/install-action@c07504cae06f832dc8de08911c9a9c5cddb0d2d3  # v2.56.13
+        with:
+          tool: git-cliff,typos
+
+      - name: Update changelog
+        run: git cliff --verbose
+        working-directory: pact-python-ffi
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+
+      - name: Generate release changelog
+        id: release-changelog
+        working-directory: pact-python-ffi
+        run: |
+          git cliff \
+            --current \
+            --strip header \
+            --output ${{ runner.temp }}/release-changelog.md
+
+          echo -e "\n\n## Pull Requests\n\n" >> ${{ runner.temp }}/release-changelog.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+
+      - name: Download wheels and sdist
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          path: wheelhouse
+          merge-multiple: true
+
+      - name: Generate release
+        id: release
+        uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8  # v2.3.2
+        with:
+          files: wheelhouse/*
+          body_path: ${{ runner.temp }}/release-changelog.md
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+
+      - name: Push build artifacts to PyPI
+        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc  # v1.12.4
+        with:
+          skip-existing: true
+          packages-dir: wheelhouse
+
+      - name: Create PR for changelog update
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e  # v7.0.8
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          commit-message: 'docs: update changelog for ${{ github.ref_name }}'
+          title: 'docs: update ffi changelog'
+          body: |
+            This PR updates the changelog for ${{ github.ref_name }}.
+          branch: docs/update-changelog
+          base: main
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -121,6 +121,10 @@ jobs:
         working-directory: pact-python-cli
         run: hatch run test
 
+      - name: Run tests (FFI)
+        working-directory: pact-python-ffi
+        run: hatch run test
+
       - name: Upload coverage
         if: matrix.python-version == env.STABLE_PYTHON_VERSION && matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24  # v5.4.3
@@ -177,6 +181,15 @@ jobs:
       - name: Install Python
         run: uv python install ${{ matrix.python-version }}
 
+      - name: Set PATH on Windows
+        if: startsWith(matrix.os, 'windows-')
+        shell: pwsh
+        run: echo "$pwd/pact-python-ffi/src/pact_ffi" >> $env:GITHUB_PATH
+
+      - name: Set DYLD_LIBRARY_PATH on macOS
+        if: startsWith(matrix.os, 'macos-')
+        run: echo "DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$PWD/pact-python-ffi/src/pact_ffi" >> $GITHUB_ENV
+
       - name: Install Hatch
         run: uv tool install hatch
 
@@ -187,6 +200,10 @@ jobs:
         working-directory: pact-python-cli
         run: hatch run test
 
+      - name: Run tests (FFI)
+        working-directory: pact-python-ffi
+        run: hatch run test
+
   example:
     name: Example
 
@@ -279,6 +296,9 @@ jobs:
         working-directory: pact-python-cli
         run: hatch run format
 
+      - name: Format (FFI)
+        working-directory: pact-python-ffi
+        run: hatch run format
   lint:
     name: Lint
 
@@ -301,13 +321,17 @@ jobs:
       - name: Install Hatch
         run: uv tool install hatch
 
-      - name: Format
+      - name: Lint
         run: hatch run lint
 
-      - name: Format (CLI)
+      - name: Lint (CLI)
         working-directory: pact-python-cli
         run: hatch run lint
 
+      - name: Lint (FFI)
+        working-directory: pact-python-ffi
+        run: hatch run lint
+
   typecheck:
     name: Typecheck
 

diff --git a/pact-python-cli/pyproject.toml b/pact-python-cli/pyproject.toml
@@ -64,12 +64,7 @@ requires-python = ">=3.9"
 ################################################################################
 [build-system]
 build-backend = "hatchling.build"
-requires = [
-  "hatch-vcs",
-  "hatchling",
-  "packaging",
-  # "setuptools ; python_version >= '3.12'",
-]
+requires      = ["hatch-vcs", "hatchling", "packaging"]
 
 [tool.hatch]
 

diff --git a/pact-python-ffi/.gitignore b/pact-python-ffi/.gitignore
@@ -0,0 +1,2 @@
+src/pact_ffi/data
+src/pact_ffi/__version__.py
diff --git a/pact-python-ffi/LICENSE b/pact-python-ffi/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pact Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/pact-python-ffi/README.md b/pact-python-ffi/README.md
@@ -0,0 +1,43 @@
+# Pact Python FFI
+
+> [!NOTE]
+>
+> This package provides direct access to the Pact Foreign Function Interface (FFI) with minimal abstraction. It is intended for advanced users who need low-level control over Pact operations in Python.
+
+---
+
+This sub-package is part of the [Pact Python](https://github.com/pact-foundation/pact-python) project and exists to expose the [Pact FFI](https://github.com/pact-foundation/pact-reference) directly to Python. If you are looking for the main Pact Python library for contract testing, please see the [root package](https://github.com/pact-foundation/pact-python#pact-python).
+
+## Overview
+
+-   The module provides a thin Python wrapper around the Pact FFI (C API).
+-   Most classes correspond directly to structs from the FFI, and are designed to wrap the underlying C pointers.
+-   Many classes implement the `__del__` method to ensure memory allocated by the Rust library is freed when the Python object is destroyed, preventing memory leaks.
+-   Functions from the FFI are exposed directly: if a function `foo` exists in the FFI, it is accessible as `pact_ffi.foo(...)`.
+-   The API is not guaranteed to be stable and is intended for use by advanced users or for building higher-level libraries. For typical contract testing, use the main Pact Python client library.
+
+## Installation
+
+You can install this package via pip:
+
+```console
+pip install pact-python-ffi
+```
+
+## Usage
+
+This package exposes the raw FFI bindings for Pact. It is suitable for advanced use cases, custom integrations, or for building higher-level libraries. For typical contract testing, prefer using the main Pact Python library.
+
+## Contributing
+
+As this is a relatively thin wrapper around the Pact FFI, the code is unlikely to change frequently; however, contributions to improve the coverage of the FFI bindings or to improve existing functionality are welcome. See the [main contributing guide](https://github.com/pact-foundation/pact-python/blob/main/CONTRIBUTING.md) for details.
+
+To release a new version of `pact-python-ffi`, simply push a tag in the format `pact-python-ffi/x.y.z.w`. This will automatically trigger a release process, pulling in version `x.y.z` of the underlying Pact FFI. Before creating and pushing such a tag, please ensure that the Python wrapper has been updated to reflect any changes or updates in the corresponding FFI version.
+
+Higher-level abstractions or utilities should be implemented in separate libraries (such as [`pact-python`](https://github.com/pact-foundation/pact-python)).
+
+---
+
+For questions or support, please visit the [Pact Foundation Slack](https://slack.pact.io) or [GitHub Discussions](https://github.com/pact-foundation/pact-python/discussions)
+
+---