Tamil Panchanga Calendar

Tamil Panchanga and Tamil solar calendar calculations for Python.

tamil-panchanga-calendar provides programmatic access to Tamil solar calendar calculations, Tamil months, Tamil years, the traditional 60-year cycle, Thiruvalluvar year, weekdays, Rasi, Sun longitude, Sankranti, and Thirukanitha-based calculations.

Features

• Tamil date calculation from a Gregorian date
• Tamil day
• Tamil month
• Tamil year
• Tamil 60-year cycle
• Thiruvalluvar year
• Tamil weekday
• English weekday
• Tamil and English month names
• Tamil and English year names
• Rasi calculation
• Sun longitude calculation
• Sankranti calculation
• Next Sankranti calculation
• Thirukanitha calculation method
• Timezone-aware calculations
• Gregorian year support from 1900 to 2100
• Python 3.10+ support
• Unicode Tamil output
• Simple Python API
• Suitable for web applications, APIs, calendars, astrology applications, and Panchanga software

Installation

Install the package from PyPI:

pip install tamil-panchanga-calendar

The package automatically installs its required dependencies.

Quick Start

from tamil_panchanga_calendar import TamilCalendar

result = TamilCalendar.from_date("2026-09-01")

print(result)

Output:

16 ஆவணி பராபவ செவ்வாய்க்கிழமை

Tamil Date

The simplest way to obtain a Tamil calendar date is:

from tamil_panchanga_calendar import TamilCalendar

result = TamilCalendar.from_date("2026-09-01")

print(result.day)
print(result.month_name_ta)
print(result.month_name_en)
print(result.year_name_ta)
print(result.year_name_en)
print(result.thiruvalluvar_year)
print(result.weekday_name_ta)
print(result.weekday_name_en)

Example output:

16
ஆவணி
Aavani
பராபவ
Parabhava
2057
செவ்வாய்க்கிழமை
Tuesday

Dictionary Output

The calculated Tamil date can also be converted into a dictionary:

from tamil_panchanga_calendar import TamilCalendar

result = TamilCalendar.from_date("2026-09-01")

data = result.as_dict()

print(data)

Example:

{
    "day": 16,
    "month": 5,
    "month_name_tamil": "ஆவணி",
    "month_name_english": "Aavani",
    "year": 40,
    "year_name_tamil": "பராபவ",
    "year_name_english": "Parabhava",
    "thiruvalluvar_year": 2057,
    "weekday": 1,
    "weekday_name_tamil": "செவ்வாய்க்கிழமை",
    "weekday_name_english": "Tuesday",
    "gregorian_date": "2026-09-01",
    "formatted": "16 ஆவணி பராபவ செவ்வாய்க்கிழமை"
}

Supported Input

TamilCalendar.from_date() accepts a Gregorian date string:

from tamil_panchanga_calendar import TamilCalendar

result = TamilCalendar.from_date("2026-09-01")

print(result)

The supported date range is:

1900-01-01 through 2100-12-31

Tamil Months

The Tamil solar calendar contains 12 traditional months.

from tamil_panchanga_calendar import all_months

for month in all_months():
    print(
        month.number,
        month.name_ta,
        month.name_en,
        month.rasi.name,
    )

Output:

1 சித்திரை Chithirai MESHA
2 வைகாசி Vaikasi VRISHABHA
3 ஆனி Aani MITHUNA
4 ஆடி Aadi KARKATA
5 ஆவணி Aavani SIMHA
6 புரட்டாசி Purattasi KANYA
7 ஐப்பசி Aippasi TULA
8 கார்த்திகை Karthigai VRISCHIKA
9 மார்கழி Margazhi DHANUS
10 தை Thai MAKARA
11 மாசி Maasi KUMBHA
12 பங்குனி Panguni MEENA

Get a Month

Get a month by its cycle number:

from tamil_panchanga_calendar import get_month

month = get_month(5)

print(month)

Output:

TamilMonthInfo(number=5, name_ta='ஆவணி', name_en='Aavani', rasi=<Rasi.SIMHA: 5>)

You can also search by Tamil name:

from tamil_panchanga_calendar import get_month

month = get_month("ஆவணி")

