ged4py.calendar

Module for parsing and representing calendar dates in gedcom format.

Classes

CalendarDate(year[, month, day, bc, original])

Interface for calendar date representation.

CalendarDateVisitor()

Interface for implementation of Visitor pattern for CalendarDate classes.

CalendarType(value)

Namespace for constants defining names of calendars.

FrenchDate(year[, month, day, bc, original])

Implementation of CalendarDate for French Republican calendar.

GregorianDate(year[, month, day, bc, …])

Implementation of CalendarDate for Gregorian calendar.

HebrewDate(year[, month, day, bc, original])

Implementation of CalendarDate for Hebrew calendar.

JulianDate(year[, month, day, bc, original])

Implementation of CalendarDate for Julian calendar.
class ged4py.calendar.CalendarType(value)[source]

Bases: enum.Enum

Namespace for constants defining names of calendars.

Note that it does not define constants for ROMAN calendar which is declared in GEDCOM standard as a placeholder for future definition, or UNKNOWN calendar which is not supported by this library.

The constants defined in this namespace are used for the values of the CalendarDate.calendar attribute. Each separate class implementing CalendarDate interface uses distinct value for that attribute, and this value can be used to deduce actual type of the CalendarDate instance.

GREGORIAN = 'GREGORIAN'

This is the value assigned to GregorianDate.calendar attribute.

JULIAN = 'JULIAN'

This is the value assigned to JulianDate.calendar attribute.

HEBREW = 'HEBREW'

This is the value assigned to HebrewDate.calendar attribute.

FRENCH_R = 'FRENCH R'

This is the value assigned to FrenchDate.calendar attribute.

class ged4py.calendar.CalendarDate(year, month=None, day=None, bc=False, original=None)[source]

Bases: object

Interface for calendar date representation.

Parameters
yearint

Calendar year number. If bc parameter is True then this year is before “epoch” of that calendar.

monthstr

Name of the month. Optional, but if day is given then month cannot be None.

dayint

Day in a month, optional.

bcbool

True if year has “B.C.”

originalstr

Original string representation of this date as it was specified in GEDCOM file, could be None.

Notes

This class defines attributes and methods that are common for all calendars defined in GEDCOM (though the meaning and representation can be different in different calendars). In GEDCOM date consists of year, month, and day; day and month are optional (either day or day+month), year must be present. Day is a number, month is month name in a given calendar. Year is a number optionally followed by B.C. or /NUMBER (latter is defined for Gregorian calendar only).

Implementation for different calendars are provided by subclasses which can implement additional attributes or methods. All subclasses need to implement key() method to support ordering of the dates from different calendars. There are presently four implementations defined in this module:

To implement type-specific code on client side one can use one of these approaches:

  • dispatch based on the value of calendar attribute, it has one of the values defined in CalendarType enum, the value maps uniquely to an implementation class;

  • dispatch based on the type of the instance using isinstance method to check the type (e.g. isinstance(date, GregorianDate));

  • double dispatch (visitor pattern) by implementing CalendarDateVisitor interface.

Attributes
calendar

Calendar used for this date, one of the CalendarType enums

year_str

Calendar year in string representation, this can include dual year and/or B.C.

Methods

accept(visitor)

Implementation of visitor pattern.

key()

Return ordering key for this instance.

months()

Ordered list of month names (in GEDCOM format) defined in calendar.

parse(datestr)

Parse <DATE> string and make CalendarDate from it.
year

Calendar year number (int)

month

Month name or None (str)

day

Day number or None (int)

bc

Flag which is True if year has a “B.C” suffix (bool).

original

Original string representation of this date as it was specified in GEDCOM file, could be None (str).

month_num

Integer month number (1-based) or None if month name is not given or unknown (int).

abstract classmethod months()[source]

Ordered list of month names (in GEDCOM format) defined in calendar.

abstract key()[source]

Return ordering key for this instance.

