{"id":13599504,"url":"https://github.com/cdfmlr/pyflowchart","last_synced_at":"2026-02-28T09:06:56.701Z","repository":{"id":37763279,"uuid":"306582856","full_name":"cdfmlr/pyflowchart","owner":"cdfmlr","description":"Python codes to Flowcharts","archived":false,"fork":false,"pushed_at":"2024-05-29T04:31:44.000Z","size":8731,"stargazers_count":384,"open_issues_count":14,"forks_count":77,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-08T22:46:15.089Z","etag":null,"topics":["flowchart","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pyflowchart/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdfmlr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-23T09:02:47.000Z","updated_at":"2025-04-07T07:29:06.000Z","dependencies_parsed_at":"2023-10-19T14:33:25.469Z","dependency_job_id":"faabd249-e397-4317-8064-cb58821539b6","html_url":"https://github.com/cdfmlr/pyflowchart","commit_stats":{"total_commits":39,"total_committers":2,"mean_commits":19.5,"dds":0.1282051282051282,"last_synced_commit":"ff0fcc8a3aff1ed36ea8f911f0b49a42e17a9327"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdfmlr%2Fpyflowchart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdfmlr%2Fpyflowchart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdfmlr%2Fpyflowchart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdfmlr%2Fpyflowchart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdfmlr","download_url":"https://codeload.github.com/cdfmlr/pyflowchart/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217145,"owners_count":21066633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flowchart","python"],"created_at":"2024-08-01T17:01:05.421Z","updated_at":"2026-01-21T06:46:27.878Z","avatar_url":"https://github.com/cdfmlr.png","language":"Python","readme":"# PyFlowchart\n\nEnglish | [机翻中文](README_zh-CN.md)\n\nPyFlowchart is a Python package that lets you:\n\n- Write flowcharts in Python.\n- Translate Python source code into flowcharts.\n\nPyFlowchart produces flowcharts in the [flowchart.js](https://github.com/adrai/flowchart.js)  flowchart DSL, a widely used textual representation of flowcharts. You can convert these flowcharts to images using [flowchart.js.org](http://flowchart.js.org), [francoislaberge/diagrams](https://github.com/francoislaberge/diagrams/#flowchart), or some markdown editors. Alternatively, we  also support an option to output the generated flowchart into a interactive HTML page.\n\n## Get PyFlowchart\n\n```sh\n$ pip install pyflowchart\n```\n\n## Quick Start\n\nWant to **flowchart your Python code in `example.py`?** Run this:\n\n```sh\n$ python -m pyflowchart example.py\n```\n\n\u003e ⚠️ PyFlowchart works with **Python 3.7+**. To check your Python version, run [`python --version`](https://docs.python.org/3/using/cmdline.html#cmdoption-version).\n\u003e\n\u003e If you have both Python 2 and Python 3 installed, you may need to use `python3` instead of `python`. This is becoming less common as [Python 2 is sunsetting](https://www.python.org/doc/sunset-python-2/).\n\nPyFlowchart will output the generated flowchart.js DSL. You can convert the output code to a rendered diagram by going to http://flowchart.js.org or using editors like Typora.\n\n**To output a HTML file** containing the generated flowchart:\n\n```sh\n$ python -m pyflowchart example.py -o example.html\n$ # open example.html\n```\n\nOpen `example.html` in your browser to see the output in graphical representation.\n\n**To specify a function (or a method in a class) to flowchartlize:**\n\n- Use the `-f` flag to specify the function or method name.\n\n```sh\n$ python -m pyflowchart example.py -f function_name\n# or\n$ python -m pyflowchart example.py -f ClassName.method_name\n```\n\nFor example, to flowchartlize the `add()` function in the `MyClass` class, you would use the following command: `python3 -m pyflowchart example.py -f MyClass.add`.\n\n🎉 **Now you are ready to flowchart your code!**\n\nTo learn more about how to use PyFlowchart, keep reading this document.\n\n## Flowchart in Python\n\nPyFlowchart lets you write flowcharts in Python, which can be automatically translated into the [flowchart.js](https://github.com/adrai/flowchart.js) DSL.\n\nThe following [flowchart.js node types](https://github.com/adrai/flowchart.js#node-types) are supported:\n\n- StartNode\n- OperationNode\n- ConditionNode\n- InputOutputNode\n- SubroutineNode\n- EndNode\n\nTo connect nodes, use the `connect()` method. For ConditionNodes, use the `connect_{yes|no}` syntax. You can optionally specify the connect_direction as a second parameter.\n\nGet a Flowchart with your start node and call its `flowchart()` method to generate flowchart.js flowchart DSL：\n\n```python\nfrom pyflowchart import *\n\nst = StartNode('a_pyflow_test')\nop = OperationNode('do something')\ncond = ConditionNode('Yes or No?')\nio = InputOutputNode(InputOutputNode.OUTPUT, 'something...')\nsub = SubroutineNode('A Subroutine')\ne = EndNode('a_pyflow_test')\n\nst.connect(op)\nop.connect(cond)\ncond.connect_yes(io)\ncond.connect_no(sub)\nsub.connect(op, \"right\")  # sub-\u003eop line starts from the right of sub\nio.connect(e)\n \nfc = Flowchart(st)\nprint(fc.flowchart())\n```\n\nOutput:\n\n```\nst0=\u003estart: start a_pyflow_test\nop1=\u003eoperation: do something\ncond2=\u003econdition: Yes or No?\nio3=\u003einputoutput: output: something...\ne5=\u003eend: end a_pyflow_test\nsub4=\u003esubroutine: A Subroutine\n\nst0-\u003eop1\nop1-\u003econd2\ncond2-\u003e\ncond2-\u003e\ncond2(yes)-\u003eio3\nio3-\u003ee5\ncond2(no)-\u003esub4\nsub4(right)-\u003eop1\n```\n\nYou can visit http://flowchart.js.org and translate the generated textual representation into SVG flow chart diagrams:\n\n![screenshot on flowchart.js page](docs/imgs/flowchart-js-org.png)\n\n(v0.3.0) You can also use `pyflowchart.output_html` to generate a page similar to the picture above:\n\n```python\noutput_html('output.html', 'a_pyflow_test', fc.flowchart())\n```\n\nBy the way, many Markdown editors, like Typora, also support this flowchart syntax. For more information, see [the Typora documentation on flowcharts]((https://support.typora.io/Draw-Diagrams-With-Markdown/#flowcharts)). If you prefer the command line, you can use [francoislaberge/diagrams]((https://github.com/francoislaberge/diagrams/#flowchart)).\n\n### Set Params to Nodes\n\nStarting with v0.2.0, you can use the `Node.set_param(key, value)` method to generate flowcharts like this:\n\n```\nelement(param1=value1,param2=value2)=\u003estart: Start\n```\n\n(See also [adrai/flowchart.js#node-specific-specifiers-by-type](https://github.com/adrai/flowchart.js#node-specific-specifiers-by-type))\n\nThere is also a shortcut to set the `align-next=no` parameter for ConditionNodes: \n\n```python\ncond = ConditionNode(\"a cond node\")\ncond.no_align_next()\n# or do this at __init__:\ncond = ConditionNode(\"a cond node\", align_next=False)\n```\n\nThis usually works with a connect_direction customization:\n\n```python\ncond.connect_yes(op, \"right\")\n```\n\nThe generated flowchart will look like:\n\n```\ncond(align-next=no)=\u003econdition: Yes or No?\n...\ncond(yes,right)-\u003eop\n```\n\n## Python to Flowchart\n\nPyFlowchart can also translate your Python code into flowcharts.\n\nFor example, let's say you have a Python file called `simple.py` with the following code:\n\n```python\ndef foo(a, b):\n    if a:\n        print(\"a\")\n    else:\n        for i in range(3):\n            print(\"b\")\n    return a + b\n```\n\nTo generate a flowchart from this code, you can run the following command in the terminal:\n\n```sh\n$ python -m pyflowchart simple.py\n\n# output flowchart code.\n```\n\nOr, in Python:\n\n```python\n\u003e\u003e\u003e from pyflowchart import Flowchart\n\u003e\u003e\u003e with open('simple.py') as f:\n...     code = f.read()\n... \n\u003e\u003e\u003e fc = Flowchart.from_code(code)\n\u003e\u003e\u003e print(fc.flowchart())\n\n# output flowchart code.\n```\n\n![simple.py to flowchart](docs/imgs/py-to-flowchart.png)\n\n## Advanced Usages\n\nAs mentioned above, we use `Flowchart.from_code` to translate Python codes into Flowcharts. The `from_code` is defined as:\n\n```python\nFlowchart.from_code(code, field=\"\", inner=True, simplify=True, conds_align=False)\n```\n\n- `code`: The Python code to be converted into a flowchart.\n- `field`: The name of a field in the code to be converted into a flowchart. If this parameter is not specified, the entire code will be converted.\n- `inner`: If `True`, the body of the field will be parsed as a nested flowchart. If `False`, the body of the field will be parsed as a single node.\n- `simplify`: If `True`, simple If and Loop statements will be simplified. For example, an If statement with a single expression will be converted into a single node.\n- `conds_align`: If `True`, consecutive If statements will be aligned in the flowchart.\n\nPyFlowchart CLI is an interface for this function:\n\n```sh\npython -m pyflowchart [-f FIELD] [-i] [--no-simplify] [--conds-align] [-o OUTPUT] code_file\n```\n\n- `-f FIELD`: The name of the field to be converted into a flowchart.\n- `-i`:  If specified, the body of the field will be parsed as a nested flowchart.\n- `--no-simplify`:  If specified, the If and Loop statements will not be simplified.\n- `--conds-align`: If specified, consecutive If statements will be aligned in the flowchart.\n- `-o OUTPUT`: If specified, output the flowchart to specific file with a format indicating by the extension name. (only support `*.html` for now)\n\n⚠️ `-o` is not a part of `Flowchart.from_code`. It's `from pyflowchar import output_html`.\n\n### field\n\nthe `field` is the path to a field (i.e. a function) you want to draw a flowchart. \n\n```python\n# example.py\nprint(\"start\")\n\ndef foo():\n    foo = \"foo\"\n\nclass Bar():\n    def buzz(self, f):\n        def g(self):\n            print(\"g\")\n            f(self)\n        return g(self)\n\nBar().buzz(foo)\nprint(\"end\")\n```\n\nFor `example.py` above, available paths are:\n\n    - \"\" (means the whole code)\n    - \"foo\"\n    - \"Bar.buzz\"\n    - \"Bar.buzz.g\"\n\nTo generate a flowchart of `Bar.buzz.g`：\n\n```python\n# Python\nfrom pyflowchart import Flowchart\nwith open('example.py') as f:\n\tcode = f.read()\nfc = Flowchart.from_code(code, field='Bar.buzz.g', inner=False)\nprint(fc.flowchart())\n```\n\nOr:\n\n```sh\n# CLI\npython -m pyflowchart example.py -f Bar.buzz.g\n```\n\nOutput result:\n\n![specify a field](docs/imgs/field.png)\n\n### inner\n\nThe `inner` parameter controls how the parser behaves. If `inner=True`, the parser will look into the field and parse its body. If `inner=False`, the parser will take the field as a single node.\n\n![pyflowchart_inner](docs/imgs/inner.png)\n\nIn CLI, the `-i` argument sets `inner=True`. The absence of `-i` argument implies `inner=False`.\n\n🔧 For developers: Techly, `inner=True` means parsing `field.body`, while `inner=False` parses `[field]`.\n\n### simplify\n\nThe `simplify` parameter controls whether to simplify If and Loop statements. When `simplify=True`, an If or Loop statements with one-line-body will be simplified into a single node.\n\nFor example, the following code:\n\n```python\n# example_simplify.py\na = 1\nif a == 1:\n    print(a)\nwhile a \u003c 4:\n    a = a + 1\n```\n\nWould be converted into the following flowchart when **simplify=True** :\n\n```python\nflowchart = Flowchart.from_code(example_simplify_py, field=\"\", inner=True)\nprint(flowchart.flowchart())\n# SH $ python -m pyflowchart example_simplify.py \n```\n\n![simplify result](docs/imgs/simplify.png)\n\nAnd with `simplify=False`:\n\n```python\nflowchart = Flowchart.from_code(example_simplify_py, field=\"\", inner=True, simplify=False)\nprint(flowchart.flowchart())\n# SH $ python -m pyflowchart --no-simplify example_simplify.py \n```\n\n![no simplify result](docs/imgs/no-simplify.png)\n\n### conds-align (Beta)\n\nThe `conds-align` parameter controls whether consecutive If statements are aligned in the flowchart. When `conds-align=True`, consecutive If statements are aligned in the flowchart.\n\n```python\n# example-conds-align.py\nif cond1:\n\top1\nif cond2:\n\top2\nif cond3:\n\top3\nop_end\n```\n\n![conds-align-result](docs/imgs/conds-align.png)\n\n**Note:** This feature is still in beta and may not work perfectly in all cases.\n\n### output html and images\n\nYou can also directly ouput the generated flowchart.js DSL into an html by adding the parameter ```-o output.html``` where you specify an output filename ending in `.html` or `.htm`.\n\n![output-html](docs/imgs/output-html.png)\n\nOpening the `output.html` in your browser will let you visualize the diagrams. You can tweak the code and click run to update the diagram. There are also links to download the current visuals as a  `.svg` or `.png` image.\n\n⚠️ The output file specified will overwrite any file that already has that name.\n\n🐍 To use this feature via Python instead of CLI, call `output_html(output_name: str, field_name: str, flowchart: str) -\u003e None`:\n\n```py\n\u003e\u003e\u003e import pyflowchart\n\u003e\u003e\u003e help(pyflowchart.output_html)\n```\n\n## Beautify Flowcharts\n\nThe flowcharts generated by PyFlowchart may not always be perfect. In these cases, you can modify the generated flowchart code yourself or consider making your Python source code more clear. Clear and beautiful Python source code will result in more beautiful flowcharts generated by PyFlowchart.\n\nAn example: If you don't like the flowchart flow direction you can tweak a condition by modifying with with directions such as:\n\n![beautify-flowchart-example](docs/imgs/beautify-example.png)\n\n## TODOs\n\n- [ ] Directly generate flowchart SVG/HTML:\n\n```sh\n$ pyflowchart example.py -o flowchart.svg\n```\n\nDepends on `node.js` and `flowchart.js`.\n\n- [ ] PyFlowchart GUI\n\nA **GUI** for PyFlowchart would be amazing. You could paste your Python code into it, and the flowchart DSL would be generated in real time, with the flowchart displayed alongside it. You could clearly see how the two are related.\n\n- [ ] ~~The Chinese README your buddies waiting for!~~ 希望有同学帮助贡献个中文 README 呀。\n- [x] Tests automation.\n\n----\n\nUnfortunately, I am too busy (pronounced as `[ˈlеizi]`——lazy) to code these ideas myself. Please [submit an issue](https://github.com/cdfmlr/pyflowchart/issues/new) to push me on. Or, PR to make it by yourself. I cannot wait to appreciate your great contribution!\n\n## References\n\n- Inspired by [Vatsha/code_to_flowchart](https://github.com/Vatsha/code_to_flowchart)\n- Based on [adrai/flowchart.js](http://flowchart.js.org), [python ast](https://docs.python.org/3/library/ast.html), [simonpercivall/astunparse](https://github.com/simonpercivall/astunparse)\n- [A blog about this project](https://clownote.github.io/2020/10/24/blog/PyFlowchart/)\n\n## License\n\nCopyright 2020-2023 CDFMLR. All rights reserved.\n\nLicensed under the MIT License.\n\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdfmlr%2Fpyflowchart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdfmlr%2Fpyflowchart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdfmlr%2Fpyflowchart/lists"}