跨语言通信：BeamDrop从CLI到GUI的pybind实战

#include <pybind11/pybind11.h>

int add(int i, int j) {
    return i + j;
}

PYBIND11_MODULE(my_math, m) {
    m.doc() = "pybind11 example";
    m.def("add", &add, "a function that add two integers");
}

import my_math

print(my_math.add(1, 2))

find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
find_package(pybind11 CONFIG REQUIRED)

pybind11_add_module(beamdrop_native
    beamdrop_pybind.cpp
)

target_link_libraries(beamdrop_native PRIVATE beamdrop_core)

set(BEAMDROP_CORE_SOURCES
    src/config/AppConfig.cpp
    src/filesystem/FileScanner.cpp
    src/filesystem/FileUtils.cpp
    src/logger/Logger.cpp
    src/network/TcpClient.cpp
    src/network/TcpConnection.cpp
    src/network/TcpServer.cpp
    src/protocol/PacketIO.cpp
    src/protocol/PacketParser.cpp
    src/protocol/Serializer.cpp
    src/transfer/FileInfoCodec.cpp
    src/transfer/Receiver.cpp
    src/transfer/ResumeAckCodec.cpp
    src/transfer/ResumeManager.cpp
    src/transfer/Sender.cpp
    src/transfer/TransferManifest.cpp
    src/utils/Sha256.cpp
    src/app/SendService.cpp
    src/app/ReceiveService.cpp
    src/app/ReceiveServerService.cpp)

add_library(beamdrop_core STATIC
    ${BEAMDROP_CORE_SOURCES}
)

#include <pybind11/pybind11.h>

namespace py = pybind11;

PYBIND11_MODULE(beamdrop_native, m) {
    m.doc() = "BeamDrop C++ application-service binding";
}

$pyd = Get-ChildItem build\windows-msvc2026-python -Recurse -Filter 'beamdrop_native*pyd' | Select-Object -First 1
$env:PYTHONPATH = $pyd.DirectoryName
& "$PWD\.venv\Scripts\python.exe" -c "import beamdrop_native; print(beamdrop_native.__doc__)"
Remove-Item Env:PYTHONPATH

BeamDrop C++ application-service binding

py::class_<beamdrop::app::ServiceError>(m, "ServiceError")
    .def_readonly("code", &beamdrop::app::ServiceError::code)
    .def_readonly("message", &beamdrop::app::ServiceError::message);

py::enum_<beamdrop::app::TransferProgress::Direction>(m, "TransferDirection")
    .value("SEND", beamdrop::app::TransferProgress::Direction::Send)
    .value("RECEIVE", beamdrop::app::TransferProgress::Direction::Receive);

py::class_<beamdrop::app::SendResult>(m, "SendResult")
    .def_readonly("file_count", &beamdrop::app::SendResult::file_count)
    .def_readonly("total_bytes", &beamdrop::app::SendResult::total_bytes);

auto beamdrop_error = py::reinterpret_steal<py::object>(
    PyErr_NewException("beamdrop_native.BeamDropError", PyExc_RuntimeError, nullptr));
m.attr("BeamDropError") = beamdrop_error;

PyErr_NewException("beamdrop_native.BeamDropError", PyExc_RuntimeError, nullptr)

namespace {
[[noreturn]] void raise_service_error(const py::object &exception_type,
                                      const beamdrop::app::ServiceError &error) {
    auto exception = exception_type(py::str(error.message));
    exception.attr("code") = py::cast(error.code);
    PyErr_SetObject(exception_type.ptr(), exception.ptr());
    throw py::error_already_set();
}
} // namespace

m.def(
    "send",
    [beamdrop_error](const std::vector<std::string> &paths, const std::string &host,
                     int port, std::size_t chunk_size) {
        if (port < 0 || port > 65535) {
            throw py::value_error("port must be in range 0..65535");
        }

        beamdrop::app::SendRequest request;
        request.host = host;
        request.port = port;
        request.chunk_size = chunk_size;
        request.paths.reserve(paths.size());
        for (const auto &path : paths) {
            request.paths.emplace_back(path);
        }

        const auto result = beamdrop::app::SendService{}.send(request);
        if (!result) {
            raise_service_error(beamdrop_error, result.error());
        }
        return result.value();
    },
    py::arg("paths"), py::arg("host"), py::arg("port"),
    py::arg("chunk_size") = 1024 * 1024);

$pyd = Get-ChildItem build\windows-msvc2026-python -Recurse -Filter 'beamdrop_native*.pyd' | Select-Object -First 1
$env:PYTHONPATH = $pyd.DirectoryName
@'
import beamdrop_native as b

try:
    b.send([], '127.0.0.1', 9000)
except b.BeamDropError as e:
    print(e.code, str(e))
'@ | & "$PWD\.venv\Scripts\python.exe"
Remove-Item Env:PYTHONPATH

[beamdrop_error](const std::vector<std::string> &paths, const std::string &host, int port,
                         std::size_t chunk_size, py::object on_progress)

if (!on_progress.is_none() && !PyCallable_Check(on_progress.ptr())) {
    throw py::type_error("on_progress must be callable or None");
}

