Metadata-Version: 2.4
Name: abdocode
Version: 1.2.0
Summary: A Python utility library for keyboard shortcuts, file tools, audio helpers and workflow utilities
Author-email: Abdalla Emad <19abdo9123@gmail.com>
License: MIT
Keywords: hotkey,utility,audio,workflow,tkinter
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: sounddevice
Dynamic: license-file

# ============/Abdo☆code\===============

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

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

## التثبيت:
```bash
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)`: إضافة صوت جديد.

---

## ملاحظة
يمكنك استيراد المكتبة كالتالي:
```python
from hotkey_engine import core
```
ثم استخدام الدوال مباشرة مثل:
```python
core.play('note_C4')
core.add_shortcut(root, '<Control-s>', '<<Save>>')
```

