gedcom7

A GEDCOM 7 parser for Python.

Background

The parser is based on regular expressions generated directly from the ABNF grammar via abnf-to-regexp, and on the structure and payload tables extracted from the specification. It targets FamilySearch GEDCOM 7.0.18.

It does not attempt to parse files that are not standards compliant: a data stream that violates the specification raises GedcomParseError rather than being partially or silently misparsed.

Installation

python -m pip install gedcom7

Usage

import gedcom7

with open("my_gedcom.ged", "r", encoding="utf-8") as f:
    string = f.read()

records = gedcom7.loads(string)

Each record is a GedcomStructure with a tag, an optional xref and pointer, the raw text payload, and children. The value property casts the payload to the data type the specification gives that structure type:

indi = records[1]  # 0 @I1@ INDI
birt = indi.children[0]  # 1 BIRT
date = birt.children[0]  # 2 DATE 1 JAN 2000
date.type_id  # 'https://gedcom.io/terms/v7/DATE'
date.value  # Date(calendar=None, day=1, month='JAN', ...)

value is None where a structure has no payload, and the payload is returned uninterpreted where the structure type is defined by an extension rather than by the specification.

Errors

loads raises GedcomParseError (a subclass of ValueError) for any data stream that does not conform to the specification, reporting where the problem is:

from gedcom7 import GedcomParseError

try:
    records = gedcom7.loads(string)
except GedcomParseError as exc:
    print(exc)  # line 42: malformed line: '1 NOTE @invalid'
    print(exc.line_number)  # 42
    print(exc.line)  # "1 NOTE @invalid"

This covers malformed lines, prohibited level sequences, banned characters, misplaced CONT continuations, duplicate or misplaced cross-reference identifiers, pointers that resolve to nothing, and a missing header or trailer.

Development

Install the package together with the development dependencies:

python -m pip install --group dev --editable .

Then run the checks:

pytest          # tests
mypy            # static type check (strict)
ruff check .    # lint
ruff format .   # format

Releasing

The version is derived from git tags by setuptools-scm; there is no version string in the source tree. To release, push a vX.Y.Z tag and publish a GitHub release for it — the PyPI deploy workflow builds the distributions and uploads them via PyPI trusted publishing.

Credits

Inspiration was drawn from the Javascript parser.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gedcom7-0.5.0.tar.gz (37.0 kB view details)

Uploaded Aug 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

gedcom7-0.5.0-py3-none-any.whl (19.3 kB view details)

Uploaded Aug 12, 2026 Python 3

File details

Details for the file gedcom7-0.5.0.tar.gz.

File metadata

Download URL: gedcom7-0.5.0.tar.gz
Upload date: Aug 12, 2026
Size: 37.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gedcom7-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`4c1b41dc4a69dfcd11853c4f63a073e2edae9352d49bbfaeb3eb123aa520a5bf`
MD5	`5a469b7cdd02d52a9fdccc0b8f4b6fa1`
BLAKE2b-256	`955b9e27c796f29e1f15da368be5fbb5f3bd01fc1225d294c11afe0cc53bd31b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for gedcom7-0.5.0.tar.gz:

Publisher: pypi.yml on DavidMStraub/python-gedcom7

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: gedcom7-0.5.0.tar.gz
- Subject digest: 4c1b41dc4a69dfcd11853c4f63a073e2edae9352d49bbfaeb3eb123aa520a5bf
- Sigstore transparency entry: 2437452194
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: DavidMStraub/python-gedcom7@ad3941a28b6919775625a2925b2be57cb2c01179
- Branch / Tag: refs/tags/v0.5.0
- Owner: https://github.com/DavidMStraub
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yml@ad3941a28b6919775625a2925b2be57cb2c01179
- Trigger Event: release