graphfaker 0.1.0

an open-source Python library designed to generate, load, and export synthetic graph datasets in a user-friendly and configurable way

GraphFaker

GraphFaker is a Python library and CLI tool for generating, loading, and exporting synthetic and real-world graph datasets. It supports faker as social graph, OpenStreetMap (OSM) road networks, and real airline flight networks. Use it for data science, research, teaching, rapid prototyping, and more!

Note: The authors and graphgeeks labs do not hold any responsibility for the correctness of this generator.

---

⭐ Star the Repo

If you find this project valuable, star ⭐ this repository to support the work and help others discover it!

---

Features

• Multiple Graph Sources:
  • faker: Synthetic social graphs with rich node/edge types
  • osm: Real-world road networks from OpenStreetMap
  • flights: Real airline, airport, and flight networks
• Flexible Export: GraphML, JSON, CSV, RDF, and more
• Easy CLI & Python API

---

Installation

Install from PyPI:

uv pip install graphfaker

For development:

git clone https://github.com/denironyx/graphfaker.git
cd graphfaker
uv pip install -e .

---

Quick Start

CLI Usage

Show help:

python -m graphfaker.cli --help

Generate a Synthetic Social Graph

python -m graphfaker.cli gen \
    --source faker \
    --total-nodes 100 \
    --total-edges 500

Generate a Real-World Road Network (OSM)

python -m graphfaker.cli gen \
    --source osm \
    --place "Berlin, Germany" \
    --network-type drive \
    --export berlin.graphml

Generate a Flight Network (Airlines/Airports/Flights)

python -m graphfaker.cli gen \
    --source flights \
    --country "United States" \
    --year 2024 \
    --month 1 \
    --export flights.graphml

You can also use --date-range for custom time spans (e.g., --date-range "2024-01-01,2024-01-15").

---

Python API Usage

from graphfaker import GraphFaker

gf = GraphFaker()
# Synthetic social/knowledge graph
g1 = gf.generate_graph(source="faker", total_nodes=200, total_edges=800)
# OSM road network
g2 = gf.generate_graph(source="osm", place="Berlin, Germany", network_type="drive")
# Flight network
g3 = gf.generate_graph(source="flights", country="United States", year=2024, month=1)

Advanced: Date Range for Flights

Note this isn't recommended and it's still being tested. We are working on ways to make this faster.

g = gf.generate_graph(source="flights", country="United States", date_range=("2024-01-01", "2024-01-15"))

---

Future Plans: Graph Export Formats

• GraphML: General graph analysis/visualization (--export graph.graphml) ✔️
• JSON/JSON-LD: Knowledge graphs/web apps (--export data.json)
• CSV: Tabular analysis/database imports (--export edges.csv)
• RDF: Semantic web/linked data (--export graph.ttl)

---

Future Plans: Integration with Graph Tools

GraphFaker generates NetworkX graph objects that can be easily integrated with:

• Graph databases: Neo4j, Kuzu, TigerGraph
• Analysis tools: NetworkX, SNAP, graph-tool
• ML frameworks: PyTorch Geometric, DGL, TensorFlow GNN
• Visualization: Gephi, Cytoscape, D3.js

---

Documentation

Full documentation: https://graphfaker.readthedocs.io

---

License

MIT License

Credits

Created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.