Metadata-Version: 2.4
Name: persian-datepicker
Version: 2.0.0
Summary: A Persian (Shamsi) DatePicker widget for Flet 1.x with animations, RTL support, and keyboard navigation.
Author-email: Ali Amini <aliamini9728@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AliAminiCode/flet-persian-datepicker
Project-URL: Bug Tracker, https://github.com/AliAminiCode/flet-persian-datepicker/issues
Keywords: flet,persian,shamsi,datepicker,jalali,gui,persain datepicker,flet persain datepicker,persain datepicker flet
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flet<2.0,>=1.0.1
Requires-Dist: jdatetime>=5.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# Flet Persian DatePicker

🇬🇧 English · [🇮🇷 فارسی](README.fa.md)

A Persian (Jalali/Shamsi) date picker widget for [Flet](https://flet.dev), built from scratch to match the look and feel of Flet's built-in `DatePicker` while adding full Persian calendar and RTL support.

## Overview
Flet's built-in `DatePicker` only supports the Gregorian calendar and English text, which makes it unsuitable for Persian-speaking users. This package provides a drop-in alternative with a similar API, built entirely on top of Flet's existing widgets. Key features:
- **Jalali calendar support**: correct leap-year handling, Persian month and day names, Persian numerals.
- **Keyboard navigation**: Enter to confirm, Escape to cancel, day/week movement, all disabled automatically while typing in input mode.
- **Input mode with validation**: type a date directly (Persian or English numerals) with format and range checking.
- **Light/dark themes** and a configurable year range.
- Built entirely with Flet's existing widgets, no external UI dependencies.

## Installation
Install the package via pip:
```bash
pip install persian-datepicker
```
Requires **Python 3.10+** and **Flet 1.0+** (`pip install "flet>=1.0.1,<2"`).

> ### ⚠️ Flet version compatibility
> Version **2.0.0 and newer** of this library is built for **Flet 1.x** (Flet 1.0.1+). It will **not** work with Flet 0.x, because Flet 1.0 renamed and removed many APIs.
>
> If your project is still on an **older Flet** release (0.28.x or earlier), please install an **older version of this library**, which is pinned to the matching Flet line:
> ```bash
> pip install "persian-datepicker<2" "flet<1"
> ```
> In short: **new Flet → this library 2.x**, **old Flet → this library 1.x**.

## Quick Start
```python
import flet as ft
from persian_datepicker import PersianDatePicker

def main(page: ft.Page):
    datepicker = PersianDatePicker()

    def handle_result(result):
        if result:
            print(f"Selected: {result['formatted_persian']}")

    datepicker.set_result_callback(handle_result)

    def show_datepicker(e):
        datepicker.show(page)

    page.add(ft.Button("Select Date", on_click=show_datepicker))

ft.run(main)
```
Run this after installing the package to see a basic datepicker with a button to open it. The selected date is printed in Persian format.

## Advanced Usage
- Set a custom year range: `PersianDatePicker(first_year=1400, last_year=1410)`.
- Set a default date: `datepicker.set_default_date(jdatetime.date(1404, 6, 1))` — this takes a `jdatetime.date` object, not a string.
- Open to a specific month/year: `datepicker.show(page, display_year=1403, display_month=6)`.
- Disable input mode or keyboard support: `PersianDatePicker(enable_input_mode=False, keyboard_support=False)`.

See `examples/example_basic.py` for all of the options above, and `examples/example_mini_project.py` for a small event-planner app built with the widget.

## Testing
This project uses `pytest` to cover the date-math and validation logic (leap years, month/year boundary crossing, input parsing).

Install the test dependencies and run the suite:
```bash
pip install -e ".[dev]"
pytest tests/
```

## Screenshots
Check out the Persian DatePicker in action:

- **Light Mode**:

<div align="center">
  <img src="screenshots/light_mode_landscape.png" alt="Light Mode">
</div>

- **Dark Mode**:

<div align="center">
  <img src="screenshots/dark_mode_landscape.png" alt="Dark Mode">
</div>

## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history.

## Contribute
Found a bug? Report it at [https://github.com/AliAminiCode/flet-persian-datepicker/issues](https://github.com/AliAminiCode/flet-persian-datepicker/issues).
Developed by [Ali Amini](mailto:aliamini9728@gmail.com).
Licensed under the [MIT License](https://github.com/AliAminiCode/flet-persian-datepicker/blob/master/LICENSE).
