عن المشروع

ticktick-py-v2 هو غلاف Python حول نقطة نهاية `api/v2` غير الرسمية لـ TickTick، وهي الواجهة الداخلية المستخدمة بواسطة تطبيق الويب وعملاء سطح المكتب. يصف المؤلف ذلك على أنه بديل لـ API الرسمي لـ TickTick القائم على OAuth، والذي يغطي المهام والمشاريع لكنه يعرض العادات للقراءة فقط ولا يحتوي على نقاط نهاية للتركيز/pomodoro. ما الذي يعرضه المكتبة، وفقًا لـ README: - المهام والمشاريع: قراءة المهام النشطة وقوائم المشاريع، وإنشاء المهام، واستكمال المهام، وإثراء كائنات المهام بخصائص المشروع مثل أسماء المشاريع. - العادات: قراءة عمليات تسجيل الدخول (مثل بعد طابع زمني معين) ونشر عمليات تسجيل الدخول، والتي يقترحها README كوسيلة لسد الفجوة في تاريخ العادات من مصدر بيانات آخر. - التركيز/Pomodoro: قراءة جلسات التركيز على مدار يوم إزاحة، والتحقق من تشغيل جلسة حاليًا، وإضافة سجلات تركيز للجلسات التاريخية (أوقات البدء/النهاية). - أحداث التقويم: استرجاع جميع الأحداث. ملاحظات التصميم من README: - يتم عرض API كـ وظائف عادية بدلاً من فئات عملاء ذات حالة؛ تقبل كل مكالمة وسيطة `headers` اختيارية، لذا يمكن جلب رؤوس المصادقة مرة واحدة عبر `get_authenticated_ticktick_headers()` وإعادة استخدامها، أو جلبها حديثًا لكل مكالمة (رخيصة بمجرد تخزين تسجيل الدخول على القرص). - يستخدم المصادقة جلسة تسجيل الدخول العادية (ملفات تعريف الارتباط)، وليس OAuth. يمكن توفير الاعتمادات من خلال متغيرات البيئة `TICKTICK_EMAIL` و`TICKTICK_PASSWORD`، مع تعامل جلسة Selenium بدون رأس مع تسجيل الدخول وتخزين ملفات تعريف الارتباط؛ أو يمكن تصدير ملفات تعريف الارتباط يدويًا إلى ملف `.ticktick-cookies.json`. - قيم الإرجاع هي مثيلات `BaseModel` من pydantic، ويمكن تحويلها باستخدام `.model_dump()` أو `.model_dump(by_alias=True)` للحصول على أسماء الحقول الأصلية لـ TickTick ذات الحروف الصغيرة والكبيرة. التركيب يتم عبر `pip install ticktick-py-v2`؛ يتم تشغيل الاختبارات باستخدام pytest ضد دليل `tests/` المضمن. تم تنظيم المستودع إلى `cookies_login.py`، `events.py`، `focus.py`، `habits.py`، `tasks.py`، بالإضافة إلى `utils/` و`web/` الداخلية. README واضح بشأن المقايضة الرئيسية: هذا API غير رسمي ومُهندَس عكسيًا يقوم بالمصادقة من خلال جلسة تسجيل دخول للمستخدم ويمكن أن يتعطل إذا قامت TickTick بتغيير نقاطها النهائية الداخلية. يدعو قسم المساهمة إلى الإبلاغ عن المشكلات وسحب الطلبات للنقاط النهائية غير المغطاة مثل حالات الحافة للمهام المتكررة، والمهام الفرعية والتذكيرات، ويطلب تفاصيل الطلب/الاستجابة الفاشلة عندما تتغير نقطة نهاية.