# <span style="font-family: 'American Typewriter', monospace; font-size: 4em;">groggy</span>
A high-performance graph language engine built with Rust and Python bindings.
## Overview
Groggy is a graph processing library designed for efficient manipulation and analysis of large-scale graphs. It combines the performance of Rust with the ease of use of Python, providing a powerful toolkit for graph-based applications.
Groggy is in development! I am excited to release this early public version for testing and development. Please contribute any thoughts or comments!
## Features
- **High Performance**: Rust-based core for maximum speed and memory efficiency
- **Python Integration**: Easy-to-use Python API with familiar syntax
- **Scalable**: Handles large graphs with millions of nodes and edges
- **Batch Operations**: Efficient bulk operations (330x faster than individual)
- **Graph Operations**: Comprehensive set of graph algorithms and operations
- **Memory Efficient**: Optimized data structures for minimal memory footprint
- **State Management**: Save, load, and track graph states over time
- **Comprehensive Testing**: Full test suite with performance benchmarks
## Installation
### From Source
```bash
git clone https://github.com/rollingstorms/groggy.git
cd groggy
# Install development dependencies
pip install maturin
# Build and install
maturin develop --release
```
## Quick Start
```python
import groggy as gr
# Create a new graph
g = gr.Graph()
# Add nodes with attributes
g.add_node("alice", age=30, role="engineer")
g.add_node("bob", age=25, role="designer")
g.add_node("charlie", age=35, role="manager")
# Add edges with attributes
g.add_edge("alice", "bob", relationship="collaborates")
g.add_edge("charlie", "alice", relationship="manages")
# Query the graph
print(f"Nodes: {len(g.nodes)}")
print(f"Edges: {len(g.edges)}")
# Check connectivity
print(f"Alice and Bob connected: {g.has_edge('alice', 'bob')}")
# Get node/edge data
alice_data = g.get_node("alice")
print(f"Alice: {alice_data}")
# Filter nodes
engineers = g.filter_nodes(lambda node_id, attrs: attrs.get("role") == "engineer")
print(f"Engineers: {engineers}")
# Efficient batch operations
nodes_data = [
{'id': 'user_1', 'score': 100, 'active': True},
{'id': 'user_2', 'score': 200, 'active': False},
{'id': 'user_3', 'score': 150, 'active': True}
]
g.add_nodes(nodes_data)
edges_data = [
{'source': 'user_1', 'target': 'user_2', 'weight': 0.8},
{'source': 'user_2', 'target': 'user_3', 'weight': 0.6}
]
g.add_edges(edges_data)
# State management
g.save_state("initial")
g.update_node("user_1", {"score": 250, "promoted": True})
g.save_state("after_promotion")
```
## Advanced Usage
```python
import groggy as gr
# Create graph with batch operations
g = gr.Graph()
# Bulk operations for efficiency
nodes = [{'id': f'node_{i}', 'value': i} for i in range(1000)]
g.add_nodes(nodes)
edges = [{'source': f'node_{i}', 'target': f'node_{i+1}', 'weight': 1.0}
for i in range(999)]
g.add_edges(edges)
# Batch updates
updates = {f'node_{i}': {'updated': True, 'timestamp': '2025-06-28'}
for i in range(0, 1000, 10)}
g.update_nodes(updates)
```
## Documentation
Full documentation is available at [groggy.readthedocs.io](https://groggy.readthedocs.io) or can be built locally:
```bash
cd docs
make html
```
## Performance
Groggy is designed for high-performance graph processing with a unified Rust-based columnar storage system:
- **Optimized Filtering**: Fast bitmap-based exact matching and range queries
- **Columnar Storage**: Efficient attribute storage with O(1) lookups for exact matches
- **Scalable Architecture**: Handles large graphs efficiently
- **Memory Efficient**: Optimized data structures for minimal memory footprint
Key architectural features:
- Unified type system (NodeData, EdgeData, GraphType)
- Bitmap indexing for fast attribute filtering
- Optimized numeric and string comparison operations
- Efficient batch operations for bulk data processing
## Development
### Building from Source
Requirements:
- Rust 1.70+
- Python 3.8+
- Maturin for building Python extensions
```bash
# Install development dependencies
pip install -r requirements-dev.txt
# Build the Rust extension
maturin develop
```
## Testing
Groggy includes comprehensive test suites to ensure reliability and performance:
### Running Tests
**Basic functionality tests:**
```bash
# Run all tests with pytest
python -m pytest tests/test_functionality.py -v
# Or run directly
python tests/test_functionality.py
```
**Stress test (10K nodes/edges):**
```bash
python tests/test_stress.py
```
### Test Coverage
The test suite includes:
- **Functionality Tests** (`test_functionality.py`):
- Basic graph operations (nodes, edges, properties)
- State management and tracking
- Node and edge filtering
- Batch updates and modifications
- Graph analysis and neighbor queries
- **Stress Tests** (`test_stress.py`, `test_stress_quick.py`):
- Large-scale graph creation (10K nodes/edges)
- Batch operations performance testing
- Memory efficiency validation
- Graph analysis on large datasets
- State management with bulk data
- **Performance Benchmarks**:
- Comprehensive filtering performance testing
- Graph creation and manipulation benchmarks
- Comparison with other graph libraries
- Memory efficiency validation
### Test Environment Setup
For development testing:
```bash
# Install test dependencies
pip install pytest pytest-benchmark
# Install groggy in development mode
pip install -e .
# Run full test suite
python -m pytest tests/ -v
```
### Performance Testing
For performance validation:
```bash
# Run comprehensive functionality tests
python run_tests.py
# Run stress tests
python tests/test_stress.py
# Benchmark against other libraries
python benchmark_graph_libraries.py
```
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/rollingstorms/groggy",
"name": "groggy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "graph, network, data-structure, algorithms",
"author": "Groggy Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6d/58/03ad58e37699e269c95e77e3f615d7542b742678bddd62befceaa97e3934/groggy-0.2.1.tar.gz",
"platform": null,
"description": "# <span style=\"font-family: 'American Typewriter', monospace; font-size: 4em;\">groggy</span>\n\nA high-performance graph language engine built with Rust and Python bindings.\n\n## Overview\n\nGroggy is a graph processing library designed for efficient manipulation and analysis of large-scale graphs. It combines the performance of Rust with the ease of use of Python, providing a powerful toolkit for graph-based applications.\n\nGroggy is in development! I am excited to release this early public version for testing and development. Please contribute any thoughts or comments!\n\n## Features\n\n- **High Performance**: Rust-based core for maximum speed and memory efficiency\n- **Python Integration**: Easy-to-use Python API with familiar syntax\n- **Scalable**: Handles large graphs with millions of nodes and edges\n- **Batch Operations**: Efficient bulk operations (330x faster than individual)\n- **Graph Operations**: Comprehensive set of graph algorithms and operations\n- **Memory Efficient**: Optimized data structures for minimal memory footprint\n- **State Management**: Save, load, and track graph states over time\n- **Comprehensive Testing**: Full test suite with performance benchmarks\n\n## Installation\n\n### From Source\n\n```bash\ngit clone https://github.com/rollingstorms/groggy.git\ncd groggy\n\n# Install development dependencies\npip install maturin\n\n# Build and install\nmaturin develop --release\n```\n\n## Quick Start\n\n```python\nimport groggy as gr\n\n# Create a new graph\ng = gr.Graph()\n\n# Add nodes with attributes\ng.add_node(\"alice\", age=30, role=\"engineer\")\ng.add_node(\"bob\", age=25, role=\"designer\")\ng.add_node(\"charlie\", age=35, role=\"manager\")\n\n# Add edges with attributes\ng.add_edge(\"alice\", \"bob\", relationship=\"collaborates\")\ng.add_edge(\"charlie\", \"alice\", relationship=\"manages\")\n\n# Query the graph\nprint(f\"Nodes: {len(g.nodes)}\")\nprint(f\"Edges: {len(g.edges)}\")\n\n# Check connectivity\nprint(f\"Alice and Bob connected: {g.has_edge('alice', 'bob')}\")\n\n# Get node/edge data\nalice_data = g.get_node(\"alice\")\nprint(f\"Alice: {alice_data}\")\n\n# Filter nodes\nengineers = g.filter_nodes(lambda node_id, attrs: attrs.get(\"role\") == \"engineer\")\nprint(f\"Engineers: {engineers}\")\n\n# Efficient batch operations\nnodes_data = [\n {'id': 'user_1', 'score': 100, 'active': True},\n {'id': 'user_2', 'score': 200, 'active': False},\n {'id': 'user_3', 'score': 150, 'active': True}\n]\ng.add_nodes(nodes_data)\n\nedges_data = [\n {'source': 'user_1', 'target': 'user_2', 'weight': 0.8},\n {'source': 'user_2', 'target': 'user_3', 'weight': 0.6}\n]\ng.add_edges(edges_data)\n\n# State management\ng.save_state(\"initial\")\ng.update_node(\"user_1\", {\"score\": 250, \"promoted\": True})\ng.save_state(\"after_promotion\")\n```\n\n## Advanced Usage\n\n```python\nimport groggy as gr\n\n# Create graph with batch operations\ng = gr.Graph()\n\n# Bulk operations for efficiency\nnodes = [{'id': f'node_{i}', 'value': i} for i in range(1000)]\ng.add_nodes(nodes)\n\nedges = [{'source': f'node_{i}', 'target': f'node_{i+1}', 'weight': 1.0} \n for i in range(999)]\ng.add_edges(edges)\n\n# Batch updates\nupdates = {f'node_{i}': {'updated': True, 'timestamp': '2025-06-28'} \n for i in range(0, 1000, 10)}\ng.update_nodes(updates)\n\n```\n\n## Documentation\n\nFull documentation is available at [groggy.readthedocs.io](https://groggy.readthedocs.io) or can be built locally:\n\n```bash\ncd docs\nmake html\n```\n\n## Performance\n\nGroggy is designed for high-performance graph processing with a unified Rust-based columnar storage system:\n\n- **Optimized Filtering**: Fast bitmap-based exact matching and range queries\n- **Columnar Storage**: Efficient attribute storage with O(1) lookups for exact matches\n- **Scalable Architecture**: Handles large graphs efficiently\n- **Memory Efficient**: Optimized data structures for minimal memory footprint\n\nKey architectural features:\n- Unified type system (NodeData, EdgeData, GraphType)\n- Bitmap indexing for fast attribute filtering\n- Optimized numeric and string comparison operations\n- Efficient batch operations for bulk data processing\n\n## Development\n\n### Building from Source\n\nRequirements:\n- Rust 1.70+\n- Python 3.8+\n- Maturin for building Python extensions\n\n```bash\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Build the Rust extension\nmaturin develop\n\n```\n\n## Testing\n\nGroggy includes comprehensive test suites to ensure reliability and performance:\n\n### Running Tests\n\n**Basic functionality tests:**\n```bash\n# Run all tests with pytest\npython -m pytest tests/test_functionality.py -v\n\n# Or run directly\npython tests/test_functionality.py\n```\n\n**Stress test (10K nodes/edges):**\n```bash\npython tests/test_stress.py\n```\n\n### Test Coverage\n\nThe test suite includes:\n\n- **Functionality Tests** (`test_functionality.py`):\n - Basic graph operations (nodes, edges, properties)\n - State management and tracking\n - Node and edge filtering\n - Batch updates and modifications\n - Graph analysis and neighbor queries\n\n- **Stress Tests** (`test_stress.py`, `test_stress_quick.py`):\n - Large-scale graph creation (10K nodes/edges)\n - Batch operations performance testing\n - Memory efficiency validation\n - Graph analysis on large datasets\n - State management with bulk data\n\n- **Performance Benchmarks**:\n - Comprehensive filtering performance testing\n - Graph creation and manipulation benchmarks\n - Comparison with other graph libraries\n - Memory efficiency validation\n\n### Test Environment Setup\n\nFor development testing:\n```bash\n# Install test dependencies\npip install pytest pytest-benchmark\n\n# Install groggy in development mode\npip install -e .\n\n# Run full test suite\npython -m pytest tests/ -v\n```\n\n### Performance Testing\n\nFor performance validation:\n```bash\n# Run comprehensive functionality tests\npython run_tests.py\n\n# Run stress tests\npython tests/test_stress.py\n\n# Benchmark against other libraries\npython benchmark_graph_libraries.py\n```\n\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Groggy - A Graph Language Engine for dynamic graphs and versioned state",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://groggy.readthedocs.io",
"Homepage": "https://github.com/rollingstorms/groggy",
"Repository": "https://github.com/rollingstorms/groggy"
},
"split_keywords": [
"graph",
" network",
" data-structure",
" algorithms"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "82ea3afe938b4e08217e983c84e5a69b925102994e8a73ae8630ca3ea137ae3e",
"md5": "f7827069147d9340102844bcc07ca926",
"sha256": "992652edec7d73a6aa52afe48d82be4ca20db09d2861675703f08007436883b5"
},
"downloads": -1,
"filename": "groggy-0.2.1-cp310-cp310-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "f7827069147d9340102844bcc07ca926",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 519323,
"upload_time": "2025-07-10T20:54:13",
"upload_time_iso_8601": "2025-07-10T20:54:13.140782Z",
"url": "https://files.pythonhosted.org/packages/82/ea/3afe938b4e08217e983c84e5a69b925102994e8a73ae8630ca3ea137ae3e/groggy-0.2.1-cp310-cp310-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6d5803ad58e37699e269c95e77e3f615d7542b742678bddd62befceaa97e3934",
"md5": "e9251aaf635c2d3e3ded4fad114c608c",
"sha256": "1e7e8e8f039243a292fe602898914f7289f32f28820990833b8470f3dd064066"
},
"downloads": -1,
"filename": "groggy-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "e9251aaf635c2d3e3ded4fad114c608c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9802608,
"upload_time": "2025-07-10T20:54:14",
"upload_time_iso_8601": "2025-07-10T20:54:14.926764Z",
"url": "https://files.pythonhosted.org/packages/6d/58/03ad58e37699e269c95e77e3f615d7542b742678bddd62befceaa97e3934/groggy-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 20:54:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rollingstorms",
"github_project": "groggy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "groggy"
}
JSON
