graph LR
subgraph main [main]
main_finalize[finalize]
main_main_final[main_final]
main_process_data[process_data]
end
subgraph utils [utils]
utils_another_helper[another_helper]
utils_format_name[format_name]
utils_helper_function[helper_function]
end
subgraph calculator [calculator]
calculator___init__[__init__]
calculator__actual_add[_actual_add]
calculator_add[add]
calculator_create_calculator[create_calculator]
calculator_multiply[multiply]
end
main_main_final --> utils_helper_function
main_main_final --> calculator_add
main_main_final --> |result| main_process_data
main_main_final --> |processed,total| main_finalize
utils_helper_function --> |name| utils_format_name
calculator_add --> |a,b| calculator__actual_add
utils_helper_function -.->|result| main_main_final
calculator_add -.->|total| main_main_final
main_process_data -.->|processed| main_main_final
main_finalize -.->|final_result| main_main_final
utils_format_name -.->|result| utils_helper_function
calculator__actual_add -.->|result| calculator_add
Examples for Reference
Run the bundled test script (fast sanity check)
This is the quickest way to see PyFlowMapper output on a known sample.
git clone https://github.com/ArunKoundinya/py-flow-mapper.git
cd py-flow-mapper
#run
python3 tests/base_example/main_new.pyExpected output
This creates a folder named flow_test_project/ and generates:
flow_test_project/project_meta.jsonflow_test_project/detailed_flow.mmd
What the diagram represents: The Mermaid below is an example of the detailed flow output you’ll get. Solid arrows show function calls. Dashed arrows represent return-value data flow (e.g., a value assigned to a variable and later passed along).
Example-2 - Analyze the tests folder using the CLI
This example runs the analyzer via CLI (recommended for normal use).
git clone https://github.com/ArunKoundinya/py-flow-mapper.git
cd py-flow-mapper
#run
pip install py-flow-mapperAnalyze
pyflow analyze ./tests/base_example --entry-point main_new.pyThis creates
./tests/base_example/project_meta.json.
Generate diagrams
pyflow diagram ./tests/base_example/project_meta.jsonAn example Mermaid structure you might see:
graph LR
subgraph main_new [main_new]
main_new_create_flow_test_project[create_flow_test_project]
main_new_main[main]
main_new_test_flow_analysis[test_flow_analysis]
end
subgraph External [External]
ext_pathlib_Path[Path]
ext_py_flow_mapper_analyzer_ProjectAnalyzer[ProjectAnalyzer]
ext_py_flow_mapper_mermaid_generator_MermaidGenerator[MermaidGenerator]
Done((Done))
end
main_new_create_flow_test_project --> |__file__| ext_pathlib_Path
main_new_test_flow_analysis --> main_new_create_flow_test_project
main_new_test_flow_analysis --> ext_py_flow_mapper_analyzer_ProjectAnalyzer
main_new_test_flow_analysis --> |meta_file| ext_py_flow_mapper_mermaid_generator_MermaidGenerator
main_new_main --> main_new_test_flow_analysis
main_new_create_flow_test_project -.->|project_dir| main_new_test_flow_analysis
ext_py_flow_mapper_analyzer_ProjectAnalyzer -.->|analyzer| main_new_test_flow_analysis
ext_py_flow_mapper_mermaid_generator_MermaidGenerator -.->|generator| main_new_test_flow_analysis
ext_py_flow_mapper_analyzer_ProjectAnalyzer -->|meta_file| ext_py_flow_mapper_mermaid_generator_MermaidGenerator
ext_py_flow_mapper_mermaid_generator_MermaidGenerator -->|output| Done
Example-3 - Including External Modules
This example runs the analyzer via CLI (recommended for normal use).
git clone https://github.com/ArunKoundinya/py-flow-mapper.git
cd py-flow-mapper
#run
pip install py-flow-mapperAnalyze
pyflow analyze ./tests/example_externalThis creates
./tests/example_external/project_meta.json.
Generate diagrams
pyflow diagram ./tests/example_external/project_meta.json --include-external pandasAn example Mermaid structure you might see:
graph LR
subgraph main [main]
main_build_pipeline[build_pipeline]
main_load_data[load_data]
main_main[main]
main_train_and_eval[train_and_eval]
end
subgraph External [External]
ext_pandas[pandas]
ext_sklearn_compose_ColumnTransformer[ColumnTransformer]
ext_sklearn_linear_model_LogisticRegression[LogisticRegression]
ext_sklearn_metrics_accuracy_score[accuracy_score]
ext_sklearn_model_selection_train_test_split[train_test_split]
ext_sklearn_pipeline_Pipeline[Pipeline]
ext_sklearn_preprocessing_OneHotEncoder[OneHotEncoder]
end
ext_sklearn_compose_ColumnTransformer --> ext_sklearn_preprocessing_OneHotEncoder
main_main --> main_load_data
main_main --> |df| main_train_and_eval
main_load_data --> |url| ext_pandas
main_train_and_eval --> |X,y| ext_sklearn_model_selection_train_test_split
main_train_and_eval --> main_build_pipeline
main_train_and_eval --> |preds,y_test| ext_sklearn_metrics_accuracy_score
main_build_pipeline --> ext_sklearn_compose_ColumnTransformer
main_build_pipeline --> ext_sklearn_linear_model_LogisticRegression
main_build_pipeline --> |model,preprocessor| ext_sklearn_pipeline_Pipeline
main_load_data -.->|df| main_main
main_train_and_eval -.->|acc| main_main
ext_pandas -.->|df| main_load_data
main_build_pipeline -.->|pipe| main_train_and_eval
ext_sklearn_metrics_accuracy_score -.->|acc| main_train_and_eval
ext_sklearn_compose_ColumnTransformer -.->|preprocessor| main_build_pipeline
ext_sklearn_linear_model_LogisticRegression -.->|model| main_build_pipeline
ext_sklearn_pipeline_Pipeline -.->|pipe| main_build_pipeline
Example-4 - Analyze PyFlowMapper itself (self-analysis)
You can point PyFlowMapper at its own source code to generate a diagram of the internal architecture.
git clone https://github.com/ArunKoundinya/py-flow-mapper.git
cd py-flow-mapper
#run
pip install py-flow-mapperAnalyze
pyflow analyze ./src/py_flow_mapper/ --entry-point cli.pyThis creates
./src/py-flow-mapper/project_meta.json.
Generate diagrams
pyflow diagram ./src/py-flow-mapper/project_meta.jsonA (large) diagram might resemble the following structure (excerpted example): ( Zoom-in & Out Accordingly)
graph LR
subgraph mermaid_generator [mermaid_generator]
mermaid_generator___init__[__init__]
mermaid_generator__find_function_full_name[_find_function_full_name]
mermaid_generator__load_metadata[_load_metadata]
mermaid_generator_external_root_name[external_root_name]
mermaid_generator_generate_all_diagrams[generate_all_diagrams]
mermaid_generator_generate_detailed_flow_graph[generate_detailed_flow_graph]
mermaid_generator_is_camel_case[is_camel_case]
mermaid_generator_is_fileish_arg[is_fileish_arg]
mermaid_generator_is_outputish_call[is_outputish_call]
mermaid_generator_keep_external[keep_external]
mermaid_generator_module_import_mapping[module_import_mapping]
mermaid_generator_nid[nid]
mermaid_generator_normalize_vars[normalize_vars]
mermaid_generator_ordered_functions_from_entry[ordered_functions_from_entry]
mermaid_generator_resolve_internal[resolve_internal]
mermaid_generator_short_label[short_label]
mermaid_generator_visit[visit]
end
subgraph utils [utils]
utils_extract_docstring[extract_docstring]
utils_find_entry_point[find_entry_point]
utils_format_module_name[format_module_name]
utils_get_function_signature[get_function_signature]
utils_get_project_structure[get_project_structure]
utils_is_stdlib_module[is_stdlib_module]
utils_load_json[load_json]
utils_save_json[save_json]
end
subgraph analyzer [analyzer]
analyzer___init__[__init__]
analyzer___post_init__[__post_init__]
analyzer__analyze_file[_analyze_file]
analyzer__build_data_flow_graph[_build_data_flow_graph]
analyzer__extract_call_info[_extract_call_info]
analyzer__find_python_files[_find_python_files]
analyzer__generate_call_graph_data[_generate_call_graph_data]
analyzer__generate_import_graph_data[_generate_import_graph_data]
analyzer__generate_metadata[_generate_metadata]
analyzer__get_attribute_name[_get_attribute_name]
analyzer__is_internal_import[_is_internal_import]
analyzer__path_to_module_name[_path_to_module_name]
analyzer__resolve_function_name[_resolve_function_name]
analyzer__save_metadata[_save_metadata]
analyzer_analyze[analyze]
analyzer_visit_Assign[visit_Assign]
analyzer_visit_Call[visit_Call]
analyzer_visit_ClassDef[visit_ClassDef]
analyzer_visit_FunctionDef[visit_FunctionDef]
analyzer_visit_Import[visit_Import]
analyzer_visit_ImportFrom[visit_ImportFrom]
analyzer_visit_Return[visit_Return]
end
subgraph cli [cli]
cli_analyze_project[analyze_project]
cli_generate_diagrams[generate_diagrams]
cli_main[main]
cli_print_tree[print_tree]
cli_show_structure[show_structure]
end
subgraph External [External]
ext_pathlib_Path[Path]
Done((Done))
end
mermaid_generator___init__ --> |metadata_path| mermaid_generator__load_metadata
mermaid_generator_generate_detailed_flow_graph --> |current_module| mermaid_generator_module_import_mapping
mermaid_generator_generate_detailed_flow_graph --> |call_name,callee,fn,n| mermaid_generator_short_label
mermaid_generator_generate_detailed_flow_graph --> |c,call_name,callee,current_module,fileish_callee,mod,p,producer,src_call,tgt_call| mermaid_generator_external_root_name
mermaid_generator_generate_detailed_flow_graph --> |base| mermaid_generator_is_camel_case
mermaid_generator_generate_detailed_flow_graph --> |c,call,candidate,current_module,mapped| mermaid_generator__find_function_full_name
mermaid_generator_generate_detailed_flow_graph --> |entry_key,target| mermaid_generator_visit
mermaid_generator_generate_detailed_flow_graph --> |caller,fn,internal_p,short_module,target_internal| mermaid_generator_nid
mermaid_generator_generate_detailed_flow_graph --> |c,callee,current_module,p| mermaid_generator_resolve_internal
mermaid_generator_generate_detailed_flow_graph --> |c,callee,current_module,mod,p,src_call,tgt_call| mermaid_generator_keep_external
mermaid_generator_generate_detailed_flow_graph --> mermaid_generator_is_outputish_call
mermaid_generator_generate_detailed_flow_graph --> mermaid_generator_ordered_functions_from_entry
mermaid_generator_generate_detailed_flow_graph --> |vars_passed,vars_used| mermaid_generator_normalize_vars
mermaid_generator_generate_detailed_flow_graph --> |a| mermaid_generator_is_fileish_arg
mermaid_generator_external_root_name --> |current_module| mermaid_generator_module_import_mapping
mermaid_generator_keep_external --> |call_name| mermaid_generator_short_label
mermaid_generator_keep_external --> |call_name,current_module| mermaid_generator_external_root_name
mermaid_generator_keep_external --> |current_module| mermaid_generator_module_import_mapping
mermaid_generator_keep_external --> |base| mermaid_generator_is_camel_case
mermaid_generator_resolve_internal --> |call,candidate,current_module,mapped| mermaid_generator__find_function_full_name
mermaid_generator_resolve_internal --> |current_module| mermaid_generator_module_import_mapping
mermaid_generator_ordered_functions_from_entry --> |c,current_module| mermaid_generator__find_function_full_name
mermaid_generator_ordered_functions_from_entry --> |entry_key,target| mermaid_generator_visit
mermaid_generator_visit --> |c,current_module| mermaid_generator__find_function_full_name
mermaid_generator_visit --> |target| mermaid_generator_visit
mermaid_generator_generate_all_diagrams --> mermaid_generator_generate_detailed_flow_graph
utils_is_stdlib_module --> |p| ext_pathlib_Path
utils_get_project_structure --> |exclude_dirs,item| utils_get_project_structure
analyzer_analyze --> analyzer__find_python_files
analyzer_analyze --> |file_path| analyzer__analyze_file
analyzer_analyze --> analyzer__build_data_flow_graph
analyzer_analyze --> analyzer__generate_metadata
analyzer_analyze --> |metadata| analyzer__save_metadata
analyzer__find_python_files --> |root| ext_pathlib_Path
analyzer__analyze_file --> |rel_path| analyzer__path_to_module_name
analyzer__analyze_file --> |tree| mermaid_generator_visit
analyzer__build_data_flow_graph --> |call,called_func| analyzer__resolve_function_name
analyzer__generate_metadata --> analyzer__generate_call_graph_data
analyzer__generate_metadata --> analyzer__generate_import_graph_data
analyzer_visit_Import --> |module_name| analyzer__is_internal_import
analyzer_visit_ImportFrom --> |module_name| analyzer__is_internal_import
analyzer_visit_FunctionDef --> |decorator| analyzer__get_attribute_name
analyzer_visit_FunctionDef --> |node| mermaid_generator_visit
analyzer_visit_ClassDef --> |item| mermaid_generator_visit
analyzer_visit_Assign --> analyzer__extract_call_info
analyzer_visit_Call --> |node,t,transformer_node| analyzer__extract_call_info
analyzer_visit_Return --> analyzer__extract_call_info
analyzer__extract_call_info --> analyzer__get_attribute_name
cli_main --> |args| cli_analyze_project
cli_main --> |args| cli_generate_diagrams
cli_main --> |args| cli_show_structure
cli_analyze_project --> ext_pathlib_Path
cli_analyze_project --> analyzer_analyze
cli_generate_diagrams --> ext_pathlib_Path
cli_generate_diagrams --> mermaid_generator_generate_all_diagrams
cli_show_structure --> ext_pathlib_Path
cli_show_structure --> |structure,value| cli_print_tree
cli_show_structure --> |project_path| utils_get_project_structure
cli_print_tree --> |value| cli_print_tree
mermaid_generator_module_import_mapping -.->|imp_map| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_module_import_mapping -.->|imp_map| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_module_import_mapping -.->|imp_map| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_short_label -.->|base| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_external_root_name -.->|root| mermaid_generator_generate_detailed_flow_graph
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_generate_detailed_flow_graph
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_generate_detailed_flow_graph
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_generate_detailed_flow_graph
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_ordered_functions_from_entry -.->|caller_order| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_nid -.->|src| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_resolve_internal -.->|target_internal| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_normalize_vars -.->|label| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_nid -.->|dst| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_resolve_internal -.->|internal_p| mermaid_generator_generate_detailed_flow_graph
mermaid_generator_module_import_mapping -.->|imp_map| mermaid_generator_external_root_name
mermaid_generator_short_label -.->|base| mermaid_generator_keep_external
mermaid_generator_external_root_name -.->|root| mermaid_generator_keep_external
mermaid_generator_module_import_mapping -.->|imp_map| mermaid_generator_keep_external
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_resolve_internal
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_resolve_internal
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_resolve_internal
mermaid_generator_module_import_mapping -.->|imp_map| mermaid_generator_resolve_internal
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_ordered_functions_from_entry
mermaid_generator__find_function_full_name -.->|target| mermaid_generator_visit
ext_pathlib_Path -.->|origin_path| utils_is_stdlib_module
analyzer__find_python_files -.->|python_files| analyzer_analyze
analyzer__generate_metadata -.->|metadata| analyzer_analyze
analyzer__path_to_module_name -.->|module_name| analyzer__analyze_file
analyzer__resolve_function_name -.->|callee_key| analyzer__build_data_flow_graph
analyzer__resolve_function_name -.->|callee_key| analyzer__build_data_flow_graph
analyzer__extract_call_info -.->|call_info| analyzer_visit_Assign
analyzer__extract_call_info -.->|call_info| analyzer_visit_Call
analyzer__extract_call_info -.->|ci| analyzer_visit_Call
analyzer__extract_call_info -.->|ci| analyzer_visit_Call
analyzer__extract_call_info -.->|call_info| analyzer_visit_Return
analyzer__get_attribute_name -.->|method_name| analyzer__extract_call_info
analyzer_analyze -.->|metadata| cli_analyze_project
mermaid_generator_generate_all_diagrams -.->|master_path| cli_generate_diagrams
utils_get_project_structure -.->|structure| cli_show_structure
Notes
Static analysis cannot resolve highly dynamic calls, but provides a strong architectural baseline.