print(month.name_ta)
print(month.name_en)

Or by English name:

from tamil_panchanga_calendar import get_month

month = get_month("Aavani")

print(month.name_ta)

Tamil Years

The Tamil calendar follows a traditional 60-year cycle.

from tamil_panchanga_calendar import all_years

for year in all_years():
    print(
        year.number,
        year.name_ta,
        year.name_en,
    )

There are 60 traditional Tamil year names:

from tamil_panchanga_calendar import all_years

years = all_years()

print(len(years))

Output:

60

Get a Tamil Year

Get a Tamil year using its cycle position:

from tamil_panchanga_calendar import get_year

year = get_year(38)

print(year)

Output:

குரோதி

You can also use the Tamil name:

from tamil_panchanga_calendar import get_year

year = get_year("குரோதி")

print(year)

Or the English name:

from tamil_panchanga_calendar import get_year

year = get_year("Krodhi")

print(year)

Gregorian Year to Tamil Year

Convert a Gregorian year into its Tamil 60-year-cycle year:

from tamil_panchanga_calendar import get_year_for_gregorian

year = get_year_for_gregorian(2026)

print(year.name_ta)
print(year.name_en)
print(year.number)

Example:

பராபவ
Parabhava
40

The supported Gregorian year range is:

1900 - 2100

For example:

from tamil_panchanga_calendar import get_year_for_gregorian

for year in [1900, 1950, 2000, 2025, 2026, 2050, 2100]:
    tamil_year = get_year_for_gregorian(year)
    print(
        year,
        "->",
        tamil_year.name_ta,
        tamil_year.name_en,
    )

Thiruvalluvar Year

Convert a Gregorian year into the corresponding Thiruvalluvar year:

from tamil_panchanga_calendar import thiruvalluvar_year_from_gregorian

print(
    thiruvalluvar_year_from_gregorian(2026)
)

Output:

2057

Weekday

The calculated result includes both Tamil and English weekday names:

from tamil_panchanga_calendar import TamilCalendar

result = TamilCalendar.from_date("2026-09-01")

print(result.weekday_name_ta)
print(result.weekday_name_en)

Output:

செவ்வாய்க்கிழமை
Tuesday

Rasi

The package provides Rasi calculation from solar longitude.

from tamil_panchanga_calendar import rasi_from_longitude

print(rasi_from_longitude(0))
print(rasi_from_longitude(30))
print(rasi_from_longitude(134.36))
print(rasi_from_longitude(359.99))

Output:

1
2
5
12

The Rasi numbering follows the traditional 12-sign sequence:

1  MESHA
2  VRISHABHA
3  MITHUNA
4  KARKATA
5  SIMHA
6  KANYA
7  TULA
8  VRISCHIKA
9  DHANUS
10 MAKARA
11 KUMBHA
12 MEENA

Sun Position

Get the Sun's calculated position for a specific datetime:

from datetime import datetime, timezone

from tamil_panchanga_calendar import sun_position_at

dt = datetime(
    2026,
    9,
    1,
    tzinfo=timezone.utc,
)

position = sun_position_at(dt)

print("Longitude:", position.longitude)
print("Rasi:", position.rasi_number)
print("Degrees:", position.degrees_in_rasi)

Example:

Longitude: 134.3611406967694
Rasi: 5
Degrees: 14.36114069676941

Sankranti

Sankranti represents the Sun entering a new Rasi.

You can calculate the next Sankranti:

from datetime import datetime, timezone

from tamil_panchanga_calendar import next_sankranti

dt = datetime(
    2026,
    9,
    1,
    tzinfo=timezone.utc,
)

result = next_sankranti(dt)

print(result)

Example:

புரட்டாசி begins at 2026-09-17T02:22:57.575684+00:00

You can also access the structured result:

print(result.rasi)
print(result.rasi_number)
print(result.longitude)
print(result.datetime_utc)
print(result.previous_rasi)
print(result.month_name_ta)

Thirukanitha Method

The package includes the Thirukanitha calculation method.

from datetime import datetime, timezone

from tamil_panchanga_calendar.methods.thirukanitha import (
    ThirukanithaMethod,
)

method = ThirukanithaMethod()

