{"id":31802226,"url":"https://github.com/techatlasdev/pyhoox","last_synced_at":"2025-10-11T00:20:24.479Z","repository":{"id":316153356,"uuid":"1061361566","full_name":"TechAtlasDev/pyhoox","owner":"TechAtlasDev","description":"🎣 Pyhoox is a useful and scalable library to implement hooks in your project!","archived":false,"fork":false,"pushed_at":"2025-09-23T00:26:37.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-23T02:37:36.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TechAtlasDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-21T18:52:53.000Z","updated_at":"2025-09-23T00:26:40.000Z","dependencies_parsed_at":"2025-09-23T02:37:52.735Z","dependency_job_id":"fd072cc8-7ec2-4865-b528-d87859df5b97","html_url":"https://github.com/TechAtlasDev/pyhoox","commit_stats":null,"previous_names":["techatlasdev/pyhoox"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/TechAtlasDev/pyhoox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyhoox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyhoox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyhoox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyhoox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TechAtlasDev","download_url":"https://codeload.github.com/TechAtlasDev/pyhoox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TechAtlasDev%2Fpyhoox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005651,"owners_count":26083941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T00:20:19.658Z","updated_at":"2025-10-11T00:20:24.458Z","avatar_url":"https://github.com/TechAtlasDev.png","language":"Python","readme":"# 🎣 PyHook\n\n[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Version](https://img.shields.io/badge/version-2.0.0-green.svg)](https://github.com/techatlasdev/pyhook)\n[![Type Hints](https://img.shields.io/badge/type--hints-✓-brightgreen.svg)](https://mypy.readthedocs.io/)\n\n\u003e **Advanced Python Hook System** - Modular, type-safe, and feature-rich event management library\n\nPyHook es una librería de hooks/eventos moderna y potente que permite crear sistemas extensibles y modulares en Python con soporte completo para programación asíncrona, validación de datos, middlewares, persistencia y mucho más.\n\n## ✨ Características Principales\n\n- 🚀 **Hooks Síncronos y Asíncronos** - Soporte completo para async/await\n- 🎯 **Sistema de Prioridades** - Controla el orden de ejecución de tus hooks\n- 🔧 **Decoradores Potentes** - `@hook`, `@before`, `@after`, `@hookable` y más\n- 🛡️ **Validación Robusta** - Schemas JSON, validadores de tipos y personalizados\n- 🏗️ **Middlewares y Filtros** - Transforma datos antes y después de la ejecución\n- 📦 **Namespaces/Contextos** - Organiza hooks en espacios aislados\n- 💾 **Persistencia** - Múltiples backends: JSON, SQLite, Pickle\n- 📊 **Monitoreo y Stats** - Estadísticas detalladas y debugging\n- ⚡ **Estrategias de Ejecución** - Secuencial, paralelo, fail-fast, ignore-errors\n- 🎭 **Hooks Condicionales** - Ejecución basada en condiciones\n- 🔄 **Hooks de Una Vez** - Auto-eliminación después de ejecutarse\n- 🏷️ **Sistema de Tags** - Organización y filtrado avanzado\n\n## 🚀 Instalación\n\n```bash\npip install pyhook\n```\n\nO usando Poetry:\n```bash\npoetry add pyhook\n```\n\n## ⚡ Quick Start\n\n### Uso Básico\n\n```python\nimport pyhook\n\n# Registrar un hook\ndef mi_callback(data):\n    print(f\"Datos recibidos: {data}\")\n\npyhook.use(\"mi_evento\", mi_callback)\n\n# Disparar el hook\npyhook.trigger(\"mi_evento\", \"¡Hola PyHook!\")\n```\n\n### Con Decoradores\n\n```python\nimport pyhook\n\n@pyhook.hook(\"usuario_login\")\ndef validar_usuario(usuario_id):\n    print(f\"Validando usuario: {usuario_id}\")\n\n@pyhook.before(\"procesar_datos\")\ndef antes_procesar(datos):\n    print(f\"Preparando datos: {datos}\")\n\n@pyhook.after(\"procesar_datos\")\ndef despues_procesar(resultado):\n    print(f\"Datos procesados: {resultado}\")\n\n# Los hooks se ejecutan automáticamente\npyhook.trigger(\"usuario_login\", 123)\n```\n\n### Hooks Asíncronos\n\n```python\nimport asyncio\nimport pyhook\n\n@pyhook.hook(\"evento_async\")\nasync def procesar_async(data):\n    await asyncio.sleep(0.1)  # Simular trabajo async\n    print(f\"Procesado async: {data}\")\n\nasync def main():\n    await pyhook.async_trigger(\"evento_async\", \"datos\")\n\nasyncio.run(main())\n```\n\n## 🎯 Ejemplos Avanzados\n\n### Sistema de Prioridades\n\n```python\nimport pyhook\nfrom pyhook import HookPriority\n\n# Los hooks se ejecutan por orden de prioridad\npyhook.use(\"proceso\", cleanup, priority=HookPriority.BACKGROUND)      # Último\npyhook.use(\"proceso\", validar, priority=HookPriority.CRITICAL)        # Primero  \npyhook.use(\"proceso\", procesar, priority=HookPriority.NORMAL)         # Medio\n\npyhook.trigger(\"proceso\", datos)  # Ejecuta: validar → procesar → cleanup\n```\n\n### Validación de Datos\n\n```python\nimport pyhook\n\n# Validación con schema JSON-like\nuser_schema = {\n    \"type\": \"object\",\n    \"required\": [\"name\", \"age\"],\n    \"properties\": {\n        \"name\": {\"type\": \"string\", \"minLength\": 2},\n        \"age\": {\"type\": \"integer\", \"minimum\": 0, \"maximum\": 120}\n    }\n}\n\n@pyhook.hook(\"registro_usuario\", validator=user_schema)\ndef procesar_usuario(user_data):\n    print(f\"Usuario válido: {user_data}\")\n\n# ✅ Funciona\npyhook.trigger(\"registro_usuario\", {\"name\": \"Ana\", \"age\": 25})\n\n# ❌ Falla validación  \npyhook.trigger(\"registro_usuario\", {\"name\": \"X\"})  # Falta age\n```\n\n### Namespaces y Contextos\n\n```python\nimport pyhook\n\n# Hooks globales\npyhook.use(\"evento_global\", lambda x: print(f\"Global: {x}\"))\n\n# Hooks en namespace específico\nwith pyhook.namespace(\"database\"):\n    pyhook.use(\"create\", lambda data: print(f\"DB Create: {data}\"))\n    pyhook.use(\"update\", lambda data: print(f\"DB Update: {data}\"))\n    \n    # Solo ejecuta dentro del namespace\n    pyhook.trigger(\"create\", {\"user\": \"Ana\"})\n\n# El evento global sigue funcionando\npyhook.trigger(\"evento_global\", \"funciona en todas partes\")\n```\n\n### Hooks Condicionales y Filtros\n\n```python\nimport pyhook\n\n# Solo ejecuta si el número es mayor a 10\n@pyhook.conditional_hook(lambda x: x \u003e 10)\ndef procesar_numero_grande(numero):\n    print(f\"Número grande: {numero}\")\n\n# Hook con filtro que transforma los datos\npyhook.use(\"multiplicar\", \n           lambda x: print(f\"Resultado: {x}\"),\n           filter=lambda x: x * 2)\n\npyhook.trigger(\"multiplicar\", 5)      # Imprime: \"Resultado: 10\"\npyhook.trigger(\"procesar_numero_grande\", 15)  # ✅ Se ejecuta\npyhook.trigger(\"procesar_numero_grande\", 5)   # ❌ No se ejecuta\n```\n\n### Estrategias de Ejecución\n\n```python\nimport pyhook\nfrom pyhook import ExecutionStrategy\n\n# Registrar múltiples processors\npyhook.use(\"datos\", processor_a)\npyhook.use(\"datos\", processor_b) \npyhook.use(\"datos\", processor_c)\n\n# Ejecución secuencial (por defecto)\npyhook.trigger(\"datos\", \"test\")\n\n# Ejecución en paralelo\npyhook.trigger(\"datos\", \"test\", _strategy=ExecutionStrategy.PARALLEL)\n\n# Parar en el primer error\npyhook.trigger(\"datos\", \"test\", _strategy=ExecutionStrategy.FAIL_FAST)\n\n# Ignorar errores\npyhook.trigger(\"datos\", \"test\", _strategy=ExecutionStrategy.IGNORE_ERRORS)\n```\n\n## 📊 Monitoreo y Debugging\n\n```python\nimport pyhook\n\n# Habilitar modo debug\npyhook.enable_debug()\n\n# Registrar algunos hooks\npyhook.use(\"test\", lambda x: print(f\"Test: {x}\"))\npyhook.trigger(\"test\", \"datos\")\n\n# Ver estadísticas\npyhook.print_stats()  # Muestra estadísticas de todos los hooks\npyhook.print_stats(\"test\")  # Estadísticas de un hook específico\n\n# Acceso programático a estadísticas\ninstance = pyhook.get_global_instance()\nstats = instance.get_stats(\"test\")\nprint(f\"Total llamadas: {stats.total_calls}\")\n```\n\n## 💾 Persistencia\n\n```python\nimport pyhook\nfrom pyhook.features.persistence import JsonPersistenceBackend\n\n# Configurar persistencia\nbackend = JsonPersistenceBackend(\"./hooks.json\")\ninstance = pyhook.get_global_instance()\ninstance.enable_persistence(backend, auto_save=True, interval=60.0)\n\n# Los hooks se guardan automáticamente\npyhook.use(\"evento_persistente\", lambda x: print(x))\n\n# Guardar manualmente\ninstance.save_hooks()\n```\n\n## 🎭 Ejemplo Completo: Sistema E-commerce\n\n```python\nimport asyncio\nimport pyhook\nfrom pyhook import HookPriority\n\nclass Order:\n    def __init__(self, order_id, user_id, total):\n        self.order_id = order_id\n        self.user_id = user_id\n        self.total = total\n\n@pyhook.hook(\"order_validation\", priority=HookPriority.CRITICAL)\ndef validate_order(order):\n    if order.total \u003c= 0:\n        raise ValueError(\"Total inválido\")\n    print(f\"✓ Orden {order.order_id} validada\")\n\n@pyhook.hook(\"order_processing\")\nasync def process_payment(order):\n    print(f\"💳 Procesando pago: ${order.total}\")\n    await asyncio.sleep(0.1)  # Simular API de pago\n    print(f\"✓ Pago procesado\")\n\n@pyhook.hook(\"order_processing\") \ndef update_inventory(order):\n    print(f\"📦 Actualizando inventario para orden {order.order_id}\")\n\n@pyhook.conditional_hook(lambda order: order.total \u003e 100)\ndef vip_processing(order):\n    print(f\"🌟 Orden VIP: {order.order_id}\")\n\n@pyhook.hookable(\n    before_hooks=[\"order_validation\"],\n    after_hooks=[\"order_completion\"]\n)\nasync def process_order(order):\n    print(f\"🛍️ Procesando orden {order.order_id}\")\n    \n    # Procesamiento con ejecución paralela\n    await pyhook.async_trigger(\"order_processing\", order, \n                              _strategy=ExecutionStrategy.PARALLEL)\n    \n    return order\n\n# Usar el sistema\nasync def main():\n    order = Order(\"ORD-001\", \"user123\", 299.99)\n    \n    processed_order = await process_order(order)\n    pyhook.trigger(\"vip_processing\", order)  # Se ejecuta porque total \u003e 100\n    \n    # Ver estadísticas\n    pyhook.print_stats()\n\nasyncio.run(main())\n```\n\n## 🧪 Ejecutar Tests de Demostración\n\nEl proyecto incluye 10 tests completos que demuestran todas las funcionalidades:\n\n```bash\n# Ejecutar test específico\npython -m tests.test1  # Hook básico\npython -m tests.test2  # Sistema de prioridades  \npython -m tests.test3_async  # Hooks asíncronos\npython -m tests.test4_validation  # Validación\npython -m tests.test5_decorators  # Decoradores\npython -m tests.test6_namespaces  # Namespaces\npython -m tests.test7_monitoring  # Monitoreo\npython -m tests.test8_strategies  # Estrategias de ejecución\npython -m tests.test9_persistence  # Persistencia\npython -m tests.test10_complete_demo  # Demo completo\n\n# Ejecutar todos los tests\npython run_all_tests.py\n```\n\n## 📚 API Reference\n\n### Funciones Principales\n\n- `use(name, callback, **options)` - Registrar hook\n- `use_once(name, callback, **options)` - Hook de una sola ejecución\n- `remove(name, callback=None)` - Eliminar hook(s)\n- `trigger(name, *args, **kwargs)` - Disparar hooks síncronos\n- `async_trigger(name, *args, **kwargs)` - Disparar hooks asíncronos\n- `trigger_with_return(name, *args, **kwargs)` - Obtener valores de retorno\n- `list_hooks(name=None)` - Listar hooks registrados\n- `clear_hooks(name=None)` - Limpiar hooks\n\n### Decoradores\n\n- `@hook(name, **options)` - Decorador básico de hook\n- `@before(hook_name)` - Ejecutar antes de un evento\n- `@after(hook_name)` - Ejecutar después de un evento\n- `@around(hook_name)` - Ejecutar antes y después\n- `@hookable(**options)` - Hacer función \"hookeable\"\n- `@conditional_hook(condition)` - Hook condicional\n- `@once_hook(name)` - Hook de una vez\n- `@priority_hook(name, priority)` - Hook con prioridad\n\n### Opciones de Configuración\n\n- `priority`: `HookPriority.CRITICAL`, `HIGH`, `NORMAL`, `LOW`, `BACKGROUND`\n- `once`: `bool` - Hook de una sola ejecución\n- `condition`: `Callable` - Condición para ejecutar\n- `filter`: `Callable` - Transformar datos antes de ejecutar\n- `validator`: `Callable|dict|type` - Validar datos\n- `tags`: `List[str]` - Tags para organización\n\n## 🤝 Contribuir\n\n1. Fork el repositorio\n2. Crea una rama para tu feature (`git checkout -b feature/amazing-feature`)\n3. Commit tus cambios (`git commit -m 'Add amazing feature'`)\n4. Push a la rama (`git push origin feature/amazing-feature`)\n5. Abre un Pull Request\n\n## 📄 Licencia\n\nEste proyecto está bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para detalles.\n\n## 👨‍💻 Autor\n\n**techatlasdev** - [gjimenezdeza@gmail.com](mailto:gjimenezdeza@gmail.com)\n\n- GitHub: [@techatlasdev](https://github.com/techatlasdev)\n- Proyecto: [https://github.com/techatlasdev/pyhook](https://github.com/techatlasdev/pyhook)\n\n## 🙏 Reconocimientos\n\n- Inspirado en sistemas de hooks de frameworks modernos\n- Construido con tipado estático completo\n- Diseñado para alta performance y extensibilidad\n\n---\n\n⭐ **¡Dale una estrella si te gusta PyHook!** ⭐","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechatlasdev%2Fpyhoox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechatlasdev%2Fpyhoox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechatlasdev%2Fpyhoox/lists"}