tzolkin_calendar Package
This is the source code reference documentation, autogenerated from tzolkin-calendar’s source code.
Submodules
tzolkin_calendar.tzolkin module
Main Tzolkin class.
- class Tzolkin(number: int, name_str: str | None = None, name_number: int | None = None)
Bases:
object
A representation of a Tzolkin date. Use to do calculations and conversions from and to gregorian dates to Tzolkin dates and search for days.
- addDays(days: int) Tzolkin
Add the number of days to this Tzolkin date and return this instance too.
- Parameters:
days (int) – The number of days to add (or subtract, if < 0) to this Tzolkin instance.
- Returns:
This instance with the number of days added (or subtracted) to it.
- Return type:
- addTimedelta(delta: timedelta) Tzolkin
Add the number of days given in the datetime.timedelta object to this Tzolkin date. Returns this Tzolkin instance with the days added to or subtracted from.
- Parameters:
delta (datetime.timedelta) – The number of days to add (or subtrace, if < 0).
- Returns:
This instance with the number of days added or subtracted.
- Return type:
- classmethod fromDate(date: date) Tzolkin
Create a Tzolkin instance from the given gregorian date.
- Parameters:
date (datetime.date) – The date to convert to a Tzolkin date.
- Returns:
The gregorion date date converted to a Tzolkin date.
- Return type:
- classmethod fromDateString(date_str: str, fmt: str) Tzolkin
Create a Tzolkin instance from the given gregorian date string. See https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior for a detailed description of date format strings.
- Parameters:
date_str (str) – The date to convert to a Tzolkin date.
fmt (str) – The format string to parse the given date string. See
strings. (datetime.datetime.strptime for a description of date format)
- Returns:
The gregorion date date_str converted to a Tzolkin date.
- Return type:
- classmethod fromIsoFormat(date_str: str) Tzolkin
Create a Tzolkin instance from the given gregorian date string in ISO format. ISO format means a date in the form ‘YYYY-MM-DD’, like ‘2019-03-21’. See https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat
- Parameters:
date_str (str) – See also datetime.date.fromisoformat
- Returns:
The gregorion date date_str converted to a Tzolkin date.
- Return type:
- classmethod fromToday() Tzolkin
Return the current date (today) as a Tzolkin date.
- Returns:
The current day (today) as a Tzolkin date.
- Return type:
- getDayDiff(other: Tzolkin) int
Return the number of days between the two Tzolkin dates. No negative differences are returned, but the number of days to reach the other date if starting from this Tzolkin date. If this date is earlier than other the difference is this - other. If other is before this, 260 - this + other (same as 260 - (other - this)) is returned.
- Parameters:
other (Tzolkin) – The Tzolkin date to calculate the time difference to.
- Returns:
- The number of days between the Tzolkin date of this Tzolkin instance
and the Tzolkin date other.
- Return type:
int
- getDayName() str
Return the day name of the Tzolkin date of this class instance.
- Returns:
The day name of this Tzolkin date.
- Return type:
str
- getDayNameNumber() int
Return the number of the Tzolkin day name of this class instance.
- Returns:
The number of the Tzolkin day name of this Tzolkin date.
- Return type:
int
- getDayNumber() int
Return the day number of the Tzolkin date of this class instance.
- Returns:
The day number of this Tzolkin date.
- Return type:
int
- getDayTimedelta(other: Tzolkin) timedelta
Return the number of days between the two Tzolkin dates as a datetime.timedelta object. No negative differences are returned, but the number of days to reach the other date if starting from this Tzolkin date. If this date is earlier than other the difference is this - other. If other is before this, 260 - this + other (same as 260 - (other - this)) is returned.
- Parameters:
other (Tzolkin) – The Tzolkin date to calculate the time difference to.
- Returns:
- The number of days between the Tzolkin date of this Tzolkin instance
and the Tzolkin date other as a datetime.timedelta object.
- Return type:
datetime.timedelta
- getLastDate(start_date: date = datetime.date(2024, 8, 27)) date
Return the last gregorian date with the Tzolkin date of this Tzolkin instance. Last means the first gregorian date with the same Tzolkin date as this Tzolkin instance before (backwards in time) start_date.
- Parameters:
start_date (datetime.date, optional) – The date to start searching for a day with the same Tzolkin date. Defaults to datetime.date.today().
- Returns:
- The gregorian date of the day with the same Tzolkin date as
this Tzolkin instance before start_date.
- Return type:
datetime.date
- getLastDateList(start_date: date = datetime.date(2024, 8, 27), list_size: int = 50) List[date]
Return a list of dates with the same Tzolkin date as this Tzolkin instance before`start_date`. Searches backwards in time, starting with start_date. The number of elements in this returned list is set with list_size, that is the number of dates to search and return. If list_size < 1, an empty list is returned.
- Parameters:
start_date (datetime.date, optional) – The date to start searching for a day with the same Tzolkin date. Defaults to datetime.date.today().
list_size (int, optional) – The number of elements in the returned list of dates. Defaults to 50.
- Returns:
- The list with list_size elements of days with the
same Tzolkin date as this instance before start_date.
- Return type:
List[datetime.date]
- static getNameNumberFromName(name_str: str) int
Return the day name’s number (between 1 and 20) of the Tzolkin day name. Imix yields the number 1, Ikʼ 2, … , Ajaw yields 20.
- Parameters:
name_str (TzolkinName) – The day name to convert to a number.
- Raises:
TzolkinException – Raised, if name_str is not a valid TzolkinName, that
is, one of "Imix", "Ikʼ", "Akʼbʼal", "Kʼan", "Chikchan", "Kimi", "Manikʼ", –
"Lamat", "Muluk", "Ok", "Chuwen", "Ebʼ", "Bʼen", "Ix", "Men", "Kʼibʼ", –
"Kabʼan", "Etzʼnabʼ", "Kawak" and "Ajaw". –
- Returns:
- The number of the Tzolkin day name, between 1 and 20 (including 1 and
20).
- Return type:
int
- getNextDate(start_date: date = datetime.date(2024, 8, 27)) date
Return the next gregorian date with the Tzolkin date of this Tzolkin instance. Next means the first gregorian date with the same Tzolkin date as this Tzolkin instance after (forward in time) start_date.
- Parameters:
start_date (datetime.date, optional) – The date to start searching for a day with the same Tzolkin date. Defaults to datetime.date.today().
- Returns:
- The gregorian date of the day with the same Tzolkin date as
this Tzolkin instance after start_date.
- Return type:
datetime.date
- getNextDateList(start_date: date = datetime.date(2024, 8, 27), list_size: int = 50) List[date]
Return a list of dates with the same Tzolkin date as this Tzolkin instance after start_date. Searches forwards in time, starting with start_date. The number of elements in this returned list is set with list_size, that is the number of dates to search and return. If list_size < 1, an empty list is returned.
- Parameters:
start_date (datetime.date, optional) – The date to start searching for a day with the same Tzolkin date. Defaults to datetime.date.today().
list_size (int, optional) – The number of elements in the returned list of dates. Defaults to 50.
- Returns:
- The list with list_size elements of days with the
same Tzolkin date as this instance after start_date.
- Return type:
List[datetime.date]
- static getTzolkinCalendar() List[str]
Return all days in a Tzolkin year as a List of strings. The returned List looks like: [“1 Imix”, “2 Ikʼ”, … , “13 Ajaw”]
- Returns:
All days with day number and name in a list of strings.
- Return type:
List[str]
- getTzolkinDate() TzolkinDate
Return the Tzolkin date as a TzolkinDate instance to use with the tzolkin_calendar.calculate functions.
- Returns:
The TzolkinDate instance of this Tzolkin date.
- Return type:
TzolkinDate
- getTzolkinYearDay() int
- Return the day of the Tzolkin year of this Tzolkin date.
1 Imix, the first day in the Tzolkin year, yields 1, 13 Ajaw, the last day of the Tzolkin year, yields 260 and so on.
- Returns:
- The day of this Tzolkin date in the Tzolkin year, an integer between
1 and 260 (including 1 and 260).
- Return type:
int
- static parseTzolkinName(name_str: str) int
Parse the given string to get a valid Tzolkin name. Ignores lower- and uppercase and all non-alphanumeric or non-ASCII letters.
Returns 0 if no Tzolkin day names matches the given string.
- Parameters:
name_str (str) – The string to parse for a Tzolkin day name.
- Returns:
- The number of the Tzolkin day name on success, 0 if no Tzolkin day name
matches.
- Return type:
int
tzolkin_calendar.calculate module
This modules holds functions needed to calculate with Tzolkin calendar dates and convert them to and from gregorian dates.
Example:
>>> import datetime
>>> import tzolkin_calendar.calculate
>>> tzolkin_calendar.calculate.gregorian2tzolkin(datetime.datetime.strptime("23.05.2014", "%d.%m.%Y"))
2 Etzʼnabʼ ()
>>> import datetime
>>> import tzolkin_calendar.calculate
>>> tzolkin_calendar.calculate.nextTzolkin(tzolkin_calendar.TzolkinDate(name=3, number=5))
datetime.date(2021, 4, 21)
>>> import datetime
>>> import tzolkin_calendar.calculate
>>> tzolkin_calendar.calculate.lastTzolkin(tzolkin_calendar.TzolkinDate(name=17, number=3))
datetime.date(2021, 1, 5)
>>> import datetime
>>> import tzolkin_calendar.calculate
>>> tzolkin_calendar.calculate.tzolkin2gregorian(tzolkin_calendar.TzolkinDate(name="2", number="7"),start=datetime.date.today())
[datetime.date(2021, 10, 15), datetime.date(2022, 7, 2), datetime.date(2023, 3, 19), datetime.date(2023, 12, 4),
>>> import datetime
>>> import tzolkin_calendar.calculate
>>> tzolkin_calendar.calculate.tzolkin2gregorian(tzolkin_calendar.TzolkinDate(name="2", number="7"), forward=False, start=datetime.date.today())
[datetime.date(2021, 10, 15), datetime.date(2021, 1, 28), datetime.date(2020, 5, 13), datetime.date(2019, 8, 27),
- calculateTzolkinName(start_name: int, to_add: int) int
Return the Tzolkin name to_add days after start_name. Add or subtracts the given integer to the index of the Tzolkin name and return the index of the new name. Adds to_add to the name index start_name and takes the value modulo 20. If the result would be 0, return 20 instead.
- Parameters:
start_name (int) – The index of the name to add days to.
to_add (int) – The number of days to add to the Tzolkin name.
- Returns:
The index of the resulting Tzolkin name, to_add days after start_name.
- Return type:
int
- calculateTzolkinNumber(start_number: int, to_add: int) int
Return the Tzolkin number to_add days after start_number. Add or subtracts the given integer to the Tzolkin number and return the new number. Adds to_add to the number start_name and takes the value modulo 13. If the result would be 0, return 13 instead.
- Parameters:
start_number (int) – The number to add the days to.
to_add (int) – The number of days to add to the Tzolkin number.
- Returns:
The resulting number to_add days after start_number.
- Return type:
int
- getTzolkinDay(tzolkin: TzolkinDate) int
Return the day number in the Tzolkin year, in the interval [1,260] (including both 1 and 260). That is, the index of the given Tzolkin date in the 260 day Tzolkin year. 1 Imix yields 1 (the first day of the year), 13 Ajaw yields 260, the last day of the Tzolkin year. If the given date tzolkin does not exist, 0 is returned.
- Parameters:
tzolkin (TzolkinDate) – The Tzolkin date to get the day in the year of.
- Returns:
- The day of the given date in the Tzolkin year, a positive integer between
and including 1 and 260. If the given date does not exist, 0 is returned.
- Return type:
int
- getTzolkinDiff(start: TzolkinDate, end: TzolkinDate) int
Return the difference in days between the two given Tzolkin dates. No negative differences are returned, but the number of days to reach the end date if starting from start. If start is earlier than end the difference is start - end. If end is before start, 260 - start + end (same as 260 - (end - start)) is returned.
Example
getTzolkinDiff returns 12 for start = 4 Manikʼ and end = 3 Kawak
>>> getTzolkinDiff( start=tzolkin_calendar.TzolkinDate(number=4, name=7), end=tzolkin_calendar.TzolkinDate(number=3, name=19), ) == 12
getTzolkinDiff returns 250 for start = 8 Chuwen and end = 11 Imix
>>> getTzolkinDiff( start=tzolkin_calendar.TzolkinDate(number=8, name=11), end=tzolkin_calendar.TzolkinDate(number=11, name=1), ) == 250
- Parameters:
start (TzolkinDate) – The Tzolkin date to start the calculation from.
end (TzolkinDate) – The Tzolkin date to calculate the time difference in days to.
- Returns:
The number of days between the two given dates. Never negative (0 if start and end are the same day).
- Return type:
int
- gregorian2tzolkin(date: date) TzolkinDate
Return the Tzolkin date of the given gregorian date.
- Parameters:
date (datetime.date) – The gregorian date to convert to Tzolkin.
- Returns:
The Tzolkin date of the given day date.
- Return type:
TzolkinDate
- lastTzolkin(tzolkin: TzolkinDate, starting: date = datetime.date(2024, 8, 27)) date
Return the last gregorian date before starting, that has a Tzolkin date of tzolkin. Search backwards in time for a day with the Tzolkin date tzolkin.
- Parameters:
tzolkin (TzolkinDate) – The Tzolkin date to search for.
starting (datetime.date, optional) – The date to start the search. Defaults to datetime.date.today().
- Returns:
- The last gregorian date with the given Tzolkin date tzolkin
before starting.
- Return type:
datetime.date
- makeLookUpTable() Dict[int, TzolkinDate]
Return a dictionary holding all TzolkinDate instances of a tzolkin year. The tzolkin year consists of all combinations of day_names and ay_numbers, day_numbers are the numbers from 1 to 13 and day_names the names from ‘Imix’ to ‘Ajaw’. So a Tzolkin year is: 1 Imix, 2 Ik’, 3 Ak’b’al, … and finishes at 12 Kawak and finally 13 Ajaw.
- Returns:
- The dictionary of all tzolkin date combinations in a
tzolkin year (of 260 days).
- Return type:
Dict[int, TzolkinDate]
- nextTzolkin(tzolkin: TzolkinDate, starting: date = datetime.date(2024, 8, 27)) date
Return the next gregorian date after starting, that has a Tzolkin date of tzolkin. Search forward in time for a day with Tzolkin date tzolkin.
- Parameters:
tzolkin (TzolkinDate) – The Tzolkin date to search for.
starting (datetime.date, optional) – The date to start the search. Defaults to datetime.date.today().
- Returns:
- The next gregorian date with the given Tzolkin date tzolkin
after starting.
- Return type:
datetime.date
- parseTzolkinName(name_str: str) int
Parse the given string to get a Tzolkin day name. Ignores lower- and uppercase, ignores all non-alphanumberic characters.
Returns 0 if no name has been found
- Parameters:
name_str (str) – The string to parse to get a Tzolkin day name.
- Returns:
The number of the found Tzolkin day name. 0 on errors.
- Return type:
int
- tzolkin2gregorian(tzolkin: TzolkinDate, start: date, num_results: int = 100, forward: bool = True) List[date]
Return a list of dates having the same Tzolkin date as the given date tzolkin.
If num_results is smaller than 1, an empty list is returned.
- Parameters:
tzolkin (TzolkinDate) – The Tzolkin date to search for.
start (datetime.date) – The gregorian date to start the search from.
num_results (int, optional) – The number of results to return. If this is < 1, an empty list is returned. Defaults to 100.
forward (bool, optional) – The direction in time to search. Either forward (if
backwards (forward is True) or)
- Returns:
- The list of gregorian dates having the same Tzolkin date as
tzolkin. The number of elements of this list is num_results.
- Return type:
List[datetime.date]
tzolkin_calendar.main module
The main entry point of the program if tzolkin_calender is not imported, but called as a script.
- main() None
Main function, called if this is called as a script and not imported.