百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
N

napkin

> 编程语言
开源

Python 作为用于写 PlantUML 序列图的 DSL

198 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

Python 作为用于写 PlantUML 序列图的 DSL

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:

plantuml
@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 ?

python

@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

bash
$ pip install napkin

Hello world

Write a simple script called hello.py as follows:

python
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:

bash
$ napkin hello.py

Usages

Command line

…

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:

python

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_, which will generate image file along with puml file.

bash
$ 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:

bash
$ 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.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Pythonplantuml-generatorpythonuml-sequence-diagram

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言