Skip to content

Commit 12589ab

Browse files
authored
Merge pull request #1 from net0well/fase-1/fundacao-core-sdk
Fase 1: fundação + Core Runner + SDK psrunner (specs 001, 002)
2 parents 936500e + 0a003e9 commit 12589ab

85 files changed

Lines changed: 9743 additions & 3 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
indent_style = space
8+
indent_size = 4
9+
trim_trailing_whitespace = true
10+
11+
[*.{json,yml,yaml,props,targets,csproj,slnx,xml,toml}]
12+
indent_size = 2
13+
14+
[*.md]
15+
trim_trailing_whitespace = false
16+
17+
[*.cs]
18+
# Namespaces and usings
19+
csharp_style_namespace_declarations = file_scoped:warning
20+
dotnet_sort_system_directives_first = true
21+
dotnet_separate_import_directive_groups = false
22+
dotnet_diagnostic.IDE0005.severity = warning
23+
dotnet_diagnostic.IDE0161.severity = warning
24+
25+
# Language preferences
26+
csharp_style_var_for_built_in_types = true:suggestion
27+
csharp_style_var_when_type_is_apparent = true:suggestion
28+
csharp_style_var_elsewhere = false:suggestion
29+
csharp_style_expression_bodied_methods = when_on_single_line:suggestion
30+
csharp_style_expression_bodied_properties = true:suggestion
31+
csharp_prefer_braces = when_multiline:suggestion
32+
csharp_style_prefer_primary_constructors = true:suggestion
33+
dotnet_style_prefer_collection_expression = when_types_loosely_match:suggestion
34+
csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
35+
dotnet_style_readonly_field = true:warning
36+
37+
# Naming
38+
dotnet_naming_rule.private_fields_underscore.symbols = private_fields
39+
dotnet_naming_rule.private_fields_underscore.style = underscore_camel
40+
dotnet_naming_rule.private_fields_underscore.severity = warning
41+
dotnet_naming_symbols.private_fields.applicable_kinds = field
42+
dotnet_naming_symbols.private_fields.applicable_accessibilities = private
43+
dotnet_naming_style.underscore_camel.required_prefix = _
44+
dotnet_naming_style.underscore_camel.capitalization = camel_case
45+
46+
dotnet_naming_rule.private_static_readonly.symbols = private_static_readonly_fields
47+
dotnet_naming_rule.private_static_readonly.style = pascal_case
48+
dotnet_naming_rule.private_static_readonly.severity = warning
49+
dotnet_naming_symbols.private_static_readonly_fields.applicable_kinds = field
50+
dotnet_naming_symbols.private_static_readonly_fields.applicable_accessibilities = private
51+
dotnet_naming_symbols.private_static_readonly_fields.required_modifiers = static, readonly
52+
dotnet_naming_style.pascal_case.capitalization = pascal_case
53+
54+
dotnet_naming_rule.private_const.symbols = private_const_fields
55+
dotnet_naming_rule.private_const.style = pascal_case
56+
dotnet_naming_rule.private_const.severity = warning
57+
dotnet_naming_symbols.private_const_fields.applicable_kinds = field
58+
dotnet_naming_symbols.private_const_fields.applicable_accessibilities = private
59+
dotnet_naming_symbols.private_const_fields.required_modifiers = const

‎.gitattributes‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
* text=auto eol=lf
2+
3+
*.cmd text eol=crlf
4+
*.bat text eol=crlf
5+
*.ps1 text eol=crlf
6+
7+
*.png binary
8+
*.jpg binary
9+
*.pdf binary
10+
*.whl binary

‎.github/workflows/ci.yml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
concurrency:
13+
group: ci-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
env:
17+
DOTNET_NOLOGO: true
18+
DOTNET_CLI_TELEMETRY_OPTOUT: true
19+
20+
jobs:
21+
dotnet:
22+
name: .NET (${{ matrix.os }})
23+
strategy:
24+
fail-fast: false
25+
matrix:
26+
os: [ubuntu-latest, windows-latest]
27+
runs-on: ${{ matrix.os }}
28+
steps:
29+
- uses: actions/checkout@v7
30+
31+
- uses: actions/setup-dotnet@v6
32+
with:
33+
global-json-file: global.json
34+
35+
# The integration tests build the psrunner wheel and create real Python environments with uv.
36+
- uses: astral-sh/setup-uv@v10.3.0
37+
38+
- name: Restore
39+
run: dotnet restore
40+
41+
- name: Build
42+
run: dotnet build --no-restore --configuration Release
43+
44+
- name: Test
45+
run: dotnet test --no-build --configuration Release
46+
47+
format:
48+
name: .NET format
49+
runs-on: ubuntu-latest
50+
steps:
51+
- uses: actions/checkout@v7
52+
53+
- uses: actions/setup-dotnet@v6
54+
with:
55+
global-json-file: global.json
56+
57+
- name: Verify formatting
58+
run: dotnet format --verify-no-changes
59+
60+
python-sdk:
61+
name: psrunner (${{ matrix.os }}, Python ${{ matrix.python }})
62+
strategy:
63+
fail-fast: false
64+
matrix:
65+
os: [ubuntu-latest]
66+
python: ['3.10', '3.11', '3.12', '3.13']
67+
include:
68+
# Windows only on the default version to save Actions minutes.
69+
- os: windows-latest
70+
python: '3.12'
71+
runs-on: ${{ matrix.os }}
72+
defaults:
73+
run:
74+
working-directory: python/psrunner
75+
steps:
76+
- uses: actions/checkout@v7
77+
78+
- uses: astral-sh/setup-uv@v10.3.0
79+
with:
80+
python-version: ${{ matrix.python }}
81+
82+
- name: Install
83+
run: uv sync --locked
84+
85+
- name: Lint
86+
run: |
87+
uv run ruff check src tests
88+
uv run ruff format --check src tests
89+
90+
- name: Type check
91+
run: uv run mypy
92+
93+
- name: Test
94+
run: uv run pytest

