convert-persian-dates

name

convert-persian-dates

description

Convert dates and datetimes between the Persian Solar Hijri calendar (Shamsi, Jalali, Iranian, Khorshidi) and the Gregorian (Miladi) calendar — including current and relative dates, Persian or Arabic-Indic digits, named Persian months and weekdays, ISO strings, timezone-aware values, formatting, and batch or in-code conversion. Use this skill whenever the user supplies or asks for a Persian/Shamsi/Jalali date, or wants a Gregorian date expressed in the Persian calendar, even if they do not say "convert" or name the calendar (for example "1403/01/01", "today in Shamsi", or "when is Nowruz 1404"). Do not use for Islamic or lunar (Qamari) Hijri dates, a different calendar this skill cannot convert.

Convert Persian Dates

Call the installed persiantools package directly. Never implement calendar arithmetic.

Follow the default procedure

1. Establish the source calendar, target calendar, and whether the value is a date or datetime.
2. Use JalaliDate for dates and JalaliDateTime for values containing a time.
3. For a simple ISO value, run the matching direct command below after substituting the user's value.
4. Load only the relevant section of references/python-api.md when the request needs named dates, digit normalization, localization, application code, batch conversion, validation, or timezone handling.
5. Verify the result with the checklist below.
6. Return a concise answer adapted to the user's technical level.

Prepare the environment

Use the active Python environment and check whether persiantools imports. Do not change a project merely to answer a one-off question. If the package is missing, ask before installing it. For application integration, use the project's existing package manager; otherwise the default is:

python -m pip install persiantools

For a nontechnical user, perform the conversion and omit setup details unless setup blocks the result.

Convert simple ISO values

Gregorian to Jalali:

python -c "from datetime import date; from persiantools.jdatetime import JalaliDate; print(JalaliDate.to_jalali(date.fromisoformat('2024-03-20')).isoformat())"

Jalali to Gregorian, including Persian digits:

python -c "from persiantools.jdatetime import JalaliDate; print(JalaliDate.fromisoformat('۱۴۰۳-۰۱-۰۱').to_gregorian().isoformat())"

Current Jalali date:

python -c "from persiantools.jdatetime import JalaliDate; print(JalaliDate.today().isoformat())"

Keep one-off commands small enough to inspect. For multi-step or application code, use the API reference instead of an oversized shell command.

Gotchas

• Treat Shamsi, Jalali, Iranian, Persian, Khorshidi, and Solar Hijri as the same calendar; treat Gregorian and Miladi as the same calendar.
• Do not treat Islamic or lunar Hijri as Persian Solar Hijri; PersianTools does not convert lunar Hijri dates.
• Treat a year such as 1403 or 2024 as a clue, not proof of the calendar. Ask when ambiguity could change the answer.
• Let PersianTools reject invalid dates. Never repair a date silently or assume Esfand always has 30 days.
• Preserve seconds, microseconds, and tzinfo. Calendar conversion does not change timezones; use astimezone() only when the user requests a timezone conversion.
• locale="en" uses Finglish Jalali names such as Farvardin and Shanbeh, not Gregorian names.
• Resolve “today” and “now” from the real system clock, never model memory.

Verify before answering

1. Confirm the package call completed without a parsing or range error.
2. Confirm the output calendar and returned type match the request.
3. For datetimes, confirm time precision and the UTC offset or tzinfo were retained.
4. For batch or application code, test a representative round trip and relevant boundaries such as Norouz and Esfand 29/30 before recommending the implementation.
5. If validation fails, report the input problem and request a correction; do not guess.

Return the answer

For a plain-language request, adapt this template to the user's language:

[input] [source calendar] equals [result] [target calendar].

For a developer request, lead with the result or API choice, then include only the smallest useful code sample. Prefer ISO YYYY-MM-DD or ISO datetime output unless another format is requested. State any assumption about an ambiguous calendar, date order, locale, or timezone.