Returned key is a tuple with two numbers (jd, flag). jd is the Julian Day number as floating point, flag is an integer flag. If month or day is not known then last month or last day should be returned in its place (in corresponding calendar, and converted to JD) and flag should be set to 1. If date and month are known then flag should be set to 0.

property year_str

Calendar year in string representation, this can include dual year and/or B.C. suffix (str)

abstract property calendar

Calendar used for this date, one of the CalendarType enums (CalendarType)

abstract accept(visitor)[source]

Implementation of visitor pattern.

Each concrete sub-class will implement this method by dispatching the call to corresponding visitor method.

Parameters
visitorCalendarDateVisitor

Visitor instance.

Returns
valueobject

Value returned from a visitor method.

classmethod parse(datestr)[source]

Parse <DATE> string and make CalendarDate from it.

Parameters
datestrstr

String with GEDCOM date.

Returns
dateCalendarDate

Date instance.

Raises
ValueError

Raised if parsing fails.

class ged4py.calendar.FrenchDate(year, month=None, day=None, bc=False, original=None)[source]

Bases: ged4py.calendar.CalendarDate

Implementation of CalendarDate for French Republican calendar.

All parameters have the same meaning as in CalendarDate class.

Attributes
calendar

Calendar used for this date, one of the CalendarType enums

year_str

Calendar year in string representation, this can include dual year and/or B.C.

Methods

accept(visitor)

Implementation of visitor pattern.

key()

Return ordering key for this instance.

months()

Ordered list of month names (in GEDCOM format) defined in calendar.

parse(datestr)

Parse <DATE> string and make CalendarDate from it.
classmethod months()[source]

Ordered list of month names (in GEDCOM format) defined in calendar.

key()[source]

Return ordering key for this instance.

property calendar

Calendar used for this date, one of the CalendarType enums (CalendarType)

accept(visitor)[source]

Implementation of visitor pattern.

Each concrete sub-class will implement this method by dispatching the call to corresponding visitor method.

Parameters
visitorCalendarDateVisitor

Visitor instance.

Returns
valueobject

Value returned from a visitor method.

class ged4py.calendar.GregorianDate(year, month=None, day=None, bc=False, original=None, dual_year=None)[source]

Bases: ged4py.calendar.CalendarDate

Implementation of CalendarDate for Gregorian calendar.

Parameter dual_year (and corresponding attribute) is used for dual year. Other parameters have the same meaning as in CalendarDate class.

Parameters
dual_yearint, optional

Dual year number or None. Actual year should be given, not just two last digits.

Notes

In GEDCOM Gregorian calendar dates are allowed to specify year in the form YEAR1/YEAR2 (a.k.a.) dual-dating. Second number is used to specify year as if calendar year starts in January, while the first number is used for actual calendar year which starts at different date. Note that GEDCOM specifies that dual year uses just two last digits in the dual year number, though some implementations use 4 digits. This class expects actual year number (e.g. as if it was specified as “1699/1700”).

Attributes
calendar

Calendar used for this date, one of the CalendarType enums

year_str

Calendar year in string representation, this can include dual year and/or B.C.

Methods

accept(visitor)

Implementation of visitor pattern.

key()

Return ordering key for this instance.

months()

Ordered list of month names (in GEDCOM format) defined in calendar.

parse(datestr)

Parse <DATE> string and make CalendarDate from it.
dual_year

If not None then this number represent year in a calendar with year starting on January 1st (int).

classmethod months()[source]

Ordered list of month names (in GEDCOM format) defined in calendar.

property calendar

Calendar used for this date, one of the CalendarType enums (CalendarType)

key()[source]

Return ordering key for this instance.

property year_str

Calendar year in string representation, this can include dual year and/or B.C. suffix (str)

accept(visitor)[source]

Implementation of visitor pattern.

Each concrete sub-class will implement this method by dispatching the call to corresponding visitor method.

Parameters
visitorCalendarDateVisitor

Visitor instance.

Returns
valueobject

Value returned from a visitor method.

class ged4py.calendar.HebrewDate(year, month=None, day=None, bc=False, original=None)[source]

