# apw-labs/pyre-python-engine architecture

> Architecture diagram of the GitHub repository apw-labs/pyre-python-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apw-labs/pyre-python-engine
- Repository: https://github.com/apw-labs/pyre-python-engine

## Overview

This Rust library bridges an IDE or other caller to Python environments: it discovers and validates interpreters, can create a virtual environment, and supervises Python execution with streamed output and timeout cleanup. The graph separates discovery sources, validation, environment creation, and process supervision. Internal calls are supported by the excerpts; the broader IDE workflow is documented in the README, and no IDE implementation is present in this repository.

Main entry points: [`src/interpreter.rs`](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs) (Interpreter scanner), [`src/supervisor.rs`](https://github.com/apw-labs/pyre-python-engine/blob/main/src/supervisor.rs) (Process supervisor), [`src/lib.rs`](https://github.com/apw-labs/pyre-python-engine/blob/main/src/lib.rs) (Public API), [`src/error.rs`](https://github.com/apw-labs/pyre-python-engine/blob/main/src/error.rs) (Engine errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Interpreter discovery"]
  node_scanner["Interpreter scanner<br/>[interpreter.rs]"]
  node_workspace_envs["Workspace env scan<br/>[interpreter.rs]"]
  node_conda_scan["Conda discovery<br/>[interpreter.rs]"]
  node_pyenv_scan["pyenv discovery<br/>[interpreter.rs]"]
  node_path_scan["PATH lookup<br/>[interpreter.rs]"]
  node_candidate_set["Candidate set<br/>[interpreter.rs]"]
  node_validator["Interpreter validation<br/>[interpreter.rs]"]
end

subgraph group_environments["Environment management"]
  node_venv_manager["Venv manager<br/>[venv.rs]"]
end

subgraph group_execution["Process execution"]
  node_supervisor["Process supervisor<br/>[supervisor.rs]"]
  node_stream_pump["Output stream pump<br/>[supervisor.rs]"]
end

subgraph group_shared["Shared API and errors"]
  node_public_api["Public API<br/>[lib.rs]"]
  node_engine_errors["Engine errors<br/>[error.rs]"]
end

node_caller(("IDE / caller"))
node_python["Python executables"]
node_process_tree["Process tree"]

node_caller -->|"requests discovery"| node_scanner
node_scanner -->|"scans workspace"| node_workspace_envs
node_scanner -->|"queries environments"| node_conda_scan
node_scanner -->|"queries versions"| node_pyenv_scan
node_scanner -->|"looks up Python"| node_path_scan
node_workspace_envs -->|"adds candidates"| node_candidate_set
node_conda_scan -->|"adds candidates"| node_candidate_set
node_pyenv_scan -->|"adds candidates"| node_candidate_set
node_path_scan -->|"adds candidates"| node_candidate_set
node_scanner -->|"validates candidates"| node_validator
node_validator -->|"runs inspection"| node_python
node_caller -.->|"creates environment"| node_venv_manager
node_venv_manager -->|"runs venv module"| node_python
node_caller -->|"spawns script"| node_supervisor
node_supervisor -->|"launches script"| node_python
node_supervisor -->|"starts pumps"| node_stream_pump
node_stream_pump -->|"sends output"| node_supervisor
node_supervisor -->|"terminates on timeout"| node_process_tree
node_supervisor -->|"cleans up on drop"| node_process_tree
node_public_api -->|"exports"| node_scanner
node_public_api -->|"exports"| node_supervisor
node_public_api -->|"exports"| node_engine_errors
node_scanner -->|"returns errors"| node_engine_errors
node_supervisor -->|"returns errors"| node_engine_errors

click node_scanner "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_workspace_envs "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_conda_scan "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_pyenv_scan "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_path_scan "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_candidate_set "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_validator "https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs"
click node_venv_manager "https://github.com/apw-labs/pyre-python-engine/blob/main/src/venv.rs"
click node_supervisor "https://github.com/apw-labs/pyre-python-engine/blob/main/src/supervisor.rs"
click node_stream_pump "https://github.com/apw-labs/pyre-python-engine/blob/main/src/supervisor.rs"
click node_public_api "https://github.com/apw-labs/pyre-python-engine/blob/main/src/lib.rs"
click node_engine_errors "https://github.com/apw-labs/pyre-python-engine/blob/main/src/error.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scanner,node_workspace_envs,node_conda_scan,node_pyenv_scan,node_path_scan,node_candidate_set,node_validator toneBlue
class node_venv_manager toneAmber
class node_supervisor,node_stream_pump toneMint
class node_public_api,node_engine_errors toneRose
class node_caller,node_python,node_process_tree toneIndigo
```

## Components

### Interpreter discovery

- [Interpreter scanner](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [Workspace env scan](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [Conda discovery](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [pyenv discovery](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [PATH lookup](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [Candidate set](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [Interpreter validation](https://github.com/apw-labs/pyre-python-engine/blob/main/src/interpreter.rs): `src/interpreter.rs`

### Environment management

- [Venv manager](https://github.com/apw-labs/pyre-python-engine/blob/main/src/venv.rs): `src/venv.rs`

### Process execution

- [Process supervisor](https://github.com/apw-labs/pyre-python-engine/blob/main/src/supervisor.rs): `src/supervisor.rs`
- [Output stream pump](https://github.com/apw-labs/pyre-python-engine/blob/main/src/supervisor.rs): `src/supervisor.rs`

### Shared API and errors

- [Public API](https://github.com/apw-labs/pyre-python-engine/blob/main/src/lib.rs): `src/lib.rs`
- [Engine errors](https://github.com/apw-labs/pyre-python-engine/blob/main/src/error.rs): `src/error.rs`

### Other components

- **IDE / caller**
- **Python executables**
- **Process tree**

## Connections

- IDE / caller → Interpreter scanner: requests discovery (evidence: `README.md`)
- Interpreter scanner → Workspace env scan: scans workspace (evidence: `src/interpreter.rs`)
- Interpreter scanner → Conda discovery: queries environments (evidence: `src/interpreter.rs`)
- Interpreter scanner → pyenv discovery: queries versions (evidence: `src/interpreter.rs`)
- Interpreter scanner → PATH lookup: looks up Python (evidence: `src/interpreter.rs`)
- Workspace env scan → Candidate set: adds candidates (evidence: `src/interpreter.rs`)
- Conda discovery → Candidate set: adds candidates (evidence: `src/interpreter.rs`)
- pyenv discovery → Candidate set: adds candidates (evidence: `src/interpreter.rs`)
- PATH lookup → Candidate set: adds candidates (evidence: `src/interpreter.rs`)
- Interpreter scanner → Interpreter validation: validates candidates (evidence: `src/interpreter.rs`)
- Interpreter validation → Python executables: runs inspection (evidence: `src/interpreter.rs`)
- IDE / caller → Venv manager: creates environment
- Venv manager → Python executables: runs venv module (evidence: `src/venv.rs`)
- IDE / caller → Process supervisor: spawns script (evidence: `README.md`)
- Process supervisor → Python executables: launches script (evidence: `src/supervisor.rs`)
- Process supervisor → Output stream pump: starts pumps (evidence: `src/supervisor.rs`)
- Output stream pump → Process supervisor: sends output (evidence: `src/supervisor.rs`)
- Process supervisor → Process tree: terminates on timeout (evidence: `src/supervisor.rs`)
- Process supervisor → Process tree: cleans up on drop (evidence: `src/supervisor.rs`)
- Public API → Interpreter scanner: exports (evidence: `src/lib.rs`)
- Public API → Process supervisor: exports (evidence: `src/lib.rs`)
- Public API → Engine errors: exports (evidence: `src/lib.rs`)
- Interpreter scanner → Engine errors: returns errors (evidence: `src/interpreter.rs`)
- Process supervisor → Engine errors: returns errors (evidence: `src/supervisor.rs`)
