persian-date-manager 1.2.0

Complete Persian date and time management with Keybit.ir API

آموزش جامع پکیج Persian Date Manager

فهرست مطالب

1. معرفی پکیج
2. نصب و راه‌اندازی
3. کلاس‌های اصلی
4. متدهای کاربردی
5. مثال‌های عملی
6. خطاها و عیب‌یابی
7. کاربردهای پیشرفته

1. معرفی پکیج

1.1 هدف پکیج

پکیج Persian Date Manager یک کتابخانه پایتون برای کار با تاریخ و زمان شمسی است. این پکیج با استفاده از API سایت Keybit.ir اطلاعات کاملی از تاریخ شمسی، میلادی و قمری را در اختیار شما قرار می‌دهد.

1.2 ویژگی‌های اصلی

• دریافت تاریخ و زمان شمسی
• تبدیل به تاریخ میلادی و قمری
• بررسی تعطیلی‌ها
• محاسبه پیشرفت سال
• اطلاعات طالع‌شناسی (حیوان سال، برج فلکی)
• خروجی در فرمت‌های مختلف

1.3 موارد استفاده

• برنامه‌های مدیریت زمان
• سیستم‌های اتوماسیون اداری
• اپلیکیشن‌های موبایل
• وب‌سایت‌های فارسی
• سیستم‌های گزارش‌گیری

2. نصب و راه‌اندازی

2.1 پیش‌نیازها

• پایتون نسخه 3.7 یا بالاتر
• دسترسی به اینترنت
• کتابخانه requests

2.2 نصب پکیج

pip install persian-date-manager

2.3 بررسی نصب

import persian_date_manager
print(persian_date_manager.__version__)

ایجاد نمونه:
python
from persian_date_manager import PersianDateManager

# ایجاد نمونه با timeout پیش‌فرض
api = PersianDateManager()

# ایجاد نمونه با timeout مشخص
api = PersianDateManager(timeout=15)

این کلاس برای قالب‌بندی و نمایش زیبای اطلاعات استفاده می‌شود.

python
from persian_date_manager import PersianDateFormatter

formatter = PersianDateFormatter(api)

دریافت زمان 12 ساعته:
python
time_12h = api.get_12h_time()
print(time_12h)

time_24h = api.get_24h_time()
print(time_24h['full']['fa'])  # خروجی: "۲۰:۰۲:۵۴"

دریافت تاریخ کامل:
python
full_date = api.get_full_persian_date()
print(full_date)  # خروجی: "دوشنبه، ۰۳ آذر ۱۴۰۴"

دریافت اطلاعات سال:
python
year_info = api.get_year_info()
print(f"سال: {year_info['number']['fa']}")
print(f"نام سال: {year_info['name']}")
print(f"حیوان سال: {year_info['animal']}")

تبدیل به تاریخ میلادی:
python
gregorian = api.get_gregorian_date()
print(gregorian['usual']['fa'])

تبدیل به تاریخ قمری:
python
ghamari = api.get_ghamari_date()
print(ghamari['usual']['fa'])  # خروجی: "۱۴۴۷/۶/۳"

بررسی تعطیلی:
python
if api.is_holiday():
    print("امروز تعطیل است")
    holiday_info = api.get_holiday_info()
    print(holiday_info['text'])
else:
    print("امروز روز کاری است")


دریافت پیشرفت سال:
python
progress = api.get_year_progress()
print(f"{progress['passed_percent']}% از سال گذشته")
print(f"{progress['passed_days']} روز گذشته")
print(f"{progress['remaining_days']} روز باقی‌مانده")


دریافت حیوان سال:
python
animal = api.get_zodiac_animal()
print(animal)  # خروجی: "مار"


دریافت برج فلکی:
python
asterism = api.get_asterism()
print(asterism)  # خروجی: "قوس"



بررسی سال کبیسه:
python
if api.is_leap_year():
    print("سال جاری کبیسه است")
else:
    print("سال جاری غیر کبیسه است")


ایجاد سیستم اطلاع‌رسانی روزانه
python
from persian_date_manager import PersianDateManager

def daily_report():
    api = PersianDateManager()
    
    report = f"""
گزارش روزانه - سیستم مدیریت تاریخ
====================================
📅 تاریخ: {api.get_full_persian_date()}
⏰ زمان: {api.get_current_time_12h()}
🌍 منطقه زمانی: {api.get_timezone_info()['name']}
🍂 فصل: {api.get_season_info()['name']}

📊 وضعیت امروز:
• {'🎉 امروز تعطیل است' if api.is_holiday() else '💼 امروز روز کاری است'}
• {api.get_year_progress()['passed_percent']}% از سال گذشته
• حیوان سال: {api.get_zodiac_animal()}
• برج فلکی: {api.get_asterism()}

📅 تاریخ‌های معادل:
• میلادی: {api.get_gregorian_date()['usual']['fa']}
• قمری: {api.get_ghamari_date()['usual']['fa']}
    """
    
    return report

