{"id":37063412,"url":"https://github.com/nexconnectio/pynnex","last_synced_at":"2026-01-14T07:13:41.101Z","repository":{"id":270327711,"uuid":"909535724","full_name":"nexconnectio/pynnex","owner":"nexconnectio","description":"PynneX provides a modern emitter-listener (signal-slot) pattern with thread safety, async support, and dynamic connection detection. Build decoupled architectures without heavy frameworks. It’s pure Python 3.10+; minimal overhead. Choose from multiple aliases (signal-slot or publisher-subscriber).","archived":false,"fork":false,"pushed_at":"2025-04-24T07:49:29.000Z","size":404,"stargazers_count":57,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-02T06:21:19.577Z","etag":null,"topics":["asyncio","decorator","emitter","event-driven","event-handling","ipc","pubsub","python","signal-slot","thread-safe"],"latest_commit_sha":null,"homepage":"https://nexconnectio.github.io/pynnex/","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/nexconnectio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":"nexconnectio","patreon":"nexconnectio"}},"created_at":"2024-12-29T02:06:12.000Z","updated_at":"2025-08-24T19:54:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"3065d657-1b13-4f02-9c49-15a708ac3cf9","html_url":"https://github.com/nexconnectio/pynnex","commit_stats":null,"previous_names":["nexconnectio/pynnex"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/nexconnectio/pynnex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexconnectio%2Fpynnex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexconnectio%2Fpynnex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexconnectio%2Fpynnex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexconnectio%2Fpynnex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nexconnectio","download_url":"https://codeload.github.com/nexconnectio/pynnex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexconnectio%2Fpynnex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28412713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["asyncio","decorator","emitter","event-driven","event-handling","ipc","pubsub","python","signal-slot","thread-safe"],"created_at":"2026-01-14T07:13:40.611Z","updated_at":"2026-01-14T07:13:41.089Z","avatar_url":"https://github.com/nexconnectio.png","language":"Python","funding_links":["https://github.com/sponsors/nexconnectio","https://patreon.com/nexconnectio"],"categories":[],"sub_categories":[],"readme":"\u003c!-- README.md --\u003e\n\n[![PyPI Version](https://img.shields.io/pypi/v/pynnex.svg)](https://pypi.org/project/pynnex/)\n[![License](https://img.shields.io/github/license/nexconnectio/pynnex.svg)](https://github.com/nexconnectio/pynnex/blob/main/LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/nexconnectio/pynnex/tests.yml?branch=main)](https://github.com/nexconnectio/pynnex/actions)\n[![Downloads](https://img.shields.io/pypi/dm/pynnex)](https://pypi.org/project/pynnex/)\n\n# PynneX\n\n**Looking for a lightweight alternative to heavier event-driven, signal-slot, or concurrency libraries in Python?**  \nPynneX is a pure-Python (asyncio-based) library that streamlines event-driven concurrency without forcing you to adopt large frameworks or external dependencies.\n\n---\n\n## Why PynneX?\n\nModern Python applications often combine async I/O and multithreading. Many existing event libraries or frameworks can bring in extra dependencies or complexities, especially if you only need clean, concurrency-focused event handling. PynneX offers a **focused** approach:\n\n- **Decorator-based emitters and listeners** for writing succinct, event-driven code  \n- **Built-in thread safety**—no need to manually handle locks or queues  \n- **Easy background tasks** via `@nx_with_worker` decorator  \n- **Asyncio integration**: either async or sync listeners work seamlessly  \n- **No external dependencies** beyond Python 3.10+ (for improved asyncio support) \n\n**PynneX** can also serve as a **lightweight** alternative to more complex concurrency or distributed event frameworks, letting you scale from simple local threads up to multi-threaded or async scenarios without overhead.\n\n---\n\n## Key Features\n\n- **Pure Python**: No external dependencies needed\n- **Event Decorators**: `@nx_emitter` and `@nx_listener` for intuitive event-based design\n- **Multiple Aliases Available**: Prefer different terminology?\n  - Use `@nx_signal` and `@nx_slot` if you like Qt-style signal-slots\n  - Use `@nx_publisher` and `@nx_subscriber` if you’re coming from a Pub/Sub background\n  - All aliases share the same underlying mechanics\n  - Use `@emitter`, `@listener`, `@signal`, `@slot`, `@publisher`, `@subscriber` interchangeably without prefix `nx_`\n- **Thread-Safe**: Automatic cross-thread invocation ensures concurrency safety\n- **asyncio-Friendly**: Support for both synchronous and asynchronous listeners\n- **Background Workers**: `@nx_with_worker` provides a dedicated event loop in a separate thread\n- **Weak Reference**: If you connect a listener with `weak=True`, the connection is removed automatically once the receiver is garbage-collected\n\n### **Requires an Existing Event Loop**\n\nPynneX depends on Python’s `asyncio`. You **must** have a running event loop (e.g., `asyncio.run(...)`) for certain features like async listeners or cross-thread calls.  \nIf no event loop is running, PynneX raises a `RuntimeError` instead of creating one behind the scenes—this ensures predictable concurrency behavior.\n\n## Installation\n\n```bash\npip install pynnex\n```\n\nPynneX requires **Python 3.10+**, leveraging newer asyncio improvements.\nAlternatively, clone from GitHub and install locally: \n\n```bash\ngit clone https://github.com/nexconnectio/pynnex.git\ncd pynnex\npip install -e .\n```\n\nFor development (includes tests and linting tools):\n```\npip install -e \".[dev]\"\n```\n\n## Quick Hello (Emitters/Listeners)\n\nHere’s the simplest “Hello, Emitters/Listeners” example. Once installed, run the snippet below:\n\n```python\n# hello_pynnex.py\nimport asyncio\nfrom pynnex import with_emitters, emitter, listener\n\n\n@with_emitters\nclass Greeter:\n    @emitter\n    def greet(self):\n        \"\"\"Emitter emitted when greeting happens.\"\"\"\n\n    def say_hello(self):\n        self.greet.emit(\"Hello from PynneX!\")\n\n\n@with_emitters\nclass Printer:\n    @listener\n    def on_greet(self, message):\n        print(message)\n\n\nasync def main():\n    # The following code needs to be inside async main() as it requires a running event loop\n    greeter = Greeter()\n    printer = Printer()\n\n    # Connect the emitter to the listener\n    greeter.greet.connect(printer, printer.on_greet)\n\n    # Fire the emitter\n    greeter.say_hello()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n**Output:**\n```\nHello from PynneX!\n```\n\nBy simply defining `emitter` and `listener`, you can set up intuitive event handling that also works smoothly in multithreaded contexts.\n\nIf you come from a Qt background or prefer “signal-slot” naming, use:\n\n```python\nimport asyncio\nfrom pynnex import with_signals, signal, slot\n\n\n@with_signals\nclass Greeter:\n    @signal\n    def greet(self):\n        \"\"\"Emitter emitted when greeting happens.\"\"\"\n\n    def say_hello(self):\n        self.greet.emit(\"Hello from PynneX!\")\n\n\n@with_signals\nclass Printer:\n    @slot\n    def on_greet(self, message):\n        print(message)\n\n\nasync def main():\n    # The following code needs to be inside async main() as it requires a running event loop\n    greeter = Greeter()\n    printer = Printer()\n\n    # Connect the emitter to the listener\n    greeter.greet.connect(printer, printer.on_greet)\n\n    # Fire the emitter\n    greeter.say_hello()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nIf you prefer a Pub/Sub style, use:\n\n```python\nimport asyncio\nfrom pynnex import with_publishers, publisher, subscriber\n\n\n@with_publishers\nclass Greeter:\n    @publisher\n    def greet(self):\n        \"\"\"Emitter emitted when greeting happens.\"\"\"\n\n    def say_hello(self):\n        self.greet.publish(\"Hello from PynneX!\")\n\n\n@with_publishers\nclass Printer:\n    @subscriber\n    def on_greet(self, message):\n        print(message)\n\n\nasync def main():\n    # The following code needs to be inside async main() as it requires a running event loop\n    greeter = Greeter()\n    printer = Printer()\n\n    # Connect the emitter to the listener\n    greeter.greet.connect(printer, printer.on_greet)\n\n    # Fire the emitter\n    greeter.say_hello()\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nThey’re all interchangeable aliases pointing to the same core functionality.\n\n---\n\n## Usage \u0026 Examples\n\nBelow are some brief examples. For more, see the [docs/](https://github.com/nexconnectio/pynnex/blob/main/docs/) directory.\n\n### Asynchronous Listener Example\n```python\nimport asyncio\nfrom pynnex import with_emitters, emitter, listener\n\n\n@with_emitters\nclass Counter:\n    def __init__(self):\n        self.count = 0\n\n    @emitter\n    def count_changed(self):\n        pass\n\n    def increment(self):\n        self.count += 1\n        self.count_changed.emit(self.count)\n\n\n@with_emitters\nclass Display:\n    @listener\n    async def on_count_changed(self, value):\n        print(f\"Count is now: {value}\")\n\n\nasync def main():\n    # Connect and use\n    counter = Counter()\n    display = Display()\n    counter.count_changed.connect(display, display.on_count_changed)\n    counter.increment()  # Will print: \"Count is now: 1\"\n\n    # Wait a bit to allow async listener to execute\n    await asyncio.sleep(0.1)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n\n```\n\n## Core Concepts\n\n### Emitters and Listeners\n- Emitters: Declared with `@nx_emitter`. Emitters are attributes of a class that can be emitted to notify interested parties.\n- Listeners: Declared with `@nx_listener`. Listeners are methods that respond to emitters. Listeners can be synchronous or async functions.\n- Connections: Use `emitter.connect(receiver, listener)` to link emitters to listeners. Connections can also be made directly to functions or lambdas.\n\n### Thread Safety and Connection Types\nPynneX automatically detects whether the emitter emission and listener execution occur in the same thread or different threads:\n\n- **Auto Connection**: When connection_type is AUTO_CONNECTION (default), PynneX checks whether the listener is a coroutine function or whether the caller and callee share the same thread affinity. If they are the same thread and listener is synchronous, it uses direct connection. Otherwise, it uses queued connection.\n- **Direct Connection**: If emitter and listener share the same thread affinity, the listener is invoked directly.\n- **Queued Connection**: If they differ, the call is queued to the listener’s thread/event loop, ensuring thread safety.\n\nThis mechanism frees you from manually dispatching calls across threads.\n\n### Thread-Safe Properties\nThe `@nx_property` decorator provides thread-safe property access with automatic emitter emission:\n\n```python\nimport asyncio\nfrom pynnex import with_emitters, emitter, nx_property\n\n\n@with_emitters\nclass Example:\n    def __init__(self):\n        super().__init__()\n        self._data = None\n\n    @emitter\n    def updated(self):\n        \"\"\"Emitter emitted when data changes.\"\"\"\n\n    @nx_property(notify=updated)\n    def data(self):\n        \"\"\"Thread-safe property with change notification.\"\"\"\n        return self._data\n\n    @data.setter\n    def data(self, value):\n        self._data = value\n        print(f\"Data set to: {value}\")\n\n\nasync def main():\n    example = Example()\n    example.data = 42  # Thread-safe property set; emits 'updated' emitter on change\n    await asyncio.sleep(0.1)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### Worker Threads\nFor background work, PynneX provides a `@nx_with_worker` decorator that:\n\n- Spawns a dedicated event loop in a worker thread.\n- Allows you to queue async tasks to this worker.\n- Enables easy start/stop lifecycle management.\n- Integrates with emitters and listeners for thread-safe updates to the main \n\n**Worker Example**\n```python\nimport asyncio\nfrom pynnex import with_worker, emitter, listener\n\n\n@with_worker\nclass DataProcessor:\n    def __init__(self):\n        self.started.connect(self.on_started)\n        self.processing_done.connect(self.on_processing_done)\n        self.result = None\n\n    @emitter\n    def processing_done(self):\n        \"\"\"Emitted when processing completes\"\"\"\n\n    @listener\n    async def on_started(self, *args, **kwargs):\n        \"\"\"Called when worker starts\"\"\"\n        print(\"Worker started, processing data...\")\n        await self.process_data(42)\n\n    @listener\n    def on_processing_done(self, result):\n        \"\"\"Called when processing completes\"\"\"\n        self.result = result\n        print(f\"Processing complete! Result: {result}\")\n\n    async def process_data(self, data):\n        \"\"\"Perform heavy computation in the worker thread\"\"\"\n        await asyncio.sleep(2)  # Simulate heavy computation\n        result = data * 2\n        self.processing_done.emit(result)\n\n\nasync def main():\n    # Create and start the processor\n    processor = DataProcessor()\n    processor.start()\n\n    # Wait for processing to complete\n    await asyncio.sleep(3)\n\n    # Stop the worker gracefully\n    processor.stop()\n\n    # Verify the result\n    assert processor.result == 84, f\"Expected 84, got {processor.result}\"\n    print(\"Worker example completed successfully!\")\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Documentation and Example\n- [Usage Guide](https://github.com/nexconnectio/pynnex/blob/main/docs/usage.md): Learn how to define emitters/listeners, manage threads, and structure your event-driven code.\n- [API Reference](https://github.com/nexconnectio/pynnex/blob/main/docs/api.md): Detailed documentation of classes, decorators, and functions.\n- [Examples](https://github.com/nexconnectio/pynnex/blob/main/docs/examples.md): Practical use cases, including UI integration, async operations, and worker pattern usage.\n- [Logging Guidelines](https://github.com/nexconnectio/pynnex/blob/main/docs/logging.md): Configure logging levels and handlers for debugging.\n- [Testing Guide](https://github.com/nexconnectio/pynnex/blob/main/docs/testing.md): earn how to run tests and contribute safely.\n\n## Logging\nConfigure logging to diagnose issues:\n\n```python\nimport logging\nlogging.getLogger('pynnex').setLevel(logging.DEBUG)\n```\n\nFor more details, see the [Logging Guidelines](https://github.com/nexconnectio/pynnex/blob/main/docs/logging.md).\n\n## Testing\n\nPynneX uses `pytest` for testing:\n\n```bash\n# Run all tests\npytest\n\n# Run with verbose output\npytest -v\n\n# Run specific test file\npytest tests/unit/test_emitter.py\n```\n\nSee the [Testing Guide](https://github.com/nexconnectio/pynnex/blob/main/docs/testing.md) for more details.\n\n## Contributing\nWe welcome contributions! Please read our [Contributing Guidelines](https://github.com/nexconnectio/pynnex/blob/main/CONTRIBUTING.md) before submitting PRs.\n\n## Sponsorship \u0026 Donations\nIf PynneX has helped simplify your async/multithreaded workflows, please consider [sponsoring us](https://github.com/nexconnectio/pynnex/blob/main/.github/FUNDING.yml). All funds go toward infrastructure, documentation, and future development.\n\nPlease note that financial contributions support only the project's maintenance and do not grant financial rewards to individual contributors.\n\n## License\n`PynneX` is licensed under the MIT License. See [LICENSE](https://github.com/nexconnectio/pynnex/blob/main/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexconnectio%2Fpynnex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnexconnectio%2Fpynnex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexconnectio%2Fpynnex/lists"}