fastgedcom.base

Classes and types for the data structure used to represent a gedcom.

Module Contents

Classes

Line	Abstract base class for gedcom lines.
FakeLine	Dummy line for syntactic sugar.
TrueLine	Represent a line of a gedcom document.
Document	Store all the information of the gedcom document.

Attributes

SubmRef	The cross-reference identifier of type '@SUB1@' or '@U1@' for a submitter
SubnRef	Deprecated. The cross-reference identifier of type '@SUB2@' for a submission.
IndiRef	The cross-reference identifier of type '@I1@' for an individual.
FamRef	The cross-reference identifier of type '@F1@' for a family.
SNoteRef	The cross-reference identifier of type '@N1@' for a shared note.
SourRef	The cross-reference identifier of type '@S1@' for a source document.
RepoRef	The cross-reference identifier of type '@R1@' for a repository (an archive).
ObjeRef	The cross-reference identifier of type '@O1@' for an object (e.g. an image).
XRef	The cross-reference identifier indicates a record to which payloads may point.
VoidRef	A pointer used for unknown value where payload can't be let empty.
Pointer	Generic pointer that is used in the payload to reference an existing record
Record	A level 0 line referenced by an XRef in the document.
fake_line	FakeLine instance returned by functions.

fastgedcom.base.SubmRef: TypeAlias

The cross-reference identifier of type ‘@SUB1@’ or ‘@U1@’ for a submitter of the document.

fastgedcom.base.SubnRef: TypeAlias

Deprecated. The cross-reference identifier of type ‘@SUB2@’ for a submission.

fastgedcom.base.IndiRef: TypeAlias

The cross-reference identifier of type ‘@I1@’ for an individual.

fastgedcom.base.FamRef: TypeAlias

The cross-reference identifier of type ‘@F1@’ for a family.

fastgedcom.base.SNoteRef: TypeAlias

The cross-reference identifier of type ‘@N1@’ for a shared note.

fastgedcom.base.SourRef: TypeAlias

The cross-reference identifier of type ‘@S1@’ for a source document.

fastgedcom.base.RepoRef: TypeAlias

The cross-reference identifier of type ‘@R1@’ for a repository (an archive).

fastgedcom.base.ObjeRef: TypeAlias

The cross-reference identifier of type ‘@O1@’ for an object (e.g. an image).

fastgedcom.base.XRef: TypeAlias

The cross-reference identifier indicates a record to which payloads may point.

fastgedcom.base.VoidRef: TypeAlias

A pointer used for unknown value where payload can’t be let empty.

e.g.: In a family record, the line ‘2 CHIL @VOID@’ indicates that the parents had a child whom we know nothing. The line is used to keep the children birth order.

fastgedcom.base.Pointer: TypeAlias

Generic pointer that is used in the payload to reference an existing record or a non-existing one.

class fastgedcom.base.Line

Bases: abc.ABC

Abstract base class for gedcom lines.

Implementations are TrueLine and FakeLine, see these classes for more information.

abstract property payload: str

See the description of TrueLine class.

abstract property payload_with_cont: str

Return the multi-line payload into a single string.

Multi-line payloads are split into several Line as written in the original gedcom file. The corresponding sub-lines are with the tags CONC and CONT. There are gathered into a single string by concatenation of the different payload of each line. A newline is added for the concatenation of sub-lines with the CONT tag.

abstract property sub_lines: list[TrueLine]

See the description of TrueLine class.

abstract __bool__() → bool

True if it is a TrueLine, False if it is a FakeLine.

abstract get_sub_lines(tag: str) → list[TrueLine]

Return all sub-lines having the given tag. Return an empty list if no line matches.

__rshift__(tag: str) → list[TrueLine]

Alias for get_sub_lines() to shorten the syntax by using the >> operator.

abstract get_sub_line(tag: str) → TrueLine | FakeLine

Return the first sub-line having the given tag. Return a FakeLine if no line matches.

__gt__(tag: str) → TrueLine | FakeLine

Alias for get_sub_line() to shorten the syntax by using the > operator.

abstract get_sub_line_payload(tag: str) → str

Return the payload of the first sub-line having the given tag. Return an empty string if no line matches.

__ge__(tag: str) → str

Alias for get_sub_line_payload() to shorten the syntax by using the >= operator.

get_all_sub_lines() → Iterator[TrueLine]

Recursively iterate on sub-lines. All lines under the given line are returned. The order is preserved as in the gedcom file, sub-sub-lines come before siblings lines.

get_source() → str

Return the gedcom text equivalent for the line and its sub-lines.

class fastgedcom.base.FakeLine

Bases: Line

Dummy line for syntactic sugar.

It allows the chaining of method calls. See these examples for the usage of chaining.

The class behave like a TrueLine (It has the same methods), but the payload is empty.

