Package: napkin
NapkinNapkin is a tool to "write" sequence diagrams effectively as Python code.MotivationThe sequence diagrams are useful tool to capture the behavioural aspect of the
design.PlantUMLis 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 fromFigure 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
@endumlIt 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()defdistributed_control(c):user=c.object('User')order=c.object('Order')orderLine=c.object('OrderLine')product=c.object('Product')customer=c.object('Customer')withuser:withorder.calculatePrice():withorderLine.calculatePrice():product.getPrice('quantity:number')withcustomer.getDiscountedValue(order):order.getBaseValue().ret('value')c.ret('discountedValue')distributed_controlis normal function accepting a context object,cto access APIs.
The function defines objects and the control starts withuserobject, which then callsorderLine.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 diagramsMany 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 editorThere can be many interesting usages by taking advantage of Python as general
language. For example, we can build a library for patterns.InstallationInstall and update usingpip$pipinstallnapkinHello worldWrite a simple script calledhello.pyas follows:importnapkin@napkin.seq_diagram()defhello_world(c):user=c.object('user')world=c.object('world')withuser:world.hello()Then, the following command will generatehello_world.puml:$napkinhello.pyUsagesCommand lineusage: 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 textStandalone code to generate diagramsInstead of passingnapkinbinary Python files, we can generate diagrams simply by running
the Python source code containing the diagrams as follows:importnapkin@napkin.seq_diagram()defhello_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 serverNapkin 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 asplantuml_<png|svg|txt>, which will generate image file along with puml file.$napkin-fplantuml_pnghello.pyAs default, the public server is used and it can be changed by--server-url.Python script examplesMost usage examples are availablehere.ChangelogsA new feature or fix will be avaialbehere.MiscHelper tool to convert PlantUML text files to image filesAs Napkin has a functionality to generate image files from PlantUML text file, a
simple script,napkin_plantumlis provided to use PlantUML server to generate
images.For example, in order to generatehello.pngimage fromhello.pumlfile:$napkin_plantumlhello.pumlhello.pngEmacs org babel supportIn order to usenapkinas literate programming toolob-napkin
packageis supported for Emacs.