jamshid 0.3.0__tar.gz

jamshid-0.3.0/Cargo.lock

@@ -0,0 +1,180 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "jamshid"
+version = "0.3.0"
+dependencies = [
+ "pyo3",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"

jamshid-0.3.0/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "jamshid"
+version = "0.3.0"
+edition = "2021"
+authors = ["Ali Kamrani <kamrani.exe@gmail.com>"]
+repository = "https://github.com/MRThugh/Jamshid"
+readme = "README.md"
+
+[lib]
+name = "_core"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.22", features = ["extension-module"] }

jamshid-0.3.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: jamshid
+Version: 0.3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: matplotlib>=3.0 ; extra == 'matplotlib'
+Requires-Dist: pandas>=1.0 ; extra == 'pandas'
+Provides-Extra: matplotlib
+Provides-Extra: pandas
+Summary: A highly accurate and modern Persian (Jalali) calendar library written in Rust and Python.
+Author-email: Ali Kamrani <kamrani.exe@gmail.com>
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/MRThugh/Jamshid

jamshid-0.3.0/README-fa.md

@@ -0,0 +1,377 @@
+<div align="center">
+
+# 🌟 Jamshid (جمشید) 🌟
+<p align="center">
+  <img 
+    src="https://raw.githubusercontent.com/MRThugh/MRThugh/main/badge.svg"
+    width="50%" 
+  />
+</p>
+
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![Rust Engine](https://img.shields.io/badge/engine-Rust--PyO3-orange.svg)](https://www.rust-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Author](https://img.shields.io/badge/author-Ali%20Kamrani-purple.svg)](https://github.com/MRThugh)
+[![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)](https://github.com/MRThugh/Jamshid)
+[![Persian](https://img.shields.io/badge/lang-PERSIAN-green)](README-fa.md)
+[![English](https://img.shields.io/badge/lang-English-blue)](README.md)
+
+**کامل‌ترین، دقیق‌ترین و سریع‌ترین زیرساخت تقویم جلالی برای پایتون. قدرت گرفته از هسته فوق‌سریع کامپایل‌شده Rust، مجهز به پشتیبانی نیتیو از Pandas، موتور تقویم تعطیلات چندمنطقه‌ای و ابزارهای پیشرفته متنی و بومی‌سازی فارسی.**
+
+</div>
+
+---
+
+## 📖 معرفی پروژه
+
+کتابخانه **جمشید** (که با دستور `import jamshid` در پروژه‌ها فراخوانی می‌شود) یک زیرساخت کامل و در سطح لول تولید (Production-grade) برای مدیریت، پردازش و تبدیل تاریخ‌های جلالی و میلادی در پایتون است.
+
+توسعه‌دهندگان فارسی‌زبان سال‌هاست که با مشکل سرعت پایین تبدیل‌های تقویمی در پایتون، عدم هماهنگی با اکوسیستم‌های تحلیل داده (مثل Pandas)، تغییرات پیچیده و تاریخی ساعت رسمی (DST) و پردازش‌های متنی دست‌وپنجه نرم می‌کنند. جمشید با ترکیب سرعت بی‌نظیر و امنیت حافظه **زبان راست (Rust از طریق PyO3)** با رابط‌های استاندارد کلاس `datetime` پایتون، عملکردی در مقیاس میکروثانیه ارائه می‌دهد؛ در حالی که همچنان سازگاری ۱۰۰٪ با کدهای قدیمی شما دارد.
+
+فرقی نمی‌کند در حال توسعه یک ابزار نجومی پیچیده هستید، یک هج‌فاند مالی با حجم تراکنش بالا روی **Pandas** دارید یا صرفاً می‌خواهید یک وب‌سایت ساده را فارسی‌سازی کنید؛ جمشید تمام ابزارها، محاسبات نجومی دقیق و دیتابیس مناسبت‌های خاورمیانه را یک‌جا در اختیارتان می‌گذارد.
+
+---
+
+## 🚀 ستون‌های معماری جمشید در نسخه 0.3.0
+
+### ۱. هسته محاسباتی فوق‌سریع راست (`jamshid._core`)
+* **عملیات فشرده روی راست**: تمام محاسبات سنگین ریاضی شامل تبدیل تاریخ‌ها (جلالی ↔ میلادی)، تعیین روزهای هفته و بررسی سال‌های کبیسه مستقیماً درون باینری‌های کامپایل‌شده راست پردازش می‌شوند.
+* **دقت فوق‌العاده نجومی**: استفاده از چرخه دقیق ۲۸۲۰ ساله بورکوفسکی (Borkowski) و پیاده‌سازی الگوریتم‌های ژان میوس (Jean Meeus) برای محاسبه لحظه اعتدال بهاری (Spring Equinox)، پایداری ریاضی تقویم را از سال **۳۰۰۰-** تا **۳۰۰۰** خورشیدی تضمین می‌کند.
+
+### ۲. موتور فرهنگی چندمنطقه‌ای (`jamshid.core`)
+* **پشتیبانی از ۳ کشور**: تقویم تعطیلات رسمی پیش‌فرض برای کشورهای **ایران**، **افغانستان** و **تاجیکستان** تنها با تغییر یک فلگ ساده.
+* **دسته‌بندی هوشمند رویدادها**: تفکیک رویدادها به دسته‌های `official` (رسمی)، `cultural` (فرهنگی)، `historical` (تاریخی) و `religious` (مذهبی) با بهره‌گیری از هر دو تقویم خورشیدی و قمری (به همراه سیستم فرمول جدولی برای سال‌های بسیار دور).
+
+### ۳. جعبه‌ابزار دیتا ساینس (`jamshid.pandas_ext`)
+* **JalaliIndex**: یک ایندکس اختصاصی برای پنداس که از کلاس پایه `Index` ارث‌بری می‌کند و به شما اجازه می‌دهد فیلترهای بازه زمانی، ویژگی‌های سال/ماه/روز و مرتب‌سازی‌ها را کاملاً بومی انجام دهید.
+* **آفست‌های فرکانسی جلالی**: مجهز به انطباق‌های فرکانسی بومی مانند `JalaliMonthEnd` (معادل JME) و `JalaliYearEnd` (معادل JYE) جهت ساده‌سازی گزارشات مالی و حسابداری سالانه و ماهانه بر اساس سال خورشیدی.
+
+### ۴. ابزارهای متنی و زبان فارسی
+* **مبدل ارقام دوطرفه**: پردازش و تبدیل سریع ارقام بین سه زبان فارسی، انگلیسی و عربی.
+* **عدد به حروف غیربازگشتی**: تبدیل اعداد بزرگ تا سقف کوادریلیون به حروف فارسی با الگوریتمی بهینه‌سازی شده و بدون سربار حافظه (مخصوص سیستم‌های صدور فاکتور و پرداخت).
+* **نرمال‌ساز متون فارسی**: اصلاح فاصله‌های اضافی، یکپارچه‌سازی نیم‌فاصله‌ها (ZWNJs) و یکدست کردن نویسه‌های عربی (ی/ک).
+
+---
+
+## ⚙️ روش نصب
+
+### ۱. نصب استاندارد و پایه
+```bash
+pip install jamshid
+```
+
+### ۲. نصب به همراه ابزارهای علمی (پنداس و ترسیم نمودار)
+```bash
+pip install jamshid[pandas,matplotlib]
+```
+
+### ۳. کامپایل لوکال از سورس کد (مخصوص توسعه‌دهندگان)
+برای بهینه‌سازی‌های اختصاصی پردازنده خود یا مشارکت در توسعه پروژه، می‌توانید کتابخانه را به کمک `maturin` کامپایل کنید:
+```bash
+git clone https://github.com/MRThugh/Jamshid.git
+cd Jamshid
+pip install maturin setuptools-rust
+maturin develop --extras pandas,matplotlib
+```
+
+*نیازمند پایتون نسخه +3.9 و کامپایلر راست (M.S.R.V 1.65+) می باشد.*
+
+---
+
+## 🛠️ مدیریت خطاهای هوشمند
+
+جمشید مجهز به سیستم اعتبارسنجی ورودی سخت‌گیرانه و دوزبانه (Farsi/English) است تا از ورود مقادیر اشتباه به پایگاه‌داده پروژه شما در فاز توسعه جلوگیری کند.
+
+```python
+import jamshid
+
+try:
+    # سال ۱۴۰۴ کبیسه نیست؛ بنابراین اسفند ۲۹ روزه است
+    invalid_date = jamshid.JalaliDate(1404, 12, 30)
+except jamshid.JalaliRangeError as e:
+    print(f"خطای اعتبارسنجی: {e}")
+    # خروجی: خطای اعتبارسنجی: روز 30 برای ماه 12 در سال 1404 (غیرکبیسه) نامعتبر است.
+    #        [Day 30 is invalid for month 12 in year 1404 (غیرکبیسه). Max allowed days: 29].
+```
+
+---
+
+## 🚀 مثال‌های کاربردی سریع
+
+```python
+from jamshid import JalaliDate, JalaliDateTime, TehranTz
+import datetime
+
+# ۱. ساخت شی تاریخ خورشیدی و سازگاری با استانداردها
+d = JalaliDate(1405, 4, 14)  # ۱۴۰۵/۰۴/۱۴
+dt = JalaliDateTime.now(TehranTz())
+
+# ۲. تبدیل بدون دردسر به تاریخ میلادی
+g_date = d.to_gregorian()    # خروجی شی استاندارد: datetime.date(2026, 7, 5)
+jd = JalaliDate.from_date(g_date)
+
+# ۳. محاسبات ساده ریاضی و فواصل زمانی
+tomorrow = d + datetime.timedelta(days=1)
+days_between = JalaliDate(1405, 4, 20) - d  # خروجی شی timedelta(days=6)
+
+# ۴. بیان متنی و عامیانه فواصل زمانی (Humanize)
+birth_date = JalaliDate(1375, 6, 15)
+print(birth_date.humanize())  # خروجی متناسب با سال جاری: ۲۹ سال پیش
+
+# ۵. فرمت‌بندی و پارس متن با اعداد فارسی خودکار
+print(d.strftime("امروز %A، %d %B سال %Y", locale='fa'))
+# خروجی: امروز یکشنبه، ۱۴ تیر سال ۱۴۰۵
+```
+
+---
+
+## 📖 مستندات عمیق API تقویم
+
+### ۱. دو کلاس `JalaliDate` و `JalaliDateTime`
+این کلاس‌ها فرزند مستقیم `datetime.date` و `datetime.datetime` در پایتون هستند و تمامی متدهای پایتون روی آن‌ها فعال است.
+
+```python
+from jamshid import JalaliDate, JalaliDateTime
+
+# متد استاتیک برای اعتبارسنجی سریع بدون ساخت شی
+is_ok = JalaliDate.is_valid(1404, 12, 30)  # False
+
+# پشتیبانی از تراز و متون راست‌به‌چپ (RTL) در خروجی کنسول یا صفحات وب
+d = JalaliDate(1405, 4, 14)
+print(repr(d.strftime_rtl("%Y/%m/%d")))  # همراه با نویسه کنترلی \u200f جهت رندر صحیح متون ترکیبی فارسی/انگلیسی
+
+# استخراج وضعیت نجومی و درصد روشنایی ماه
+phase_name, illumination = d.get_moon_phase()
+print(f"Moon Phase: {phase_name} | Illumination: {illumination:.2f}%")
+# خروجی: Moon Phase: هلال کاهنده (Waning Crescent) | Illumination: 78.43%
+```
+
+### ۲. مرزهای تغییر ساعت رسمی تهران (`TehranTz`)
+ساعت رسمی ایران (DST) از ابتدای سال ۱۴۰۲ خورشیدی به طور کامل لغو شد. کلاس `TehranTz` برخلاف سایر لایبرری‌های سنتی پایتون، سوابق لغو DST را دارد. این کلاس تا قبل از سال ۱۴۰۲ مرزها را طبق ساعت قدیم (۱ فروردین تا ۳۰ شهریور) تغییر می‌دهد و از ۱۴۰۲ به بعدDST را متوقف می‌کند.
+
+```python
+from jamshid import JalaliDateTime, TehranTz
+
+tz = TehranTz()
+# قبل از سال ۱۴۰۲ (ساعت تابستانی اعمال می‌شود)
+dt_1400 = JalaliDateTime(1400, 2, 15, 12, 0, tzinfo=tz)
+print(dt_1400.tzname())  # IRDT (+04:30)
+
+# بعد از سال ۱۴۰۲ (DST لغو شده است)
+dt_1405 = JalaliDateTime(1405, 2, 15, 12, 0, tzinfo=tz)
+print(dt_1405.tzname())  # IRST (+03:30)
+```
+
+### ۳. محاسبه پیشرفته سن خورشیدی نجومی (`SolarAge`)
+سن دقیق شما را بر اساس گردش کامل زمین به دور خورشید محاسبه کرده و خروجی را با جزئیات کامل ارائه می‌دهد.
+
+```python
+from jamshid import JalaliDate
+
+birth = JalaliDate(1375, 6, 15)
+ref_date = JalaliDate(1405, 4, 14)
+
+age = birth.age_to(ref_date)
+print(age.years, "سال و", age.months, "ماه و", age.days, "روز")
+# خروجی: 29 سال و 9 ماه و 29 روز
+
+print(f"سن اعشاری خورشیدی: {age.fraction:.4f}")
+# خروجی: سن اعشاری خورشیدی: 29.8282
+
+print(age.to_persian())
+# خروجی: ۲۹ سال و ۹ ماه و ۲۹ روز
+```
+
+### ۴. کانتینر بازه‌های زمانی پیوسته (`JalaliPeriod`)
+```python
+from jamshid import JalaliDate, JalaliPeriod
+
+start = JalaliDate(1405, 1, 1)
+end = JalaliDate(1405, 1, 31)
+period = JalaliPeriod(start, end)
+
+print(JalaliDate(1405, 1, 15) in period)  # True
+print(period.days)  # 30
+```
+
+### ۵. ابزارهای زبانی و پردازش متون فارسی
+```python
+import jamshid.core as j_utils
+
+# مبدل‌های سریع ارقام متن
+print(j_utils.to_persian_digits("Calling 09123456789"))  # Calling ۰۹۱۲۳۴۵۶۷۸۹
+print(j_utils.to_english_digits("تلفن: ۰۹۱۲۳۴۵۶۷۸۹"))      # تلفن: 09123456789
+
+# تبدیل غیربازگشتی عدد به کلمات (ایده‌آل برای فاکتورهای مالی)
+print(j_utils.num_to_words(1405623910))
+# خروجی: یک میلیارد و چهارصد و پنج میلیون و ششصد و بیست و سه هزار و نهصد و ده
+
+# نرمال‌سازی متون مخدوش و بهبود نیم‌فاصله‌ها
+dirty_text = "كتاب‌ ها  ميباشد‌"
+print(j_utils.normalize_persian(dirty_text))  # کتاب‌ها میباشد
+```
+
+---
+
+## 📈 تحلیل داده و فریم‌ورک Pandas
+
+جمشید ساختارهای بومی منحصربه‌فردی جهت همگام‌سازی و تحلیل داده‌های زمانی جلالی در بستر **Pandas** فراهم کرده است.
+
+```python
+import pandas as pd
+import jamshid
+from jamshid.pandas_ext import JalaliIndex, jalali_date_range, JalaliMonthEnd, JalaliYearEnd
+
+# ۱. تولید ایندکس جلالی منظم به همراه فرکانس‌های پنداس
+idx = jalali_date_range(start="1405/01/01", end="1405/03/31", freq="D")
+print(idx)
+# خروجی: JalaliIndex([1405/01/01, 1405/01/02, ..., 1405/03/31], dtype='object')
+
+# استخراج سریع ویژگی‌ها از کل ستون ایندکس
+print(idx.year)   # pd.Index([1405, 1405, ...])
+print(idx.month)  # pd.Index([1, 1, 1, ...])
+
+# ۲. ادغام در دیتافریم‌ها به کمک اکسسور بومی .jalali
+df = pd.DataFrame({
+    "g_date": pd.date_range("2026-03-21", "2026-06-21", freq="D")
+})
+
+# تبدیل مستقیم ستون گریگوری به آبجکت‌های JalaliDate
+df["j_date"] = df["g_date"].jalali.to_jalali()
+
+# مپ کردن ویژگی‌های تعطیلی یا مناسبت‌ها روی ستون به صورت وکتورایز شده
+df["is_holiday"] = df["j_date"].jalali.is_holiday
+df["daily_events"] = df["j_date"].jalali.events
+
+# ۳. ریسمپل و خلاصه‌سازی داده‌های مالی با آفست انتهای ماه جلالی (JME)
+df_financial = pd.DataFrame({"revenue": [1000, 1500, 2000]}, index=idx[:3])
+# ریسمپل فرکانسی بر اساس ماه‌های جلالی
+monthly_resampled = df_financial.resample(JalaliMonthEnd()).sum()
+```
+
+---
+
+## 🖼️ ترسیم بصری تقویم ماهانه (`plot_calendar`)
+برای استفاده در نوت‌بوک‌های ژوپیتر، گزارشات سازمانی یا رابط‌های کاربری، می‌توانید تقویم ماهانه زیبایی را در قالب تصویر با وضوح بالا ذخیره یا ترسیم کنید:
+
+```python
+from jamshid import JalaliDate
+
+# ساخت تاریخ نمونه از ماه هدف
+d = JalaliDate(1405, 4, 14)
+# ترسیم گرید تقویم با هایلایت کردن روز نمونه
+fig = d.plot_calendar()
+fig.savefig("calendar_tir_1405.png")
+```
+
+---
+
+## 💻 راهنمای ابزار خط فرمان (CLI Reference)
+
+جمشید دارای یک رابط ترمینالی تعاملی با پشتیبانی از کدهای رنگی ANSI و فرمت‌های مختلف خروجی است.
+
+### ۱. بررسی سریع وضعیت امروز
+```bash
+jamshid today
+```
+*خروجی: نمایش تاریخ جلالی امروز، معادل میلادی، نام روز هفته، ساعت، وضعیت تعطیلی و مناسبت فعال خورشیدی یا مذهبی.*
+
+### ۲. محاسبه مابه‌التفاوت دو تاریخ به زبان فارسی روان
+```bash
+jamshid diff 1405/01/01 1406/05/12 --human
+```
+*خروجی: `Difference: ۱ سال و ۵ ماه و ۱۱ روز بعد`*
+
+### ۳. چاپ گرید کامل تقویم با مشخص کردن رنگی روزهای تعطیل
+```bash
+jamshid calendar 1405 --highlight-holidays
+```
+*خروجی: نمایش گرید ماه‌های سال ۱۴۰۵ به صورت منظم به همراه رنگ‌آمیزی قرمز روزهای جمعه و تعطیلات.*
+
+### ۴. دریافت مناسبت‌ها و خروجی استاندارد به CSV یا iCal
+```bash
+# خروجی تقویم تعطیلات به فرمت iCal جهت استفاده در Google Calendar یا Outlook
+jamshid holidays 1405 --filter official --export ical > holidays_1405.ics
+
+# خروجی گرفتن رویدادها به فرمت ساختاریافته JSON
+jamshid holidays 1405 --filter cultural --export json
+```
+
+---
+
+## 📊 جدول مقایسه ویژگی‌ها با لایبرری‌های همکار
+
+| ویژگی‌ها | **Jamshid (v0.3.0)** | `jdatetime` | `persiantools` | `khayyam` |
+| :--- | :---: | :---: | :---: | :---: |
+| **زبان هسته پردازشی** | **Rust (کامپایل‌شده PyO3)** | پایتون ساده | پایتون ساده | پایتون ساده |
+| **بازدهی و سرعت محاسبات** | **فوق‌العاده سریع (میکروثانیه‌ای)** | پایه و معمولی | پایه و معمولی | متوسط |
+| **پشتیبانی از Pandas** | **کامل (JalaliIndex + آفست‌ها)** | ❌ ندارد | ❌ ندارد | ❌ ندارد |
+| **دقت محاسبات تاریخی** | **فرمول ۲۸۲۰ ساله بورکوفسکی** | چرخه ریاضی ۳۳ ساله | چرخه پایه ۳۳ ساله | ریاضیات ساده |
+| **بازه سال‌های تحت پوشش** | **۳۰۰۰- تا ۳۰۰۰ خورشیدی** | ۱ تا ۹۹۹۹ | ۱ تا ۹۹۹۹ | ۱ تا ۹۹۹۹ |
+| **سوابق تاریخی DST تهران** | **فعال (لغو خودکار از ۱۴۰۲)**| آفست ثابت ساده | ❌ ندارد | آفست ثابت |
+| **تعطیلات چندمنطقه‌ای** | **ایران، افغانستان، تاجیکستان**| ❌ ندارد | ❌ ندارد | ❌ ندارد |
+| **نمودار و خروجی تصویری** | **بومی با Matplotlib** | ❌ ندارد | ❌ ندارد | ❌ ندارد |
+| **ابزارهای بومی زبان فارسی**| **حروف فارسی، ارقام، نرمال‌ساز** | ❌ ندارد | متوسط | ❌ ندارد |
+| **خط فرمان ترمینال (CLI)**| **بسیار قوی با ساختار JSON/iCal** | ❌ ندارد | ❌ ندارد | ❌ ندارد |
+
+---
+
+## 🧪 بنچمارک‌های فنی و مقایسه سرعت
+به دلیل پردازش مستقیم لایه زیرین ریاضی بر روی زبان بومی راست، عملیات پردازش دسته‌ای و تبدیل‌های تقویمی جمشید به شدت کارآمدتر از رویکردهای قدیمی پایتون عمل می‌کند:
+
+```python
+# اجرای بنچمارک ساده برای تبدیل ۱۰۰,۰۰۰ نمونه تاریخ
+import time
+import jdatetime
+import jamshid
+
+# زمان اجرای jdatetime
+t0 = time.time()
+for _ in range(100000):
+    _ = jdatetime.date.fromgregorian(day=5, month=7, year=2026)
+print(f"jdatetime: {time.time() - t0:.4f} seconds")
+
+# زمان اجرای Jamshid با هسته کامپایل‌شده راست
+t0 = time.time()
+for _ in range(100000):
+    _ = jamshid.JalaliDate.from_gregorian(2026, 7, 5)
+print(f"Jamshid: {time.time() - t0:.4f} seconds")
+```
+*در سخت‌افزار مدرن، لایبرری جمشید بین **۴ تا ۸ برابر سریع‌تر** از کدهای پایتون ساده در تبدیلات دسته‌ای عمل می‌کند که آن را به گزینه‌ای ایده‌آل برای دیتابیس‌های حجیم تبدیل می‌سازد.*
+
+---
+
+## 🤝 مشارکت در پروژه
+
+از مشارکت‌های شما در جهت ارتقای پروژه جمشید استقبال می‌کنیم!
+1. پروژه را فورک کنید.
+2. یک شاخه توسعه بسازید (`git checkout -b feature/AmazingFeature`).
+3. تغییرات خود را کامیت کنید (`git commit -m 'Add some AmazingFeature'`).
+4. شاخه خود را پوش کنید (`git push origin feature/AmazingFeature`).
+5. یک Pull Request ایجاد نمایید.
+
+لطفاً پیش از باز کردن PR، از پاس شدن یونیت‌تست‌ها اطمینان حاصل کنید:
+```bash
+python -m unittest discover -s tests
+```
+
+---
+
+## 👨‍💻 نویسنده و راه‌های ارتباطی
+
+**علی کامرانی**
+
+* **گیت‌هاب**: [@MRThugh](https://github.com/MRThugh)
+* **ایمیل**: [kamrani.exe@gmail.com](mailto:kamrani.exe@gmail.com)
+
+---
+
+## 📄 لایسنس
+
+این پکیج تحت لایسنس بین‌المللی **MIT** توزیع می‌شود. استفاده، ویرایش و توسعه آن در تمام پروژه‌های تجاری و متن‌باز بلامانع است.
+
+---
+
+<div align="center">
+  <b>Jamshid</b> — تعریفی نوین از محاسبات گاه‌شماری خورشیدی. 🚀
+</div>