Metadata-Version: 2.4
Name: sinhaladate
Version: 0.3.0
Summary: A Python library for parsing and formatting Sinhala dates and times
Author-email: Ravindu Pabasara Karunarathna <karurpabe@gmail.com>
Maintainer-email: Ravindu Pabasara Karunarathna <karurpabe@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/RavinduPabasara/sinhaladate
Project-URL: Documentation, https://github.com/RavinduPabasara/sinhaladate#readme
Project-URL: Repository, https://github.com/RavinduPabasara/sinhaladate
Project-URL: Bug Tracker, https://github.com/RavinduPabasara/sinhaladate/issues
Keywords: sinhala,date,time,parsing,formatting,sri lanka,natural language
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# SinhalaDate

[![PyPI version](https://img.shields.io/pypi/v/sinhaladate.svg)](https://pypi.org/project/sinhaladate/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A Python library for parsing and formatting Sinhala dates and times. SinhalaDate makes it easy to work with natural language date expressions in Sinhala, the official language of Sri Lanka.

## Features

- **Natural Language Parsing**: "හෙට උදේ 10.30ට" (tomorrow at 10:30 a.m.)
- **Relative Days**: අද, හෙට, අනිද්දා, ඉන් අනිද්දා, ඊයේ, පෙරේදා
- **Weekdays**: "සඳුදා", "ලබන සිකුරාදා" (next Friday), "පසුගිය සඳුදා" (last Monday)
- **Days of the Month**: "පහළොස්වෙනිදා" / "පහළොස්වැනිදා" / "15 වැනිදා" (the 15th)
- **Full Dates**: "ජූලි හතරවෙනිදා", "දෙසැම්බර් 25", "2024 ජූලි 4 වැනිදා", "2024-07-04"
- **Times**: "උදේ 10.30ට", "සවස 3යි", "රෑ 8ට", "14:30", "3 හමාරට" (half past three)
- **Formatting**: Sinhala month and weekday names, with any `strftime` code
- **Testable**: pass `now=` to resolve expressions against a fixed time

## Installation

```bash
pip install sinhaladate
```

## Quick Start

```python
import datetime
from sinhaladate import parse, format_sinhala_dates

parse("හෙට උදේ 10.30ට")          # tomorrow at 10:30
parse("ලබන සිකුරාදා සවස 3යි")      # next Friday at 15:00
parse("2024 ජූලි හතරවෙනිදා")       # 2024-07-04 00:00

# Resolve against a fixed reference time instead of "now"
now = datetime.datetime(2026, 10, 12, 9, 0)    # a Monday
parse("අනිද්දා රෑ 8ට", now=now)       # datetime(2026, 10, 14, 20, 0)

format_sinhala_dates(datetime.datetime(2024, 12, 25, 19, 30))
# '2024 දෙසැම්බර් 25 වැනිදා, බදාදා, 07:30 ප.ව.'
```

## How expressions are resolved

- A date without a year is the **next** one on or after today: in October,
  "ජූලි හතරවෙනිදා" is next July.
- A day without a month is the next such day: on the 20th, "පළවෙනිදා" is
  the 1st of next month.
- A weekday on its own is the next one, including today. "ලබන" (next) on
  the same weekday means a week later; "මේ" (this) means today.
- Time-of-day words set a.m./p.m.: උදේ, උදෑසන, පාන්දර are morning; සවස,
  හවස, රෑ, රාත්‍රී are afternoon/night ("රෑ 2ට" is 2 a.m., and "රෑ 12ට" is
  midnight at the end of the day); දහවල් 12 is noon.
- A bare number is only a time when it has a time suffix (10ට, 3යි), minutes
  (10.30, 14:30), or a time-of-day word (උදේ 10). So the digits of a year are
  never read as a time.
- Words match only as whole words, with or without a case suffix
  (සිකුරාදාට, හෙටත්), and with or without ZWJ (බ්‍රහස්පතින්දා).

Every assumption is reported when you ask for details:

```python
result = parse("ජූලි 4", return_details=True)
result.datetime     # the next 4 July
result.warnings     # ['Year not specified, assuming 2027']
result.components   # {'month_word': 'ජූලි', 'month': 7, 'day_number': 4, 'year': 2027}
```

## Usage Examples

### Parsing Relative Dates

```python
from sinhaladate import parse

parse("අද")            # Today
parse("හෙට")           # Tomorrow
parse("අනිද්දා")       # Day after tomorrow
parse("ඉන් අනිද්දා")   # In three days
parse("ඊයේ")           # Yesterday
parse("පෙරේදා")        # Day before yesterday
```

### Parsing Days of Week

```python
# Days of the week
parse("සඳුදා")        # Monday
parse("අඟහරුවාදා")    # Tuesday
parse("බදාදා")        # Wednesday
parse("බ්‍රහස්පතින්දා") # Thursday
parse("සිකුරාදා")      # Friday
parse("සෙනසුරාදා")     # Saturday
parse("ඉරිදා")         # Sunday

# With modifiers
parse("ලබන සිකුරාදා")  # Next Friday
parse("පසුගිය සඳුදා")   # Last Monday
```

### Parsing Ordinal Dates

```python
# Ordinal dates
parse("පළවෙනිදා")     # 1st
parse("15 වැනිදා")     # 15th
parse("දෙවෙනිදා")      # 2nd
parse("පහළොස්වෙනිදා")  # 15th
parse("තිස්වෙනිදා")    # 30th

# With months and years
parse("ජූලි හතරවෙනිදා")            # July 4th
parse("දෙසැම්බර් විසිපස්වෙනිදා")     # December 25th
parse("දෙසැම්බර් 25")               # December 25th
parse("2024 ජූලි මස 4 වැනිදා")      # 2024-07-04
parse("2024-07-04 14:30")           # ISO dates
```

### Parsing Time

```python
# Time expressions
parse("උදේ 10.30ට")    # 10:30 AM
parse("සවස 3යි")       # 3:00 PM
parse("රාත්‍රී 9ට පමණ")  # 9:00 PM
parse("14:30ට")         # 2:30 PM
parse("3 හමාරට")        # 3:30
```

### Formatting Dates

```python
from sinhaladate import format_sinhala_dates
import datetime

# Default formatting
date = datetime.datetime(2024, 12, 25, 19, 30)
formatted = format_sinhala_dates(date)
print(formatted)  # 2024 දෙසැම්බර් 25 වැනිදා, බදාදා, 07:30 ප.ව.

# Custom formatting
custom = format_sinhala_dates(date, "%S_A විතර")  # Just the day name
print(custom)  # බදාදා විතර
```

## Format String Codes

`format_sinhala_dates()` accepts a `datetime` or a `date`, and adds these
codes to the usual `strftime` ones (`%Y`, `%m`, `%d`, `%H`, `%I`, `%M`, ...):

- `%S_B` - Sinhala month name (දෙසැම්බර්)
- `%S_A` - Sinhala day name (බදාදා)
- `%S_Do` - Ordinal suffix (වැනිදා)
- `%p` - a.m./p.m. in Sinhala (පෙ.ව. / ප.ව.)

## Error Handling

The library gracefully handles parsing errors:

```python
from sinhaladate import parse, SinhalaDateError

# Invalid expressions return None
result = parse("invalid text")
print(result)  # None

# You can check for parsing success
if result is None:
    print("Could not parse the date expression")
```

## Supported Sinhala Expressions

### Relative Days
- අද (today)
- හෙට (tomorrow)
- අනිද්දා (day after tomorrow)
- ඉන් අනිද්දා (in three days)
- ඊයේ (yesterday)
- පෙරේදා (day before yesterday)

### Days of Week
- සඳුදා (Monday)
- අඟහරුවාදා (Tuesday)
- බදාදා (Wednesday)
- බ්‍රහස්පතින්දා (Thursday)
- සිකුරාදා (Friday)
- සෙනසුරාදා (Saturday)
- ඉරිදා (Sunday)

### Months
- ජනවාරි (January)
- පෙබරවාරි (February)
- මාර්තු (March)
- අප්‍රේල් (April)
- මැයි (May)
- ජූනි (June)
- ජූලි (July)
- අගෝස්තු (August)
- සැප්තැම්බර් (September)
- ඔක්තෝබර් (October)
- නොවැම්බර් (November)
- දෙසැම්බර් (December)

### Time of Day
- උදේ / උදෑසන (morning/AM)
- සවස / හවස (afternoon/PM)
- රාත්‍රී / රෑ (night)
- දහවල් (midday)
- පාන්දර (early morning/AM)

### Modifiers (before a weekday)
- ලබන / එළඹෙන / එන (next)
- මේ / මෙම (this)
- පසුගිය / පහුගිය / ගිය (last)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Related projects

More Sri Lanka–focused Python tools by the same author:
[slnic](https://pypi.org/project/slnic/) (NIC numbers) ·
[tokscope](https://pypi.org/project/tokscope/) (tokenizer efficiency) ·
[cetana](https://pypi.org/project/cetana/) (BDI agents)

## Acknowledgments

- Thanks to the Sinhala language community for inspiration
- Built with ❤️ for Sri Lanka 
