Skip to content

Latest commit

 

History

History
62 lines (40 loc) · 3.07 KB

README.md

File metadata and controls

62 lines (40 loc) · 3.07 KB

gedcom7

Tests PyPI Python versions License: MIT

Read and write GEDCOM 7 files in Python — a format for exchanging genealogical data between family history applications.

Background

Reading and writing are both 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. The library targets FamilySearch GEDCOM 7.0.18: it does not attempt to parse files that are not standards compliant, and raises rather than writing malformed lines.

Installation

python -m pip install gedcom7

Usage

import gedcom7

with open("my_gedcom.ged", "rb") as f:
    records = gedcom7.load(f)

with open("out.ged", "wb") as f:
    gedcom7.dump(records, f)

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

loads and dumps are the string equivalents. Non-conforming input raises GedcomParseError, a ValueError carrying line_number. A pointer to a record that does not exist is kept rather than rejected; gedcom7.validate(records) lists each one as a dangling-pointer error.

validate returns a list of Error, each with a category, a message and the path to the structure, such as @I1@ INDI > BIRT > DATE. An Error whose severity is "recommendation" breaks only a recommendation of the specification, so the dataset still conforms; dumps(records, validate=True) raises only for the others. An empty list does not prove a dataset conforms: cardinality and enumeration values are not checked, and substructures of extensions are left to the extension's own definition.

GEDZIP

with gedcom7.GedzipReader("family.gdz") as archive:
    records = archive.records
    with archive.open("media/photo.jpg") as f:  # a FILE payload
        data = f.read()

gedcom7.dump_gedzip(records, "out.gdz", {"media/photo.jpg": data})

File content can be given as bytes, a path, or a function returning an open binary file. Where the files are stored is left to the caller.

Development

python -m pip install --group dev --editable .
pytest && mypy && ruff check . && ruff format --check .

The version is derived from git tags by setuptools-scm. To release, push a vX.Y.Z tag and publish a GitHub release for it.

Credits

Inspiration was drawn from the Javascript parser.