fastgedcom.base =============== .. py:module:: fastgedcom.base .. autoapi-nested-parse:: Classes and types for the data structure used to represent a gedcom. Attributes ---------- .. autoapisummary:: fastgedcom.base.SubmRef fastgedcom.base.SubnRef fastgedcom.base.IndiRef fastgedcom.base.FamRef fastgedcom.base.SNoteRef fastgedcom.base.SourRef fastgedcom.base.RepoRef fastgedcom.base.ObjeRef fastgedcom.base.XRef fastgedcom.base.VoidRef fastgedcom.base.Pointer fastgedcom.base.Record fastgedcom.base.fake_line Classes ------- .. autoapisummary:: fastgedcom.base.Line fastgedcom.base.FakeLine fastgedcom.base.TrueLine fastgedcom.base.Document Module Contents --------------- .. py:data:: SubmRef :type: TypeAlias :value: str The cross-reference identifier of type '@SUB1@' or '@U1@' for a submitter of the document. .. py:data:: SubnRef :type: TypeAlias :value: str Deprecated. The cross-reference identifier of type '@SUB2@' for a submission. .. py:data:: IndiRef :type: TypeAlias :value: str The cross-reference identifier of type '@I1@' for an individual. .. py:data:: FamRef :type: TypeAlias :value: str The cross-reference identifier of type '@F1@' for a family. .. py:data:: SNoteRef :type: TypeAlias :value: str The cross-reference identifier of type '@N1@' for a shared note. .. py:data:: SourRef :type: TypeAlias :value: str The cross-reference identifier of type '@S1@' for a source document. .. py:data:: RepoRef :type: TypeAlias :value: str The cross-reference identifier of type '@R1@' for a repository (an archive). .. py:data:: ObjeRef :type: TypeAlias :value: str The cross-reference identifier of type '@O1@' for an object (e.g. an image). .. py:data:: XRef :type: TypeAlias :value: SubmRef | SubnRef | IndiRef | FamRef | SNoteRef | SourRef | RepoRef | ObjeRef The cross-reference identifier indicates a record to which payloads may point. .. py:data:: VoidRef :type: TypeAlias :value: Literal['@VOID@'] 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. .. py:data:: Pointer :type: TypeAlias :value: XRef | VoidRef Generic pointer that is used in the payload to reference an existing record or a non-existing one. .. py:class:: Line Bases: :py:obj:`abc.ABC` Abstract base class for gedcom lines. Implementations are :py:class:`.TrueLine` and :py:class:`.FakeLine`, see these classes for more information. .. py:method:: __bool__() -> bool :abstractmethod: True if it is a :py:class:`.TrueLine`, False if it is a :py:class:`.FakeLine`. .. py:property:: payload :type: str :abstractmethod: See the description of :py:class:`.TrueLine` class. .. py:property:: payload_with_cont :type: str :abstractmethod: Return the multi-line payload into a single string. Multi-line payloads are split into several :py:class:`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. .. py:property:: sub_lines :type: list[TrueLine] :abstractmethod: See the description of :py:class:`.TrueLine` class. .. py:method:: __iter__() -> Iterator[TrueLine] Iterate on sub-lines, i.e. the next-level lines that are part of this structure. .. py:method:: get_sub_lines(tag: str) -> list[TrueLine] :abstractmethod: Return all sub-lines having the given :any:`tag`. Return an empty list if no line matches. .. py:method:: __rshift__(tag: str) -> list[TrueLine] Alias for :py:meth:`get_sub_lines` to shorten the syntax by using the >> operator. .. py:method:: get_sub_line(tag: str) -> TrueLine | FakeLine :abstractmethod: Return the first sub-line having the given :any:`tag`. Return a :py:class:`.FakeLine` if no line matches. .. py:method:: __gt__(tag: str) -> TrueLine | FakeLine Alias for :py:meth:`get_sub_line` to shorten the syntax by using the > operator. .. py:method:: get_sub_line_payload(tag: str) -> str :abstractmethod: Return the payload of the first sub-line having the given :any:`tag`. Return an empty string if no line matches. .. py:method:: __ge__(tag: str) -> str Alias for :py:meth:`get_sub_line_payload` to shorten the syntax by using the >= operator. .. py:method:: 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. .. py:method:: get_source() -> str Return the gedcom text equivalent for the line and its sub-lines. .. py:class:: FakeLine Bases: :py:obj:`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 :py:class:`.TrueLine` (It has the same methods), but the payload is empty. To differentiate a :py:class:`.FakeLine` from a :py:class:`.TrueLine` a simple boolean test is enough. .. py:attribute:: payload :value: '' See the description of :py:class:`.TrueLine` class. .. py:attribute:: payload_with_cont :value: '' Return the multi-line payload into a single string. Multi-line payloads are split into several :py:class:`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. .. py:attribute:: sub_lines :value: [] See the description of :py:class:`.TrueLine` class. .. py:method:: __bool__() -> Literal[False] Return False. .. py:method:: get_sub_lines(tag: str) -> list[TrueLine] Return all sub-lines having the given :any:`tag`. Return an empty list if no line matches. .. py:method:: __rshift__(tag: str) -> list[TrueLine] Alias for :py:meth:`get_sub_lines` to shorten the syntax by using the >> operator. .. py:method:: get_sub_line(tag: str) -> TrueLine | FakeLine Return the first sub-line having the given :any:`tag`. Return a :py:class:`.FakeLine` if no line matches. .. py:method:: __gt__(tag: str) -> TrueLine | FakeLine Alias for :py:meth:`get_sub_line` to shorten the syntax by using the > operator. .. py:method:: get_sub_line_payload(tag: str) -> str Return the payload of the first sub-line having the given :any:`tag`. Return an empty string if no line matches. .. py:method:: __ge__(tag: str) -> str Alias for :py:meth:`get_sub_line_payload` to shorten the syntax by using the >= operator. .. py:method:: __repr__() -> str Return the string representation of the class. .. py:method:: __eq__(value: object) -> bool .. py:class:: TrueLine Bases: :py:obj:`Line` Represent a line of a gedcom document. Contain the :py:attr:`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 :py:attr:`tag` is either the normalized Tag or the optional Xref. Hence, the :py:attr:`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 :py:attr:`level`, it matches the definition of the gedcom standard. .. py:attribute:: level :type: int The line level defined by the gedcom standard. .. py:attribute:: tag :type: 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. .. py:attribute:: payload :type: str :value: '' The payload of the structure, also called content or value. Warning: Multi-line payloads are split into several :py:class:`Line` as written in the original gedcom file. The corresponding sub-lines are with the tags CONC and CONT. Use the :py:attr:`payload_with_cont` property to get the complete multi-line payloads. .. py:attribute:: sub_lines :type: list[TrueLine] List of the sub-lines, i.e. the next-level lines that are part of this structure. .. py:method:: __bool__() -> Literal[True] Return True. .. py:method:: get_sub_lines(tag: str) -> list[TrueLine] Return all sub-lines having the given :any:`tag`. Return an empty list if no line matches. .. py:method:: __rshift__(tag: str) -> list[TrueLine] Alias for :py:meth:`get_sub_lines` to shorten the syntax by using the >> operator. .. py:method:: get_sub_line(tag: str) -> TrueLine | FakeLine Return the first sub-line having the given :any:`tag`. Return a :py:class:`.FakeLine` if no line matches. .. py:method:: __gt__(tag: str) -> TrueLine | FakeLine Alias for :py:meth:`get_sub_line` to shorten the syntax by using the > operator. .. py:method:: get_sub_line_payload(tag: str) -> str Return the payload of the first sub-line having the given :any:`tag`. Return an empty string if no line matches. .. py:method:: __ge__(tag: str) -> str Alias for :py:meth:`get_sub_line_payload` to shorten the syntax by using the >= operator. .. py:method:: __str__() -> str Return the gedcom representation of the line (sub-lines excluded). .. py:method:: __repr__() -> str Return the string representation of the class. .. py:property:: payload_with_cont :type: str Return the multi-line payload into a single string. Multi-line payloads are split into several :py:class:`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. .. py:data:: Record :type: TypeAlias :value: TrueLine A level 0 line referenced by an XRef in the document. .. py:class:: Document Store all the information of the gedcom document. All records (level 0 lines) are directly accessible via the :py:attr:`records` dictionnary and the other lines are accessible via :py:attr:`.TrueLine.sub_lines`. .. py:attribute:: records :type: dict[XRef, Record] Dictionnary of records, accessible via :py:meth:`get_records` or :py:meth:`__getitem__`. Access it directly to raise KeyError instead of getting a :py:class:`.FakeLine`. Usefull when you a pretty sure of the Record existing in the document. .. py:method:: __iter__() -> Iterator[Record] Iterate on the lines of level 0: the records, the header, and the TRLR line. .. py:method:: __contains__(identifier: XRef) -> bool Return True if the identifier refers to an existing record. .. py:method:: 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.. .. py:attribute:: __rshift__ Alias for :py:meth:`get_records` to shorten the syntax by using the >> operator. .. py:method:: get_record(identifier: XRef | Literal['HEAD']) -> Record | FakeLine Return the record under that ``identifier``. .. py:attribute:: __getitem__ Alias for :py:meth:`get_record` to shorten the syntax by using the [] operator. .. py:method:: all_lines() -> Iterator[list[TrueLine]] Return an iterator over all lines of the document. An element of the iterator is the sequence of lines to access the last line of the list. For example, given the following gedcom document:: 0 @I1@ INDI 1 NAME John /Doe/ 2 SURN Doe 0 @I2@ INDI >>> list(document.all_lines()) [ [ 1>], [ 1>, 1>], [ 1>, 1>, 0>], [ 0>], ] .. py:method:: __eq__(__value: object) -> bool .. py:method:: get_source() -> str Return the gedcom text equivalent for the :py:class:`.Document` into a string. Usefull to save a modified :py:class:`.Document` into a file. .. py:data:: fake_line :py:class:`.FakeLine` instance returned by functions. Used to avoid having multiple unnecessary instances of :py:class:`.FakeLine`.