PyUML Generator
      
Preview and export UML class diagrams from Python source without leaving Visual Studio Code. PyUML Generator analyzes source text locally, builds a versioned UML model, and renders an interactive diagram without importing or executing your project.
PyUML Generator is pre-1.0 software. Version 1.0 remains a later compatibility milestone.
Quick start
- Open a Python repository in VS Code.
- In Explorer, right-click the repository root or any directory and select PyUML: Preview Folder Class Diagram.
- To diagram one file or a selection of Python files, right-click the file or selection and choose PyUML: Preview Class Diagram.
- Use the preview to search, filter, change the layout, navigate to source, and export the diagram as PlantUML, Mermaid, JSON, SVG, or PNG.
You can also open the Command Palette with Ctrl+Shift+P (Cmd+Shift+P on macOS) and run PyUML: Preview Class Diagram, PyUML: Preview Folder Class Diagram, PyUML: Preview Workspace Class Diagram, or PyUML: Export Class Diagram....
Features
| Capability |
0.3.x support |
| Analysis |
Static Tree-sitter analysis; Python is never imported or executed |
| Scope |
Current file, selected files, folder, workspace, and multi-root workspace |
| Classifiers |
Classes, abstract classes, dataclasses, protocols, enums, and TypedDict |
| Members |
Attributes, properties, constructors, sync/async methods, parameters, and returns |
| Relationships |
Inheritance, realization, association, aggregation, composition, and dependency |
| Types |
Generics, unions, optionals, literals, callables, tuples, aliases, and forward references |
| Preview |
Search, filters, outline, zoom/pan/fit, direction, source navigation, and refresh modes |
| Export |
PlantUML (.puml), Mermaid (.mmd), PyUML JSON, portable SVG, and PNG |
| AI assistants |
Native VS Code MCP server with read-only workspace and supplied-source diagram tools |
| Workspace |
Local, remote Extension Host, Restricted Mode, multi-root, and virtual workspace.fs sources |
Relationship inference is heuristic. Confidence and diagnostic information remain available so incomplete or ambiguous source does not silently look authoritative.
Supported Python syntax
The tested syntax baseline is Python 3.10 through 3.12. PyUML does not require an installed Python runtime; syntax support comes from the bundled parser. Modern annotations, X | None, built-in generics, protocols, dataclasses, TypedDict, Self, PEP 695 type parameters, and type aliases are covered.
Dynamic runtime behavior cannot be reconstructed safely from text. See supported syntax and limitations for details.
AI assistants and MCP
PyUML registers a bundled MCP server through VS Code's native MCP extension API. In a trusted file-based workspace, AI assistants can call two read-only tools:
generate_class_diagram: analyze workspace-relative Python files or folders, or the complete workspace.generate_class_diagram_from_source: analyze Python source already supplied in the request.
Both tools return PlantUML, Mermaid, or canonical PyUML JSON without writing files, executing Python, loading project dependencies, or making network requests. Paths are confined to the workspace and file-count, source-size, and result-size limits are enforced.
Start and use the MCP server
Open a trusted, file-based Python workspace in VS Code.
Open the Command Palette with Ctrl+Shift+P (Cmd+Shift+P on macOS).
Run MCP: List Servers.
Select PyUML Generator (workspace-name).
Select Start Server and approve VS Code's trust prompt.
Open VS Code Chat in Agent mode and open the tools picker.
Enable PyUML's generate_class_diagram and generate_class_diagram_from_source tools.
Ask the assistant to generate a diagram. For example:
- “Generate a Mermaid class diagram for the
commerce folder using PyUML.”
- “Generate PlantUML for the Python source in this chat using PyUML.”
To stop, restart, inspect output, or change trust for the server, run MCP: List Servers again and select the PyUML server. The MCP SERVERS section in the Extensions sidebar focuses on Marketplace and configuration-installed servers; PyUML's dynamically provided server might not appear there. Use MCP: List Servers to verify and manage it.
The native provider requires VS Code 1.101 or newer. It is available for local, WSL, Dev Container, and Remote SSH file workspaces. Virtual workspaces do not expose a local stdio server, and VS Code disables agents in Restricted Mode.
Settings
| Setting |
Default |
Purpose |
pyuml.analysis.include |
**/*.py |
Included folder/workspace globs |
pyuml.analysis.exclude |
common generated/environment folders |
Excluded globs |
pyuml.analysis.maxFiles |
2000 |
Maximum files in one request |
pyuml.analysis.maxSourceBytes |
5242880 |
Maximum UTF-8 bytes per source file |
pyuml.analysis.maxClassifiers |
5000 |
Maximum classifiers retained |
pyuml.analysis.maxRelationships |
10000 |
Maximum relationships retained |
pyuml.analysis.cacheSize |
2000 |
In-memory analyzed-file cache size |
pyuml.analysis.showExternalTypes |
false |
Show placeholders for types outside the scope |
pyuml.relationships.inferenceMode |
balanced |
conservative, balanced, or aggressive inference |
pyuml.members.showPrivate |
true |
Include private/protected members |
pyuml.members.showDunder |
false |
Include non-constructor dunder members |
pyuml.preview.layoutDirection |
topDown |
topDown or leftRight layout |
pyuml.preview.updateMode |
onSave |
manual, onSave, or debounced live refresh |
pyuml.preview.theme |
auto |
Automatic, light, dark, or high-contrast rendering |
pyuml.render.maxRelationships |
2000 |
Preview relationship rendering bound |
pyuml.packages.groupBy |
module |
Group text exports by module or not at all |
pyuml.export.defaultFormat |
plantuml |
Default Quick Export text format |
pyuml.export.outputDirectory |
empty |
Workspace-relative Quick Export directory |
pyuml.export.fileNamePattern |
${scope}.class-diagram.${format} |
Safe export naming pattern |
pyuml.export.includeAbsoluteSourceUris |
false |
Include absolute URIs in JSON exports |
pyuml.export.pngScale |
2 |
PNG output scale (1, 2, or 3) |
pyuml.export.pngBackground |
white |
White or transparent PNG background |
pyuml.logging.level |
info |
Output-channel detail |
Privacy and security
- Analysis and rendering are local to the VS Code Extension Host/webview.
- PyUML does not execute Python, load project dependencies, or invoke project tools.
- PyUML makes no product network requests and contains no telemetry in
0.3.x.
- Source code is not persisted by default. Analysis facts and preview state are held in memory.
- Absolute source URIs are omitted from JSON exports unless explicitly enabled.
- The diagnostic summary contains only versions, safe settings, counts, and diagnostic codes.
Read the complete privacy statement, security policy, and webview threat review.
Troubleshooting
- No Python files found: check
pyuml.analysis.include, pyuml.analysis.exclude, and the selected scope.
- Diagram is truncated: narrow the scope or review the
maxFiles, maxClassifiers, maxRelationships, and preview relationship settings.
- A relationship is missing or ambiguous: enable external types, try a broader inference mode, and review PyUML diagnostic codes.
- Quick Export does nothing: set
pyuml.export.outputDirectory to a workspace-relative directory.
- Preview is stale: run PyUML: Refresh Preview or change
pyuml.preview.updateMode.
Run PyUML: Show Output for local logs. Run PyUML: Copy Diagnostic Summary before opening an issue; the copied summary excludes source, symbol names, diagnostic messages, and paths. See the diagnostic-code catalog.
Migration from 0.0.2
The legacy Generate UML Class Diagram command routes to the new export flow and shows a one-time migration notice. The old _UML.txt output is no longer produced by default. Use Preview and choose an explicit export format instead.
Compatibility and known limitations
The declared minimum is VS Code 1.101. PyUML runs in the workspace Extension Host, including common remote scenarios, and declares support for Restricted Mode and virtual workspaces. The automated and manual status is tracked in the compatibility matrix.
Runtime-created classes, arbitrary metaprogramming, dynamic setattr, monkey-patching, and framework behavior requiring execution are intentionally not evaluated. Conditional declarations may be included without evaluating their condition. Large or highly connected diagrams are bounded to protect Extension Host responsiveness.
Development
See CONTRIBUTING.md for local setup, Development Host instructions, example test journeys, and automated quality gates. Architecture and delivery details are in the project plan.
License
Licensed under the Apache License 2.0.
| |