Bases: ged4py.calendar.CalendarDate

Implementation of CalendarDate for Hebrew calendar.

All parameters have the same meaning as in CalendarDate class.

Attributes
calendar

Calendar used for this date, one of the CalendarType enums

year_str

Calendar year in string representation, this can include dual year and/or B.C.

Methods

accept(visitor)

Implementation of visitor pattern.

key()

Return ordering key for this instance.

months()

Ordered list of month names (in GEDCOM format) defined in calendar.

parse(datestr)

Parse <DATE> string and make CalendarDate from it.
classmethod months()[source]

Ordered list of month names (in GEDCOM format) defined in calendar.

key()[source]

Return ordering key for this instance.

property calendar

Calendar used for this date, one of the CalendarType enums (CalendarType)

accept(visitor)[source]

Implementation of visitor pattern.

Each concrete sub-class will implement this method by dispatching the call to corresponding visitor method.

Parameters
visitorCalendarDateVisitor

Visitor instance.

Returns
valueobject

Value returned from a visitor method.

class ged4py.calendar.JulianDate(year, month=None, day=None, bc=False, original=None)[source]

Bases: ged4py.calendar.CalendarDate

Implementation of CalendarDate for Julian calendar.

All parameters have the same meaning as in CalendarDate class.

Attributes
calendar

Calendar used for this date, one of the CalendarType enums

year_str

Calendar year in string representation, this can include dual year and/or B.C.

Methods

accept(visitor)

Implementation of visitor pattern.

key()

Return ordering key for this instance.

months()

Ordered list of month names (in GEDCOM format) defined in calendar.

parse(datestr)

Parse <DATE> string and make CalendarDate from it.
classmethod months()[source]

Ordered list of month names (in GEDCOM format) defined in calendar.

key()[source]

Return ordering key for this instance.

property calendar

Calendar used for this date, one of the CalendarType enums (CalendarType)

accept(visitor)[source]

Implementation of visitor pattern.

Each concrete sub-class will implement this method by dispatching the call to corresponding visitor method.

Parameters
visitorCalendarDateVisitor

Visitor instance.

Returns
valueobject

Value returned from a visitor method.

class ged4py.calendar.CalendarDateVisitor[source]

Bases: object

Interface for implementation of Visitor pattern for CalendarDate classes.

One can easily extend behavior of the CalendarDate class hierarchy without modifying classes themselves. Clients need to implement new behavior by sub-classing CalendarDateVisitor and calling CalendarDate.accept() method, e.g.:

class FormatterVisitor(CalendarDateVisitor):

    def visitGregorian(self, date):
        return "Gregorian date:" + str(date)

    # and so on for each date type

visitor = FormatterVisitor()

date = CalendarDate.parse(date_string)
formatted = date.accept(visitor)

Methods

visitFrench(date)

Visit an instance of FrenchDate type.

visitGregorian(date)

Visit an instance of GregorianDate type.

visitHebrew(date)

Visit an instance of HebrewDate type.

visitJulian(date)

Visit an instance of JulianDate type.
abstract visitGregorian(date)[source]

Visit an instance of GregorianDate type.

Parameters
dateGregorianDate

Date instance.

Returns
valueobject

Implementation of this method can return anything, value will be returned from CalendarDate.accept() method.

abstract visitJulian(date)[source]

Visit an instance of JulianDate type.

Parameters
dateJulianDate

Date instance.

Returns
valueobject

Implementation of this method can return anything, value will be returned from CalendarDate.accept() method.

abstract visitHebrew(date)[source]

Visit an instance of HebrewDate type.

Parameters
dateHebrewDate

Date instance.

Returns
valueobject

Implementation of this method can return anything, value will be returned from CalendarDate.accept() method.

abstract visitFrench(date)[source]

Visit an instance of FrenchDate type.

Parameters
dateFrenchDate

Date instance.

Returns
valueobject

Implementation of this method can return anything, value will be returned from CalendarDate.accept() method.