How tonybaloney/csnakes works
Project Type & Purpose
• CSnakes is an open-source .NET Source Generator and Runtime library that embeds Python into .NET without using HTTP or REST.
• It supports compile-time generation of .NET APIs from Python signatures and a runtime component that manages Python environments, locates installs, and calls into the Python C-API.
High-Level Components
1. Developer Code
– C# projects referencing CSnakes attributes/source generator
– Python scripts/modules (e.g. example.py, samples/)
2. Source Generation Pipeline (Compile-time)
– .NET Compiler
– CSnakes Source Generator (analyzes Python signatures, emits static C# classes)
3. Generated Bindings
– Static .NET classes (e.g. Example.HelloWorld(...))
4. CSnakes Runtime Library
– Core API (CSnakes.Runtime)
– Sub-components:
• EnvironmentManagement (Conda, venv)
• Locators (CondaLocator, WindowsStoreLocator, etc.)
• PackageManagement (PipInstaller, UVInstaller)
• CPython wrapper modules (GIL, Call, Buffer, Object, Import, Sequence, Coroutine, Exceptions, etc.)
• PyObjectTypeConverter (maps between .NET types and Python types)
5. Native Python/C-API
– Python interpreter runtime (3.9–3.13)
– C API calls managed via P/Invoke
6. External Resources & Support
– File system (searching for Python installs, virtual environments)
– NuGet packaging targets (Packaging.targets, Directory.Packages.props)
– CI/CD pipelines (.github/workflows dotnet-ci, publish, docs)
– Documentation site (mkdocs.yml + docs/)
– Samples & Tests (unit, integration, profiling)
Relationships & Data Flows
• Developer writes .NET + Python code → .NET build invokes CSnakes Source Generator → emits static C# glue code.
• At runtime, application invokes generated C# methods → CSnakes Runtime dispatches to CPython wrapper → acquires GIL → marshals arguments → calls Python C-API → executes Python function → marshals return → back to .NET.
• EnvironmentManagement + Locators run before any call to configure or find a Python runtime.
• Packaging targets run on build/publish to include appropriate native artifacts in NuGet packages.
Architectural Patterns & Design Principles
• Compile-time vs. run-time separation: Source generator for code emission, runtime for execution.
• Dependency Injection & Extensions: ServiceCollectionExtensions to register environment/locator providers.
• Strategy pattern: multiple locator and environment-management implementations.
• Layered design: Generated Bindings → Runtime API → Native C-API → Python interpreter.
Technologies & Frameworks
• .NET 8–9, C# Source Generators
• Python 3.9–3.13, CPython C-API
• xUnit for tests, GitHub Actions for CI/CD
• VS Code DevContainer, Docker for reproducible dev env
• MkDocs for docs site