# PySharp

**Repository Path**: vulild/py-sharp

## Basic Information

- **Project Name**: PySharp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PySharp SDK 使用手册

**日期：** 2026-07-21  
**SDK 版本：** **0.6.0**  
**目标框架：** **net10.0**（需安装 [.NET 10 SDK](https://dotnet.microsoft.com/download)）  
**仓库：** [https://gitee.com/vulild/py-sharp](https://gitee.com/vulild/py-sharp)  

相关文档：[使用方法（简版）](docs/usage/guide.md) · [实现方案](docs/architecture/implementation.md) · [已支持与未支持功能](docs/usage/features.md) · [嵌入式 CPython 设计](docs/superpowers/specs/2026-07-20-pysharp-embedded-cpython-runtime-design.md) · [变更记录](docs/CHANGELOG.md)

---

## 1. SDK 包含什么


| NuGet 包                                 | 类型              | 用途                                        |
| --------------------------------------- | --------------- | ----------------------------------------- |
| `Vulild.Net.Compilers.Python.Toolset`   | 开发依赖（MSBuild）   | `.pyproj` 编译：LanguageTargets + `Pyc` Task |
| `Vulild.PySharp.Templates`              | 模板包             | `dotnet new python` / `pythonclasslib`    |
| `Vulild.CodeAnalysis.Python`            | 类库              | 可编程编译 API（对标 Roslyn C#/VB）                |
| `Vulild.CodeAnalysis.Python.Decompiler` | 类库              | 程序集 → Python 子集源码                         |
| `Vulild.PySharp.CPython`                | 类库（可选）         | CPython/pip 桥（pythonnet）+ Locator；Enable 时须显式引用 |
| `Vulild.PySharp.CPython.Runtime.<rid>`  | 原生 Runtime     | 嵌入 CPython 3.12.10（win/linux × x64/arm64）   |
| `Vulild.PySharp.pyc`                    | **dotnet tool** | 命令行编译器 `pyc`                              |
| `Vulild.PySharp.pyc-decompile`          | **dotnet tool** | 命令行反编译器 `pyc-decompile`                   |


本地打包产物默认在仓库根目录 `nupkgs/`。

---

## 2. 本地打包（发布前）

在仓库根目录执行：

```powershell
powershell -File scripts\pack-sdk.ps1 -Configuration Release -Output nupkgs
```

或逐个 `dotnet pack`（输出到 `nupkgs`）：

```powershell
dotnet pack src\Compilers\Python\Portable\Vulild.CodeAnalysis.Python.csproj -c Release -o nupkgs
dotnet pack src\Decompiler\Vulild.CodeAnalysis.Python.Decompiler\Vulild.CodeAnalysis.Python.Decompiler.csproj -c Release -o nupkgs
dotnet pack src\Compilers\Python\pyc\pyc.csproj -c Release -o nupkgs
dotnet pack src\Decompiler\pyc-decompile\pyc-decompile.csproj -c Release -o nupkgs
dotnet pack src\Runtime\Vulild.PySharp.CPython\Vulild.PySharp.CPython.csproj -c Release -o nupkgs
# Runtime 包需先 scripts\fetch-embedded-python.ps1；推荐直接用 pack-sdk.ps1
dotnet pack src\NuGet\Vulild.Net.Compilers.Python.Toolset\Vulild.Net.Compilers.Python.Toolset.csproj -c Release -o nupkgs
dotnet pack src\Templates\PySharp.Templates\PySharp.Templates.csproj -c Release -o nupkgs
```

预期生成（版本均为 `0.6.0`；含四个 Runtime）：

```text
Vulild.CodeAnalysis.Python.0.6.0.nupkg
Vulild.CodeAnalysis.Python.Decompiler.0.6.0.nupkg
Vulild.Net.Compilers.Python.Toolset.0.6.0.nupkg
Vulild.PySharp.CPython.0.6.0.nupkg
Vulild.PySharp.CPython.Runtime.win-x64.0.6.0.nupkg
Vulild.PySharp.CPython.Runtime.linux-x64.0.6.0.nupkg
Vulild.PySharp.CPython.Runtime.win-arm64.0.6.0.nupkg
Vulild.PySharp.CPython.Runtime.linux-arm64.0.6.0.nupkg
Vulild.PySharp.Templates.0.6.0.nupkg
Vulild.PySharp.pyc.0.6.0.nupkg
Vulild.PySharp.pyc-decompile.0.6.0.nupkg
```

仓库 `nuget.config` 已配置本地源 `pysharp-local` → `./nupkgs`，便于在本仓库内验证样例。

---

## 3. 发布到 NuGet.org

### 3.1 准备

1. 注册 [nuget.org](https://www.nuget.org/) 账号并验证邮箱。
2. 创建 API Key：Account → API Keys → Create（建议勾选推送权限，并限制到你的包 ID 前缀）。
3. 本机已安装 .NET 10 SDK。

**安全提示：** 不要把 API Key 写进仓库或提交到 Git。可用环境变量或一次性交互输入。

### 3.2 推送全部 SDK 包

在仓库根目录（`nupkgs` 已含 `0.6.0` 包）执行：

```powershell
# 可选：写入本机 NuGet 配置（不要提交 nuget.config 中的明文 key）
# dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

$apiKey = $env:NUGET_API_KEY   # 或: Read-Host "NuGet API Key"
$pkgs = @(
  "Vulild.CodeAnalysis.Python.0.6.0.nupkg",
  "Vulild.CodeAnalysis.Python.Decompiler.0.6.0.nupkg",
  "Vulild.Net.Compilers.Python.Toolset.0.6.0.nupkg",
  "Vulild.PySharp.CPython.0.6.0.nupkg",
  "Vulild.PySharp.CPython.Runtime.win-x64.0.6.0.nupkg",
  "Vulild.PySharp.CPython.Runtime.linux-x64.0.6.0.nupkg",
  "Vulild.PySharp.CPython.Runtime.win-arm64.0.6.0.nupkg",
  "Vulild.PySharp.CPython.Runtime.linux-arm64.0.6.0.nupkg",
  "Vulild.PySharp.Templates.0.6.0.nupkg",
  "Vulild.PySharp.pyc.0.6.0.nupkg",
  "Vulild.PySharp.pyc-decompile.0.6.0.nupkg"
)
foreach ($p in $pkgs) {
  dotnet nuget push "nupkgs\$p" --api-key $apiKey --source https://api.nuget.org/v3/index.json --skip-duplicate
}
```

说明：

- `--skip-duplicate`：同一版本已存在时跳过，避免重复推送报错。  
- 首次发布后，包在 nuget.org 上可能有数分钟索引延迟。  
- 包 ID 需未被占用；若冲突需改 `PackageId` 或联系 nuget.org 支持。

### 3.3 发布后自检

```powershell
dotnet nuget search Vulild.Net.Compilers.Python.Toolset
dotnet tool install -g Vulild.PySharp.pyc --version 0.6.0
pyc --help
```

---

## 4. 安装与使用

### 4.1 MSBuild / `.pyproj`（推荐日常开发）

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Vulild.Net.Compilers.Python.Toolset" Version="0.6.0">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>
</Project>
```

同目录放置 `.py`（Toolset 默认收集 `**/*.py`，并排除 `bin`/`obj`）。0.4.0 起多文件采用「一文件一类 + 目录命名空间」语义：`lib/utils.py` → 模块类型 `lib.utils`；`from lib.utils import f` 解析为同项目模块静态方法。

```powershell
dotnet run --project MyApp.pyproj
```

语言样例请使用纯 Python（如 `print`）；CLR 互操作见仓库 `samples/InteropClr`。

### 4.1.1 Python 示例（多文件）

目录（与 `samples/ModuleImport` 同语义，一文件一模块）：

```text
MyApp/
  MyApp.pyproj
  Program.py          → 入口模块
  lib/
    greet.py          → 模块 lib.greet
    person.py         → 模块 lib.person（用户类 lib.Person）
```

`lib/greet.py`：

```python
def hello():
    return "hi"
```

`lib/person.py`：

```python
class Person:
    def __init__(self, name):
        self.name = name

    def get_name(self):
        return self.name
```

`Program.py`：

```python
from lib.greet import hello
from lib.person import Person

print(hello())
p = Person("py")
print(p.get_name())
```

运行仓库完整样例（含深目录 `import lib.io.path`）：

```powershell
dotnet run --project samples\ModuleImport\ModuleImport.pyproj
```

### 4.1.2 启用可选 CPython / pip 互操作（0.6.0）

`EnableCPythonInterop` 默认 **`false`**（与未启用互操作的行为一致）。为 `true` 时：前三层未解析的 `import` 由嵌入 CPython 加载；自有代码仍编译为 CLR（双运行时）。

**Path A：** Enable=true 时项目 **必须** 显式引用桥包；Toolset **不会**自动 `CollectPackageReferences` 注入。缺省则构建期报错。

```xml
<PropertyGroup>
  <EnableCPythonInterop>true</EnableCPythonInterop>
</PropertyGroup>
<ItemGroup>
  <PackageReference Include="Vulild.PySharp.CPython" Version="0.6.0" />
</ItemGroup>
```

| 项 | 说明 |
| -- | --- |
| 嵌入 | 默认 **CPython 3.12.10**；RID：`win-x64`、`linux-x64`、`win-arm64`、`linux-arm64` |
| 发布 | 跨平台须 `dotnet publish -r <rid>`（输出含桥 DLL + `python/`） |
| macOS | **未支持** |
| 覆盖 | `PYTHONNET_PYDLL` / `CPythonInitOptions.PythonDll` 优先于嵌入 |
| pip | 手动装到嵌入 `site-packages`，或 venv + `PYSHARP_VENV`（仅插入 path，不改 DLL） |
| 运行时自动 pip | `Import` 缺模块时**默认**自动 `pip install`（顶层模块名 = PyPI 包名，无别名表）；目标 venv site-packages 优先，否则嵌入；关闭：`PYSHARP_AUTO_INSTALL_PIP=0` 或 `AutoInstallMissingPipPackages=false` |

```powershell
# 可选 venv（第三方包）；解释器来自 Runtime 包
python -m venv samples\CPythonInterop\.venv
samples\CPythonInterop\.venv\Scripts\pip install -r samples\CPythonInterop\requirements.txt
$env:PYSHARP_VENV = (Resolve-Path samples\CPythonInterop\.venv).Path
dotnet publish samples\CPythonInterop\CPythonInterop.pyproj -r win-x64
dotnet run --project samples\CPythonInterop\CPythonInterop.pyproj
```

CLI：`pyc --cpython`。详见 [功能清单 §2.9](docs/usage/features.md) 与 [使用方法 §5.7](docs/usage/guide.md)。

### 4.2 项目模板

**从 nuget.org（发布后）：**

```powershell
dotnet new install Vulild.PySharp.Templates@0.6.0
dotnet new python -n MyApp
dotnet new pythonclasslib -n MyLib
dotnet run --project MyApp\MyApp.pyproj
```

**从本地 nupkg：**

```powershell
dotnet new install .\nupkgs\Vulild.PySharp.Templates.0.6.0.nupkg
```


| shortName        | 用途    |
| ---------------- | ----- |
| `python`         | 控制台应用 |
| `pythonclasslib` | 类库    |


卸载模板：`dotnet new uninstall Vulild.PySharp.Templates`

### 4.3 命令行工具 `pyc` / `pyc-decompile`

```powershell
# nuget.org
dotnet tool install -g Vulild.PySharp.pyc --version 0.6.0
dotnet tool install -g Vulild.PySharp.pyc-decompile --version 0.6.0

# 或本地包
dotnet tool install -g --add-source .\nupkgs Vulild.PySharp.pyc --version 0.6.0
dotnet tool install -g --add-source .\nupkgs Vulild.PySharp.pyc-decompile --version 0.6.0
```

编译示例：

```powershell
pyc Program.py -o out\App.dll -t exe
pyc Program.py -o out\App.dll -t exe -r "C:\Program Files\dotnet\packs\Microsoft.NETCore.App.Ref\10.0.x\ref\net10.0\System.Runtime.dll"
```

反编译示例：

```powershell
pyc-decompile path\to\App.dll -o restored.py
```

更新 / 卸载：

```powershell
dotnet tool update -g Vulild.PySharp.pyc
dotnet tool uninstall -g Vulild.PySharp.pyc
```

### 4.4 编译器 API（`Vulild.CodeAnalysis.Python`）

```xml
<PackageReference Include="Vulild.CodeAnalysis.Python" Version="0.6.0" />
```

```csharp
using Vulild.CodeAnalysis.Python;

var result = PythonCompiler.CompileFiles(
    sourcePaths: ["Program.py"],
    outputPath: "App.dll",
    outputKind: PythonOutputKind.ConsoleApplication,
    assemblyName: "App",
    emitPdb: true,
    referenceAssemblyPaths: /* 可选：ref 程序集路径 */);

if (!result.Success)
{
    foreach (var d in result.Diagnostics)
        Console.Error.WriteLine(d);
}
```

诊断语言服务（IDE 可用最小 API）：

```csharp
var diags = PythonLanguageService.GetDiagnostics(sourceText, "file.py");
```

### 4.5 反编译 API

```xml
<PackageReference Include="Vulild.CodeAnalysis.Python.Decompiler" Version="0.6.0" />
```

```csharp
using Vulild.CodeAnalysis.Python.Decompiler;

string py = PythonDecompiler.Decompile(assemblyPath);
```

### 4.6 VS Code 调试

PySharp 产出的是 **.NET 程序集 + Portable PDB**，用 **.NET 调试器** 调试，**不要**用 VS Code 的 Python 扩展去跑解释器。

**准备**

1. 安装扩展：[C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit)（或至少 **C#** / `ms-dotnettools.csharp`）。
2. 项目为 `.pyproj` + `Vulild.Net.Compilers.Python.Toolset`；Toolset 默认 `DebugSymbols=true`、`DebugType=portable`。
3. PDB 写入 **绝对** `.py` 源路径，断点可落在对应 Python 源文件上；调试构建会写入局部变量名与 `DebuggableAttribute`，**Locals / 监视** 面板可显示 Python 变量。
4. 编译错误经 MSBuild 带上 **文件路径与行列**，可在 Problems 面板点击跳转。

**推荐步骤（以仓库样例为例）**

```powershell
# 仓库根目录
dotnet build samples\HelloWorld\HelloWorld.pyproj -c Debug
```

1. 用 VS Code 打开仓库根（或你的 `.pyproj` 所在目录）。
2. 打开要调试的 `.py`（如 `samples/HelloWorld/Program.py`），在目标行设断点。
3. 按 **F5**，选择 **.NET Core** / **C#** 调试配置；若尚无配置，可按下方模板创建 `.vscode`。

`**.vscode/launch.json`（示例：调试 HelloWorld）**

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug HelloWorld",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build-helloworld",
      "program": "${workspaceFolder}/samples/HelloWorld/bin/Debug/net10.0/HelloWorld.dll",
      "args": [],
      "cwd": "${workspaceFolder}/samples/HelloWorld",
      "console": "internalConsole",
      "stopAtEntry": false
    }
  ]
}
```

`**.vscode/tasks.json`（示例）**

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-helloworld",
      "command": "dotnet",
      "type": "process",
      "args": [
        "build",
        "${workspaceFolder}/samples/HelloWorld/HelloWorld.pyproj",
        "-c",
        "Debug",
        "/property:GenerateFullPaths=true"
      ],
      "group": "build",
      "problemMatcher": "$msCompile"
    }
  ]
}
```

自有项目时：把 `program` 改成 `bin/Debug/net10.0/<AssemblyName>.dll`，`preLaunchTask` 指向对应 `dotnet build …pyproj`。

**多文件项目**

- 断点设在各个 `.py` 上即可（0.4.0 每源文件一份 PDB document）。
- Exe 入口默认 `Program.py`；若用了 `StartupObject`，从入口模块的执行路径开始单步。

**注意**


| 情况                                            | 说明                                                  |
| --------------------------------------------- | --------------------------------------------------- |
| `Release` / `--no-pdb` / `DebugSymbols=false` | 可能无法映射回 `.py` 源码                                    |
| 只装了 Python 扩展                                 | 无法按上述方式调试托管程序集                                      |
| 附加到已运行进程                                      | 可用 “.NET Core Attach”，目标为已启动的 `dotnet` / AppHost 进程 |


更短的调试说明亦见 [使用方法 § 调试](docs/usage/guide.md#6-调试)。

---

## 5. 语言与互操作速查

- **语言子集：** 控制流、`class`/`def`、`list`/`dict`/`set`、`with`、`async`/`await`（简化）、装饰器等。详见 [已支持与未支持功能](docs/usage/features.md)。  
- **推荐样例写法：** 语言示例用 `print` 等纯 Python；CLR 调用放在互操作示例（`Console`、`MemoryStream`、`List` 等）。  
- **多文件：** 0.4.0 起 `CompileFiles` / `pyc` 多源采用「一文件一类 + 目录命名空间」语义；`from lib.utils import f` 解析同项目模块静态方法，`import lib.utils` 绑定模块别名后 `lib.utils.f()` 调用；MSBuild 默认收集 `**/*.py`（注意勿把 `obj` 下临时文件编进去）。  
- **调试：** Toolset 默认 Portable PDB；VS Code 步骤见 [§4.6](#46-vs-code-调试)。

仓库样例：


| 示例                            | 说明                               |
| ----------------------------- | -------------------------------- |
| `samples/HelloWorld`          | 最小 `print`                       |
| `samples/LanguageP2`～`P6`     | 语言特性（纯 Python）                   |
| `samples/InteropClr`          | CLR 互操作                          |
| `samples/PackageRefApp`       | NuGet 依赖（如 Newtonsoft.Json）      |
| `samples/PyRefCs` / `CsRefPy` | 与 C# 交叉引用                        |
| `samples/ModuleImport`        | 同项目多文件：`from`/`import`、深目录、用户类   |
| `samples/PyModuleLib`         | 可引用的 Python 模块类库（DLL）            |
| `samples/ModuleImportRef`     | `ProjectReference` → PyModuleLib |
| `samples/CPythonInterop`      | Path A：显式桥 + pip（可选 venv）   |
| `samples/EmbeddedPythonSmoke` | publish `-r` 含嵌入 `python/`    |


---

## 6 架构概览

PySharp 总体架构

编译器内部模块

更细说明见 [实现方案](docs/architecture/implementation.md)。矢量原稿：`[pysharp-architecture.svg](docs/architecture/pysharp-architecture.svg)`、`[pysharp-compiler-internals.svg](docs/architecture/pysharp-compiler-internals.svg)`。

---

## 7. 版本与兼容性


| 项            | 值                |
| ------------ | ---------------- |
| SDK / 包版本    | 0.6.0            |
| TFM          | net10.0          |
| 最低 SDK       | .NET 10          |
| Toolset 任务路径 | `tasks/net10.0/` |
| CPython 互操作  | 可选；默认关闭；嵌入 3.12.10（四 RID；无 macOS） |


从 0.5.x 升级：将 `PackageReference` 改为 `0.6.0`；默认互操作仍关闭。启用互操作时须按 Path A **显式**引用 `Vulild.PySharp.CPython`，并用 `publish -r <rid>` 获取嵌入 Runtime（见 §4.1.2）。从 0.4.x 升级同理并改版本号；从 0.3.0 升级还需「一文件一类 + 目录命名空间」。

---

## 8. 常见问题

**Q: `dotnet build` 找不到 Toolset？**  
A: 确认已 `dotnet pack` 到本地源，或已推送到 nuget.org；检查 `PackageReference` 版本与 `nuget.config` 源。

**Q: 推送到 nuget.org 报 401/403？**  
A: API Key 无效、过期或未授权该包 ID；重新生成 Key，确认账号对包有 Push 权限。

**Q: 推送报包 ID 已存在且不属于你？**  
A: 需更换 `PackageId`（例如加组织前缀）后重新打包推送。

**Q: `dotnet tool install` 找不到命令？**  
A: 确认全局 tools 路径在 PATH 中（通常 `%USERPROFILE%\.dotnet\tools`）。

**Q: MSBuild 报 Modified types / Emit 内部错误？**  
A: 请使用 **0.6.0** Toolset（含 .NET 10 + 多文件模块类 + 可选嵌入 CPython）。语言样例避免混用未排除的 `obj/**/*.py`。

**Q: EnableCPythonInterop=true 构建报错要 PackageReference？**  
A: Path A 要求显式 `<PackageReference Include="Vulild.PySharp.CPython" Version="0.6.0" />`；Toolset 不会自动注入。见 §4.1.2。

---

## 8. 发布检查清单

- `scripts/pack-sdk.ps1` 成功，SDK + 四个 Runtime `0.6.0` nupkg 齐全  
- 本地：`dotnet new install` / `dotnet tool install --add-source nupkgs` 验证  
- 本地：`dotnet run --project samples\HelloWorld\HelloWorld.pyproj`  
- 可选：§4.1.2 冒烟 `samples\EmbeddedPythonSmoke` / `CPythonInterop`（`publish -r`）  
- `dotnet test`（全量）  
- `dotnet nuget push` 全部包到 nuget.org  
- 清空本地缓存后，仅从 nuget.org 再装 Toolset / Templates / tools 做一次冒烟