|
1 | 1 | # PythonScriptRunner |
2 | 2 |
|
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 |
5 | 5 | cron e painel Vue opcional. |
6 | 6 |
|
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 | +``` |
8 | 84 |
|
9 | 85 | ## Licença |
10 | 86 |
|
|
0 commit comments