ProcessPiper

repository·main·Indexed 41 days ago

An open-source Python library for 'Business Process Diagram as Code'. It enables the generation of professional business process diagrams using either a programmatic Python API (via the ProcessMap class) or a custom English-like syntax called PiperFlow. It supports BPMN-like elements including various Events, Activities (Tasks, Subprocesses), and Gateways (Exclusive, Parallel, Inclusive, Event), and exports diagrams to PNG, SVG, and .bpmn XML formats.

Tokens: 11K
Snippets: 33
Records: 51
Agent score: 52%

What's inside ProcessPiper

Use Gateway elements to define process logic
main
Gateways are diamond-shaped elements used in business process diagrams to control the flow of activities. ProcessPiper provides several specialized gateway classes that automatically handle their visual representation (symbols) when the draw method is called with a Painter instance.
Available Gateway types:
- Exclusive: An exclusive gateway, represented by a diamond with an 'X' symbol.
- Parallel: A parallel gateway, represented by a diamond with a '+' symbol.
- Inclusive: An inclusive gateway, represented by a diamond with an 'O' symbol.
- EventGateway: An event gateway, represented by a diamond containing a pentagon inside concentric circles.
https://github.com/csgoh/processpiper/blob/main/src/processpiper/gateway.py

Generate diagrams using the ProcessPiper Python API

main

For programmatic control, use the ProcessMap class and its associated methods. This approach allows you to build complex diagrams using Python objects, providing fine-grained control over pools, lanes, and element types.

Core components:

ProcessMap(title, colour_theme): The root container for the diagram.
add_pool(name): Adds a new pool to the map.
add_lane(name): Adds a lane to a pool or the map.
add_element(label, type): Adds an element (Event, Activity, or Gateway) to a lane.
element.connect(target, label): Creates a directed connection between elements, supporting method chaining.
draw(): Renders the diagram.
save(filename): Exports the diagram to a file (supports PNG and SVG).

from processpiper import ProcessMap, EventType, ActivityType, GatewayType

with ProcessMap(
    "Sample Test Process", colour_theme="BLUEMOUNTAIN") as my_process_map:
    with my_process_map.add_lane("End User") as lane1:
        start = lane1.add_element("Start", EventType.START)
        enter_keyword = lane1.add_element("Enter Keyword", ActivityType.TASK)

    with my_process_map.add_pool("System Search") as pool1:
        with pool1.add_lane("Database System") as lane2:
            login = lane2.add_element("Login", ActivityType.TASK)
            search_records = lane2.add_element("Search Records", ActivityType.TASK)
            result_found = lane2.add_element("Result Found?", GatewayType.EXCLUSIVE)
            display_result = lane2.add_element("Display Result", ActivityType.TASK)
            logout = lane2.add_element("Logout", ActivityType.TASK)
            end = lane2.add_element("End", EventType.END)

        with pool1.add_lane("Log System") as lane3:
            log_error = lane3.add_element("Log Error", ActivityType.TASK)

    start.connect(login, "User \nAuthenticates").connect(
        enter_keyword, "Authenticated"
    ).connect(search_records, "Search Criteria")
    search_records.connect(result_found, "Result").connect(display_result, "Yes")
    display_result.connect(logout).connect(end)
    result_found.connect(log_error, "No").connect(display_result)

    my_process_map.set_footer("Generated by ProcessPiper")
    my_process_map.draw()
    my_process_map.save("my_process_map.png")

Generate diagrams using PiperFlow syntax

main

You can generate business process diagrams by providing a string written in PiperFlow syntax to the render function. This method allows you to define titles, colour themes, pools, lanes, and elements (using specific bracket notations) in a human-readable text format.

Key syntax elements include:

title: to set the diagram title.
colourtheme: to set the visual theme.
pool: to define a process pool.
lane: to define a lane within a pool.
(element) for events, [element] for tasks, and <element> for gateways.
element1->element2: label to define connections with labels.

from processpiper.text2diagram import render

input_syntax = """
title: Sample Test Process
colourtheme: BLUEMOUNTAIN
    lane: End User
        (start) as start
        [Enter Keyword] as enter_keyword
        (end) as end
pool: System Search
    lane: Database System
        [Login] as login
        [Search Records] as search_records
        <Result Found?> as result_found
        [Display Result] as display_result
        [Logout] as logout
    lane: Log System
        [Log Error] as log_error

start->login: User \nAuthenticate
login->enter_keyword: Authenticated
enter_keyword->search_records: Search Criteria
search_records->result_found: Result
result_found->display_result: Yes
display_result->logout->end
result_found->log_error: No
log_error->display_result

footer: Generated by ProcessPiper
"""

render(input_syntax, "my_process_map.png")

