first commit
This commit is contained in:
Beyhan Oğur
@@ -0,0 +1,328 @@
|
||||
# Python Integration
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
</cite>
|
||||
|
||||
## Table of Contents
|
||||
1. [Introduction](#introduction)
|
||||
2. [Project Structure](#project-structure)
|
||||
3. [Core Components](#core-components)
|
||||
4. [Architecture Overview](#architecture-overview)
|
||||
5. [Detailed Component Analysis](#detailed-component-analysis)
|
||||
6. [Dependency Analysis](#dependency-analysis)
|
||||
7. [Performance Considerations](#performance-considerations)
|
||||
8. [Troubleshooting Guide](#troubleshooting-guide)
|
||||
9. [Conclusion](#conclusion)
|
||||
10. [Appendices](#appendices)
|
||||
|
||||
## Introduction
|
||||
This document explains how Python scripting is integrated into ClassicAssist.Avalonia using Python.NET (pythonnet). It covers the runtime initialization, execution environment setup, memory management across C# and Python contexts, the exposed API surface for macro scripts, IntelliSense and debugging support, practical automation patterns, performance considerations, and troubleshooting guidance.
|
||||
|
||||
## Project Structure
|
||||
The Python integration spans multiple projects:
|
||||
- ClassicAssist.Avalonia: Avalonia UI host that initializes the engine and exposes platform-specific invokers/dispatchers.
|
||||
- ClassicAssist.Shared: Shared logic including macro management and invocation infrastructure.
|
||||
- ClassicAssist: Legacy WPF project containing some Python-related assets and completion data used by the editor.
|
||||
|
||||
Key files related to Python integration:
|
||||
- Project configuration includes Python.NET dependencies.
|
||||
- Engine entry points initialize the Python runtime and expose APIs.
|
||||
- Macro manager and invoker orchestrate script execution.
|
||||
- Completion data supports IntelliSense for Python macros.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "ClassicAssist.Avalonia"
|
||||
A_Proj["ClassicAssist.Avalonia.csproj"]
|
||||
A_Engine["Engine.cs"]
|
||||
A_Program["Program.cs"]
|
||||
A_UIInvoker["AvaloniaUIInvoker.cs"]
|
||||
A_Dispatcher["AvaloniaDispatcher.cs"]
|
||||
end
|
||||
subgraph "ClassicAssist.Shared"
|
||||
S_MacroMgr["MacroManager.cs"]
|
||||
S_MacroInv["MacroInvoker.cs"]
|
||||
S_SysWriter["SystemMessageTextWriter.cs"]
|
||||
end
|
||||
subgraph "ClassicAssist"
|
||||
C_Completion["PythonCompletionData.cs"]
|
||||
end
|
||||
A_Proj --> A_Engine
|
||||
A_Program --> A_Engine
|
||||
A_Engine --> S_MacroMgr
|
||||
S_MacroMgr --> S_MacroInv
|
||||
S_MacroInv --> S_SysWriter
|
||||
A_Engine --> A_UIInvoker
|
||||
A_Engine --> A_Dispatcher
|
||||
A_Engine -.-> C_Completion
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
## Core Components
|
||||
- Python runtime initialization: The application bootstraps the Python runtime via Python.NET and configures import paths so that user macro scripts can import shared modules or third-party packages as needed.
|
||||
- Execution environment: The engine sets up a dedicated Python context per macro run, binds C# types and helpers, and provides a safe execution pipeline with logging and error capture.
|
||||
- Macro orchestration: MacroManager loads macro entries and delegates execution to MacroInvoker, which coordinates environment setup, script compilation/execution, and result handling.
|
||||
- UI thread bridging: AvaloniaUIInvoker and AvaloniaDispatcher ensure that any UI updates from Python-invoked C# code are marshaled onto the Avalonia UI thread safely.
|
||||
- IntelliSense and debugging: PythonCompletionData supplies completion metadata to the editor; debug support leverages standard Python.NET debugging facilities when available.
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
## Architecture Overview
|
||||
The following diagram shows how Python.NET integrates with the Avalonia host and macro system.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Host as "Program.cs"
|
||||
participant Engine as "Engine.cs"
|
||||
participant PyNET as "Python.NET Runtime"
|
||||
participant MacroMgr as "MacroManager.cs"
|
||||
participant Invoker as "MacroInvoker.cs"
|
||||
participant Writer as "SystemMessageTextWriter.cs"
|
||||
participant UIInv as "AvaloniaUIInvoker.cs"
|
||||
participant Disp as "AvaloniaDispatcher.cs"
|
||||
Host->>Engine : Initialize()
|
||||
Engine->>PyNET : Initialize Python runtime
|
||||
Engine->>Engine : Configure import paths and bindings
|
||||
MacroMgr->>Invoker : Execute(macroEntry)
|
||||
Invoker->>PyNET : Create execution context
|
||||
Invoker->>PyNET : Load and execute macro script
|
||||
PyNET-->>Invoker : Results / Exceptions
|
||||
Invoker->>Writer : Write logs and messages
|
||||
Invoker->>UIInv : Marshal UI updates
|
||||
UIInv->>Disp : Invoke on Avalonia dispatcher
|
||||
Disp-->>UIInv : UI update completed
|
||||
Invoker-->>MacroMgr : Execution status
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Program.cs](file://ClassicAssist.Avalonia/Program.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
|
||||
## Detailed Component Analysis
|
||||
|
||||
### Python.NET Initialization and Environment Setup
|
||||
- Runtime bootstrap: The engine initializes the Python runtime once during application startup and ensures it remains alive for the process lifetime.
|
||||
- Import path configuration: Paths to user macro directories and shared libraries are added to sys.path so scripts can import modules without full paths.
|
||||
- Binding exposure: Selected C# classes and methods are exposed to Python through pythonnet’s automatic interop, enabling direct calls from macro scripts.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Application Startup"]) --> InitPy["Initialize Python.NET Runtime"]
|
||||
InitPy --> ConfigPaths["Configure sys.path and imports"]
|
||||
ConfigPaths --> BindAPIs["Expose C# APIs to Python"]
|
||||
BindAPIs --> Ready(["Execution Environment Ready"])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
|
||||
### Macro Execution Pipeline
|
||||
- Loading: MacroManager enumerates and loads macro entries (including Python scripts).
|
||||
- Invocation: MacroInvoker prepares an isolated execution context, injects bindings, and runs the script.
|
||||
- Output: SystemMessageTextWriter captures output and logs for display in the UI.
|
||||
- Threading: Any UI interactions are marshaled via AvaloniaUIInvoker and AvaloniaDispatcher to avoid cross-thread exceptions.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant MM as "MacroManager.cs"
|
||||
participant MI as "MacroInvoker.cs"
|
||||
participant PY as "Python.NET"
|
||||
participant SW as "SystemMessageTextWriter.cs"
|
||||
participant UI as "AvaloniaUIInvoker.cs"
|
||||
participant D as "AvaloniaDispatcher.cs"
|
||||
MM->>MI : Execute(pythonScript)
|
||||
MI->>PY : Create context and load script
|
||||
MI->>SW : Redirect stdout/stderr
|
||||
MI->>PY : Run script
|
||||
PY-->>MI : Return results or raise exception
|
||||
MI->>UI : Marshal UI updates if needed
|
||||
UI->>D : Dispatch on UI thread
|
||||
D-->>UI : Completed
|
||||
MI-->>MM : Status and logs
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
|
||||
**Section sources**
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
- [SystemMessageTextWriter.cs](file://ClassicAssist.Shared/Data/Macros/SystemMessageTextWriter.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
|
||||
### Memory Management Between C# and Python
|
||||
- Reference semantics: Objects passed between C# and Python are wrapped by Python.NET. Long-lived references should be minimized to prevent GC pressure.
|
||||
- Disposal: When interacting with unmanaged resources (e.g., file handles), prefer explicit disposal patterns on the C# side and release references promptly in Python.
|
||||
- Cross-context lifetimes: Avoid holding strong references to Python objects in long-running C# caches; use weak references or periodic cleanup strategies where appropriate.
|
||||
- Thread affinity: Some C# objects may require access on specific threads; use the provided UI invoker/dispatcher to marshal calls safely.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Python API Surface for Macros
|
||||
The Python API surface consists of C# types and methods exposed to Python via Python.NET. Typical categories include:
|
||||
- Game state queries: Accessing entities, items, skills, spells, and other UO-related data.
|
||||
- Actions: Targeting, movement, casting, vendor operations, and other gameplay actions.
|
||||
- Utilities: Logging, timers, lists, dictionaries, and helper functions.
|
||||
- UI interaction: Safe UI updates via the Avalonia invoker.
|
||||
|
||||
For exact class names, methods, and properties, refer to the binding layer in the engine and the completion data used by the editor.
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
### IntelliSense Configuration and Code Completion
|
||||
- Completion data source: PythonCompletionData provides metadata about available symbols, method signatures, and parameter hints.
|
||||
- Editor integration: The editor consumes this metadata to provide autocomplete and signature help for Python macro scripts.
|
||||
- Customization: Extend completion data by adding new bindings in the engine and updating completion definitions accordingly.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PythonCompletionData {
|
||||
+ProvideCompletions()
|
||||
+GetSymbolInfo(name)
|
||||
+GetSignatureHelp(member)
|
||||
}
|
||||
class Engine {
|
||||
+ExposeBindings()
|
||||
+UpdateCompletionData()
|
||||
}
|
||||
Engine --> PythonCompletionData : "updates"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
|
||||
**Section sources**
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
|
||||
### Debugging Support for Python Scripts
|
||||
- Standard debugging: Use Python.NET-compatible debuggers (e.g., VS Code with Python extension) attached to the process.
|
||||
- Breakpoints: Place breakpoints in Python scripts; ensure symbols are loaded and the correct interpreter path is configured.
|
||||
- Logging: Leverage SystemMessageTextWriter to capture outputs and errors for post-mortem analysis.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
### Practical Automation Patterns
|
||||
Common patterns for Python macros:
|
||||
- Conditional logic: Branch based on game state (e.g., health thresholds, inventory counts).
|
||||
- File I/O: Read/write configuration or logs using Python’s built-in file operations.
|
||||
- Network requests: Perform HTTP calls for external integrations or telemetry.
|
||||
- Timed loops: Use timers or sleep-based loops to poll state changes.
|
||||
|
||||
Example references:
|
||||
- Conditional branching and loops: See macro examples under the macros directory.
|
||||
- File operations: Refer to sample scripts demonstrating read/write patterns.
|
||||
- Network requests: Look at samples using urllib or requests within Python macros.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Dependency Analysis
|
||||
The Python integration depends on Python.NET and the macro subsystem. The following diagram highlights key dependencies.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
PNET["Python.NET (pythonnet)"]
|
||||
CA_Av["ClassicAssist.Avalonia"]
|
||||
CA_Shared["ClassicAssist.Shared"]
|
||||
CA_WPF["ClassicAssist"]
|
||||
CA_Av --> PNET
|
||||
CA_Av --> CA_Shared
|
||||
CA_Shared --> CA_WPF
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
**Section sources**
|
||||
- [ClassicAssist.Avalonia.csproj](file://ClassicAssist.Avalonia/ClassicAssist.Avalonia.csproj)
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [MacroManager.cs](file://ClassicAssist.Shared/Data/Macros/MacroManager.cs)
|
||||
- [MacroInvoker.cs](file://ClassicAssist.Shared/Data/Macros/MacroInvoker.cs)
|
||||
|
||||
## Performance Considerations
|
||||
- Minimize cross-boundary calls: Batch operations and reduce frequent C# calls from Python to avoid overhead.
|
||||
- Prefer local computations: Perform heavy processing in Python when possible; only call C# for necessary interop.
|
||||
- Reuse objects: Cache frequently accessed C# objects in Python to avoid repeated lookups.
|
||||
- Avoid blocking the UI thread: Always marshal UI updates via the Avalonia invoker/dispatcher.
|
||||
- Manage references: Release large objects and avoid circular references between C# and Python contexts.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
|
||||
## Troubleshooting Guide
|
||||
Common issues and resolutions:
|
||||
- Python runtime not found: Ensure Python.NET is correctly installed and the expected Python version is available on PATH.
|
||||
- Import errors: Verify sys.path configuration and that macro directories are included.
|
||||
- Cross-thread exceptions: Use AvaloniaUIInvoker and AvaloniaDispatcher for UI updates from Python.
|
||||
- Memory leaks: Check for lingering references to Python objects in C# caches; implement periodic cleanup.
|
||||
- IntelliSense missing symbols: Update PythonCompletionData and rebuild to refresh editor metadata.
|
||||
|
||||
**Section sources**
|
||||
- [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs)
|
||||
- [AvaloniaUIInvoker.cs](file://ClassicAssist.Avalonia/AvaloniaUIInvoker.cs)
|
||||
- [AvaloniaDispatcher.cs](file://ClassicAssist.Avalonia/AvaloniaDispatcher.cs)
|
||||
- [PythonCompletionData.cs](file://ClassicAssist/Data/Macros/PythonCompletionData.cs)
|
||||
|
||||
## Conclusion
|
||||
ClassicAssist.Avalonia integrates Python scripting via Python.NET, providing a robust execution environment, safe UI threading, and rich IntelliSense support. By following best practices for memory management and performance, developers can create efficient and maintainable Python macros that interact seamlessly with the game and UI.
|
||||
|
||||
## Appendices
|
||||
- Example macro locations: Explore the macros directory for sample Python scripts demonstrating conditional logic, file I/O, and network requests.
|
||||
- API reference: Consult the engine’s binding layer and completion data for the complete list of exposed classes, methods, and properties.
|
||||
|
||||
[No sources needed since this section provides general guidance]
|
||||
Reference in New Issue
Block a user