# Gramps Performance Tests
This directory contains performance tests for Gramps using pytest-benchmark.
## Installation
### Install from PyPI
```bash
pip install gramps-bench
```
### Install from source
```bash
# Clone the repository
git clone https://github.com/gramps-project/gramps-benchmarks.git
cd gramps-benchmarks
# Install in development mode
pip install -e .
```
## Quick Start
### Run Performance Tests
```bash
# 🚀 Run performance tests and automatically save results
gramps-bench example/gramps/example.gramps
# 🚀 Run with custom version override
gramps-bench example/gramps/example.gramps --version 6.0.4-b1
# 🚀 Run with custom output directory
gramps-bench example/gramps/example.gramps --output /path/to/results
```
### Run Multi-Version Performance Tests
```bash
# 🔄 Run benchmarks across multiple Gramps versions
gramps-bench-all /path/to/gramps_file.gramps /path/to/gramps/source
# 🔄 Run with specific versions
gramps-bench-all data.gramps /home/user/gramps --versions v5.1.6 v5.2.4 v6.0.4
# 🔄 Run with custom output and auto-open PDFs
gramps-bench-all data.gramps /home/user/gramps --output /tmp/results --open
```
### Generate Charts from Existing Results
```bash
# 📊 Generate charts from existing benchmark files
gramps-bench
# 📊 Generate charts from specific directory
gramps-bench --output /path/to/benchmarks
```
## Advanced Usage
### Direct pytest Usage
```bash
# Set environment variable and run (results automatically saved)
GRAMPS_FILE=example/gramps/example.gramps python -m pytest gramps_bench/performance_tests.py --benchmark-save=6.0.4
# Run with version override
GRAMPS_FILE=example/gramps/example.gramps GRAMPS_VERSION=6.0.4-b1 python -m pytest gramps_bench/performance_tests.py --benchmark-save=6.0.4-b1
```
### Python Module Usage
```python
from gramps_bench import gramps_benchmark, generate_charts
# Run benchmarks programmatically
success = gramps_benchmark(gramps_file="example.gramps", output_dir="./results")
# Generate charts programmatically
generate_charts(output_dir="./results")
```
### Version Override
You can override the Gramps version used in performance tests and result naming:
```bash
# Using the command-line script
gramps-bench example.gramps --version 6.0.4-b1
# Using environment variable with pytest directly
GRAMPS_VERSION=6.0.4-b1 python -m pytest gramps_bench/performance_tests.py
```
This is useful when:
- Testing pre-release versions
- Comparing performance across different versions
- Creating custom version labels for your test results
## Multi-Version Benchmarking with gramps-bench-all
The `gramps-bench-all` command allows you to run performance benchmarks across multiple Gramps versions and generate comparative charts. This is particularly useful for:
- **Version Comparison**: Compare performance between different Gramps releases
- **Regression Testing**: Identify performance regressions between versions
- **Release Planning**: Assess performance impact of new features
### Prerequisites
Before using `gramps-bench-all`, ensure you have:
1. **Gramps Source Repository**: A local clone of the Gramps git repository
2. **Test Data**: A Gramps database file to use for benchmarking
3. **Git Access**: The ability to checkout different versions in the Gramps repository
### Basic Usage
```bash
# Run benchmarks across default versions (v5.1.6, v5.2.4, v6.0.4)
gramps-bench-all /path/to/gramps_file.gramps /path/to/gramps/source
# Run with specific versions
gramps-bench-all data.gramps /home/user/gramps --versions v5.1.6 v5.2.4
# Run with custom output directory
gramps-bench-all data.gramps /home/user/gramps --output /tmp/benchmark_results
```
### Advanced Options
```bash
# Run with auto-opening PDF results
gramps-bench-all data.gramps /home/user/gramps --open
# Skip chart generation (only run benchmarks)
gramps-bench-all data.gramps /home/user/gramps --skip-charts
# Combine multiple options
gramps-bench-all data.gramps /home/user/gramps \
--versions v5.1.6 v5.2.4 v6.0.4 \
--output /tmp/results \
--open
```
### What gramps-bench-all Does
1. **Git Checkout**: Automatically checks out each specified version in the Gramps source repository
2. **Benchmark Execution**: Runs the full benchmark suite for each version
3. **Result Collection**: Saves benchmark results with version-specific naming
4. **Chart Generation**: Creates comparative PDF charts showing performance across versions
5. **PDF Opening**: Optionally opens the generated charts with the default PDF viewer
### Output Structure
When using `gramps-bench-all`, the output directory will contain:
```
output_directory/
├── .benchmarks/
│ └── Linux-CPython-3.12-64bit/
│ ├── 0001_v5.1.6.json
│ ├── 0002_v5.2.4.json
│ ├── 0003_v6.0.4.json
│ └── 0004_current.json
├── benchmark_charts.pdf
└── performance_comparison.pdf
```
## What the Tests Measure
The performance tests benchmark various Gramps operations:
- **Database Loading**: Time to load a Gramps database file
- **Person Queries**: Retrieving person records from the database
- **Family Queries**: Retrieving family records
- **Source Queries**: Retrieving source records
- **Filter Operations**: Applying filters to person data
- **Transaction Operations**: Adding new records to the database
- **Scalability Tests**: Performance with different data sizes (10, 50, 100 records)
## Output
- **Console**: Real-time benchmark results with statistics
- **Charts**: PDF files with performance visualizations (when generating charts)
- **Benchmark Files**: Automatically saved in `.benchmarks/` directory with gramps version as default name
## Results Naming
When you run the tests with a gramps file, results are automatically saved with the naming convention:
- **Default**: `{version}` (e.g., `6.0.4`)
- **With Override**: `{override_version}` (e.g., `6.0.4-b1`)
- **Location**: `.benchmarks/Linux-CPython-3.12-64bit/0001_{version}.json`
## Requirements
- pytest
- pytest-benchmark
- matplotlib
- numpy
- gramps (the main application)
## Development
### Building the Package
```bash
# Build source distribution
python -m build
# Build wheel
python -m build --wheel
```
### Running Tests
```bash
# Run the benchmark tests
python -m pytest gramps_bench/performance_tests.py
# Run with coverage
python -m pytest gramps_bench/ --cov=gramps_bench
```
Raw data
{
"_id": null,
"home_page": "https://github.com/dsblank/gramps-bench",
"name": "gramps-bench",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Gramps Development Team <gramps-devel@lists.sourceforge.net>",
"keywords": "gramps, genealogy, benchmark, performance, testing",
"author": "Gramps Development Team",
"author_email": "Gramps Development Team <gramps-devel@lists.sourceforge.net>",
"download_url": "https://files.pythonhosted.org/packages/1e/a9/54484794009944e26fbe675107992435d272de4a6d11c1981c5fb5405184/gramps_bench-1.0.1.tar.gz",
"platform": null,
"description": "# Gramps Performance Tests\n\nThis directory contains performance tests for Gramps using pytest-benchmark.\n\n## Installation\n\n### Install from PyPI\n```bash\npip install gramps-bench\n```\n\n### Install from source\n```bash\n# Clone the repository\ngit clone https://github.com/gramps-project/gramps-benchmarks.git\ncd gramps-benchmarks\n\n# Install in development mode\npip install -e .\n```\n\n## Quick Start\n\n### Run Performance Tests\n```bash\n# \ud83d\ude80 Run performance tests and automatically save results\ngramps-bench example/gramps/example.gramps\n\n# \ud83d\ude80 Run with custom version override\ngramps-bench example/gramps/example.gramps --version 6.0.4-b1\n\n# \ud83d\ude80 Run with custom output directory\ngramps-bench example/gramps/example.gramps --output /path/to/results\n```\n\n### Run Multi-Version Performance Tests\n```bash\n# \ud83d\udd04 Run benchmarks across multiple Gramps versions\ngramps-bench-all /path/to/gramps_file.gramps /path/to/gramps/source\n\n# \ud83d\udd04 Run with specific versions\ngramps-bench-all data.gramps /home/user/gramps --versions v5.1.6 v5.2.4 v6.0.4\n\n# \ud83d\udd04 Run with custom output and auto-open PDFs\ngramps-bench-all data.gramps /home/user/gramps --output /tmp/results --open\n```\n\n### Generate Charts from Existing Results\n```bash\n# \ud83d\udcca Generate charts from existing benchmark files\ngramps-bench\n\n# \ud83d\udcca Generate charts from specific directory\ngramps-bench --output /path/to/benchmarks\n```\n\n## Advanced Usage\n\n### Direct pytest Usage\n```bash\n# Set environment variable and run (results automatically saved)\nGRAMPS_FILE=example/gramps/example.gramps python -m pytest gramps_bench/performance_tests.py --benchmark-save=6.0.4\n\n# Run with version override\nGRAMPS_FILE=example/gramps/example.gramps GRAMPS_VERSION=6.0.4-b1 python -m pytest gramps_bench/performance_tests.py --benchmark-save=6.0.4-b1\n```\n\n### Python Module Usage\n```python\nfrom gramps_bench import gramps_benchmark, generate_charts\n\n# Run benchmarks programmatically\nsuccess = gramps_benchmark(gramps_file=\"example.gramps\", output_dir=\"./results\")\n\n# Generate charts programmatically\ngenerate_charts(output_dir=\"./results\")\n```\n\n### Version Override\n\nYou can override the Gramps version used in performance tests and result naming:\n\n```bash\n# Using the command-line script\ngramps-bench example.gramps --version 6.0.4-b1\n\n# Using environment variable with pytest directly\nGRAMPS_VERSION=6.0.4-b1 python -m pytest gramps_bench/performance_tests.py\n```\n\nThis is useful when:\n- Testing pre-release versions\n- Comparing performance across different versions\n- Creating custom version labels for your test results\n\n## Multi-Version Benchmarking with gramps-bench-all\n\nThe `gramps-bench-all` command allows you to run performance benchmarks across multiple Gramps versions and generate comparative charts. This is particularly useful for:\n\n- **Version Comparison**: Compare performance between different Gramps releases\n- **Regression Testing**: Identify performance regressions between versions\n- **Release Planning**: Assess performance impact of new features\n\n### Prerequisites\n\nBefore using `gramps-bench-all`, ensure you have:\n\n1. **Gramps Source Repository**: A local clone of the Gramps git repository\n2. **Test Data**: A Gramps database file to use for benchmarking\n3. **Git Access**: The ability to checkout different versions in the Gramps repository\n\n### Basic Usage\n\n```bash\n# Run benchmarks across default versions (v5.1.6, v5.2.4, v6.0.4)\ngramps-bench-all /path/to/gramps_file.gramps /path/to/gramps/source\n\n# Run with specific versions\ngramps-bench-all data.gramps /home/user/gramps --versions v5.1.6 v5.2.4\n\n# Run with custom output directory\ngramps-bench-all data.gramps /home/user/gramps --output /tmp/benchmark_results\n```\n\n### Advanced Options\n\n```bash\n# Run with auto-opening PDF results\ngramps-bench-all data.gramps /home/user/gramps --open\n\n# Skip chart generation (only run benchmarks)\ngramps-bench-all data.gramps /home/user/gramps --skip-charts\n\n# Combine multiple options\ngramps-bench-all data.gramps /home/user/gramps \\\n --versions v5.1.6 v5.2.4 v6.0.4 \\\n --output /tmp/results \\\n --open\n```\n\n### What gramps-bench-all Does\n\n1. **Git Checkout**: Automatically checks out each specified version in the Gramps source repository\n2. **Benchmark Execution**: Runs the full benchmark suite for each version\n3. **Result Collection**: Saves benchmark results with version-specific naming\n4. **Chart Generation**: Creates comparative PDF charts showing performance across versions\n5. **PDF Opening**: Optionally opens the generated charts with the default PDF viewer\n\n### Output Structure\n\nWhen using `gramps-bench-all`, the output directory will contain:\n\n```\noutput_directory/\n\u251c\u2500\u2500 .benchmarks/\n\u2502 \u2514\u2500\u2500 Linux-CPython-3.12-64bit/\n\u2502 \u251c\u2500\u2500 0001_v5.1.6.json\n\u2502 \u251c\u2500\u2500 0002_v5.2.4.json\n\u2502 \u251c\u2500\u2500 0003_v6.0.4.json\n\u2502 \u2514\u2500\u2500 0004_current.json\n\u251c\u2500\u2500 benchmark_charts.pdf\n\u2514\u2500\u2500 performance_comparison.pdf\n```\n\n## What the Tests Measure\n\nThe performance tests benchmark various Gramps operations:\n\n- **Database Loading**: Time to load a Gramps database file\n- **Person Queries**: Retrieving person records from the database\n- **Family Queries**: Retrieving family records\n- **Source Queries**: Retrieving source records\n- **Filter Operations**: Applying filters to person data\n- **Transaction Operations**: Adding new records to the database\n- **Scalability Tests**: Performance with different data sizes (10, 50, 100 records)\n\n## Output\n\n- **Console**: Real-time benchmark results with statistics\n- **Charts**: PDF files with performance visualizations (when generating charts)\n- **Benchmark Files**: Automatically saved in `.benchmarks/` directory with gramps version as default name\n\n## Results Naming\n\nWhen you run the tests with a gramps file, results are automatically saved with the naming convention:\n- **Default**: `{version}` (e.g., `6.0.4`)\n- **With Override**: `{override_version}` (e.g., `6.0.4-b1`)\n- **Location**: `.benchmarks/Linux-CPython-3.12-64bit/0001_{version}.json`\n\n## Requirements\n\n- pytest\n- pytest-benchmark\n- matplotlib\n- numpy\n- gramps (the main application)\n\n## Development\n\n### Building the Package\n```bash\n# Build source distribution\npython -m build\n\n# Build wheel\npython -m build --wheel\n```\n\n### Running Tests\n```bash\n# Run the benchmark tests\npython -m pytest gramps_bench/performance_tests.py\n\n# Run with coverage\npython -m pytest gramps_bench/ --cov=gramps_bench\n``` \n",
"bugtrack_url": null,
"license": "GPL-2.0-or-later",
"summary": "Performance benchmarking tools for Gramps genealogy software",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/dsblank/gramps-bench",
"Issues": "https://github.com/dsblank/gramps-bench/issues",
"Repository": "https://github.com/dsblank/gramps-bench"
},
"split_keywords": [
"gramps",
" genealogy",
" benchmark",
" performance",
" testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30b42c48e890c92f80407636bc9bb0b09adf21d193ff421c48185e4e06ea27c9",
"md5": "edea08ed9614439298ebbc8c20c19716",
"sha256": "c857025b937485c3a01e27c2a92c732d6b13919dc0bb555c9f3cd1d7a68e46ca"
},
"downloads": -1,
"filename": "gramps_bench-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "edea08ed9614439298ebbc8c20c19716",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22655,
"upload_time": "2025-08-14T12:44:11",
"upload_time_iso_8601": "2025-08-14T12:44:11.849755Z",
"url": "https://files.pythonhosted.org/packages/30/b4/2c48e890c92f80407636bc9bb0b09adf21d193ff421c48185e4e06ea27c9/gramps_bench-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1ea954484794009944e26fbe675107992435d272de4a6d11c1981c5fb5405184",
"md5": "cca2bc20765ec4ae4b8df8078dd0638e",
"sha256": "bfebe268ed402a3639841416d6811bb16a29b58429092540608b5d17c4891290"
},
"downloads": -1,
"filename": "gramps_bench-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "cca2bc20765ec4ae4b8df8078dd0638e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25229,
"upload_time": "2025-08-14T12:44:13",
"upload_time_iso_8601": "2025-08-14T12:44:13.359579Z",
"url": "https://files.pythonhosted.org/packages/1e/a9/54484794009944e26fbe675107992435d272de4a6d11c1981c5fb5405184/gramps_bench-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 12:44:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dsblank",
"github_project": "gramps-bench",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gramps-bench"
}
JSON
