From af4898030626872c30f4cb7541c51daa83ecb448 Mon Sep 17 00:00:00 2001 From: Josh Holbrook Date: Mon, 17 Jan 2022 16:33:06 -0500 Subject: [PATCH] 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 | 37 ++++++++++++++++++++++++++++++++----- CONTRIBUTORS.rst | 1 + Makefile | 2 +- docs/conf.py | 2 +- docs/index.rst | 10 +++++----- pyee/base.py | 15 ++++++--------- pyee/trio.py | 10 +++++----- pyee/twisted.py | 4 ++-- pyee/uplift.py | 5 +++-- setup.py | 2 +- 10 files changed, 57 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 1d7b7ee..53afe62 100644 --- a/CHANGELOG.rst +++ b/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 ----------------------- diff --git a/CONTRIBUTORS.rst b/CONTRIBUTORS.rst index f0eaf7a..51fa718 100644 --- a/CONTRIBUTORS.rst +++ b/CONTRIBUTORS.rst @@ -12,3 +12,4 @@ Listed in no particular order: - Fabian Affolter @fabaff - Anton Bolshakov @blshkv - Åke Forslund @forslund +- Ivan Gretchka @leirons diff --git a/Makefile b/Makefile index 34188fd..9eba7d8 100644 --- a/Makefile +++ b/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: diff --git a/docs/conf.py b/docs/conf.py index e17fa18..b69aaea 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index c410f5c..ccdfb81 100644 --- a/docs/index.rst +++ b/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 diff --git a/pyee/base.py b/pyee/base.py index 99c9962..b3bf3ae 100644 --- a/pyee/base.py +++ b/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,7 +120,7 @@ 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: @@ -131,7 +128,7 @@ def _emit_handle_potential_error(self, event: str, error: Any) -> None: 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, diff --git a/pyee/trio.py b/pyee/trio.py index fa12000..e79d457 100644 --- a/pyee/trio.py +++ b/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 diff --git a/pyee/twisted.py b/pyee/twisted.py index 35116a3..2b9d20b 100644 --- a/pyee/twisted.py +++ b/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 diff --git a/pyee/uplift.py b/pyee/uplift.py index 52fead4..512b16a 100644 --- a/pyee/uplift.py +++ b/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: diff --git a/setup.py b/setup.py index 571768b..34dc38e 100644 --- a/setup.py +++ b/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.",