fastgedcom.helpers ================== .. py:module:: fastgedcom.helpers .. autoapi-nested-parse:: Utilitary functions to sort, format, or extract information. Classes ------- .. autoapisummary:: fastgedcom.helpers.DateType Functions --------- .. autoapisummary:: fastgedcom.helpers.get_all_sub_lines fastgedcom.helpers.get_source fastgedcom.helpers.format_name fastgedcom.helpers.extract_name_parts fastgedcom.helpers.get_date_type fastgedcom.helpers.remove_trailing_zeros fastgedcom.helpers.format_date fastgedcom.helpers.extract_year fastgedcom.helpers.extract_int_year fastgedcom.helpers.to_datetime fastgedcom.helpers.to_datetime_range fastgedcom.helpers.add_time fastgedcom.helpers.line_to_datetime Module Contents --------------- .. py:function:: get_all_sub_lines(line: fastgedcom.base.TrueLine) -> Iterator[fastgedcom.base.TrueLine] /!\ DEPRECATED /!\ use the method :py:meth:`Line.get_all_sub_lines` instead. Recursively iterate on :py:class:`.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. .. py:function:: get_source(line: fastgedcom.base.TrueLine | fastgedcom.base.FakeLine) -> str /!\ DEPRECATED /!\ use the method :py:meth:`Line.get_source` instead. Return the gedcom text equivalent for the line and its sub-lines. .. py:function:: format_name(name: str) -> str Format the payload of NAME lines. Remove the backslash around the surname. .. py:function:: 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 '/'. .. py:class:: DateType(*args, **kwds) Bases: :py:obj:`enum.Enum` Date modifiers allowed by the Gedcom specifications. They can appear in payload of DATE lines. .. py:attribute:: BC :value: '{date} BC' Date before Christ. Old version from Gedcom5. .. py:attribute:: BCE :value: '{date} BCE' Date before common era. New version from Gedcom7. .. py:attribute:: ABT :value: 'ABT {date}' About date. .. py:attribute:: EST :value: 'EST {date}' Estimated date. .. py:attribute:: CAL :value: 'CAL {date}' Calculated date. .. py:attribute:: BEF :value: 'BEF {date}' Before date. .. py:attribute:: AFT :value: 'AFT {date}' After date. .. py:attribute:: TO :value: 'TO {date}' To date. Not prefixed by :py:attr:`FROM`. .. py:attribute:: FROM :value: 'FROM {date}' From date. Not followed by :py:attr:`TO`. .. py:attribute:: BET_AND :value: 'BET {date1} AND {date2}' Between date1 and date2. .. py:attribute:: FROM_TO :value: 'FROM {date1} TO {date2}' From date1 to date2. .. py:function:: get_date_type(date: str) -> DateType | None Return the modifier used by DATE line payloads. If no modifier is recognized, return None. Ignore :py:attr:`BC` and :py:attr:`BCE` and return None, because these modifiers can be combined with the others. .. py:function:: remove_trailing_zeros(date: str) -> str Removes useless 0 prefixing numbers. .. py:function:: 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: * :py:attr:`BC` is replaced by `-`. * :py:attr:`BCE` is replaced by `-`. * :py:attr:`ABT` is replaced by `~`. * :py:attr:`EST` is replaced by `~`. * :py:attr:`CAL` is replaced by `~`. * :py:attr:`BEF` is replaced by `<`. * :py:attr:`AFT` is replaced by `>`. * :py:attr:`FROM` is removed. * :py:attr:`TO` is removed. * :py:attr:`BET_AND` is replaced by `--`. * :py:attr:`FROM_TO` is replaced by `--`. .. py:function:: extract_year(date: str) -> str Format the payload of DATE lines. Keep the context of the date, i.e. replacements produced by :py:func:`format_date`. To extract the year but not the context, use :py:func:`.extract_int_year`. Remove the day and the month if present. The parameter is the DATE payload or the formatted date string. .. py:function:: extract_int_year(date: str) -> float | None 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 :py:attr:`BCE` date returns a negative number. For :py:attr:`BET_AND` and :py:attr:`FROM_TO` date types, this function returns the median number of the range, hence the float type. .. py:function:: 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 :py:func:`.extract_int_year`, but works less often. Infact, this method only works for positive dates (i.e. not :py:attr:`BC`) and :py:attr:`ABT`, :py:attr:`CAL`, :py:attr:`EST` date types. For :py:attr:`BET_AND` or :py:attr:`TO_FROM` date types, use the :py:func:`.to_datetime_range` function. The :py:attr:`BEF` and :py:attr:`AFT` date types are not supported. .. py:function:: 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 :py:attr:`BET_AND`, or :py:attr:`FROM_TO`. Call :py:func:`.to_datetime` on the first and second date. .. py:function:: 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. .. py:function:: 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. When the date is a range, return the median date of the range.