abdocode 1.2.0

A Python utility library for keyboard shortcuts, file tools, audio helpers and workflow utilities

============/Abdo☆code===============

مكتبة abdocode توفر أدوات مساعدة قوية لتطبيقات بايثون، خاصة العمليات المرتبطة بالاختصارات، إدارة الملفات، الصوت، والمزيد.

المميزات:

• نظام اختصارات لوحة مفاتيح سهل الاستخدام مع إدارة تشغيل الأحداث.
• أدوات تعديل الحافظة ونسخ/لصق تاريخي.
• وظائف قراءة وكتابة ملفات نصية، والبحث عن الملفات.
• تحويل نصوص وحسابات سريعة، بالإضافة إلى أدوات الوقت والتاريخ.
• دعم صوتي ذكي لتشغيل نغمات ومقاطع موسيقية باستخدام sounddevice.
• أدوات HTTP بسيطة لتنزيل وقراءة JSON من الإنترنت.
• مدير إعدادات وقيم مع وظائف مساعدة لتهيئة واستخدام الإعدادات.
• نظام تسجيل وتدفق أحداث مع EventBus ومحرّك لوغاريتمي للتطبيقات البسيطة.

التثبيت:

pip install abdocode

شرح الدوال الرئيسية

فيما يلي أهم دوال المكتبة ومجالات استخدامها:

1. إدارة الاختصارات

• add_shortcut(root, key, event): يسجّل اختصار لوحة مفاتيح إلى حدث مع واجهة tkinter.
• remove_shortcut(root, key): يزيل اختصارًا مسجّلًا.
• disable_all(): يعطّل جميع الاختصارات النشطة.
• enable_all(): يعيد تفعيل جميع الاختصارات.
• reset_all(root): يعيد تهيئة ملحقات الاختصارات في النافذة.
• list_shortcuts(): يعرض قائمة الاختصارات المفعلة.

2. اختصارات جاهزة

توفر المكتبة اختصارات جاهزة مثل:

• copy(root), paste(root), cut(root)
• select_all(root), undo(root), redo(root)
• save(root), open_file(root), new_file(root)
• refresh(root), print_file(root)

3. لوحة الحافظة والملفات

• write_clipboard(root, text): يضع نصًا في الحافظة.
• read_clipboard(root): يقرأ نصًا من الحافظة.
• clear_clipboard(root): ينظف الحافظة.
• read_text_file(path, encoding='utf-8'): يقرأ ملفًا نصيًا.
• write_text_file(path, text, encoding='utf-8'): يكتب إلى ملف نصي.
• append_text_file(path, text, encoding='utf-8'): يلحق نصًا في نهاية ملف.
• list_files(folder, extension=None, recursive=False): يسرد الملفات في مجلد.
• find_files(folder, pattern, recursive=True, extension=None): يبحث عن ملفات بنمط مع دعم التكرار.

4. أدوات النص

• normalize_whitespace(text): ينظف الفراغات المتكررة.
• count_words(text): يعد الكلمات في النص.
• to_title_case(text): يحول النص إلى حالة العنوان.
• snake_to_camel(text) و camel_to_snake(text): تحويل أسماء المتغيرات.
• remove_punctuation(text): يزيل علامات الترقيم.

5. مؤقتات وجدولة

• set_timeout(callback, delay, *args, **kwargs): ينفّذ وظيفة بعد تأخير.
• set_interval(callback, interval, *args, **kwargs): ينفّذ وظيفة بشكل متكرر.
• cancel_timer(timer_id): يوقف مؤقتًا مسجّلًا.
• active_timers(): يعرض المؤقتات الحالية.

6. معلومات النظام

• get_system_info(): يسترجع معلومات النظام الأساسية.
• get_environment_variables(): يقرأ متغيرات البيئة.
• open_folder(path): يفتح مجلدًا في مدير الملفات.
• get_file_size(path): يعرض حجم الملف.

7. واجهات المستخدم المبسطة

• show_info(title, message): يعرض رسالة معلومات.
• show_warning(title, message): يعرض تحذيرًا.
• show_error(title, message): يعرض خطأ.
• ask_yes_no(title, message): يطلب تأكيد نعم/لا.
• ask_input(title, prompt, default=''): يطلب إدخال نص.
• simple_popup(root, title, message): يعرض نافذة منبثقة بسيطة.

8. صوت وموسيقى

• note_to_frequency(note): يحول اسم نغمة إلى تردد صوتي.
• play_tone(note, duration=0.2, volume=0.5, waveform='sine'): يشغّل نغمة.
• play_notes(sequence, tempo=120, volume=0.4, waveform='sine'): يشغّل سلسلة نغمات.

9. التحقق من القيم والصيغ

• is_integer(value), is_float(value), is_string(value), is_list(value), is_dict(value), is_boolean(value): فحوصات نوع القيمة.
• validate_schema(data, schema, path=''): يتحقق من بنية البيانات.
• ensure_schema(data, schema): يضمن تطابق البيانات مع المخطط.
• assert_type(value, expected_type): يؤكد نوع قيمة.

10. JSON وبيانات