‎Directory.Build.props‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<Project>
2+
<PropertyGroup>
3+
<TargetFramework>net10.0</TargetFramework>
4+
<LangVersion>14</LangVersion>
5+
<Nullable>enable</Nullable>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
8+
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
9+
<AnalysisLevel>latest</AnalysisLevel>
10+
<Deterministic>true</Deterministic>
11+
<ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
12+
</PropertyGroup>
13+
14+
<PropertyGroup Label="Package">
15+
<VersionPrefix>0.1.0</VersionPrefix>
16+
<Authors>net0well</Authors>
17+
<Copyright>Copyright (c) 2026 net0well</Copyright>
18+
<PackageLicenseExpression>MIT</PackageLicenseExpression>
19+
<PackageProjectUrl>https://github.com/net0well/PythonScriptRunner</PackageProjectUrl>
20+
<RepositoryUrl>https://github.com/net0well/PythonScriptRunner</RepositoryUrl>
21+
<RepositoryType>git</RepositoryType>
22+
<PublishRepositoryUrl>true</PublishRepositoryUrl>
23+
<EmbedUntrackedSources>true</EmbedUntrackedSources>
24+
<IncludeSymbols>true</IncludeSymbols>
25+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
26+
<PackageTags>python;scripts;pipelines;runner;uv</PackageTags>
27+
</PropertyGroup>
28+
</Project>

‎Directory.Packages.props‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<Project>
2+
<PropertyGroup>
3+
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
4+
</PropertyGroup>
5+
<ItemGroup>
6+
<PackageVersion Include="JsonSchema.Net" Version="9.4.1" />
7+
<PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.13" />
8+
<PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.13" />
9+
<PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.13" />
10+
<PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.13" />
11+
<PackageVersion Include="Microsoft.Extensions.Diagnostics" Version="10.0.13" />
12+
<PackageVersion Include="Microsoft.Extensions.Diagnostics.Testing" Version="10.11.0" />
13+
<PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.13" />
14+
<PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.13" />
15+
<PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.13" />
16+
<PackageVersion Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.11.0" />
17+
<PackageVersion Include="Shouldly" Version="4.3.0" />
18+
<PackageVersion Include="xunit.v3" Version="4.0.2" />
19+
</ItemGroup>
20+
</Project>

‎PythonScriptRunner.slnx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<Solution>
2+
<Folder Name="/src/">
3+
<Project Path="src/PythonScriptRunner.Abstractions/PythonScriptRunner.Abstractions.csproj" />
4+
<Project Path="src/PythonScriptRunner.Core/PythonScriptRunner.Core.csproj" />
5+
</Folder>
6+
<Folder Name="/tests/">
7+
<Project Path="tests/PythonScriptRunner.Core.Tests/PythonScriptRunner.Core.Tests.csproj" />
8+
</Folder>
9+
</Solution>

‎README.md‎

Lines changed: 79 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,86 @@
11
# PythonScriptRunner
22

3-
Biblioteca .NET 10 para executar Python de forma tipada, encadeável e observável: etapas (Stages)
4-
com contrato de entrada/saída, trilhas (Pipelines), execução assíncrona com RabbitMQ, agendamento
3+
Biblioteca .NET 10 para executar Python de forma tipada, encadeável e observável: etapas (**Stages**)
4+
com contrato de entrada/saída, trilhas (**Pipelines**), execução assíncrona com RabbitMQ, agendamento
55
cron e painel Vue opcional.
66

