pyflowchart

There is a planned feature to directly generate flowchart SVG or HTML files from a Python script using the CLI. This feature will require node.js and flowchart.js to be installed on your system.

$ pyflowchart example.py -o flowchart.svg

When generating flowcharts from Python code, you can control the level of detail using the simplify parameter.

• simplify=True: Collapses logic into more concise operation nodes (e.g., combining a condition and its action into a single node).
• simplify=False: Provides a granular breakdown of every logical step, including explicit condition nodes and subroutine nodes for actions.

# Example of how simplification affects output logic
# result(simplify=True) produces condensed operation nodes
# result(simplify=False) produces detailed condition and subroutine nodes

You can attempt to generate flowcharts directly as SVG or HTML files using the command line. Note that this feature requires node.js and flowchart.js to be installed on your system.

$ pyflowchart example.py -o flowchart.svg

Install the package using pip to enable both the CLI and the Python API.

$ pip install pyflowchart

Flowcharts generated by PyFlowchart may require manual adjustments to improve readability. You can improve the output in two ways:

1. Tweak the DSL directly: Modify the generated flowchart DSL (Domain Specific Language) to adjust layout or logic representation.
2. Simplify Python source: Remove non-algorithmic code, such as defensive engineering guards or input validation checks, to produce a cleaner, more focused diagram.

For example, you can change the flow direction of a condition branch by adding a direction specifier to the DSL.

Use the -f flag to target a specific function or a method within a class using dotted notation.

# For a function:
$ python -m pyflowchart example.py -f function_name

# For a method in a class:
$ python -m pyflowchart example.py -f ClassName.method_name

If the generated flowchart is too complex or visually unappealing, consider the following strategies:

1. Simplify the source Python code: Remove defensive engineering code that is irrelevant to the core algorithm (e.g., input validation, error handling). Flowcharts should represent the algorithm's logic, not the implementation details required for machine execution.
2. Modify the DSL directly: You can manually edit the generated Domain Specific Language (DSL) to refine the output.
3. Add direction qualifiers: If you are unhappy with the flow of conditional branches, you can add direction qualifiers to the connections in the DSL to control the layout.

To output a rendered, interactive HTML file instead of raw DSL text, use the -o flag.

$ python -m pyflowchart example.py -o example.html

Install PyFlowchart using pip. It requires Python 3.7 or higher (tested on 3.7 through 3.14).

$ pip install pyflowchart

You can quickly generate a flowchart from a Python file using the command line. By default, this prints the flowchart.js DSL to stdout.

Basic usage:

$ python -m pyflowchart example.py
# or if on PATH:
$ pyflowchart example.py

Requirements:

• Python 3.7+
• PyFlowchart is tested on Python 3.7 through 3.14.

A TransparentNode is a virtual node used to facilitate connections without adding a visible node to the flowchart.js output. It is primarily used to connect parents to children directly (e.g., parent->child) when working with NodesGroup or complex branching where a real node isn't desired.

• connect(sub_node, *params): Updates the virtual node to point to a new child with optional connection parameters.
• CondYN: A specialized subclass of TransparentNode used specifically for ConditionNode branches (e.g., cond(yes)->next). While CondYN is still available for compatibility, it is recommended to use TransparentNode for new implementations.

The If class is a NodesGroup representing if statements. It manages the branching logic for both the if body and the else (or elif) body.

Structure: If $\rightarrow$ IfCondition $\rightarrow$ (yes) $\rightarrow$ if-body $\rightarrow$ tails. $\quad$ $\searrow$ (no) $\rightarrow$ else-body $\rightarrow$ tails.

Simplification: If simplify=True is passed, an if statement with no else block and a single-line body is collapsed into a single OperationNode (e.g., operation if condition).