A Python library to manage Maya (Mesoamerican) calendar systems as a MayaDate object, and for converting between Gregorian (datetime object) and Maya date. Supports all three traditional Maya calendars: Long Count, Tzolkin, and Haab'.
The Maya civilization developed multiple sophisticated calendar systems that worked together. This library provides accurate conversions between the Gregorian (standard) calendar and these three Mayan systems:
- Long Count
- A linear count of days from a mythical creation date (August 11, 3114 BCE in the proleptic Gregorian calendar)
- Format: Baktun.Katun.Tun.Uinal.Kin (e.g., 13.0.12.2.12)
- Cycle: 5,125 years (13 baktuns)
- Purpose: Historical and ceremonial dating
- References:
- Tzolkin (Divine Calendar)
- A 260-day sacred calendar combining 13 numbers with 20 day names
- Cycle: 260 days (13 × 20)
- Format: Number Name (e.g., 4 Ahau)
- Purpose: Religious ceremonies, divination, naming
- References:
- Haab' (Solar Calendar)
- A 365-day solar calendar similar to our year
- 18 months of 20 days each plus 5 "nameless" days (Uayeb)
- Format: Day Month (e.g., 12 Kankin)
- Purpose: Agricultural and seasonal tracking
- References:
The Mayan calendar system requires a correlation to convert to the Gregorian calendar. This library supports two main systems:
- Most widely accepted by scholars
- Reference: August 11, 3114 BCE = 0.0.0.0.0
- Julian Day Number: 584283
- Used by virtually all modern Mayanists
- Alternative system proposed in the 1930s
- 2 days later than GMT
- Julian Day Number: 584285
- Less commonly used but historically significant
- Convert archaeological dates to Mayan calendar systems
- Analyze historical documents with Mayan dates
- Educational tools for learning about Maya civilization
- Cultural preservation and documentation
- Track celestial events in Mayan calendar context
- Study astronomical alignments in ancient sites
- Historical simulation games
- Cultural education applications
pip install MayaCalendaruv pip install MayaCalendarOr add to your project:
uv add MayaCalendarfrom mayacalendar import MayaDate
from datetime import datetime
# Create MayaDate Object for datetime (defaults to GMT correlation)
maya_date = MayaDate(datetime=datetime(2024, 12, 10))
# Create MayaDate Object for Long Count String (defaults to GMT correlation)
maya_date = MayaDate(long_count="13.0.12.2.12")
# With Correlation
# GMT (Default)
# Create MayaDate Object for datetime (defaults to GMT correlation)
maya_date = MayaDate(datetime=datetime(2024, 12, 10), correlation="GMT")
# Create MayaDate Object for Long Count String (defaults to GMT correlation)
maya_date = MayaDate(long_count="13.0.12.2.12", correlation="GMT")
# GMT (Default)
# Create MayaDate Object for datetime (defaults to GMT correlation)
maya_date = MayaDate(datetime=datetime(2024, 12, 10), correlation="Spinden")
# Create MayaDate Object for Long Count String (defaults to GMT correlation)
maya_date = MayaDate(long_count="13.0.12.2.12", correlation="Spinden")from mayacalendar import MayaDate
from datetime import datetime
# Initialize converter (defaults to GMT correlation)
converter = MayaDate()
# Convert Gregorian to Mayan calendars
date = datetime(2024, 12, 10)
print(f"Long Count: {converter.gregorian_to_long_count(date)}")
print(f"Tzolkin: {converter.gregorian_to_tzolkin(date)}")
print(f"Haab': {converter.gregorian_to_haab(date)}")
# Convert back to Gregorian
long_count = "13.0.12.2.12"
gregorian_date = converter.long_count_to_gregorian(long_count)
print(f"Back to Gregorian: {gregorian_date}")# GMT (Goodman-Martinez-Thompson) correlation (default)
gmt_converter = MayaDate(correlation='GMT')
# Spinden correlation (2 days later)
spinden_converter = MayaDate(correlation='Spinden')
date = datetime(2024, 1, 1)
gmt_result = gmt_converter.gregorian_to_long_count(date)
spinden_result = spinden_converter.gregorian_to_long_count(date)
print(f"GMT: {gmt_result}")
print(f"Spinden: {spinden_result}") # Will be 2 days earlierfrom mayacalendar import MayaDate
# Current dates using class methods, returning each individual system as a string
print(f"Today's Long Count: {MayaDate.long_count_now()}")
print(f"Today's Tzolkin: {MayaDate.tzolkin_now()}")
print(f"Today's Haab': {MayaDate.haab_now()}")
# With specific correlation
print(f"GMT Today: {MayaDate.long_count_now('GMT')}")
print(f"Spinden Today: {MayaDate.long_count_now('Spinden')}")
# Current date as a MayaDate object
maya_date = MayaDate.now()
print(maya_date)
str(maya_date)
repr(maya_date)
# From a MayaDate object, get each individual system as a string
print(f"Today's Long Count: {maya_date.long_count}")
print(f"Today's Tzolkin: {maya_date.tzolkin}")
print(f"Today's Haab': {maya_date.haab}")
print(f"MayaDate Correlation Used': {maya_date.correlation}")
# Current date as a MayaDate object, Using Different Correlations
maya_date_gmt = MayaDate.now(correlation='GMT') # Default
maya_date_spinden = MayaDate.now(correlation='Spinden')converter = MayaDate(correlation='GMT') # 'GMT' or 'Spinden'gregorian_to_long_count(dt)- Convert datetime to Long Count stringgregorian_to_tzolkin(dt)- Convert datetime to Tzolkin stringgregorian_to_haab(dt)- Convert datetime to Haab' stringlong_count_to_gregorian(long_count)- Convert Long Count to datetimetzolkin_to_gregorian(tzolkin, reference_year=2000)- Convert Tzolkin to datetimehaab_to_gregorian(haab, reference_year=2000)- Convert Haab' to datetime
MayaDate.long_count_now(correlation='GMT')MayaDate.tzolkin_now(correlation='GMT')MayaDate.haab_now(correlation='GMT')
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.