To differentiate a FakeLine from a TrueLine a simple boolean test is enough.

payload = ''

payload_with_cont = ''

sub_lines = []

__bool__() → Literal[False]

Return False.

get_sub_lines(tag: str) → list[TrueLine]

Return all sub-lines having the given tag. Return an empty list if no line matches.

__rshift__(tag: str) → list[TrueLine]

Alias for get_sub_lines() to shorten the syntax by using the >> operator.

get_sub_line(tag: str) → TrueLine | FakeLine

Return the first sub-line having the given tag. Return a FakeLine if no line matches.

__gt__(tag: str) → TrueLine | FakeLine

Alias for get_sub_line() to shorten the syntax by using the > operator.

get_sub_line_payload(tag: str) → str

Return the payload of the first sub-line having the given tag. Return an empty string if no line matches.

__ge__(tag: str) → str

Alias for get_sub_line_payload() to shorten the syntax by using the >= operator.

__repr__() → str

Return the string representation of the class.

__eq__(value: object) → bool

Return self==value.

class fastgedcom.base.TrueLine

Bases: Line

Represent a line of a gedcom document.

Contain the sub-lines of the gedcom structure to form a recursive representation of the gedcom file.

This class uses the simplified format, instead of the normalized Level [Xref] Tag [LineVal] format.

The format of a gedcom line: Level Tag Payload.

In the simplified format, the tag is either the normalized Tag or the optional Xref. Hence, the payload is the LineVal - when the Xref is not present - or the normalized Tag plus the LineVal (generally an empty string) - when the Xref is present. The Payload can be an empty string. As for the level, it matches the definition of the gedcom standard.

property payload_with_cont: str

Return the multi-line payload into a single string.

Multi-line payloads are split into several Line as written in the original gedcom file. The corresponding sub-lines are with the tags CONC and CONT. There are gathered into a single string by concatenation of the different payload of each line. A newline is added for the concatenation of sub-lines with the CONT tag.

level: int

The line level defined by the gedcom standard.

tag: str | XRef

The cross-reference identifier for level 0 line (also called record identifier), or the tag defining the information and the structure of the data.

payload: str

The payload of the structure, also called content or value.

Warning: Multi-line payloads are split into several Line as written in the original gedcom file. The corresponding sub-lines are with the tags CONC and CONT. Use the payload_with_cont property to get the complete multi-line payloads.

sub_lines: list[TrueLine]

List of the sub-lines, i.e. the next-level lines that are part of this structure.

__bool__() → Literal[True]

Return True.

get_sub_lines(tag: str) → list[TrueLine]

Return all sub-lines having the given tag. Return an empty list if no line matches.

__rshift__(tag: str) → list[TrueLine]

Alias for get_sub_lines() to shorten the syntax by using the >> operator.

get_sub_line(tag: str) → TrueLine | FakeLine

Return the first sub-line having the given tag. Return a FakeLine if no line matches.

__gt__(tag: str) → TrueLine | FakeLine

Alias for get_sub_line() to shorten the syntax by using the > operator.

get_sub_line_payload(tag: str) → str

Return the payload of the first sub-line having the given tag. Return an empty string if no line matches.

__ge__(tag: str) → str

Alias for get_sub_line_payload() to shorten the syntax by using the >= operator.

__str__() → str

Return the gedcom representation of the line (sub-lines excluded).

__repr__() → str

Return the string representation of the class.

fastgedcom.base.Record: TypeAlias

A level 0 line referenced by an XRef in the document.

class fastgedcom.base.Document

Store all the information of the gedcom document.

All records (level 0 lines) are directly accessible via the records dictionnary and the other lines are accessible via TrueLine.sub_lines.

records: dict[XRef, Record]

Dictionnary of records, accessible via get_records() or __getitem__(). Access it directly to raise KeyError instead of getting a FakeLine. Usefull when you a pretty sure of the Record existing in the document.

__rshift__

Alias for get_records() to shorten the syntax by using the >> operator.

__getitem__

Alias for get_record() to shorten the syntax by using the [] operator.

__iter__() → Iterator[Record]

Iterate on the lines of level 0: the records, the header, and the TRLR line.

__contains__(identifier: XRef) → bool

Return True if the identifier refers to an existing record.

get_records(record_type: str) → Iterator[Record]

Return an iterator over records of that record_type. The type is the payload of level 0 lines: INDI, FAM, etc..

get_record(identifier: XRef | Literal[HEAD]) → Record | FakeLine

Return the record under that identifier.

__eq__(__value: object) → bool

Return self==value.

get_source() → str

Return the gedcom text equivalent for the Document into a string. Usefull to save a modified Document into a file.

fastgedcom.base.fake_line

FakeLine instance returned by functions. Used to avoid having multiple unnecessary instances of FakeLine.