Package: py2cfg
py2cfgPython3 control flow graph generatorpy2cfgis a package that can be used to produce control flow graphs (CFGs) for Python 3 programs.
The CFGs it generates can be easily visualised with graphviz.
That graphical analysis is the main purpose of the module.ExamplesBelow is an example of a piece of code that generates the Fibonacci sequence and the CFG produced for it with py2cfg:# fib.pydeffib():a,b=0,1whileTrue:yieldaa,b=b,a+bfib_gen=fib()for_inrange(10):next(fib_gen)classSort:defmerge(self,l,r):i=0j=0arr=[]size=len(l)+len(r)forkinrange(0,size):lSentinel=i==len(l)rSentinel=j==len(r)ifi==len(l):arr.append(r[j])j+=1elifj==len(r):arr.append(l[i])i+=1elifl[i]<=r[j]:arr.append(l[i])i+=1else:arr.append(r[j])j+=1returnarrdefmerge_sort(self,src):n=len(src)/2l=src[0:n]r=src[n:]iflen(l)>1:l=self.merge_sort(l)iflen(r)>1:r=self.merge_sort(r)src=self.merge(l,r)returnsrcdefinsertion_sort(self,src):j=1forjinrange(1,len(src)):i=j-1key=src[j]whilei>=0andsrc[i]>=key:src[i+1]=src[i]i=i-1src[i+1]=keyreturnsrcIt can also be used interactively with pudb3.More examplesAfter cloning, see./examples/for some code snippets to run this on.
To generate_cfg.svgor_cfg.pngor_cfg.pdfimages for each example, clone this repo and run the following command in the repo root directory:gitclonerepourlcdintorepodirectory
./generate_examples.shInstallation via pip3Note: installation is not required, but is handy.To install simply runpip3installpy2cfg--useror clone this repo and pip install locallygit clone <url>
cd intoprojectdirectory
pip3 install . --userUsageIt can be used three ways:Run via shell commandIf you have installed, then the default command is py2cfg:py2cfg<file.py>This will create a<file>_cfg.svgfile, which contains the colored cfg of the file.
If you don't want to install via pip, the innards of the py2cfg command can be run right from the repo:Run with pudb3py2cfg<file.py>--debugVia wrapperIf you have not installed, then you can run a script present in the repo,py2cfg/_runner.py, to directly generate a CFG of a Python program and visualise it:cdintoreporootdir
python3py2cfg/_runner.pypath_to_my_code.pyVia importWhether or not you have installed (easier if you have), to use py2cfg in your own python code, simply import the module in your Python interpreter or program.
Then use thepy2cfg.CFGBuilderclass to build CFGs.
For example, to build the CFG of a program defined in a file with the path./example.py, the following code can be used:frompy2cfgimportCFGBuildercfg=CFGBuilder().build_from_file('example','./example.py')This returns the CFG for the code in./example.pyin thecfgvariable.
The first parameter ofbuild_from_fileis the desired name for the CFG, and the second one is the path to the file containing the source code.
The produced CFG can then be visualised with:cfg.build_visual('exampleCFG','pdf')The first paramter ofbuild_visualis the desired name for the DOT file produced by the method, and the second one is the format to use for the visualisation.ContributingIssuesModifications and improvements to this project are driven via Gitlab-Issues.
Check them out to create one, or fix one.Unit testsOur minimal tests are run via Gitlab-CI.
Make sure you don't break them!Type hintingNote: any new additions to the project should adhere to type-hinting standards enforced by:mypy--strict--disallow-any-explicit*.pyThis is a current issue -- yes we need to fix some things...StyleTo maximize the ability of version control to pin down changes, and keep the style consistent, before you make any commit to the project, run this strict code auto-formatter:blackpy2cfg/*.pyDo so automatically with pre-commit:https://black.readthedocs.io/en/stable/version_control_integration.htmlProject historyNote: py2cfg took it's original inspiration from an older cfg project, though has long since diverged:https://github.com/coetaur0/staticfghttps://pypi.org/project/staticfg/