查看“LessPythonInvoke”的源代码


= LessPython C# &#x3C;-&#x3E; Python Interop =
A high-performance, cross-platform interop layer between C# and Python using shared memory (MMF) for data transfer and a lightweight TCP notify channel. Optimized for large <code>NumPy</code> arrays via a compact binary protocol and zero-copy views.

== Quick start ==

# Ensure Python is available (optionally in a venv) and <code>numpy</code> installed if you use array features.
# Add this project to your solution or reference the produced DLL.
# Write a Python module with functions to call from C#.
# Initialize and call via a typed interface:
<syntaxhighlight lang="python"># exporting_module.py:
def add_ints(a, b):
    return int(a) + int(b)</syntaxhighlight><syntaxhighlight lang="csharp">public interface IMyPyApi
{
    [PythonImport] int add_ints(int a, int b);
    [PythonImport] NdArray inc_ndarray(NdArray nd);
    [PythonImport("inc_ndarray_timed")] (NdArray, double) inc_ndarray_timed(NdArray nd);
}

var api = LessPythonInvoke.Initialize<IMyPyApi>(
    pythonVenvPath: "",                 // optional venv root ("" => system python)
    exportingPyPath: "lesspy_work/exporting_module.py", // your module path
    debug: false,
    keepAlive: true,
    capacity: 256 * 1024 * 1024          // per-file MMF capacity
);

int x = api.add_ints(2, 40);</syntaxhighlight>

== Initialization ==
<code>LessPythonInvoke.Initialize&#x3C;T&#x3E;(string pythonVenvPath, string exportingPyPath, bool debug=false, bool keepAlive=false, int capacity=16*1024*1024)</code> - <code>pythonVenvPath</code>: optional; empty string uses system <code>python</code>/<code>python3</code>. - <code>exportingPyPath</code>: path to your Python module file. - <code>debug</code>: enables extra logging from the shim. - <code>keepAlive</code>: keep Python server and MMFs running across C# process runs. - <code>capacity</code>: size of each MMF file (request/response). Must be large enough for your largest payload.

MMF/aux files are placed under <code>bin/&#x3C;config&#x3E;/&#x3C;tfm&#x3E;/lesspy_work/</code>: - <code>req.mmf</code>, <code>resp.mmf</code>: shared memory files - <code>lesspy_shim.py</code>: shim injected and launched - <code>python.pid</code>: Python PID (keepalive) - <code>notify.port</code>: TCP port (keepalive reconnect)

== Attributes and binding ==

* Mark interface methods with <code>[PythonImport]</code>. The method name maps to the Python function name by default; override via <code>[PythonImport(&#x22;py_name&#x22;)]</code>.
* Supported argument/return types:
** <code>int</code>, <code>long</code>, <code>float</code>, <code>double</code>, <code>bool</code>, <code>string</code>, <code>byte[]</code>
** <code>int[]</code>, <code>int[][]</code> (nested)
** <code>ValueTuple</code> with supported element types
** <code>NdArray</code> (NumPy) with shape/dtype/data

== NdArray ==
<code>NdArray</code> represents a NumPy array: <code>Shape</code>, <code>Dtype</code>, and data. On responses, if Python returns a NumPy array, the C# side returns an <code>NdArray</code> backed by a zero-copy view over <code>resp.mmf</code> (<code>DataMemory</code>). Accessing <code>NdArray.Data</code> materializes a copy only on demand.

== KeepAlive ==

* When <code>keepAlive: true</code>, the Python process keeps running after C# exits.
* On next run, C# will reuse the existing Python server by reading <code>python.pid</code> and <code>notify.port</code>, then connect over TCP.
* If the notify connection drops, Python keeps listening; subsequent runs will reconnect.

== Performance ==

* Binary protocol (no JSON) over SHM, single-byte notify via localhost TCP.
* Direct pointer copies for MMF read/write; no intermediate payload buffers on C# side.
* Zero-copy ndarray responses (views over <code>resp.mmf</code>).
* Example (4096x4096 float32 inc): ~24.9 ms end-to-end for one un-timed call (~5.1 GB/s raw read+write).

Tips: - Use larger <code>capacity</code> for big transfers. - Prefer returning arrays directly from Python for zero-copy on C#. - For transforms, compute into the response buffer on Python side to avoid extra copies.

== Troubleshooting ==

* MMF locked on rapid restarts: you may see <code>user-mapped section open</code>. Retry after a moment; add exponential backoff if needed.
* Type mismatch in tuples: ensure element types align (e.g., <code>float</code> vs <code>double</code>). The invoker coerces primitives where needed.
* KeepAlive not reusing: ensure <code>python.pid</code>, <code>notify.port</code>, and <code>req.mmf</code>/<code>resp.mmf</code> remain present and Python is still running.
* Capacity exceeded: increase <code>capacity</code> to fit your largest request/response.