print(daily_report())


سیستم لاگ‌گیری تاریخ
python
import json
from datetime import datetime
from persian_date_manager import PersianDateManager

class DateLogger:
    def __init__(self, log_file='date_log.json'):
        self.api = PersianDateManager()
        self.log_file = log_file
    
    def log_entry(self, activity):
        log_data = {
            'timestamp': datetime.now().isoformat(),
            'persian_date': self.api.get_full_persian_date(),
            'time_24h': self.api.get_current_time_24h(),
            'is_holiday': self.api.is_holiday(),
            'activity': activity,
            'year_progress': self.api.get_year_progress()
        }
        
        try:
            with open(self.log_file, 'a', encoding='utf-8') as f:
                f.write(json.dumps(log_data, ensure_ascii=False) + '\n')
            return True
        except Exception as e:
            print(f"خطا در ذخیره لاگ: {e}")
            return False

# استفاده از سیستم لاگ‌گیری
logger = DateLogger()
logger.log_entry("شروع سیستم")
logger.log_entry("پردازش داده‌ها")

from persian_date_manager import PersianDateManager

class WeeklyPlanner:
    def __init__(self):
        self.api = PersianDateManager()
    
    def get_week_recommendations(self):
        recommendations = []
        
        # بررسی تعطیلی
        if self.api.is_holiday():
            recommendations.append("استراحت و زمان با خانواده")
        else:
            recommendations.append("فعالیت‌های کاری طبق برنامه")
        
        # بررسی فصل
        season = self.api.get_season_info()['name']
        if season == 'زمستان':
            recommendations.append("پوشیدن لباس گرم")
            recommendations.append("مصرف نوشیدنی‌های گرم")
        elif season == 'تابستان':
            recommendations.append("نوشیدن آب به مقدار کافی")
            recommendations.append("استفاده از کلاه و عینک آفتابی")
        
        # بررسی پیشرفت سال
        progress = self.api.get_year_progress()['passed_percent']
        if progress > 80:
            recommendations.append("بررسی اهداف سال و برنامه‌ریزی برای سال جدید")
        elif progress > 50:
            recommendations.append("بازبینی میانسالانه اهداف")
        
        return recommendations

# استفاده از برنامه‌ریز
planner = WeeklyPlanner()
recommendations = planner.get_week_recommendations()

print("پیشنهادهای این هفته:")
for i, rec in enumerate(recommendations, 1):
    print(f"{i}. {rec}")



تولید گزارش HTML
python
from persian_date_manager import PersianDateFormatter

def create_html_report():
    api = PersianDateManager()
    formatter = PersianDateFormatter(api)
    
    # تولید گزارش HTML
    html_content = formatter.format_as_html("گزارش تاریخ شمسی - شرکت نمونه")
    
    # ذخیره در فایل
    with open('date_report.html', 'w', encoding='utf-8') as f:
        f.write(html_content)
    
    print("گزارش HTML با موفقیت ایجاد شد")

create_html_report()


استفاده در برنامه وب
python
from flask import Flask, jsonify, render_template_string
from persian_date_manager import PersianDateManager

app = Flask(__name__)

@app.route('/')
def home():
    api = PersianDateManager()
    
    template = """
    <!DOCTYPE html>
    <html dir="rtl" lang="fa">
    <head>
        <meta charset="UTF-8">
        <title>اطلاعات تاریخ شمسی</title>
        <style>
            body { font-family: Tahoma; direction: rtl; padding: 20px; }
            .card { background: #f9f9f9; padding: 20px; margin: 10px; border-radius: 10px; }
        </style>
    </head>
    <body>
        <h1>اطلاعات تاریخ و زمان شمسی</h1>
        <div class="card">
            <h2>📅 {{ date }}</h2>
            <h2>⏰ {{ time }}</h2>
            <p>وضعیت: {{ status }}</p>
        </div>
    </body>
    </html>
    """
    
    return render_template_string(
        template,
        date=api.get_full_persian_date(),
        time=api.get_current_time_12h(),
        status="تعطیل" if api.is_holiday() else "کاری"
    )

@app.route('/api/date-info')
def date_info():
    api = PersianDateManager()
    return jsonify(api.get_complete_info())

if __name__ == '__main__':
    app.run(debug=True)