dt = datetime(
    2026,
    9,
    1,
    tzinfo=timezone.utc,
)

print(method.sun_longitude(dt))
print(method.rasi(dt))

Example:

134.3611406967694
5

Sankranti can also be calculated using the method:

from datetime import datetime, timezone

from tamil_panchanga_calendar.methods.thirukanitha import (
    ThirukanithaMethod,
)

method = ThirukanithaMethod()

dt = datetime(
    2026,
    9,
    1,
    tzinfo=timezone.utc,
)

result = method.sankranti(
    dt,
    150,
)

print(result)

Timezone Support

The package uses Python's timezone support for astronomical calculations.

For timezone-aware datetime calculations:

from datetime import datetime
from zoneinfo import ZoneInfo

from tamil_panchanga_calendar import sun_position_at

dt = datetime(
    2026,
    9,
    1,
    5,
    30,
    tzinfo=ZoneInfo("Asia/Kolkata"),
)

position = sun_position_at(dt)

print(position)

The package includes tzdata as a dependency to provide timezone data on platforms where the operating system does not provide it.

Calculation Method

Tamil month boundaries are determined using solar longitude and Sankranti calculations.

The package uses:

• Swiss Ephemeris for astronomical calculations
• Lahiri sidereal calculations
• Thirukanitha-based solar calculations
• Solar longitude
• Rasi transitions
• Sankranti determination

The Tamil solar month begins according to the Sun's transition into the corresponding sidereal Rasi.

Accuracy

Astronomical calculations are performed using Swiss Ephemeris.

Calendar results depend on:

• Astronomical ephemeris calculations
• Sidereal calculation settings
• Timezone
• Gregorian date and time
• Sankranti calculation

This library is intended for software applications and computational use.

For religious, ceremonial, or official calendar purposes, users should verify results against the appropriate traditional or authoritative Panchanga source.

API Overview

The main public API includes:

from tamil_panchanga_calendar import (
    TamilCalendar,
    TamilDate,

    all_months,
    get_month,
    get_month_by_rasi,

    all_years,
    get_year,
    get_year_for_gregorian,
    get_year_by_cycle_position,
    get_year_by_name,

    cycle_position_from_gregorian_year,
    thiruvalluvar_year_from_gregorian,

    rasi_from_longitude,
    sun_position_at,
    next_sankranti,
)

Error Handling

The package provides specific exceptions for invalid Tamil year operations:

from tamil_panchanga_calendar import (
    TamilYearError,
    get_year,
)

try:
    get_year(61)
except TamilYearError as exc:
    print(exc)

Example:

Tamil year cycle position must be between 1 and 60.

Python Compatibility

Supported Python versions:

• Python 3.10
• Python 3.11
• Python 3.12
• Python 3.13

Dependencies

The package uses:

• pyswisseph
• tzdata

These dependencies are installed automatically when installing the package from PyPI.

Development

Clone the repository:

git clone https://github.com/codewithvignesh-dev/tamil-panchanga-calendar.git
cd tamil-panchanga-calendar

Create a virtual environment:

python -m venv myenv

Activate it on Windows:

myenv\Scripts\activate

Install the project:

python -m pip install -e .

Install development dependencies when required:

python -m pip install pytest build twine

Running Tests

Run the test suite:

pytest

Or:

python -m pytest

Building the Package

Build the source distribution and wheel:

python -m build

The generated files will be placed in:

dist/

Typical output:

dist/
├── tamil_panchanga_calendar-0.1.0.tar.gz
└── tamil_panchanga_calendar-0.1.0-py3-none-any.whl

Validate the Package

Use Twine to validate the generated distributions:

python -m twine check dist/*

Both the wheel and source distribution should pass validation before publishing.

License

This project is licensed under the MIT License.

See the LICENSE file for details.

Author

codewithvignesh-dev

Project

GitHub:

https://github.com/codewithvignesh-dev/tamil-panchanga-calendar

PyPI:

https://pypi.org/project/tamil-panchanga-calendar/

Disclaimer

This software provides computational Tamil calendar and Panchanga-related calculations.

The results should not be considered an official religious calendar or authoritative Panchanga publication.

Users are responsible for independently verifying results when exact traditional or ceremonial timings are required.