# tonybaloney/csnakes architecture

> Architecture diagram of the GitHub repository tonybaloney/csnakes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonybaloney/csnakes
- Repository: https://github.com/tonybaloney/csnakes

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Developer Code" 
        direction TB
        DevSimple["samples/simple"]:::external
        DevAspire["samples/Aspire"]:::external
        PyScripts["Python Scripts/Modules"]:::external
    end

    Compiler[".NET Compiler"]:::compile
    SourceGen["CSnakes Source Generator"]:::compile
    Generated["Generated C# Bindings"]:::compile

    subgraph "CSnakes.Runtime Library"
        direction TB
        RuntimeCore["Core API (CSnakes.Runtime)"]:::runtime
        EnvMgmt["EnvironmentManagement"]:::runtime
        Locators["Locators"]:::runtime
        PackageMgmt["PackageManagement"]:::runtime
        CPythonWrap["CPython Wrapper Modules"]:::runtime
        TypeConv["PyObjectTypeConverter"]:::runtime
    end

    PythonCAPI["Python/C-API (via P/Invoke)"]:::native
    PyInterp["Python Interpreter + Modules/venv"]:::native

    subgraph "External Tools & Support"
        direction TB
        CI["CI/CD Workflows"]:::external
        Docs["Documentation Site"]:::external
        Packaging["Packaging Targets & NuGet Props"]:::external
        SamplesTests["Samples & Tests"]:::external
    end

    %% Flows
    DevSimple -->|"build"| Compiler
    DevAspire -->|"build"| Compiler
    PyScripts -->|"analyze signatures"| SourceGen
    Compiler --> SourceGen
    SourceGen -->|"emit C# glue"| Generated
    Generated -->|"runtime call"| RuntimeCore
    RuntimeCore --> EnvMgmt
    RuntimeCore --> Locators
    RuntimeCore --> PackageMgmt
    RuntimeCore --> CPythonWrap
    RuntimeCore --> TypeConv
    CPythonWrap --> PythonCAPI
    PythonCAPI --> PyInterp

    %% External relations
    CI -.-> Compiler
    CI -.-> Packaging
    Docs -.-> SamplesTests
    Packaging -.-> Generated
    SamplesTests -.-> RuntimeCore

    %% Click Events
    click DevSimple "https://github.com/tonybaloney/csnakes/tree/main/samples/simple"
    click DevAspire "https://github.com/tonybaloney/csnakes/tree/main/samples/Aspire"
    click PyScripts "https://github.com/tonybaloney/csnakes/tree/main/samples/simple/ExamplePythonDependency"
    click Compiler "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Tests"
    click SourceGen "https://github.com/tonybaloney/csnakes/tree/main/src/CSnakes.Tests/PythonStaticGeneratorTests"
    click SourceGen "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Tests/TokenizerTests.cs"
    click SourceGen "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Tests/GeneratedSignatureTests.cs"
    click RuntimeCore "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Runtime"
    click EnvMgmt "https://github.com/tonybaloney/csnakes/tree/main/src/CSnakes.Runtime/EnvironmentManagement"
    click Locators "https://github.com/tonybaloney/csnakes/tree/main/src/CSnakes.Runtime/Locators"
    click PackageMgmt "https://github.com/tonybaloney/csnakes/tree/main/src/CSnakes.Runtime/PackageManagement"
    click CPythonWrap "https://github.com/tonybaloney/csnakes/tree/main/src/CSnakes.Runtime/CPython"
    click TypeConv "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Runtime/PyObjectTypeConverter.cs"
    click PythonCAPI "https://github.com/tonybaloney/csnakes/tree/main/src/CSnakes.Runtime/CPython"
    click Packaging "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Runtime/Packaging.targets"
    click Packaging "https://github.com/tonybaloney/csnakes/blob/main/src/Packaging.targets"
    click Packaging "https://github.com/tonybaloney/csnakes/blob/main/src/Packaging.props"
    click Packaging "https://github.com/tonybaloney/csnakes/blob/main/src/Directory.Packages.props"
    click CI "https://github.com/tonybaloney/csnakes/tree/main/.github/workflows/"
    click Docs "https://github.com/tonybaloney/csnakes/tree/main/docs/"
    click SamplesTests "https://github.com/tonybaloney/csnakes/blob/main/src/Integration.Tests"
    click SamplesTests "https://github.com/tonybaloney/csnakes/blob/main/src/CSnakes.Runtime.Tests"
    click SamplesTests "https://github.com/tonybaloney/csnakes/blob/main/src/RedistributablePython.Tests"
    click SamplesTests "https://github.com/tonybaloney/csnakes/blob/main/src/Conda.Tests"
    click SamplesTests "https://github.com/tonybaloney/csnakes/tree/main/Profile/"

    %% Styles
    classDef compile fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef runtime fill:#d4edda,stroke:#28a745,color:#000;
    classDef native fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef external fill:#ececec,stroke:#6c757d,color:#000;
```
