Add back dialogs

.readthedocs.yml

@@ -9,7 +9,7 @@ build:
   image: latest
 
 python:
-  version: 3
+  version: 3.8
   install:
     - method: pip
       path: .

docs/source/conf.py

@@ -39,8 +39,13 @@
     ("py:class", "qtrio._core.EmissionsNursery"),
     ("py:class", "qtrio._core.Outcomes"),
     ("py:class", "qtrio._core.Reenter"),
+    ("py:class", "qtrio._qt.Signal"),
     # https://github.com/Czaki/sphinx-qt-documentation/issues/10
     ("py:class", "<class 'PySide2.QtCore.QEvent.Type'>"),
+    ("py:class", "<class 'PySide2.QtWidgets.QFileDialog.FileMode'>"),
+    ("py:class", "<class 'PySide2.QtWidgets.QFileDialog.AcceptMode'>"),
+    ("py:class", "<class 'PySide2.QtWidgets.QFileDialog.Option'>"),
+    ("py:class", "<class 'PySide2.QtWidgets.QMessageBox.Icon'>"),
     # https://github.com/sphinx-doc/sphinx/issues/8136
     ("py:class", "typing.AbstractAsyncContextManager"),
 ]

docs/source/core.rst

@@ -28,6 +28,11 @@ their errors on the floor they will be run inside a nursery.
 .. autofunction:: qtrio.open_emissions_nursery
 .. autoclass:: qtrio.EmissionsNursery
 
+Helpers
+-------
+
+.. autoclass:: qtrio.Signal
+
 Reentry Events
 --------------
 

docs/source/dialogs.rst

@@ -0,0 +1,38 @@
+Dialogs
+=======
+
+Usage Pattern
+-------------
+
+Creation Functions
+------------------
+
+.. autofunction:: qtrio.dialogs.create_integer_dialog
+.. autofunction:: qtrio.dialogs.create_text_input_dialog
+.. autofunction:: qtrio.dialogs.create_file_save_dialog
+.. autofunction:: qtrio.dialogs.create_message_box
+
+
+Classes
+-------
+
+.. autoclass:: qtrio.dialogs.IntegerDialog
+   :members:
+
+.. autoclass:: qtrio.dialogs.TextInputDialog
+   :members:
+
+.. autoclass:: qtrio.dialogs.FileDialog
+   :members:
+
+.. autoclass:: qtrio.dialogs.MessageBox
+   :members:
+
+
+Protocol
+--------
+
+.. autoclass:: qtrio.dialogs.DialogProtocol
+   :members:
+
+.. autofunction:: qtrio.dialogs.check_dialog_protocol

docs/source/exceptions.rst

@@ -8,3 +8,6 @@ Exceptions
 .. autoclass:: qtrio.RequestedEventTypeUnavailableError
 .. autoclass:: qtrio.EventTypeAlreadyRegisteredError
 .. autoclass:: qtrio.ReturnCodeError
+.. autoclass:: qtrio.InternalError
+.. autoclass:: qtrio.UserCancelledError
+.. autoclass:: qtrio.InvalidInputError

docs/source/index.rst

@@ -12,6 +12,7 @@
    tutorial.rst
    core.rst
    testing.rst
+   dialogs.rst
    exceptions.rst
    examples/examples.rst
    development/index.rst

newsfragments/2.feature.rst

@@ -0,0 +1 @@
+Introduce QTrio specific wrappers for some builtin dialogs.

qtrio/__init__.py

@@ -11,6 +11,9 @@
     EventTypeAlreadyRegisteredError,
     ReturnCodeError,
     RunnerTimedOutError,
+    UserCancelledError,
+    InvalidInputError,
+    InternalError,
 )
 
 from ._core import (
@@ -28,4 +31,5 @@
     Reenter,
 )
 
+from ._qt import Signal
 from ._pytest import host

qtrio/_exceptions.py

@@ -85,6 +85,13 @@ def __eq__(self, other: object) -> bool:
         return self.args == other.args
 
 
+class InternalError(QTrioException):
+    """Raised when an internal state is inconsistent."""
+
+    # https://github.com/sphinx-doc/sphinx/issues/7493
+    __module__ = "qtrio"
+
+
 class UserCancelledError(QTrioException):
     """Raised when a user requested cancellation of an operation."""
 
@@ -97,3 +104,10 @@ class RunnerTimedOutError(QTrioException):
 
     # https://github.com/sphinx-doc/sphinx/issues/7493
     __module__ = "qtrio"
+
+
+class InvalidInputError(QTrioException):
+    """Raised when invalid input is provided such as via a dialog."""
+
+    # https://github.com/sphinx-doc/sphinx/issues/7493
+    __module__ = "qtrio"

qtrio/_qt.py

@@ -10,10 +10,10 @@
 
 
 class Signal:
-    """This is a (nearly) drop-in replacement for QtCore.Signal.  The useful difference
-    is that it does not require inheriting from :class:`QtCore.QObject`.  The not-quite
-    part is that it will be a bit more complicated to change thread affinity of the
-    relevant :class:`QtCore.QObject`.  If you need this, maybe just inherit.
+    """This is a (nearly) drop-in replacement for :class:`QtCore.Signal`.  The useful
+    difference is that it does not require inheriting from :class:`QtCore.QObject`.  The
+    not-quite part is that it will be a bit more complicated to change thread affinity
+    of the relevant :class:`QtCore.QObject`.  If you need this, maybe just inherit.
 
     This signal gets around the normally required inheritance by creating
     :class:`QtCore.QObject` instances behind the scenes to host the real signals.  Just
@@ -22,7 +22,7 @@ class Signal:
     object.
     """
 
-    attribute_name: str = ""
+    _attribute_name: typing.ClassVar[str] = ""
 
     def __init__(self, *args: object, **kwargs: object) -> None:
         class _SignalQObject(QtCore.QObject):
@@ -39,19 +39,23 @@ def __get__(self, instance: object, owner: object) -> qtrio._util.SignalInstance
         return o.signal
 
     def object(self, instance: object) -> QtCore.QObject:
-        """Get the :class:`QtCore.QObject` that hosts the real signal.
+        """Get the :class:`QtCore.QObject` that hosts the real signal.  This can be
+        called such as ``type(instance).signal_name.object(instance)``.  Yes this is
+        non-obvious but you have to do something special to get around the
+        :ref:`descriptor protocol <python:descriptors>` so you can get at this method
+        instead of just having the underlying :class:`QtCore.SignalInstance`.
 
         Arguments:
             instance: The object on which this descriptor instance is hosted.
 
         Returns:
             The signal-hosting :class:`QtCore.QObject`.
         """
-        d = getattr(instance, self.attribute_name, None)
+        d = getattr(instance, self._attribute_name, None)
 
         if d is None:
             d = {}
-            setattr(instance, self.attribute_name, d)
+            setattr(instance, self._attribute_name, d)
 
         o = d.get(self.object_cls)
         if o is None:
@@ -61,7 +65,7 @@ def object(self, instance: object) -> QtCore.QObject:
         return o
 
 
-Signal.attribute_name = qtrio._python.identifier_path(Signal)
+Signal._attribute_name = qtrio._python.identifier_path(Signal)
 
 
 @contextlib.contextmanager