Rationalize generic exception names

- Rename BrokenStreamError to BrokenResourceError
- Rename ResourceBusyError to BusyResourceError

Fixes python-triogh-620 (and see there for the rationale).

docs/source/reference-core.rst

@@ -1544,10 +1544,12 @@ Exceptions and warnings
 
 .. autoexception:: WouldBlock
 
-.. autoexception:: ResourceBusyError
+.. autoexception:: BusyResourceError
 
 .. autoexception:: ClosedResourceError
 
+.. autoexception:: BrokenResourceError
+
 .. autoexception:: RunFinishedError
 
 .. autoexception:: TrioInternalError

docs/source/reference-hazmat.rst

@@ -134,7 +134,7 @@ All environments provide the following functions:
    different, and this works on ``SOCKET`` handles or Python socket
    objects.
 
-   :raises trio.ResourceBusyError:
+   :raises trio.BusyResourceError:
        if another task is already waiting for the given socket to
        become readable.
 
@@ -148,7 +148,7 @@ All environments provide the following functions:
    different, and this works on ``SOCKET`` handles or Python socket
    objects.
 
-   :raises trio.ResourceBusyError:
+   :raises trio.BusyResourceError:
        if another task is already waiting for the given socket to
        become writable.
    :raises trio.ClosedResourceError:
@@ -192,7 +192,7 @@ Unix-like systems provide the following functions:
 
    :arg fd:
        integer file descriptor, or else an object with a ``fileno()`` method
-   :raises trio.ResourceBusyError:
+   :raises trio.BusyResourceError:
        if another task is already waiting for the given fd to
        become readable.
    :raises trio.ClosedResourceError:
@@ -213,7 +213,7 @@ Unix-like systems provide the following functions:
 
    :arg fd:
        integer file descriptor, or else an object with a ``fileno()`` method
-   :raises trio.ResourceBusyError:
+   :raises trio.BusyResourceError:
        if another task is already waiting for the given fd to
        become writable.
    :raises trio.ClosedResourceError:

docs/source/reference-io.rst

@@ -144,10 +144,6 @@ Abstract base classes
    :members:
    :show-inheritance:
 
-.. currentmodule:: trio
-
-.. autoexception:: BrokenStreamError
-
 .. currentmodule:: trio.abc
 
 .. autoclass:: trio.abc.Listener

docs/source/tutorial.rst

@@ -987,7 +987,7 @@ to isolate that to making just this one task crash, without taking
 down the whole program. For example, if the client closes the
 connection at the wrong moment then it's possible this code will end
 up calling ``send_all`` on a closed connection and get an
-:exc:`BrokenStreamError`; that's unfortunate, and in a more serious
+:exc:`BrokenResourceError`; that's unfortunate, and in a more serious
 program we might want to handle it more explicitly, but it doesn't
 indicate a problem for any *other* connections. On the other hand, if
 the exception is something like a :exc:`KeyboardInterrupt`, we *do*

trio/__init__.py

@@ -17,9 +17,9 @@
 
 from ._core import (
     TrioInternalError, RunFinishedError, WouldBlock, Cancelled,
-    ResourceBusyError, ClosedResourceError, MultiError, run, open_nursery,
+    BusyResourceError, ClosedResourceError, MultiError, run, open_nursery,
     open_cancel_scope, current_effective_deadline, TASK_STATUS_IGNORED,
-    current_time
+    current_time, BrokenResourceError
 )
 
 from ._timeouts import (
@@ -36,9 +36,7 @@
     BlockingTrioPortal
 )
 
-from ._highlevel_generic import (
-    aclose_forcefully, BrokenStreamError, StapledStream
-)
+from ._highlevel_generic import aclose_forcefully, StapledStream
 
 from ._signals import catch_signals, open_signal_receiver
 
@@ -87,6 +85,20 @@
             issue=36,
             instead=ClosedResourceError
         ),
+    "BrokenStreamError":
+        _deprecate.DeprecatedAttribute(
+            BrokenResourceError,
+            "0.8.0",
+            issue=620,
+            instead=BrokenResourceError
+        ),
+    "ResourceBusyError":
+        _deprecate.DeprecatedAttribute(
+            BusyResourceError,
+            "0.8.0",
+            issue=620,
+            instead=BusyResourceError
+        ),
 }
 
 _deprecate.enable_attribute_deprecations(hazmat.__name__)

trio/_abc.py

@@ -296,10 +296,10 @@ async def send_all(self, data):
           data (bytes, bytearray, or memoryview): The data to send.
 
         Raises:
-          trio.ResourceBusyError: if another task is already executing a
+          trio.BusyResourceError: if another task is already executing a
               :meth:`send_all`, :meth:`wait_send_all_might_not_block`, or
               :meth:`HalfCloseableStream.send_eof` on this stream.
