fastgedcom.helpers

Utilitary functions to sort, format, or extract information.

Module Contents

Classes

DateType

Date modifiers allowed by the Gedcom specifications.

Functions

get_all_sub_lines(→ Iterator[fastgedcom.base.TrueLine])	/!DEPRECATED /!use the method Line.get_all_sub_lines() instead.
get_source(→ str)	/!DEPRECATED /!use the method Line.get_source() instead.
format_name(→ str)	Format the payload of NAME lines.
extract_name_parts(→ tuple[str, str])	Split the payload of NAME lines into the given name and the surname parts.
get_date_type(→ DateType | None)	Return the modifier used by DATE line payloads.
remove_trailing_zeros(→ str)	Removes useless 0 prefixing numbers.
format_date(→ str)	Format the payload of DATE lines.
extract_year(→ str)	Format the payload of DATE lines.
extract_int_year(…)	Format the payload of DATE lines.
to_datetime(→ datetime.datetime)	Convert the payload of DATE lines to datetime object.
to_datetime_range(→ tuple[datetime.datetime, ...)	Convert the payload of DATE lines to datetime objects.
add_time(→ datetime.datetime)	Parse the payload of TIME lines.
line_to_datetime(→ datetime.datetime)	Convert DATE lines to datetime object using the payload and the TIME sub-line.

fastgedcom.helpers.get_all_sub_lines(line: fastgedcom.base.TrueLine) → Iterator[fastgedcom.base.TrueLine]

/!DEPRECATED /!use the method Line.get_all_sub_lines() instead.

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

fastgedcom.helpers.get_source(line: fastgedcom.base.TrueLine | fastgedcom.base.FakeLine) → str

/!DEPRECATED /!use the method Line.get_source() instead.

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

fastgedcom.helpers.format_name(name: str) → str

Format the payload of NAME lines. Remove the backslash around the surname.

fastgedcom.helpers.extract_name_parts(name: str) → tuple[str, str]

Split the payload of NAME lines into the given name and the surname parts. The surname is the part of the payload surrounded by ‘/’.

class fastgedcom.helpers.DateType(*args, **kwds)

Bases: enum.Enum

Date modifiers allowed by the Gedcom specifications. They can appear in payload of DATE lines.

BC = '{date} BC'

Date before Christ. Old version from Gedcom5.

BCE = '{date} BCE'

Date before common era. New version from Gedcom7.

ABT = 'ABT {date}'

About date.

EST = 'EST {date}'

Estimated date.

CAL = 'CAL {date}'

Calculated date.

BEF = 'BEF {date}'

Before date.

AFT = 'AFT {date}'

After date.

TO = 'TO {date}'

To date. Not prefixed by FROM.

FROM = 'FROM {date}'

From date. Not followed by TO.

BET_AND = 'BET {date1} AND {date2}'

Between date1 and date2.

FROM_TO = 'FROM {date1} TO {date2}'

From date1 to date2.

fastgedcom.helpers.get_date_type(date: str) → DateType | None

Return the modifier used by DATE line payloads. If no modifier is recognized, return None. Ignore BC and BCE and return None, because these modifiers can be combined with the others.

fastgedcom.helpers.remove_trailing_zeros(date: str) → str

Removes useless 0 prefixing numbers.

fastgedcom.helpers.format_date(date: str) → str

Format the payload of DATE lines. Return a short string representation of the date by replacing gedcom keywords by symbols.

Replacements:

• BC is replaced by -.

• BCE is replaced by -.

• ABT is replaced by ~.

• EST is replaced by ~.

• CAL is replaced by ~.

• BEF is replaced by <.

• AFT is replaced by >.

• FROM is removed.

• TO is removed.

• BET_AND is replaced by –.

• FROM_TO is replaced by –.

fastgedcom.helpers.extract_year(date: str) → str

Format the payload of DATE lines.

Keep the context of the date, i.e. replacements produced by format_date(). To extract the year but not the context, use extract_int_year().

Remove the day and the month if present. The parameter is the DATE payload or the formatted date string.

fastgedcom.helpers.extract_int_year(date: str) → float | None

fastgedcom.helpers.extract_int_year(date: str, default: float) → float

Format the payload of DATE lines. Return the year of the date as an integer. On failure, return the default.

A BCE date returns a negative number. For BET_AND and FROM_TO date types, this function returns the median number of the range, hence the float type.

fastgedcom.helpers.to_datetime(date: str, default: datetime.datetime | None = None) → datetime.datetime

Convert the payload of DATE lines to datetime object.

If default is provided, return default on failure. Otherwise, raise ValueError on failure.

If no day or month is specified, the first day and month are used.

The returned date is more precise than extract_int_year(), but works less often. Infact, this method only works for positive dates (i.e. not BC) and ABT, CAL, EST date types. For BET_AND or TO_FROM date types, use the to_datetime_range() function. The BEF and AFT date types are not supported.

fastgedcom.helpers.to_datetime_range(date: str, default: datetime.datetime | None = None) → tuple[datetime.datetime, datetime.datetime]

Convert the payload of DATE lines to datetime objects.

If default is provided, return default on failure. Otherwise, raise ValueError on failure.

A case of failure is if the date types is not BET_AND, or FROM_TO.

Call to_datetime() on the first and second date.

fastgedcom.helpers.add_time(date: datetime.datetime, time_: str) → datetime.datetime

Parse the payload of TIME lines. If the time is parsed, return the datetime with its time set. Otherwise, return the datetime as it was.

Note: datetime is immutable, thus the presence of a returned value.

fastgedcom.helpers.line_to_datetime(date: fastgedcom.base.TrueLine | fastgedcom.base.FakeLine, default: datetime.datetime | None = None) → datetime.datetime

Convert DATE lines to datetime object using the payload and the TIME sub-line.

If default is provided, return default on date parsing failure. Otherwise, raise ValueError on failure.