Welcome to plantuml’s documentation!

Plantuml is a library for generating UML diagrams from a simple text markup language.

This is a simple python remote client interface to a plantuml server using the same custom encoding used by most other plantuml clients. Python was missing from the list, and while there are other plantuml python libraries, like sphinxcontrib-plantuml, they require downloading and installing the java executable and spawning a shell subprocesses.

This client defaults to the public plantuml server, but can be used against any server.

Project Links:

• Documentation
• PyPi
• GitHub

Commandline Use

sample.txt

title Authentication Sequence

Alice->Bob: Authentication Request
note right of Bob: Bob thinks about it
Bob->Alice: Authentication Response

commandline

$ ls
sample.txt
$ python -m plantuml sample.txt
sample.txt: success.
$ ls
sample.png  sample.txt

sample.png

Library

class plantuml.PlantUML(url='http://www.plantuml.com/plantuml/img/', basic_auth={}, form_auth={}, http_opts={}, request_opts={})

Connection to a PlantUML server with optional authentication.

All parameters are optional.

Parameters:

• url (str) – URL to the PlantUML server image CGI. defaults to http://www.plantuml.com/plantuml/img/
• basic_auth (dict) – This is if the plantuml server requires basic HTTP authentication. Dictionary containing two keys, ‘username’ and ‘password’, set to appropriate values for basic HTTP authentication.
• form_auth (dict) – This is for plantuml server requires a cookie based webform login authentication. Dictionary containing two primary keys, ‘url’ and ‘body’. The ‘url’ should point to the login URL for the server, and the ‘body’ should be a dictionary set to the form elements required for login. The key ‘method’ will default to ‘POST’. The key ‘headers’ defaults to {‘Content-type’:’application/x-www-form-urlencoded’}. Example: form_auth={‘url’: ‘http://example.com/login/‘, ‘body’: { ‘username’: ‘me’, ‘password’: ‘secret’}
• http_opts (dict) – Extra options to be passed off to the httplib2.Http() constructor.
• request_opts (dict) – Extra options to be passed off to the httplib2.Http().request() call.

get_url(plantuml_text)

Return the server URL for the image. You can use this URL in an IMG HTML tag.

Parameters:plantuml_text (str) – The plantuml markup to render Returns:the plantuml server image URL

processes(plantuml_text)

Processes the plantuml text into the raw PNG image data.

Parameters:plantuml_text (str) – The plantuml markup to render Returns:the raw image data

processes_file(filename, outfile=None, errorfile=None)

Take a filename of a file containing plantuml text and processes it into a .png image.

Parameters:

• filename (str) – Text file containing plantuml markup
• outfile (str) – Filename to write the output image to. If not supplied, then it will be the input filename with the file extension replaced with ‘.png’.
• errorfile (str) – Filename to write server html error page to. If this is not supplined, then it will be the input filename with the extension replaced with ‘_error.html’.

Returns:

True if the image write succedded, False if there was an error written to errorfile.

exception plantuml.PlantUMLConnectionError

Error connecting or talking to PlantUML Server.

exception plantuml.PlantUMLError

Error in processing.

exception plantuml.PlantUMLHTTPError(response, content, *args, **kwdargs)

Request to PlantUML server returned HTTP Error.

plantuml.SERVER_URL = 'http://www.plantuml.com/plantuml/img/'

Default plantuml service url

plantuml.deflate_and_encode(plantuml_text)

zlib compress the plantuml text and encode it for the plantuml server.

plantuml.encode(data)

encode the plantuml data which may be compresses in the proper encoding for the plantuml server

License

Copyright (c) 2013, Doug Napoleone All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Indices and tables

• Index
• Search Page