-          trio.BrokenStreamError: if something has gone wrong, and the stream
+          trio.BrokenResourceError: if something has gone wrong, and the stream
               is broken.
           trio.ClosedResourceError: if you previously closed this stream
               object, or if another task closes this stream object while
@@ -329,10 +329,10 @@ async def wait_send_all_might_not_block(self):
         return. When implementing it, err on the side of returning early.
 
         Raises:
-          trio.ResourceBusyError: if another task is already executing a
+          trio.BusyResourceError: if another task is already executing a
               :meth:`send_all`, :meth:`wait_send_all_might_not_block`, or
               :meth:`HalfCloseableStream.send_eof` on this stream.
-          trio.BrokenStreamError: if something has gone wrong, and the stream
+          trio.BrokenResourceError: if something has gone wrong, and the stream
               is broken.
           trio.ClosedResourceError: if you previously closed this stream
               object, or if another task closes this stream object while
@@ -406,9 +406,9 @@ async def receive_some(self, max_bytes):
           bytes or bytearray: The data received.
 
         Raises:
-          trio.ResourceBusyError: if two tasks attempt to call
+          trio.BusyResourceError: if two tasks attempt to call
               :meth:`receive_some` on the same stream at the same time.
-          trio.BrokenStreamError: if something has gone wrong, and the stream
+          trio.BrokenResourceError: if something has gone wrong, and the stream
               is broken.
           trio.ClosedResourceError: if you previously closed this stream
               object, or if another task closes this stream object while
@@ -474,11 +474,11 @@ async def send_eof(self):
         succeed.
 
         Raises:
-          trio.ResourceBusyError: if another task is already executing a
+          trio.BusyResourceError: if another task is already executing a
               :meth:`~SendStream.send_all`,
               :meth:`~SendStream.wait_send_all_might_not_block`, or
               :meth:`send_eof` on this stream.
-          trio.BrokenStreamError: if something has gone wrong, and the stream
+          trio.BrokenResourceError: if something has gone wrong, and the stream
               is broken.
           trio.ClosedResourceError: if you previously closed this stream
               object, or if another task closes this stream object while
@@ -504,7 +504,7 @@ async def accept(self):
           SOCK_SEQPACKET sockets or similar.
 
         Raises:
-          trio.ResourceBusyError: if two tasks attempt to call
+          trio.BusyResourceError: if two tasks attempt to call
               :meth:`accept` on the same listener at the same time.
           trio.ClosedResourceError: if you previously closed this listener
               object, or if another task closes this listener object while

trio/_core/__init__.py

@@ -16,7 +16,7 @@ def _public(fn):
 
 from ._exceptions import (
     TrioInternalError, RunFinishedError, WouldBlock, Cancelled,
-    ResourceBusyError, ClosedResourceError
+    BusyResourceError, ClosedResourceError, BrokenResourceError
 )
 
 from ._multierror import MultiError

trio/_core/_exceptions.py

@@ -1,16 +1,5 @@
 import attr
 
-# Re-exported
-__all__ = [
-    "TrioInternalError",
-    "RunFinishedError",
-    "WouldBlock",
-    "Cancelled",
-    "ResourceBusyError",
-    "ClosedResourceError",
-]
-
-
 class TrioInternalError(Exception):
     """Raised by :func:`run` if we encounter a bug in trio, or (possibly) a
     misuse of one of the low-level :mod:`trio.hazmat` APIs.
@@ -95,12 +84,12 @@ def _init(cls):
         return cls(_marker=cls.__marker)
 
 
-class ResourceBusyError(Exception):
+class BusyResourceError(Exception):
     """Raised when a task attempts to use a resource that some other task is
     already using, and this would lead to bugs and nonsense.
 
     For example, if two tasks try to send data through the same socket at the
-    same time, trio will raise :class:`ResourceBusyError` instead of letting
+    same time, trio will raise :class:`BusyResourceError` instead of letting
     the data get scrambled.
 
     """
@@ -114,6 +103,21 @@ class ClosedResourceError(Exception):
     by exiting a context manager. If a problem arises elsewhere – for example,
     because of a network failure, or because a remote peer closed their end of
     a connection – then that should be indicated by a different exception
-    class, like :exc:`BrokenStreamError` or an :exc:`OSError` subclass.
+    class, like :exc:`BrokenResourceError` or an :exc:`OSError` subclass.
+
+    """
+
+class BrokenResourceError(Exception):
+    """Raised when an attempt to use a resource fails due to external
+    circumstances.
+
+    For example, you might get this if you try to send data on a stream where
+    the remote side has already closed the connection.
+
+    You *don't* get this error if *you* closed the resource – in that case you
+    get :class:`ClosedResourceError`.
+
+    This exception's ``__cause__`` attribute will often contain more
+    information about the underlying error.
 
     """