if (!on_progress.is_none()) {
    py::function callback = py::reinterpret_borrow<py::function>(on_progress);
    request.progress_callback = [callback = std::move(callback)](
                                    const beamdrop::app::TransferProgress &progress) {
        py::gil_scoped_acquire aquire;
        try {
            callback(progress);
        } catch (py::error_already_set &error) {
            const std::string message = error.what();
            error.discard_as_unraisable(callback);
            throw PythonProgressCallbackError(message);
        }
    };
}

py::function callback = py::reinterpret_borrow<py::function>(on_progress);

py::gil_scoped_acquire acquire;

py::gil_scoped_release release;

try {
    callback(progress);
} catch (py::error_already_set &error) {
    const std::string message = error.what();
    error.discard_as_unraisable(callback);
    throw PythonProgressCallbackError(message);
}

py::class_<beamdrop::app::ReceiveServerService,
            std::shared_ptr<beamdrop::app::ReceiveServerService>>(m, "ReceiverService")
    .def(py::init<>())
    .def(
        "start",
        [beamdrop_error](beamdrop::app::ReceiveServerService &service, const std::string &host,
                            int port, const std::string &save_dir, const std::string &state_file) {
            if (port < 0 || port > 65535) {
                throw py::value_error("port must be in range 0..65535");
            }

            beamdrop::app::ReceiveServerRequest request;
            request.host = host;
            request.port = static_cast<std::uint16_t>(port);
            request.receive_request.save_dir = std::filesystem::path{save_dir};
            request.receive_request.state_file = std::filesystem::path{state_file};

            const auto result = service.start(request);
            if (!result) {
                raise_service_error(beamdrop_error, result.error());
            }
            return result.value();
        },
        py::arg("host"), py::arg("port"), py::arg("save_dir"), py::arg("state_file"))
    .def("status", &beamdrop::app::ReceiveServerService::status)
    .def("stop", [beamdrop_error](beamdrop::app::ReceiveServerService &service) {
        const auto result = service.stop();
        if (!result) {
            raise_service_error(beamdrop_error, result.error());
        }
        return result.value();
    });

import hashlib
import socket
import time
from pathlib import Path

import pytest

import beamdrop_native as b


def free_loopback_port() -> int:
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]


def wait_for_file(path: Path, timeout_seconds: float = 2.0) -> None:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        if path.exists():
            return
        time.sleep(0.02)
    raise AssertionError(f"received file not found: {path}")


@pytest.fixture
def receiver(tmp_path: Path):
    service = b.ReceiverService()
    port = free_loopback_port()
    received_dir = tmp_path / "received"
    received_dir.mkdir()

    started = service.start(
        "127.0.0.1",
        port,
        str(received_dir),
        str(tmp_path / "receiver-state.json"),
    )
    assert started.state == b.ReceiverState.RUNNING

    try:
        yield service, port, received_dir
    finally:
        status = service.status()
        if status.state != b.ReceiverState.STOPPED:
            service.stop()


def test_send_reports_progress_and_transfers_file(receiver, tmp_path: Path) -> None:
    service, port, received_dir = receiver
    del service  # fixture owns lifetime; prevents an unused-variable warning

    source = tmp_path / "数据.bin"
    source.write_bytes(bytes(range(256)) * 16_384)  # 4 MiB
    stages: list[object] = []

    result = b.send(
        [str(source)],
        "127.0.0.1",
        port,
        on_progress=lambda progress: stages.append(progress.stage),
    )

    assert result.file_count == 1
    assert result.total_bytes == source.stat().st_size
    assert b.TransferStage.TASK_STARTED in stages
    assert b.TransferStage.TRANSFERRING in stages
    assert b.TransferStage.FILE_COMPLETED in stages
    assert b.TransferStage.TASK_COMPLETED in stages

    received = received_dir / source.name
    wait_for_file(received)
    assert hashlib.sha256(received.read_bytes()).digest() == hashlib.sha256(source.read_bytes()).digest()


def test_send_converts_python_callback_exception_to_internal_error(receiver, tmp_path: Path) -> None:
    service, port, _ = receiver
    del service

    source = tmp_path / "数据.bin"
    source.write_bytes(b"callback failure test")

    def failing_callback(_: object) -> None:
        raise RuntimeError("intentional callback failure")

    with pytest.raises(b.BeamDropError) as caught:
        b.send([str(source)], "127.0.0.1", port, on_progress=failing_callback)

    assert caught.value.code == b.ErrorCode.INTERNAL_ERROR


def test_send_rejects_non_callable_progress_handler() -> None:
    with pytest.raises(TypeError, match="on_progress must be callable or None"):
        b.send([], "127.0.0.1", 19090, on_progress=42)

add_test(
    NAME beamdrop_python_binding_tests
    COMMAND ${Python_EXECUTABLE} -m pytest
            ${CMAKE_CURRENT_SOURCE_DIR}/tests
            -v
)
set_tests_properties(beamdrop_python_binding_tests PROPERTIES
    ENVIRONMENT "PYTHONPATH=$<TARGET_FILE_DIR:beamdrop_native>"
)

@app.post("api/transfer/send")
async def send(request: SendRequest):
    result = await beamdrop_native.send(request)
    ...

class NativeGateway(Protocol):
    def send(self, on_progress: ProgressCallback, cancel_event: Event | None = None) -> NativeSendResult:
        ...

    def start_receiver(self, request: StartReceiverRequest) -> ReceiverSnapshot:
        ...

    def receiver_status(self) -> ReceiverSnapshot:
        ...

    def stop_receiver(self) -> ReceiverSnapshot:
        ...