Create painters using PainterFactory
main
The PainterFactory class provides a centralized way to instantiate different types of painters by name. It caches created painters to reuse them if requested with the same parameters.
To use it, call get_painter(painter_name, width, height). The painter_name should correspond to the prefix of the painter class (e.g., `
https://github.com/csgoh/processpiper
Connect shapes using the connect() method
main
You can establish a relationship between two shapes using the connect method on a Shape instance. This method creates a Connection object that links the source shape to a target shape.
Key behaviors:
- Connection Limit: An element can have a maximum of 4 combined incoming and outgoing connections. If this limit is exceeded, a TooManyConnectionsException is raised. It is recommended to use a gateway to combine connections if you hit this limit.
- Return Value: The method returns the target shape, allowing for method chaining.
- Connection Types: The default connection_type is `
https://github.com/csgoh/processpiper
Supported diagram elements and themes
main
ProcessPiper supports a variety of BPMN-like elements and visual styles:
Supported Elements
- Events: Start, End, Timer, Intermediate, Message, Signal, Conditional, and Link.
- Activities: Task, Subprocess.
- Gateways: Inclusive, Exclusive, Parallel, and Event.
Supported Colour Themes
- Default
- GREYWOOF
- BLUEMOUNTAIN
- ORANGEPEEL
- GREENTURTLE
- SUNFLOWER
- PURPLERAIN
- RUBYRED
- TEALWATERS
- SEAFOAMS
Export Formats
- PNG
- SVG
- .bpmn XML
https://github.com/csgoh/processpiper/blob/main/README.md
Draw connections and arrows between boxes
main
The Painter base class provides high-level methods for drawing connections between two points (typically the faces of boxes).
- draw_line_and_arrow: Draws a line and an arrow between two boxes. It handles calculating right-angle points for elbow connections and placing text labels.
- draw_connection: A lower-level method that takes a list of points (representing the path of the connection) and draws the line, label, and arrow head.
Parameters for connection styling:
- connection_style: `
https://github.com/csgoh/processpiper
ProcessMap validation errors
main
When calling draw(), the ProcessMap validates the integrity of your diagram. The following exceptions may be raised:
- ValueError: Raised if the process map does not contain a title.
- EmptyProcessMapException: Raised if there are no pools/lanes defined, or if a pool contains a lane with no shapes.
- UnconnectedElementException: Raised if an element is defined but has no incoming or outgoing connections.
- DanglingElementException: Raised if a non-event element (like a task/shape) has no incoming connection.
https://github.com/csgoh/processpiper/blob/main/src/processpiper/processmap.py
Position and draw a Title
main
To render a Title on a diagram, you must first set its position using set_draw_position and then call draw.
1. set_draw_position(x, y, painter): This method calculates the title's dimensions based on the provided Painter and sets the internal Coordinate to the specified x and y values. It returns a tuple containing (x_pos, y_pos, width, height).
2. draw(): This method uses the internal painter and the previously set coordinates to render the text onto the diagram.
```
# Assuming 'painter' is an initialized Painter instance
title = Title(name="Process Map")

# 1. Set position and calculate dimensions
x, y, w, h = title.set_draw_position(100, 50, painter)

# 2. Render the title
title.draw()
```
https://github.com/csgoh/processpiper/blob/main/src/processpiper/title.py
Use PNGPainter for raster diagram generation
main
The PNGPainter class is a wrapper for the Pillow library, used to generate raster images (PNG). It supports drawing shapes, text, and connections.
Key capabilities:
- Boxes: draw_box (rectangular) and draw_rounded_box.
- Shapes: draw_circle, draw_polygon, and draw_dot.
- Lines: draw_line (supports solid or dashed styles).
- Text: draw_text and specialized draw_box_with_text or draw_box_with_vertical_text.
- Output: Use save_surface(filename) to save the result to a PNG file.
```
from processpiper.painter import PNGPainter

painter = PNGPainter(width=800, height=600)
painter.draw_box(x=10, y=10, width=100, height=50, box_fill_colour="#FFFFFF", box_outline_colour="black", box_outline_width=2)
painter.draw_text(x=15, y=25, text="Hello World", font="Arial", font_size=12, font_colour="black")
painter.save_surface("output.png")
```
https://github.com/csgoh/processpiper/blob/main/src/processpiper/painter.py
Add a lane to a Pool
main
Use the add_lane method on a Pool instance to create and append a new Lane. If specific styling arguments are not provided, the lane will inherit default values from the painter associated with the pool.
Arguments:
- lane_name (str): The name of the lane.
- font (str, optional): Lane text font. Defaults to "".
- font_size (int, optional): Lane text font size. Defaults to 0.
- font_colour (str, optional): Lane text font colour. Defaults to "".
- fill_colour (str, optional): Lane fill colour. Defaults to "".
- text_alignment (str, optional): Lane text alignment. Defaults to "".
- background_fill_colour (str, optional): Lane background fill colour. Defaults to "".
Returns:
- Lane: The newly created Lane object.
```
lane = my_pool.add_lane(
    lane_name="Sales",
    font="Arial",
    font_size=12,
    fill_colour="#FF0000"
)
```
https://github.com/csgoh/processpiper/blob/main/src/processpiper/pool.py
Initialize and use the ProcessMap class
main
The ProcessMap class is the central entry point for creating business process diagrams. You can use it as a context manager to ensure proper lifecycle management. When initializing, you can specify the diagram's title, dimensions, and output format.
Initialization Parameters:
- title (str): The title of the process map. Defaults to <Process Map Title>.
- width (int): Width of the canvas. Defaults to 5000.
- height (int): Height of the canvas. Defaults to 5000.
- auto_size (bool): If True, the canvas will resize to fit the content. Defaults to True.
- colour_theme (str): The color palette to use (e.g., "DEFAULT").
- painter_type (str): The output format (e.g., "png").
```
from processpiper.processmap import ProcessMap

with ProcessMap(title="My Business Process", painter_type="png") as pm:
    # Build your diagram here
    pm.draw()
    pm.save("output.png")
```
https://github.com/csgoh/processpiper/blob/main/src/processpiper/processmap.py

ProcessPiper

What's inside ProcessPiper

Supported Elements

Supported Colour Themes

Export Formats