Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 4
trim_trailing_whitespace = true

[*.{json,yml,yaml,props,targets,csproj,slnx,xml,toml}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

[*.cs]
# Namespaces and usings
csharp_style_namespace_declarations = file_scoped:warning
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false
dotnet_diagnostic.IDE0005.severity = warning
dotnet_diagnostic.IDE0161.severity = warning

# Language preferences
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_style_var_elsewhere = false:suggestion
csharp_style_expression_bodied_methods = when_on_single_line:suggestion
csharp_style_expression_bodied_properties = true:suggestion
csharp_prefer_braces = when_multiline:suggestion
csharp_style_prefer_primary_constructors = true:suggestion
dotnet_style_prefer_collection_expression = when_types_loosely_match:suggestion
csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
dotnet_style_readonly_field = true:warning

# Naming
dotnet_naming_rule.private_fields_underscore.symbols = private_fields
dotnet_naming_rule.private_fields_underscore.style = underscore_camel
dotnet_naming_rule.private_fields_underscore.severity = warning
dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private
dotnet_naming_style.underscore_camel.required_prefix = _
dotnet_naming_style.underscore_camel.capitalization = camel_case

dotnet_naming_rule.private_static_readonly.symbols = private_static_readonly_fields
dotnet_naming_rule.private_static_readonly.style = pascal_case
dotnet_naming_rule.private_static_readonly.severity = warning
dotnet_naming_symbols.private_static_readonly_fields.applicable_kinds = field
dotnet_naming_symbols.private_static_readonly_fields.applicable_accessibilities = private
dotnet_naming_symbols.private_static_readonly_fields.required_modifiers = static, readonly
dotnet_naming_style.pascal_case.capitalization = pascal_case

dotnet_naming_rule.private_const.symbols = private_const_fields
dotnet_naming_rule.private_const.style = pascal_case
dotnet_naming_rule.private_const.severity = warning
dotnet_naming_symbols.private_const_fields.applicable_kinds = field
dotnet_naming_symbols.private_const_fields.applicable_accessibilities = private
dotnet_naming_symbols.private_const_fields.required_modifiers = const
10 changes: 10 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
* text=auto eol=lf

*.cmd text eol=crlf
*.bat text eol=crlf
*.ps1 text eol=crlf

*.png binary
*.jpg binary
*.pdf binary
*.whl binary
94 changes: 94 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
name: CI

on:
push:
branches: [main]
pull_request:
branches: [main]

permissions:
contents: read

concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true

env:
DOTNET_NOLOGO: true
DOTNET_CLI_TELEMETRY_OPTOUT: true

jobs:
dotnet:
name: .NET (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v7

- uses: actions/setup-dotnet@v6
with:
global-json-file: global.json

# The integration tests build the psrunner wheel and create real Python environments with uv.
- uses: astral-sh/setup-uv@v10.3.0

- name: Restore
run: dotnet restore

- name: Build
run: dotnet build --no-restore --configuration Release

- name: Test
run: dotnet test --no-build --configuration Release

format:
name: .NET format
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7

- uses: actions/setup-dotnet@v6
with:
global-json-file: global.json

- name: Verify formatting
run: dotnet format --verify-no-changes

python-sdk:
name: psrunner (${{ matrix.os }}, Python ${{ matrix.python }})
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest]
python: ['3.10', '3.11', '3.12', '3.13']
include:
# Windows only on the default version to save Actions minutes.
- os: windows-latest
python: '3.12'
runs-on: ${{ matrix.os }}
defaults:
run:
working-directory: python/psrunner
steps:
- uses: actions/checkout@v7

- uses: astral-sh/setup-uv@v10.3.0
with:
python-version: ${{ matrix.python }}

- name: Install
run: uv sync --locked

- name: Lint
run: |
uv run ruff check src tests
uv run ruff format --check src tests

- name: Type check
run: uv run mypy

- name: Test
run: uv run pytest
28 changes: 28 additions & 0 deletions Directory.Build.props
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
<Project>
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<LangVersion>14</LangVersion>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
<AnalysisLevel>latest</AnalysisLevel>
<Deterministic>true</Deterministic>
<ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
</PropertyGroup>

<PropertyGroup Label="Package">
<VersionPrefix>0.1.0</VersionPrefix>
<Authors>net0well</Authors>
<Copyright>Copyright (c) 2026 net0well</Copyright>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageProjectUrl>https://github.com/net0well/PythonScriptRunner</PackageProjectUrl>
<RepositoryUrl>https://github.com/net0well/PythonScriptRunner</RepositoryUrl>
<RepositoryType>git</RepositoryType>
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<EmbedUntrackedSources>true</EmbedUntrackedSources>
<IncludeSymbols>true</IncludeSymbols>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
<PackageTags>python;scripts;pipelines;runner;uv</PackageTags>
</PropertyGroup>
</Project>
20 changes: 20 additions & 0 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="JsonSchema.Net" Version="9.4.1" />
<PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.Diagnostics" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.Diagnostics.Testing" Version="10.11.0" />
<PackageVersion Include="Microsoft.Extensions.Hosting.Abstractions" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.13" />
<PackageVersion Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.11.0" />
<PackageVersion Include="Shouldly" Version="4.3.0" />
<PackageVersion Include="xunit.v3" Version="4.0.2" />
</ItemGroup>
</Project>
9 changes: 9 additions & 0 deletions PythonScriptRunner.slnx
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<Solution>
<Folder Name="/src/">
<Project Path="src/PythonScriptRunner.Abstractions/PythonScriptRunner.Abstractions.csproj" />
<Project Path="src/PythonScriptRunner.Core/PythonScriptRunner.Core.csproj" />
</Folder>
<Folder Name="/tests/">
<Project Path="tests/PythonScriptRunner.Core.Tests/PythonScriptRunner.Core.Tests.csproj" />
</Folder>
</Solution>
82 changes: 79 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,86 @@
# PythonScriptRunner

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

> Projeto em desenvolvimento.
> Projeto em desenvolvimento. Esta versão entrega o **Core Runner** (execução síncrona de Stages) e o
> SDK Python **`psrunner`**.

## Como funciona

Cada Stage declara suas entradas e saídas (12 tipos: `number`, `integer`, `decimal`, `string`, `bool`,
`date`, `datetime`, `enum`, `json`, `table`, `file`, `list<T>`) e tem exatamente um script Python.
O runner valida as entradas, executa o script num processo isolado (ambiente limpo, timeout, limite
de memória, segredos injetados só nele), valida as saídas e devolve o resultado tipado.

```python
# stages/progressao-termos/script.py
from psrunner import stage

@stage
def run(inputs, ctx):
a1, razao, n = inputs["a1"], inputs["razao"], inputs["n"]
termos = [a1 * razao**i for i in range(n)]
ctx.log.info("gerados %d termos", n)
return {"termos": termos}
```

```jsonc
// stages/progressao-termos/stage.json
{
"$schema": "https://raw.githubusercontent.com/net0well/PythonScriptRunner/main/schemas/stage.v1.json",
"key": "progressao-termos",
"version": 1,
"name": "Termos de progressão",
"inputs": [
{ "name": "a1", "type": "number" },
{ "name": "razao", "type": "number" },
{ "name": "n", "type": "integer" }
],
"outputs": [ { "name": "termos", "type": "list", "itemType": "number" } ]
}
```

```csharp
builder.Services
.AddPythonScriptRunner()
.AddFileCatalog("./psr"); // pasta com stages/<chave>/stage.json

// ...
await using var result = await runner.RunStageAsync("progressao-termos", new { a1 = 1, razao = 2, n = 4 });
result.EnsureSuccess();
double[] termos = result.GetOutput<double[]>("termos"); // [1, 2, 4, 8]
```

Stages também podem ser definidos em C# (`AddStage("chave", s => s.Script(...).Input(...).Output(...))`)
e testados localmente com pytest pelo `psrunner.testing.run_stage`, sem .NET.

## Requisitos

- .NET 10 SDK
- [uv](https://docs.astral.sh/uv/) no PATH (cria e cacheia um ambiente Python por conjunto de dependências)

## Estrutura

| Pasta | Conteúdo |
|-------|----------|
| `src/PythonScriptRunner.Abstractions` | contratos públicos (tipos de campo, `StageDefinition`, `RunResult`, `PsrFile`, interfaces) |
| `src/PythonScriptRunner.Core` | catálogos (código e pasta), validação, ambientes uv, executor de processos, runner |
| `python/psrunner` | SDK Python (`@stage`, `Context`, `File`, `StageError`, `psrunner.testing`, CLI) |
| `schemas` | JSON Schema do `stage.json` |
| `tests` | testes .NET (unitários e de integração com Python real) |

## Desenvolvimento

```bash
dotnet build
dotnet test --project tests/PythonScriptRunner.Core.Tests

cd python/psrunner
uv sync
uv run pytest
```

## Licença

Expand Down
9 changes: 9 additions & 0 deletions global.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"sdk": {
"version": "10.0.400",
"rollForward": "latestFeature"
},
"test": {
"runner": "Microsoft.Testing.Platform"
}
}
31 changes: 31 additions & 0 deletions python/psrunner/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# psrunner

Python SDK for [PythonScriptRunner](https://github.com/net0well/PythonScriptRunner) stages.

A stage is one Python script with typed inputs and outputs. The .NET runner validates the inputs,
runs the script in an isolated process and validates the outputs. `psrunner` handles the protocol,
so the script only contains the logic:

```python
from psrunner import stage

@stage
def run(inputs, ctx):
a1, ratio, n = inputs["a1"], inputs["ratio"], inputs["n"]
terms = [a1 * ratio**i for i in range(n)]
ctx.log.info("generated %d terms", n)
return {"terms": terms}
```

Test it locally with pytest, without .NET:

```python
from psrunner.testing import run_stage

def test_terms():
result = run_stage("stages/terms/script.py", {"a1": 1, "ratio": 2, "n": 4},
stage_json="stages/terms/stage.json")
assert result.outputs == {"terms": [1, 2, 4, 8]}
```

Install the `pandas` extra to receive `table` inputs as `pandas.DataFrame`: `pip install psrunner[pandas]`.
Loading
Loading