• load_json(path, encoding='utf-8'): يقرأ JSON من ملف.
• save_json(path, data, encoding='utf-8', indent=4): يحفظ JSON.
• merge_dicts(*dicts, deep=True): يدمج قواميس عميقًا.
• deep_get(data, path, default=None, separator='.'): يحصل على قيمة متداخلة.
• deep_set(data, path, value, separator='.'): يعيّن قيمة متداخلة.

11. طلبات HTTP

• load_json_url(url, headers=None, timeout=10): يقرأ JSON من URL.
• http_get(url, headers=None, timeout=10): يرسل طلب GET.
• http_post(url, data=None, json_data=None, headers=None, timeout=10): يرسل طلب POST.
• fetch_json(url, headers=None, timeout=10): يجلب JSON من الإنترنت.
• check_url(url, timeout=5): يتحقق من صلاحية عنوان URL.
• download_file(url, dest, chunk_size=8192, timeout=10): يحمل ملفًا.

12. الوقت والتاريخ

• current_timestamp(): يقرأ الطابع الزمني الحالي.
• format_datetime(value=None, fmt='%Y-%m-%d %H:%M:%S'): ينسق التاريخ.
• parse_datetime(text, fmt='%Y-%m-%d %H:%M:%S'): يحول نصًا إلى تاريخ.
• relative_time(value, now=None): يحسب الوقت النسبي.
• countdown(seconds, callback=None, interval=1): عد تنازلي مع استدعاء.
• is_weekend(value=None): يتحقق من أن اليوم عطلة.
• add_business_days(value, days): يضيف أيام عمل.

13. حسابات ومساعدة رياضية

• clamp(value, minimum, maximum): يقيد قيمة ضمن مدى.
• lerp(start, end, fraction): ينجز استيفاء خطيًا.
• remap(value, old_min, old_max, new_min, new_max): يعيد تعيين مدى.
• mean_values(values), median_values(values), mode_values(values): إحصاءات بسيطة.
• variance(values, sample=False), stddev(values, sample=False): تباين وانحراف معياري.
• percent_change(original, new): نسبة التغير.
• safe_divide(a, b, default=0.0): قسمة آمنة بدون خطأ.
• random_choice_weighted(choices): اختيار عشوائي مرجح.

14. أوامر النظام والعمليات

• run_command(command, shell=False, cwd=None, env=None, timeout=None): تشغيل أمر مزامني.
• run_command_async(command, callback=None, shell=False, cwd=None, env=None, timeout=None): تشغيل أمر غير مزامني.
• which(program): البحث عن برنامج في المسار.
• is_process_running(name): التحقق من وجود عملية.
• kill_process(pid): إنهاء عملية.

15. إدارة الملفات والمجموعات

• copy_file(src, dst), move_file(src, dst), delete_file(path): إدارة الملفات.
• chunk_list(sequence, chunk_size): تجزئة قائمة.
• flatten_list(nested_list): تسطيح قائمة متداخلة.
• unique_preserve(sequence): إزالة التكرار مع حفظ الترتيب.
• group_by(sequence, key_function): تجميع عناصر القائمة.
• coalesce(*values): اختيار أول قيمة غير فارغة.
• dict_merge(*dicts): دمج القواميس.

16. إعدادات وتكوين

• load_settings(path, default=None, encoding='utf-8'): تحميل إعدادات JSON.
• save_settings(path, settings, encoding='utf-8', indent=4): حفظ إعدادات.
• get_setting(settings, key, default=None): الحصول على قيمة إعداد.
• set_setting(settings, key, value): تعيين قيمة إعداد.
• update_settings(settings, updates): تحديث إعدادات موجودة.
• flatten_settings(settings, separator='.'): تسطيح إعدادات متداخلة.

17. سجل الأحداث ونظام الرسائل

• EventBus: يدير الاشتراكات والأحداث.
• subscribe(event_name, listener): الاشتراك في حدث.
• unsubscribe(event_name, listener=None): إلغاء الاشتراك.
• emit(event_name, *args, **kwargs): بث حدث.
• clear(): مسح جميع المستمعين.

18. تسجيل السجلات

• set_log_file(path, level=logging.INFO, mode='a'): تعيين ملف السجل.
• log_info(message), log_warning(message), log_error(message), log_debug(message): وظائف تسجيل.
• get_log_file(): استرجاع مسار ملف السجل.
• configure_logging(level=logging.INFO, fmt='[%(levelname)s] %(message)s'): إعداد تكوين التسجيل.

19. مساعدة العرض

• print_table(rows, headers=None, padding=2): طباعة جدول منظم.
• progress_bar(iterable, prefix='', size=40, fill='█'): شريط تقدم في الطرفية.
• prompt_choices(root, title, options, default_index=0): اختيار من قائمة.
• clear_console(): تنظيف الشاشة.
• confirm_action(message='Proceed?', default=True): نافذة تأكيد.
• show_progress(title, current, total): عارض نسبة تنفيذ.
• play(name): تشغيل صوت مسجل.
• add_sound(name, func): إضافة صوت جديد.

---

ملاحظة

يمكنك استيراد المكتبة كالتالي:

from hotkey_engine import core

ثم استخدام الدوال مباشرة مثل:

core.play('note_C4')
core.add_shortcut(root, '<Control-s>', '<<Save>>')