cevent 1.0.0

C#-style event system for Python

🪶 CEvent

CEvent is a lightweight Python library that brings C#-style event mechanics to Python.
It provides a clean and intuitive way to manage event subscriptions and callbacks using += and -= operators.

---

✨ Features

• ✅ Subscribe and unsubscribe with += / -=
• ✅ Invoke events explicitly via .invoke()
• ✅ Pass positional and keyword arguments (*args, **kwargs)
• ✅ Prevent duplicate subscriptions
• ✅ Safely call handlers — skips incompatible ones
• ✅ Clear all subscribers with .clear()
• ✅ No external dependencies — pure Python

---

💾 Installation

From PyPI

pip install cevent

Or install locally from source

git clone https://github.com/PippinStall/cevent
cd cevent
pip install .

---

🚀 Quick Start

from cevent import CEvent

# Create an event
on_click = CEvent()

# Subscribe handlers
def greet(name):
    print(f"Hello, {name}!")

def goodbye(name):
    print(f"Goodbye, {name}!")

on_click += greet
on_click += goodbye

# Invoke the event
on_click.invoke("World")
# → Hello, World!
# → Goodbye, World!

# Unsubscribe a handler
on_click -= goodbye

---

⚙️ Publisher–Subscriber Example

CEvent can be used as a lightweight publisher/subscriber (observer) system.

from cevent import CEvent

class Button:
    def __init__(self):
        self.on_click = CEvent()

    def click(self):
        print("[Button] Click detected.")
        self.on_click.invoke(self)

class Logger:
    def log_click(self, sender):
        print(f"[Logger] {sender} clicked.")

button = Button()
logger = Logger()

button.on_click += logger.log_click
button.click()

📤 Output:

[Button] Click detected.
[Logger] <__main__.Button object at 0x...> clicked.

---

🧩 Example with Argument Safety

If different handlers have incompatible function signatures,
CEvent will skip them safely and display a warning.

from cevent import CEvent

event = CEvent()

event += lambda: print("Handler without arguments")
event += lambda x: print(f"Handler with arg: {x}")

event.invoke(42)

📤 Output:

Handler with arg: 42
[CEvent] Warning: some handlers failed to invoke:
 - <function <lambda> at 0x...>: <lambda>() takes 0 positional arguments but 1 was given

This makes event handling safe even when subscribers have different parameter requirements.

---

🧹 Managing Subscribers

from cevent import CEvent

event = CEvent()

event += lambda: print("One")
event += lambda: print("Two")

# List current subscribers
print(list(event))
# → [<function <lambda> at ...>, <function <lambda> at ...>]

# Clear all
event.clear()
print(list(event))  # → []

---

🧠 Why Use CEvent?

Problem	CEvent Solution
Manual callback management	Simple += / -= operators
Duplicate subscriptions	Automatically prevented
Different argument signatures	Safe invocation with warning
Hard-to-read callback lists	repr() and iteration supported
Too much boilerplate	Minimal, expressive, and readable

---

🧪 Testing

CEvent includes a minimal test suite.
You can run it locally with:

pip install pytest
pytest

---

🧰 Async Compatibility

CEvent works seamlessly in asynchronous environments,
though it does not depend on asyncio.

import asyncio
from cevent import CEvent

on_ready = CEvent()

async def prepare():
    await asyncio.sleep(1)
    print("System ready.")
    on_ready.invoke()

def notify():
    print("✅ Received ready event!")

on_ready += notify
asyncio.run(prepare())

📤 Output:

System ready.
✅ Received ready event!

---

📦 Package Structure

cevent/
├── cevent/
│   ├── __init__.py
│   └── core.py
├── tests/
│   └── test_cevent.py
├── LICENSE
├── README.md
└── pyproject.toml

---

🔖 Version

CEvent v1.0.0

---

📜 License

MIT License — free for personal and commercial use.

---