Metadata-Version: 2.4
Name: gedcom-reports
Version: 0.1.0
Summary: Genealogy reports built on top of gedcom-lite.
Project-URL: Homepage, https://github.com/vaelen/gedcom-reports
Project-URL: Source, https://github.com/vaelen/gedcom-reports
Project-URL: Issues, https://github.com/vaelen/gedcom-reports/issues
Author-email: Andrew Young <andrew@vaelen.org>
License: MIT
License-File: LICENSE
Keywords: ancestry,family-tree,gedcom,genealogy,report
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Other/Nonlisted Topic
Requires-Python: >=3.11
Requires-Dist: gedcom-lite>=0.2
Requires-Dist: pyyaml>=6.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# gedcom-reports

Genealogy reports built on top of [gedcom-lite][].

This package provides higher-level report generators for GEDCOM files. Where
`gedcom-lite` answers questions like *"who are this person's ancestors?"*,
`gedcom-reports` produces a complete document — *"a 10-generation
Sosa-numbered ancestor report with categorized immigrant tables and a
colonial-ancestors section, in markdown."*

The tools in this package make editorial choices about how family history
should be presented. Those choices (region taxonomies, era boundaries,
numbering schemes) live in package-level config files that can be overridden
on the command line.

## Install

```bash
pip install gedcom-reports
```

Or run without installing:

```bash
uvx --from gedcom-reports gedcom-ancestor-report --help
```

## Tools

### `gedcom-ancestor-report`

Generates a markdown report of a person's direct ancestors. Sosa-Stradonitz
numbered. Categorizes ancestors into immigrant tables by region of birth and
into a colonial-ancestors section by birth/death era.

```bash
gedcom-ancestor-report tree.ged --root @I1@ --depth 7 --output report.md
```

Sections produced:

- **Per-generation listing** of every ancestor, numbered using the
  Ahnentafel system (#1 = subject, father = 2N, mother = 2N+1).
- **Alternate Family Tree sections** for each FAMC entry the user did not
  pick (only when `--alternate` is passed for that child).
- **Optional FAMC Conflicts list** (with `--show-conflicts`).
- **Immigrants section** with subsections per region (German and
  Scandinavian, Dutch, French, Spanish and Portuguese, Italian, Irish,
  Scottish, Welsh, English by default — fully configurable).
- **Colonial Ancestors section** — colonial immigrants, ancestors born in
  the colonies, and early US immigrants.

#### Flags

```
--root @I1@                   Root individual xref. (required)
--depth N                     Generations to walk (default: 7).
--override "@C@=@F@,@M@"      Pick parents @F@ and @M@ for child @C@.
                              Repeatable. Either parent may be empty.
--alternate @C@               Render an Alternate Family Tree section for
                              child @C@ from any FAMC entries that weren't
                              chosen. Repeatable.
--regions PATH                Path to regions.yaml or regions.json
                              (default: bundled).
--alt-depth N                 Cap depth of alternate family trees
                              (default: --depth).
--show-conflicts              Include a FAMC Conflicts section before the
                              tables.
--colonial / --no-colonial    Include or suppress the Colonial Ancestors
                              section (default: included). Pass
                              --no-colonial for non-US-focused reports.
--output PATH                 Write to a file (default: stdout).
```

#### FAMC default behavior

By default, the tool follows only the **first FAMC** of each individual.
This keeps the main tree unambiguous. To choose a different FAMC for an
individual, use `--override`. Overrides are silent — the un-chosen parent
set is dropped — unless you also pass `--alternate @C@`, which surfaces it
as a separate Alternate Family Tree section.

This split lets you handle two distinct cases cleanly:

- **Reconciling a data-entry error** (a person whose mother and father were
  entered as two separate FAMC families that should have been one) — use
  `--override` alone to merge them silently.
- **Documenting an unresolved parentage question** (sources disagree on
  someone's biological parents) — use `--override` *and* `--alternate` so
  both the chosen and rejected parent sets are visible in the report.

If you want to see which ancestors have multiple FAMC entries before
deciding on overrides, use `--show-conflicts`.

#### Region classification

A YAML/JSON config file controls how birth places are bucketed. The default
config ships with the package and includes Germanic, Scandinavian, Dutch,
French, Iberian, Italian, Irish, Scottish, Welsh, and English buckets.

The classification is two-pass: any US/colonies keyword in the place string
classifies the place as US (excluded from immigrant tables); otherwise
regions are tested in config order, first match wins.

To customize, copy the bundled `regions.yaml` (location reported by
`gedcom-ancestor-report --print-default-regions`) and pass `--regions PATH`.

## Relationship to gedcom-lite

`gedcom-lite` is the parser and low-level query layer. `gedcom-reports`
sits on top, depends on `gedcom-lite`, and produces complete documents.
This separation keeps the parser free of editorial choices and lets new
report types be added here without growing the parser's scope.

## License

MIT.

[gedcom-lite]: https://github.com/vaelen/gedcom-lite
