Finalize API for Document-based apps

changes/2209.removal.rst

@@ -1,11 +1,13 @@
 The API for Documents and Document-based apps has been significantly modified. Unfortunately, these changes are not backwards compatible; any existing Document-based app will require modification.
 
-The ``DocumentApp`` base class is no longer required. Apps can subclass ``App``, providing the same arguments as before.
+The ``DocumentApp`` base class is no longer required. Apps can subclass ``App`` directly, passing the document types as a ``list`` of ``Document`` classes, rather than a mapping of extension to document type.
 
 The API for ``Document`` subclasses has also changed:
 
 * A path is no longer provided as an argument to the Document constructor;
 
 * The ``document_type`` is now specified as a class property; and
 
+* Extensions are now defined as a class property of the ``Document``; and
+
 * The ``can_close()`` handler is no longer honored. Documents now track if they are modified, and have a default ``on_close`` handler that uses the modification status of a document to control whether a document can close. Invoking ``touch()`` on document will mark a document as modified. This modification flag is cleared by saving the document.

cocoa/src/toga_cocoa/app.py

@@ -54,7 +54,7 @@ def applicationOpenUntitledFile_(self, sender) -> bool:
 
     @objc_method
     def applicationShouldOpenUntitledFile_(self, sender) -> bool:
-        return bool(self.interface.document_types)
+        return bool(self.interface.documents.types)
 
     @objc_method
     def application_openFiles_(self, app, filenames) -> None:

core/src/toga/app.py

