v9.0.0 (#100)

* Update CHANGELOG.rst for 9.0.0 release

* Fix CHANGELOG formatting, oops

* Update sphinx index

* CHANGELOG rst formatting tweaks

* Update contributors

* Fix docstring

* update version in setup.py

* Add new event_names method to changelog

* update version in docs

* Update docs for add_listener

* Roll back PyeeError change

* Fix uplift docs

* Fix formatting

CHANGELOG.rst

@@ -1,11 +1,38 @@
-Pre-Release
+2022/01/11 Version 9.0.0
 -----------
 
-- Remove dead, untested, un-exposed CompatEventEmitter
-- Add docstring to BaseEventEmitter
-- Update docstrings to reference EventEmitter instead of BaseEventEmitter
+Compatibility:
+
+- Drop 3.6 support
+
+New features:
+
+- New ``EventEmitter.event_names()`` method (see PR #96)
+- Type annotations and type checking with ``pyright``
+- Exprimental ``pyee.cls`` module exposing an ``@evented`` class decorator
+  and a ``@on`` method decorator (see PR #84)
+
+Moved/deprecated interfaces:
+
+- ``pyee.TwistedEventEmitter`` -> ``pyee.twisted.TwistedEventEmitter``
+- ``pyee.AsyncIOEventEmitter`` -> ``pyee.asyncio.AsyncIOEventEmitter``
+- ``pyee.ExecutorEventEmitter`` -> ``pyee.executor.ExecutorEventEmitter``
+- ``pyee.TrioEventEmitter`` -> ``pyee.trio.TrioEventEmitter``
+
+Removed interfaces:
+
+- ``pyee.CompatEventEmitter``
+
+Documentation fixes:
+
+- Add docstring to ``BaseEventEmitter``
+- Update docstrings to reference ``EventEmitter`` instead of ``BaseEventEmitter``
   throughout
-- Move linting tools to test deps (fixed broken build)
+
+Developer Setup & CI:
+
+- Migrated builds from Travis to GitHub Actions
+- Refactor developer setup to use a local virtualenv
 
 2021/8/14 Version 8.2.2
 -----------------------

CONTRIBUTORS.rst

@@ -12,3 +12,4 @@ Listed in no particular order:
 - Fabian Affolter @fabaff <mail@fabian-affolter.ch>
 - Anton Bolshakov @blshkv
 - Åke Forslund @forslund <ake.forslund@gmail.com>
+- Ivan Gretchka @leirons

Makefile

@@ -35,7 +35,7 @@ format:
 build_docs:
 	if [ -d venv ]; then . ./venv/bin/activate; fi; cd docs && make html
 
-serve_docs:
+serve_docs: build_docs
 	if [ -d venv ]; then . ./venv/bin/activate; fi; cd docs/_build/html && python -m http.server
 
 clean:

docs/conf.py

@@ -62,7 +62,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = "8.2.2"
+version = "9.0.0"
 
 # The full version, including alpha/beta/rc tags.
 release = version

docs/index.rst

@@ -21,19 +21,19 @@ API Docs:
 
 .. automodule:: pyee
 
-.. autoclass:: EventEmitter
+.. autoclass:: pyee.EventEmitter
     :members:
 
-.. autoclass:: AsyncIOEventEmitter
+.. autoclass:: pyee.asyncio.AsyncIOEventEmitter
     :members:
 
-.. autoclass:: TwistedEventEmitter
+.. autoclass:: pyee.twisted.TwistedEventEmitter
     :members:
 
-.. autoclass:: ExecutorEventEmitter
+.. autoclass:: pyee.executor.ExecutorEventEmitter
     :members:
 
-.. autoclass:: TrioEventEmitter
+.. autoclass:: pyee.trio.TrioEventEmitter
     :members:
 
 .. autoclass:: BaseEventEmitter

pyee/base.py

@@ -9,10 +9,6 @@ class PyeeException(Exception):
     """An exception internal to pyee."""
 
 
-class PyeeError(PyeeException):
-    """An error internal to pyee."""
-
-
 class EventEmitter:
     """The base event emitter class. All other event emitters inherit from
     this class.
@@ -94,9 +90,10 @@ def on(f: Callable) -> Callable:
         return on
 
     def add_listener(self, event: str, f: Callable) -> Callable:
-        """Register the function ``f`` to the event name ``event``. By only
-        supporting non-decorator use cases, this method has improved type
-        safety over ``EventEmitter#on``.
+        """Register the function ``f`` to the event name ``event``. This method
+        doesn't afford narrower types than ``EventEmitter#on`` but is a natural
+        pair to ``EventEmitter#listens_to`` and if nothing else has simpler
+        behavior.
         """
         self._add_event_handler(event, f, f)
         return f
@@ -123,15 +120,15 @@ def _emit_run(
         f(*args, **kwargs)
 
     def event_names(self) -> Set[str]:
-        """Get a list of events that this emitter is listening to."""
+        """Get a set of events that this emitter is listening to."""
         return set(self._events.keys())
 
     def _emit_handle_potential_error(self, event: str, error: Any) -> None:
         if event == "error":
             if isinstance(error, Exception):
                 raise error
             else:
-                raise PyeeError(f"Uncaught, unspecified 'error' event: {error}")
+                raise PyeeException(f"Uncaught, unspecified 'error' event: {error}")
 
     def _call_handlers(
         self,

pyee/trio.py

@@ -6,7 +6,7 @@
 
 import trio
 
-from pyee.base import EventEmitter, PyeeError
+from pyee.base import EventEmitter, PyeeException
 
 __all__ = ["TrioEventEmitter"]
 
@@ -57,7 +57,7 @@ def __init__(
         self._manager: Optional["AbstractAsyncContextManager[trio.Nursery]"] = None
         if nursery:
             if manager:
-                raise PyeeError(
+                raise PyeeException(
                     "You may either pass a nursery or a nursery manager " "but not both"
                 )
             self._nursery = nursery
@@ -87,7 +87,7 @@ def _emit_run(
         kwargs: Dict[str, Any],
     ) -> None:
         if not self._nursery:
-            raise PyeeError("Uninitialized trio nursery")
+            raise PyeeException("Uninitialized trio nursery")
         self._nursery.start_soon(self._async_runner(f, args, kwargs))
 
     @asynccontextmanager
@@ -106,7 +106,7 @@ async def context(
                 self._nursery = nursery
                 yield self
         else:
-            raise PyeeError("Uninitialized nursery or nursery manager")
+            raise PyeeException("Uninitialized nursery or nursery manager")
 
     async def __aenter__(self) -> "TrioEventEmitter":
         self._context: Optional[
@@ -121,7 +121,7 @@ async def __aexit__(
         traceback: Optional[TracebackType],
     ) -> Optional[bool]:
         if self._context is None:
-            raise PyeeError("Attempting to exit uninitialized context")
+            raise PyeeException("Attempting to exit uninitialized context")
         rv = await self._context.__aexit__(type, value, traceback)
         self._context = None
         self._nursery = None

pyee/twisted.py

@@ -5,7 +5,7 @@
 from twisted.internet.defer import Deferred, ensureDeferred
 from twisted.python.failure import Failure
 
-from pyee.base import EventEmitter, PyeeError
+from pyee.base import EventEmitter, PyeeException
 
 try:
     from asyncio import iscoroutine
@@ -86,7 +86,7 @@ def _emit_handle_potential_error(self, event: str, error: Any) -> None:
             elif isinstance(error, Exception):
                 self.emit("error", error)
             else:
-                self.emit("error", PyeeError(f"Unexpected failure object: {error}"))
+                self.emit("error", PyeeException(f"Unexpected failure object: {error}"))
         else:
             (super(TwistedEventEmitter, self))._emit_handle_potential_error(
                 event, error

pyee/uplift.py

@@ -15,6 +15,7 @@
 
 
 def unwrap(event_emitter: EventEmitter) -> None:
+    """Unwrap an uplifted EventEmitter, returning it to its prior state."""
     if event_emitter in EMIT_WRAPPERS:
         EMIT_WRAPPERS[event_emitter]()
 
@@ -115,8 +116,8 @@ def uplift(
     method was handled by either emitter. Execution order prefers the event
     emitter on which ``emit`` was called.
 
-    ``uplift`` also adds an ``unwrap`` method to both instances, either of
-    which will unwrap both ``emit`` methods when called.
+    The ``unwrap`` function may be called on either instance; this will
+    unwrap both ``emit`` methods.
 
     The ``error_handling`` flag can be configured to control what happens to
     unhandled errors:

setup.py

@@ -11,7 +11,7 @@
 
 setup(
     name="pyee",
-    version="8.2.2",
+    version="9.0.0",
     packages=find_packages(),
     include_package_data=True,
     description="A port of node.js's EventEmitter to python.",