PySharp.Interop 1.0.1

PySharp 🐍⚡

Type-safe Python interop for C# — Call Python like it's native code.

PySharp lets you define C# interfaces that map directly to Python classes and modules. No boilerplate, no string-based method calls, no runtime surprises. Just clean, strongly-typed code.

[PyClass("math_ops")]
public interface IMathOps
{
    [PyMethod("add")]
    int Add(int a, int b);
    
    [PyMethod("mul")]
    Task<int> MultiplyAsync(int a, int b);
}

// Use it like any C# interface
var math = PyWrapperFactory.Create<IMathOps>();
Console.WriteLine(math.Add(3, 5));           // 8
Console.WriteLine(await math.MultiplyAsync(6, 7)); // 42

✨ Features

• Type-Safe — Define interfaces with proper C# types. Get compile-time safety and IntelliSense.
• Attribute-Based Mapping — Use [PyClass], [PyModule], [PyMethod], and [PyClassMethod] to declaratively map C# to Python.
• Async Support — Return Task<T> from any method for non-blocking Python calls.
• Direct Module Access — Call static/class methods on Python modules without writing wrapper classes.
• Object Handles — Pass complex Python objects (like ML models) between C# methods with PyObjectHandle.
• Auto-Detection — Automatically finds Python installation on Windows, macOS, and Linux.

📦 Installation

Prerequisites

• .NET Standard 2.1 compatible framework (.NET Core 3.0+, .NET 5+, .NET Framework 4.8+ with .NET Standard 2.1 support)
• Python 3.7–3.13 installed on your system

NuGet Package

Install via Package Manager Console:

Install-Package PySharp.Interop

Or via .NET CLI:

dotnet add package PySharp.Interop

Or add to your .csproj:

<PackageReference Include="PySharp.Interop" Version="1.0.0" />

Clone & Build

git clone https://github.com/mertyildiz41/PySharp.git
cd PySharp
dotnet build

🚀 Quick Start

1. Create a Python Module

# python/math_ops.py
class math_ops:
    def add(self, a, b):
        return a + b

    def mul(self, a, b):
        return a * b

2. Define a C# Interface

using PySharp.Attributes;

[PyClass("math_ops")]
public interface IMathOps
{
    [PyMethod("add")]
    int Add(int a, int b);

    [PyMethod("mul")]
    int Multiply(int a, int b);

    [PyMethod("mul")]
    Task<int> MultiplyAsync(int a, int b);
}

3. Use It

using PySharp.Core;

// Initialize Python engine (auto-detects Python installation)
PythonEngineInitializer.Initialize(extraPaths: new[] { "./python" });

// Create a typed wrapper
var mathOps = PyWrapperFactory.Create<IMathOps>();

Console.WriteLine(mathOps.Add(3, 5));              // 8
Console.WriteLine(mathOps.Multiply(2, 4));         // 8
Console.WriteLine(await mathOps.MultiplyAsync(6, 7)); // 42

📚 API Reference

Attributes

[PyClass(className, moduleName?)]

Maps a C# interface to a Python class. An instance of the class is created automatically.

[PyClass("Calculator", "my_math_module")]
public interface ICalculator { ... }

[PyModule(moduleName)]

Maps a C# interface directly to a Python module for calling static/class methods.

[PyModule("transformers")]
public interface ITransformers { ... }

[PyMethod(methodName)]

Maps a C# method to a Python instance method.

[PyMethod("calculate_sum")]
int Sum(int a, int b);

[PyClassMethod(className, methodName)]

Maps a C# method to a Python class/static method. Use with [PyModule].

[PyClassMethod("AutoModelForCausalLM", "from_pretrained")]
PyObjectHandle LoadModel(string modelName);

🤖 Advanced: Direct Module Access (LLM Example)

PySharp can call Python libraries directly without writing Python wrapper code. Here's an example using HuggingFace Transformers:

[PyModule("transformers")]
public interface ITransformers
{
    [PyClassMethod("AutoModelForCausalLM", "from_pretrained")]
    PyObjectHandle LoadModel(string modelName);

    [PyClassMethod("AutoModelForCausalLM", "from_pretrained")]
    Task<PyObjectHandle> LoadModelAsync(string modelName);

    [PyClassMethod("AutoTokenizer", "from_pretrained")]
    PyObjectHandle LoadTokenizer(string modelName);
}

[PyModule("torch")]
public interface ITorch
{
    [PyClassMethod("cuda", "is_available")]
    bool IsCudaAvailable();
}

Using PyObjectHandle

PyObjectHandle lets you store and pass Python objects between method calls:

var transformers = PyWrapperFactory.Create<ITransformers>();

// Load model and tokenizer
var model = await transformers.LoadModelAsync("Qwen/Qwen2.5-0.5B-Instruct");
var tokenizer = await transformers.LoadTokenizerAsync("Qwen/Qwen2.5-0.5B-Instruct");

// Call methods on Python objects
var text = tokenizer.CallWithKwargs<string>(
    "apply_chat_template",
    new object[] { messages },
    new Dictionary<string, object?> 
    { 
        ["tokenize"] = false, 
        ["add_generation_prompt"] = true 
    }
);

// Get attributes
using var device = model.GetAttrPy("device");

// Move tensors between devices
using var inputsOnDevice = modelInputs.To(device);

// Clean up when done
model.Dispose();
tokenizer.Dispose();

PyObjectHandle Extension Methods

⚙️ Configuration

Environment Variables

Manual Initialization

PythonEngineInitializer.Initialize(
    pythonHome: "/usr/local/python",  // Optional: PYTHONHOME override
    extraPaths: new[] { "./python", "./lib" }  // Additional sys.path entries
);

🗂 Project Structure

PySharp/
├── PySharp/                     # Core library
│   ├── Attributes/              # [PyClass], [PyModule], [PyMethod], etc.
│   ├── Core/                    # Engine, proxy, converters
│   └── Examples/                # Sample interfaces
├── PySharp.Examples.LLM/        # HuggingFace Transformers example
├── python/                      # Python modules
└── PySharp.sln

🔧 How It Works

1. Interface Analysis — PySharp reads your interface attributes at runtime
2. DispatchProxy — Creates a dynamic proxy implementing your interface
3. GIL Management — Automatically acquires Python's Global Interpreter Lock
4. Type Conversion — Marshals arguments and return values between C# and Python
5. Module Caching — Python modules are cached for performance

🧪 Running Examples

Basic Math Example

cd PySharp
dotnet run

Output:

3 + 5 = 8
2 * 4 = 8
6 * 7 (async) = 42

LLM Example

cd PySharp.Examples.LLM
pip install transformers torch
dotnet run

📋 Supported Types

📄 License

MIT License — Use it freely in your projects.

🤝 Contributing

Contributions welcome! Please open an issue or PR.

<p align="center"> <b>PySharp</b> — Because Python and C# should be friends. 🐍🤝⚡ </p>