trio/_core/_io_epoll.py

@@ -104,7 +104,7 @@ async def _epoll_wait(self, fd, attr_name):
         waiters = self._registered[fd]
         if getattr(waiters, attr_name) is not None:
             await _core.checkpoint()
-            raise _core.ResourceBusyError(
+            raise _core.BusyResourceError(
                 "another task is already reading / writing this fd"
             )
         setattr(waiters, attr_name, _core.current_task())

trio/_core/_io_kqueue.py

@@ -82,7 +82,7 @@ def current_kqueue(self):
     def monitor_kevent(self, ident, filter):
         key = (ident, filter)
         if key in self._registered:
-            raise _core.ResourceBusyError(
+            raise _core.BusyResourceError(
                 "attempt to register multiple listeners for same "
                 "ident/filter pair"
             )
@@ -98,7 +98,7 @@ async def wait_kevent(self, ident, filter, abort_func):
         key = (ident, filter)
         if key in self._registered:
             await _core.checkpoint()
-            raise _core.ResourceBusyError(
+            raise _core.BusyResourceError(
                 "attempt to register multiple listeners for same "
                 "ident/filter pair"
             )

trio/_core/_io_windows.py

@@ -299,7 +299,7 @@ async def wait_overlapped(self, handle, lpOverlapped):
         if isinstance(lpOverlapped, int):
             lpOverlapped = ffi.cast("LPOVERLAPPED", lpOverlapped)
         if lpOverlapped in self._overlapped_waiters:
-            raise _core.ResourceBusyError(
+            raise _core.BusyResourceError(
                 "another task is already waiting on that lpOverlapped"
             )
         task = _core.current_task()
@@ -340,7 +340,7 @@ async def _wait_socket(self, which, sock):
             sock = sock.fileno()
         if sock in self._socket_waiters[which]:
             await _core.checkpoint()
-            raise _core.ResourceBusyError(
+            raise _core.BusyResourceError(
                 "another task is already waiting to {} this socket"
                 .format(which)
             )

trio/_core/tests/test_io.py

@@ -157,7 +157,7 @@ async def test_double_read(socketpair, wait_readable):
         nursery.start_soon(wait_readable, a)
         await wait_all_tasks_blocked()
         with assert_checkpoints():
-            with pytest.raises(_core.ResourceBusyError):
+            with pytest.raises(_core.BusyResourceError):
                 await wait_readable(a)
         nursery.cancel_scope.cancel()
 
@@ -172,7 +172,7 @@ async def test_double_write(socketpair, wait_writable):
         nursery.start_soon(wait_writable, a)
         await wait_all_tasks_blocked()
         with assert_checkpoints():
-            with pytest.raises(_core.ResourceBusyError):
+            with pytest.raises(_core.BusyResourceError):
                 await wait_writable(a)
         nursery.cancel_scope.cancel()
 

trio/_highlevel_generic.py

@@ -3,12 +3,6 @@
 from . import _core
 from .abc import HalfCloseableStream
 
-__all__ = [
-    "aclose_forcefully",
-    "BrokenStreamError",
-    "StapledStream",
-]
-
 
 async def aclose_forcefully(resource):
     """Close an async resource or async generator immediately, without
@@ -40,23 +34,6 @@ async def aclose_forcefully(resource):
         await resource.aclose()
 
 
-class BrokenStreamError(Exception):
-    """Raised when an attempt to use a stream fails due to external
-    circumstances.
-
-    For example, you might get this if you try to send data on a stream where
-    the remote side has already closed the connection.
-
-    You *don't* get this error if *you* closed the stream – in that case you
-    get :class:`ClosedResourceError`.
-
-    This exception's ``__cause__`` attribute will often contain more
-    information about the underlying error.
-
-    """
-    pass
-
-
 @attr.s(cmp=False, hash=False)
 class StapledStream(HalfCloseableStream):
     """This class `staples <https://en.wikipedia.org/wiki/Staple_(fastener)>`__

trio/_highlevel_socket.py

@@ -7,7 +7,6 @@
 from . import socket as tsocket
 from ._util import ConflictDetector
 from .abc import HalfCloseableStream, Listener
-from ._highlevel_generic import BrokenStreamError
 
 __all__ = ["SocketStream", "SocketListener"]
 
@@ -29,7 +28,7 @@ def _translate_socket_errors_to_stream_errors():
                 "this socket was already closed"
             ) from None
         else:
-            raise BrokenStreamError(
+            raise _core.BrokenResourceError(
                 "socket connection broken: {}".format(exc)
             ) from exc