Python PlantUML Client

0.3.0 · active · verified Thu Apr 16

The `plantuml` Python library provides a client to generate PlantUML diagrams from Python code. It can interact with a local PlantUML JAR file (requiring Java) or a remote PlantUML server (including the public one). The current version is 0.3.0, with updates occurring infrequently but the project is actively maintained for compatibility and minor enhancements.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'java'
```
cause The `plantuml` library, when configured for local processing via `jar_path`, attempts to execute the `java` command, but Java is not installed or not found in the system's PATH.

fix Install a Java Development Kit (JDK) or Java Runtime Environment (JRE) on your system. Ensure the `java` executable is available in your system's PATH environment variable. Verify by running `java -version` in your terminal.
```
requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
```
cause This (or similar `ConnectionError`) typically occurs when the PlantUML server specified in the `url` parameter (or the default public server) is unreachable, down, or a network issue (e.g., firewall, proxy) is preventing the connection.

fix Check your internet connection. If using a custom `url`, verify the PlantUML server is running and accessible from your machine. If using the default public server, try again later or consider hosting your own PlantUML server.
```
Diagram output is blank, incomplete, or shows syntax errors within the image.
```
cause The PlantUML diagram code provided to the `processes()` method contains syntax errors or is malformed, preventing PlantUML from generating a correct diagram.

fix Validate your PlantUML code. Use an online PlantUML editor (e.g., `plantuml.com/text`) to paste and preview your code, identifying and fixing any syntax issues before passing it to the `plantuml` library.

Warnings

gotcha Local diagram generation (using `jar_path`) requires Java to be installed and accessible in your system's PATH, as well as a downloaded PlantUML JAR file.
Fix: Ensure Java is installed (`java -version`) and `jar_path` points to a valid PlantUML.jar file. Alternatively, use remote generation by specifying a `url` or relying on the default public server.
gotcha The default remote server `http://www.plantuml.com/plantuml` might be subject to rate limits, uptime issues, or network restrictions.
Fix: For production or high-volume usage, consider hosting your own PlantUML server and providing its URL to the `PlantUML` constructor: `PlantUML(url='http://your-server:8080/plantuml')`.
gotcha When using a custom `url` for a remote server, ensure the URL is correct and the PlantUML server is running and accessible from where your Python script is executed.
Fix: Verify the `url` parameter. Test connectivity to the PlantUML server URL directly (e.g., in a browser or using `curl`). Ensure no firewalls are blocking the connection.

Install

pip install plantuml Install latest version

Imports

PlantUML
```
from plantuml import PlantUML
```

Quickstart

This quickstart demonstrates how to initialize the PlantUML client and generate a basic PNG diagram using the default public PlantUML server. The generated image data is then saved to a file.

from plantuml import PlantUML

# Initialize PlantUML client.
# By default, it uses the public server: http://www.plantuml.com/plantuml
# For a local server, provide the jar_path or custom url:
# pu = PlantUML(jar_path='/path/to/plantuml.jar')
# pu = PlantUML(url='http://localhost:8080/plantuml')
pu = PlantUML() # Uses the default public server

puml_code = """
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
"""

try:
    # Generate the diagram image data (PNG by default)
    image_data = pu.processes(puml_code)

    # Define the output filename
    output_filename = "quickstart_diagram.png"

    # Save the image data to a file
    with open(output_filename, "wb") as f:
        f.write(image_data)

    print(f"Successfully generated PlantUML diagram to {output_filename}")

except Exception as e:
    print(f"An error occurred during diagram generation: {e}")
    print("Please ensure you have an internet connection if using the default server,")
    print("or that your local PlantUML setup (Java + JAR) is correct.")

view raw JSON →