Python DSL for writing PlantUML sequence diagram
Project description
Napkin
Napkin is a tool to "write" sequence diagrams effectively as Python code.
Motivation
The sequence diagrams are useful tool to capture the behavioural aspect of the design. PlantUML is a great tool to draw nice sequence diagrams with simple human readable plain text.
However, the syntax of PlantUML is hard to use when there are nested calls, where lifeline with multiple activation/deactivation are involved. Unfortunately, this situation is quite common in sequence diagram for S/W.
For example, consider the following common sequence diagram,
which is from Figure 4.2, UML Distilled 3E:
The PlainUML script for the diagram will be as follows:
@startuml
participant User
participant Order
participant OrderLine
participant Product
participant Customer
User -> Order : calculatePrice()
activate Order
Order -> OrderLine : calculatePrice()
activate OrderLine
OrderLine -> Product : getPrice(quantity:number)
OrderLine -> Customer : getDiscountedValue(Order)
activate Customer
Customer -> Order : getBaseValue()
activate Order
Customer <-- Order: value
deactivate Order
OrderLine <-- Customer: discountedValue
deactivate Customer
deactivate OrderLine
deactivate Order
@enduml
It is quite hard to follow especially as there are multiple level of nested activation/deactivation.
What if we express the same thing as the following Python code ?
@napkin.seq_diagram()
def distributed_control(c):
user = c.object('User')
order = c.object('Order')
orderLine = c.object('OrderLine')
product = c.object('Product')
customer = c.object('Customer')
with user:
with order.calculatePrice():
with orderLine.calculatePrice():
product.getPrice('quantity:number')
with customer.getDiscountedValue(order):
order.getBaseValue().ret('value')
c.ret('discountedValue')
distributed_control
is normal function accepting a context object, c
to access APIs.
The function defines objects and the control starts with user
object, which then calls orderLine.calculatePrice()
.
Basically, the sequence diagram is expressed as "almost" normal python code.
There are several advantages in using Python instead of using other special syntax language:
- Easy to write/maintain scripts for the correct diagrams
- Many common mistakes are detected as normal Python error. For example, method call to an undefined object will be just normal Python error.(This can be even checked by IDE without running scripts).
- Any Python editor can become sequence diagram editor
- There can be many interesting usages by taking advantage of Python as general language. For example, we can build a library for patterns.
Installation
Install and update using pip
$ pip install napkin
Hello world
Write a simple script called hello.py
as follows:
import napkin
@napkin.seq_diagram()
def hello_world(c):
user = c.object('user')
world = c.object('world')
with user:
world.hello()
Then, the following command will generate hello_world.puml
:
$ napkin hello.py
Usages
Command line
usage: napkin [-h] [--output-format {plantuml,plantuml_png,plantuml_svg,plantuml_txt}] [--output-dir DIR] [--version] [--raw-header-file FILE]
[--server-url URL]
srcs [srcs ...]
Generate UML sequence diagram from Python code
positional arguments:
srcs Python file or directory containing diagram functions
optional arguments:
-h, --help show this help message and exit
--output-format {plantuml,plantuml_png,plantuml_svg,plantuml_txt}, -f {plantuml,plantuml_png,plantuml_svg,plantuml_txt}
--output-dir DIR, -o DIR
--version show program's version number and exit
--raw-header-file FILE, -H FILE
file to copy its contents right after @startuml. It is mainly for changing styles
--server-url URL (only for plantuml_png/svg/txt format) Default is the public server
Supported output formats:
plantuml : PlantUML script (default)
plantuml_png : PlantUML script and PNG image
plantuml_svg : PlantUML script and SVG image
plantuml_txt : PlantUML script and ASCII art text
Standalone code to generate diagrams
Instead of passing napkin
binary Python files, we can generate diagrams simply by running
the Python source code containing the diagrams as follows:
import napkin
@napkin.seq_diagram()
def hello_world(c):
...
if __name__ == '__main__':
napkin.generate()
napkin.generate(output_format='plantuml', output_dir='.')
will generate all the diagrams described in the same file.
Generate image files using PlantUML server
Napkin can generate PNG/SVG image or ASCII art text files by asking PlantUML server.
In order to generate image file, image format needs to be specified as plantuml_<png|svg|txt>
, which will generate image file along with puml file.
$ napkin -f plantuml_png hello.py
As default, the public server is used and it can be changed by --server-url
.
Python script examples
Most usage examples are available here.
Changelogs
A new feature or fix will be avaialbe here.
Misc
Helper tool to convert PlantUML text files to image files
As Napkin has a functionality to generate image files from PlantUML text file, a
simple script, napkin_plantuml
is provided to use PlantUML server to generate
images.
For example, in order to generate hello.png
image from hello.puml
file:
$ napkin_plantuml hello.puml hello.png
Emacs org babel support
In order to use napkin
as literate programming tool ob-napkin
package is supported for Emacs.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.