Metadata-Version: 2.4
Name: tamil-panchanga-calendar
Version: 0.1.1
Summary: Tamil Panchanga and Tamil solar calendar calculations
Author: codewithvignesh-dev
Project-URL: Homepage, https://github.com/codewithvignesh-dev/tamil-panchanga-calendar
Project-URL: Repository, https://github.com/codewithvignesh-dev/tamil-panchanga-calendar
Project-URL: Issues, https://github.com/codewithvignesh-dev/tamil-panchanga-calendar/issues
Keywords: tamil,tamil-calendar,panchanga,panchangam,indian-calendar,solar-calendar,astronomy,tamil-date,tamil-month,tamil-year,sankranti,thirukanitha
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Tamil
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyswisseph>=2.10.0
Requires-Dist: tzdata>=2026.3
Dynamic: license-file

# Tamil Panchanga Calendar

[![PyPI version](https://img.shields.io/pypi/v/tamil-panchanga-calendar.svg)](https://pypi.org/project/tamil-panchanga-calendar/)
[![Python versions](https://img.shields.io/pypi/pyversions/tamil-panchanga-calendar.svg)](https://pypi.org/project/tamil-panchanga-calendar/)
[![License](https://img.shields.io/pypi/l/tamil-panchanga-calendar.svg)](https://github.com/codewithvignesh-dev/tamil-panchanga-calendar/blob/main/LICENSE)

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:

```bash
pip install tamil-panchanga-calendar
```

The package automatically installs its required dependencies.

## Quick Start

```python
from tamil_panchanga_calendar import TamilCalendar

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

print(result)
```

Output:

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

## Tamil Date

The simplest way to obtain a Tamil calendar date is:

```python
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:

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

## Dictionary Output

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

```python
from tamil_panchanga_calendar import TamilCalendar

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

data = result.as_dict()

print(data)
```

Example:

```python
{
    "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:

```python
from tamil_panchanga_calendar import TamilCalendar

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

print(result)
```

The supported date range is:

```text
1900-01-01 through 2100-12-31
```

## Tamil Months

The Tamil solar calendar contains 12 traditional months.

```python
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:

```text
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:

```python
from tamil_panchanga_calendar import get_month

month = get_month(5)

print(month)
```

Output:

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

You can also search by Tamil name:

```python
from tamil_panchanga_calendar import get_month

month = get_month("ஆவணி")

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

Or by English name:

```python
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.

```python
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:

```python
from tamil_panchanga_calendar import all_years

years = all_years()

print(len(years))
```

Output:

```text
60
```

## Get a Tamil Year

Get a Tamil year using its cycle position:

```python
from tamil_panchanga_calendar import get_year

year = get_year(38)

print(year)
```

Output:

```text
குரோதி
```

You can also use the Tamil name:

```python
from tamil_panchanga_calendar import get_year

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

print(year)
```

Or the English name:

```python
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:

```python
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:

```text
பராபவ
Parabhava
40
```

The supported Gregorian year range is:

```text
1900 - 2100
```

For example:

```python
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:

```python
from tamil_panchanga_calendar import thiruvalluvar_year_from_gregorian

print(
    thiruvalluvar_year_from_gregorian(2026)
)
```

Output:

```text
2057
```

## Weekday

The calculated result includes both Tamil and English weekday names:

```python
from tamil_panchanga_calendar import TamilCalendar

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

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

Output:

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

## Rasi

The package provides Rasi calculation from solar longitude.

```python
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:

```text
1
2
5
12
```

The Rasi numbering follows the traditional 12-sign sequence:

```text
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:

```python
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:

```text
Longitude: 134.3611406967694
Rasi: 5
Degrees: 14.36114069676941
```

## Sankranti

Sankranti represents the Sun entering a new Rasi.

You can calculate the next Sankranti:

```python
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:

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

You can also access the structured result:

```python
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.

```python
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:

```text
134.3611406967694
5
```

Sankranti can also be calculated using the method:

```python
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:

```python
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:

```python
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:

```python
from tamil_panchanga_calendar import (
    TamilYearError,
    get_year,
)

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

Example:

```text
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:

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

Create a virtual environment:

```bash
python -m venv myenv
```

Activate it on Windows:

```powershell
myenv\Scripts\activate
```

Install the project:

```bash
python -m pip install -e .
```

Install development dependencies when required:

```bash
python -m pip install pytest build twine
```

## Running Tests

Run the test suite:

```bash
pytest
```

Or:

```bash
python -m pytest
```

## Building the Package

Build the source distribution and wheel:

```bash
python -m build
```

The generated files will be placed in:

```text
dist/
```

Typical output:

```text
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:

```bash
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.