7-
> Projeto em desenvolvimento.
7+
> Projeto em desenvolvimento. Esta versão entrega o **Core Runner** (execução síncrona de Stages) e o
8+
> SDK Python **`psrunner`**.
9+
10+
## Como funciona
11+
12+
Cada Stage declara suas entradas e saídas (12 tipos: `number`, `integer`, `decimal`, `string`, `bool`,
13+
`date`, `datetime`, `enum`, `json`, `table`, `file`, `list<T>`) e tem exatamente um script Python.
14+
O runner valida as entradas, executa o script num processo isolado (ambiente limpo, timeout, limite
15+
de memória, segredos injetados só nele), valida as saídas e devolve o resultado tipado.
16+
17+
```python
18+
# stages/progressao-termos/script.py
19+
from psrunner import stage
20+
21+
@stage
22+
def run(inputs, ctx):
23+
a1, razao, n = inputs["a1"], inputs["razao"], inputs["n"]
24+
termos = [a1 * razao**i for i in range(n)]
25+
ctx.log.info("gerados %d termos", n)
26+
return {"termos": termos}
27+
```
28+
29+
```jsonc
30+
// stages/progressao-termos/stage.json
31+
{
32+
"$schema": "https://raw.githubusercontent.com/net0well/PythonScriptRunner/main/schemas/stage.v1.json",
33+
"key": "progressao-termos",
34+
"version": 1,
35+
"name": "Termos de progressão",
36+
"inputs": [
37+
{ "name": "a1", "type": "number" },
38+
{ "name": "razao", "type": "number" },
39+
{ "name": "n", "type": "integer" }
40+
],
41+
"outputs": [ { "name": "termos", "type": "list", "itemType": "number" } ]
42+
}
43+
```
44+
45+
```csharp
46+
builder.Services
47+
.AddPythonScriptRunner()
48+
.AddFileCatalog("./psr"); // pasta com stages/<chave>/stage.json
49+
50+
// ...
51+
await using var result = await runner.RunStageAsync("progressao-termos", new { a1 = 1, razao = 2, n = 4 });
52+
result.EnsureSuccess();
53+
double[] termos = result.GetOutput<double[]>("termos"); // [1, 2, 4, 8]
54+
```
55+
56+
Stages também podem ser definidos em C# (`AddStage("chave", s => s.Script(...).Input(...).Output(...))`)
57+
e testados localmente com pytest pelo `psrunner.testing.run_stage`, sem .NET.
58+
59+
## Requisitos
60+
61+
- .NET 10 SDK
62+
- [uv](https://docs.astral.sh/uv/) no PATH (cria e cacheia um ambiente Python por conjunto de dependências)
63+
64+
## Estrutura
65+
66+
| Pasta | Conteúdo |
67+
|-------|----------|
68+
| `src/PythonScriptRunner.Abstractions` | contratos públicos (tipos de campo, `StageDefinition`, `RunResult`, `PsrFile`, interfaces) |
69+
| `src/PythonScriptRunner.Core` | catálogos (código e pasta), validação, ambientes uv, executor de processos, runner |
70+
| `python/psrunner` | SDK Python (`@stage`, `Context`, `File`, `StageError`, `psrunner.testing`, CLI) |
71+
| `schemas` | JSON Schema do `stage.json` |
72+
| `tests` | testes .NET (unitários e de integração com Python real) |
73+
74+
## Desenvolvimento
75+
76+
```bash
77+
dotnet build
78+
dotnet test --project tests/PythonScriptRunner.Core.Tests
79+
80+
cd python/psrunner
81+
uv sync
82+
uv run pytest
83+
```
884

985
## Licença
1086

‎global.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"sdk": {
3+
"version": "10.0.400",
4+
"rollForward": "latestFeature"
5+
},
6+
"test": {
7+
"runner": "Microsoft.Testing.Platform"
8+
}
9+
}

‎python/psrunner/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# psrunner
2+
3+
Python SDK for [PythonScriptRunner](https://github.com/net0well/PythonScriptRunner) stages.
4+
5+
A stage is one Python script with typed inputs and outputs. The .NET runner validates the inputs,
6+
runs the script in an isolated process and validates the outputs. `psrunner` handles the protocol,
7+
so the script only contains the logic:
8+
9+
```python
10+
from psrunner import stage
11+
12+
@stage
13+
def run(inputs, ctx):
14+
a1, ratio, n = inputs["a1"], inputs["ratio"], inputs["n"]
15+
terms = [a1 * ratio**i for i in range(n)]
16+
ctx.log.info("generated %d terms", n)
17+
return {"terms": terms}
18+
```
19+
20+
Test it locally with pytest, without .NET:
21+
22+
```python
23+
from psrunner.testing import run_stage
24+
25+
def test_terms():
26+
result = run_stage("stages/terms/script.py", {"a1": 1, "ratio": 2, "n": 4},
27+
stage_json="stages/terms/stage.json")
28+
assert result.outputs == {"terms": [1, 2, 4, 8]}
29+
```
30+
31+
Install the `pandas` extra to receive `table` inputs as `pandas.DataFrame`: `pip install psrunner[pandas]`.

0 commit comments

Comments
 (0)