@@ -158,7 +158,7 @@ def __init__(
         home_page: str | None = None,
         description: str | None = None,
         startup: AppStartupMethod | None = None,
-        document_types: dict[str, type[Document]] | None = None,
+        document_types: list[type[Document]] | None = None,
         on_running: OnRunningHandler | None = None,
         on_exit: OnExitHandler | None = None,
         id: None = None,  # DEPRECATED
@@ -198,8 +198,8 @@ def __init__(
         :param startup: A callable to run before starting the app.
         :param on_running: The initial :any:`on_running` handler.
         :param on_exit: The initial :any:`on_exit` handler.
-        :param document_types: A mapping of document types managed by this app, to
-             the :any:`Document` class managing that document type.
+        :param document_types: A list of :any:`Document` classes that this app
+            can manage.
         :param id: **DEPRECATED** - This argument will be ignored. If you need a
             machine-friendly identifier, use ``app_id``.
         :param windows: **DEPRECATED** – Windows are now automatically added to the
@@ -315,8 +315,10 @@ def __init__(
             self.icon = icon
 
         # Set up the document types and collection of documents being managed.
-        self._document_types = {} if document_types is None else document_types
-        self._documents = DocumentSet(self)
+        self._documents = DocumentSet(
+            self,
+            types=[] if document_types is None else document_types,
+        )
 
         # Install the lifecycle handlers. If passed in as an argument, or assigned using
         # `app.on_event = my_handler`, the event handler will take the app as the first
@@ -535,45 +537,34 @@ def _create_standard_commands(self):
         ]:
             self.commands.add(Command.standard(self, cmd_id))
 
-        if self.document_types:
-            default_document_type = list(self.document_types.values())[0]
+        if self.documents.types:
+            default_document_type = self.documents.types[0]
             command = Command.standard(
                 self,
                 Command.NEW,
                 action=simple_handler(self.documents.new, default_document_type),
             )
             if command:
-                if len(set(self.document_types.values())) == 1:
+                if len(self.documents.types) == 1:
                     # There's only 1 document type. The new command can be used as is.
                     self.commands.add(command)
                 else:
                     # There's more than one document type. Create a new command for each
                     # document type, updating the title of the command to disambiguate,
                     # and modifying the shortcut, order and ID of the document types 2+
-                    known_document_classes = set()
-                    for i, (extension, document_class) in enumerate(
-                        self.document_types.items()
-                    ):
-                        if document_class not in known_document_classes:
-                            command = Command.standard(
-                                self,
-                                Command.NEW,
-                                action=simple_handler(
-                                    self.documents.new, document_class
-                                ),
-                            )
-                            command.text = (
-                                command.text + f" {document_class.document_type}"
-                            )
-                            if i > 0:
-                                command.shortcut = None
-                                command._id = f"{command.id}:{extension}"
-                                command.order = command.order + len(
-                                    known_document_classes
-                                )
-
-                            self.commands.add(command)
-                            known_document_classes.add(document_class)
+                    for i, document_class in enumerate(self.documents.types):
+                        command = Command.standard(
+                            self,
+                            Command.NEW,
+                            action=simple_handler(self.documents.new, document_class),
+                        )
+                        command.text = command.text + f" {document_class.description}"
+                        if i > 0:
+                            command.shortcut = None
+                            command._id = f"{command.id}:{document_class.extensions[0]}"
+                            command.order = command.order + i
+
+                        self.commands.add(command)
 
             for cmd_id in [
                 Command.OPEN,
@@ -595,7 +586,7 @@ def _create_initial_windows(self):
         if self._impl.HANDLES_COMMAND_LINE:
             return
         doc_count = len(self.windows)
-        if self.document_types:
+        if self.documents.types:
             for filename in sys.argv[1:]:
                 if self._open_initial_document(filename):
                     doc_count += 1
@@ -604,9 +595,9 @@ def _create_initial_windows(self):
         if self.main_window is None and doc_count == 0:
             try:
                 # Pass in the first document type as the default
-                default_doc_type = next(iter(self.document_types.values()))
+                default_doc_type = self.documents.types[0]
                 self.documents.new(default_doc_type)
-            except StopIteration:
+            except IndexError:
                 # No document types defined.
                 raise RuntimeError(
                     "App didn't create any windows, or register any document types."
@@ -681,16 +672,6 @@ def commands(self) -> CommandSet:
         """The commands available in the app."""
         return self._commands
 
-    @property
-    def document_types(self) -> dict[str, type[Document]]:
-        """The document types this app can manage.
-
-        A dictionary of file extensions, without leading dots, mapping to the
-        :class:`toga.Document` subclass that will be created when a document with that
-        extension is opened.
-        """
-        return self._document_types
-
     @property
     def documents(self) -> DocumentSet:
         """The list of documents associated with this app."""
@@ -896,6 +877,26 @@ def add_background_task(self, handler: BackgroundTask) -> None:
 
         self.loop.call_soon_threadsafe(wrapped_handler(self, handler))
 
+    ######################################################################
+    # 2024-08: Backwards compatibility
+    ######################################################################
+
+    @property
+    def document_types(self) -> dict[str, type[Document]]:
+        """**DEPRECATED** - Use ``documents.types``; extensions can be
+        obtained from the individual document classes itself.
+        """
+        warnings.warn(
+            "App.document_types is deprecated. Use App.documents.types",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return {
+            extension: doc_type
+            for doc_type in self.documents.types
+            for extension in doc_type.extensions
+        }
+
     ######################################################################
     # End backwards compatibility
     ######################################################################
@@ -911,4 +912,8 @@ def __init__(self, *args, **kwargs):
             DeprecationWarning,
             stacklevel=2,
         )
+        # Convert document types from dictionary format to list format.
+        # The old API guaranteed that document_types was provided
+        kwargs["document_types"] = list(kwargs["document_types"].values())
+
         super().__init__(*args, **kwargs)

core/src/toga/command.py

@@ -161,32 +161,42 @@ def __call__(self, command: Command, **kwargs) -> bool:
 
 class Command:
     #: An identifier for the standard "About" menu item. This command is always
-    #: installed by default.
+    #: installed by default. Uses :meth:`toga.App.about` as the default action.
     ABOUT: str = "about"
     #: An identifier for the standard "Exit" menu item. This command may be installed by
-    #: default, depending on platform requirements.
+    #: default, depending on platform requirements. Uses :meth:`toga.App.request_exit`
+    #: as the default action.
     EXIT: str = "request_exit"
     #: An identifier for the standard "New" menu item. This constant will be used for
     #: the default document type for your app; if you specify more than one document
     #: type, the command for the subsequent commands will have a colon and the first
-    #: extension for that data type appended to the ID.
+    #: extension for that data type appended to the ID. Uses
+    #: :meth:`toga.documents.DocumentSet.new` as the default action.
     NEW: str = "documents.new"
     #: An identifier for the standard "Open" menu item. This command will be
-    #: automatically installed if your app declares any document types.
+    #: automatically installed if your app declares any document types. Uses
+    #: :meth:`toga.documents.DocumentSet.request_open` as the default action.
     OPEN: str = "documents.request_open"
-    #: An identifier for the standard "Preferences" menu item.
+    #: An identifier for the standard "Preferences" menu item. The Preferences item is
+    #: not installed by default. If you install it manually, it will attempt to use
+    #: ``toga.App.preferences()`` as the default action; your app will need to define
+    #: this method, or provide an explicit value for the action.
     PREFERENCES: str = "preferences"
     #: An identifier for the standard "Save" menu item. This command will be
-    #: automatically installed if your app declares any document types.
+    #: automatically installed if your app declares any document types. Uses
+    #: :meth:`toga.documents.DocumentSet.save` as the default action.
     SAVE: str = "documents.save"
     #: An identifier for the standard "Save As..." menu item. This command will be
-    #: automatically installed if your app declares any document types.
+    #: automatically installed if your app declares any document types. Uses
+    #: :meth:`toga.documents.DocumentSet.save_as` as the default action.
     SAVE_AS: str = "documents.save_as"
     #: An identifier for the standard "Save All" menu item. This command will be
-    #: automatically installed if your app declares any document types.
+    #: automatically installed if your app declares any document types. Uses
+    #: :meth:`toga.documents.DocumentSet.save_all` as the default action.
     SAVE_ALL: str = "documents.save_all"
     #: An identifier for the standard "Visit Homepage" menu item. This command may be
-    #: installed by default, depending on platform requirements.
+    #: installed by default, depending on platform requirements. Uses
+    #: :meth:`toga.App.visit_homepage` as the default action.
     VISIT_HOMEPAGE: str = "visit_homepage"
 
     def __init__(