Metadata-Version: 2.4
Name: kimon-gedgraph
Version: 1.2.1
Summary: Generate genealogical charts from GEDCOM files
Author: Kimon Andreou
License-Expression: MIT
Project-URL: Homepage, https://github.com/kimon1230/gedgraph
Keywords: genealogy,gedcom,graphviz,pedigree,family-tree
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Sociology :: Genealogy
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ged4py<0.6,>=0.5.2
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: black<27,>=26.5; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Requires-Dist: pip-audit>=2.10; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0; extra == "dev"
Requires-Dist: mypy<3,>=2.3; extra == "dev"
Dynamic: license-file

# GedGraph

Generate genealogical charts from GEDCOM files using GraphViz.

## Features

- **Pedigree Charts**: Visualize ancestors of an individual
- **Relationship Charts**: Find and visualize relationships between two individuals
- **Hourglass Charts**: Show ancestors and descendants or split by parental lines
- **Bowtie Charts**: Horizontal hourglass layout with left-right orientation
- **Smart Path Finding**: Automatically finds the shortest relationship path using breadth-first search
- **Relationship Prioritization**: Prefers blood relationships via male line, then female line, then half-blood relationships
- **Multiple Path Detection**: Identifies when multiple equally short paths exist
- **Spouse Visualization**: Shows spouses/partners alongside the direct bloodline
- **Marriage Status Indicators**: Solid lines for married couples, dashed lines for unmarried couples
- **Flexible Date Handling**: Uses birth/death dates with fallback to baptism/burial dates
- **Enhanced Name Formatting**: Supports GEDCOM name components (prefix, title, given, surname, suffix)
- **Progress Feedback**: Braille-spinner progress indicators with `--verbose`, `--quiet`, `--no-color`, and `--ascii` options
- **GraphViz Output**: Generates DOT files that can be rendered to various image formats

## Prerequisites

- Python 3.11+
- [GraphViz](https://graphviz.org/) (`dot` command) installed on your system to render DOT files to images

## Installation

```bash
pip install kimon-gedgraph
```

### Development Setup

```bash
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"
```

## Usage

### Pedigree Chart

Generate a pedigree chart showing ancestors of an individual:

```bash
gedgraph pedigree family.ged @I10@ -o output.dot
```

Options:
- `-g, --generations`: Number of generations to include (default: 4)

Example:
```bash
gedgraph pedigree family.ged @I10@ -g 5 -o pedigree.dot
```

### Relationship Chart

Find and visualize the relationship between two individuals:

```bash
gedgraph relationship family.ged @I10@ @I20@ -o output.dot
```

Options:
- `-d, --max-depth`: Maximum search depth (default: 50)

Example:
```bash
gedgraph relationship family.ged @I1@ @I50@ -d 15 -o relationship.dot
```

### Hourglass Chart

Visualize ancestors and descendants or split by parental lines:

```bash
# Ancestors above, descendants below
gedgraph hourglass family.ged @I10@ -v descendants -o hourglass.dot

# Father's line above, mother's line below
gedgraph hourglass family.ged @I10@ -v ancestor-split -o hourglass.dot
```

Options:
- `-g, --generations`: Number of generations in each direction (default: 4)
- `-v, --variant`: Chart variant - `ancestor-split` or `descendants` (default: ancestor-split)

### Bowtie Chart

Horizontal hourglass layout with left-right orientation:

```bash
# Ancestors left, descendants right
gedgraph bowtie family.ged @I10@ -v descendants -o bowtie.dot

# Father's line left, mother's line right
gedgraph bowtie family.ged @I10@ -v ancestor-split -o bowtie.dot
```

Options:
- `-g, --generations`: Number of generations in each direction (default: 4)
- `-v, --variant`: Chart variant - `ancestor-split` or `descendants` (default: ancestor-split)

### Global Options

These flags must appear before the subcommand name:

```bash
# Suppress progress output
gedgraph --quiet pedigree family.ged @I10@ -o output.dot

# Show progress with timing
gedgraph --verbose relationship family.ged @I10@ @I20@ -o output.dot

# Disable colored output
gedgraph --no-color hourglass family.ged @I10@ -o output.dot

# Use ASCII decorations instead of braille/check marks
gedgraph --ascii pedigree family.ged @I10@ -o output.dot
```

| Flag | Description |
|------|-------------|
| `--verbose` | Show detailed progress with timing |
| `-q, --quiet` | Suppress progress output |
| `--no-color` | Disable colored output |
| `--ascii` / `--no-ascii` | Use ASCII decorations (`[OK]`, `[!]`, `\|/-\`) instead of `✓`, `✗` and the braille spinner |

`--ascii` is for consoles whose fonts cannot draw braille — common on Windows,
where the spinner otherwise renders as a row of boxes. It can also be set with
`GEDGRAPH_ASCII=1`; the flag wins over the environment variable in both
directions.

### Output Encoding

Names are written to stdout in the console's own encoding. When output is
redirected to a file or a pipe, UTF-8 is used instead — there is no terminal on
the other end whose encoding matters, and this is what makes names with Greek,
Cyrillic or accented characters survive `gedgraph ... > out.txt`.

If you pin an encoding yourself with `PYTHONIOENCODING`, that choice is
respected. Characters it cannot represent are escaped (`Α`) rather than
causing the command to fail. Generated DOT files are always UTF-8, independent
of the console.

### Rendering DOT Files

Convert DOT files to images using GraphViz:

```bash
# PNG
dot -Tpng output.dot -o output.png

# PDF
dot -Tpdf output.dot -o output.pdf

# SVG
dot -Tsvg output.dot -o output.svg
```

## Relationship Path Sorting

When multiple equally short paths exist between two individuals, GedGraph prioritizes them in this order:

1. Full blood relationships via male line
2. Full blood relationships via female line
3. Half-blood relationships via male line
4. Half-blood relationships via female line

The tool will generate charts for all paths of equal shortest length.

## Example Output

The generated DOT files include:

- **Comments**: Generation distance, path length, and relationship description
- **Color Coding**:
  - Start individual (coral)
  - End individual (light blue)
  - Direct bloodline (light green)
  - Spouses/partners (light yellow)
- **Labels**: Names with birth/death years in (YYYY - YYYY) format
- **Relationship Lines**:
  - Solid arrows for parent-child relationships
  - Solid lines for married couples
  - Dashed lines for unmarried couples
- **Horizontal Alignment**: Spouses are positioned next to their partners using rank constraints

## Error Handling

GedGraph will exit with an error if:

- The GEDCOM file doesn't exist
- An individual ID is not found in the GEDCOM file
- No relationship exists between two individuals (for relationship charts)

## Development

See [DEVELOPER.md](DEVELOPER.md) for development setup and architecture details.

## License

MIT
