File associations

changes/2284.feature.rst

@@ -0,0 +1 @@
+Added improved document types (file associations) for Windows and macOS platforms

src/briefcase/config.py

@@ -146,6 +146,44 @@ def validate_document_type_config(document_type_id, document_type):
             f"The URL associated with document type {document_type_id!r} is invalid: {e}"
         )
 
+    if sys.platform == "darwin":  # pragma: no-cover-if-not-macos
+        from briefcase.platforms.macOS.utils import mime_type_to_UTI
+
+        macOS = document_type.setdefault("macOS", {})
+        mime_type = document_type.get("mime_type", None)
+        if (uti := mime_type_to_UTI(mime_type)) is not None:
+            macOS.setdefault("is_core_type", True)
+            macOS.setdefault("LSItemContentTypes", uti)
+            macOS.setdefault("LSHandlerRank", "Alternate")
+        else:
+            # LSItemContentTypes will default to bundle.app_name.document_type_id
+            # in the Info.plist template if it is not provided.
+            macOS.setdefault("is_core_type", False)
+            macOS.setdefault("LSHandlerRank", "Owner")
+            macOS.setdefault("UTTypeConformsTo", ["public.data", "public.content"])
+
+        macOS.setdefault("CFBundleTypeRole", "Viewer")
+
+        content_types = macOS.get("LSItemContentTypes", None)
+        if isinstance(content_types, list):
+            if len(content_types) > 1:
+                raise BriefcaseConfigError(
+                    f"""
+Document type {document_type_id!r} has multiple content types. Specifying
+multiple values in a LSItemContentTypes key is only valid when multiple document
+types are manually grouped together in the Info.plist file. For Briefcase apps,
+document types are always separately declared in the configuration file, so only
+a single value should be provided.
+                """
+                )
+            else:
+                macOS["LSItemContentTypes"] = content_types[0]
+        else:
+            # This is basically a no-op to satisfy coverage checkers
+            content_types = "string or None"
+    else:  # pragma: no-cover-if-is-macos
+        pass
+
 
 VALID_BUNDLE_RE = re.compile(r"[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+$")
 

src/briefcase/platforms/macOS/utils.py

@@ -3,11 +3,15 @@
 import concurrent
 import email
 import hashlib
+import pathlib
+import plistlib
 import subprocess
 from pathlib import Path
 
 from briefcase.exceptions import BriefcaseCommandError
 
+CORETYPES_PATH = "/System/Library/CoreServices/CoreTypes.bundle/Contents/Info.plist"
+
 
 def sha256_file_digest(path: Path) -> str:
     """Compute a sha256 checksum digest of a file.
@@ -272,3 +276,52 @@ def merge_app_packages(
                             raise future.exception()
         else:
             self.console.info("No libraries require merging.")
+
+
+def mime_type_to_UTI(mime_type: str) -> str | None:  # pragma: no-cover-if-not-macos
+    """Convert a MIME type to a Uniform Type Identifier (UTI).
+
+    This function reads the system's CoreTypes Info.plist file to determine the
+    UTI for a given MIME type.
+
+    Args:
+        mime_type: The MIME type to convert.
+
+    Returns:
+        The UTI for the MIME type, or None if the UTI cannot be determined.
+    """
+    try:
+        plist_data = pathlib.Path(CORETYPES_PATH).read_bytes()
+    except FileNotFoundError:
+        # If the file is not found, we assume that the system is not macOS
+        # or the file has been moved in recent macOS versions.
+        # In this case, we return None to indicate that the UTI cannot be determined.
+        return None
+    plist = plistlib.loads(plist_data)
+    for type_declaration in (
+        plist["UTExportedTypeDeclarations"] + plist["UTImportedTypeDeclarations"]
+    ):
+        # We check both the system built-in types (exported) and the known
+        # third-party types (imported) to find the UTI for the given MIME type.
+        # Most type declarations will have a UTTypeTagSpecification dictionary
+        # with a "public.mime-type" key. That can be either a list of MIME types
+        # or a single MIME type. We check if the MIME type is in the list or
+        # matches the single MIME type. If we find a match, we return the UTI
+        # identifier. If we don't find a match, we return None.
+
+        mime_types = type_declaration.get("UTTypeTagSpecification", {}).get(
+            "public.mime-type", []
+        )
+        if isinstance(mime_types, list):
+            # Most MIME types are declared as a list even if they are a
+            # single type. Some types define multiple closely-related MIME
+            # types.
+            if mime_type in mime_types:
+                return type_declaration["UTTypeIdentifier"]
+        else:
+            # some MIME types are declared as a single type
+            if mime_types == mime_type:
+                return type_declaration["UTTypeIdentifier"]
+
+    # If no match is found in the entire list, return None
+    return None

tests/config/test_AppConfig.py

@@ -1,3 +1,5 @@
+import sys
+
 import pytest
 
 from briefcase.config import AppConfig
@@ -78,14 +80,34 @@ def test_extra_attrs():
     # Properties that are derived by default have been set explicitly
     assert config.formal_name == "My App!"
     assert config.class_name == "MyApp"
-    assert config.document_types == {
-        "document": {
-            "icon": "icon",
-            "extension": "doc",
-            "description": "A document",
-            "url": "https://testurl.com",
+
+    if sys.platform == "darwin":
+        assert config.document_types == {
+            "document": {
+                "icon": "icon",
+                "extension": "doc",
+                "description": "A document",
+                "url": "https://testurl.com",
+                "macOS": {
+                    "CFBundleTypeRole": "Viewer",
+                    "LSHandlerRank": "Owner",
+                    "UTTypeConformsTo": [
+                        "public.data",
+                        "public.content",
+                    ],
+                    "is_core_type": False,
+                },
+            }
+        }
+    else:
+        assert config.document_types == {
+            "document": {
+                "icon": "icon",
+                "extension": "doc",
+                "description": "A document",
+                "url": "https://testurl.com",
+            }
         }
-    }
 
     # Explicit additional properties have been set
     assert config.first == "value 1"

tests/config/test_document_type_config.py

@@ -1,7 +1,10 @@
+import sys
+
 import pytest
 
 from briefcase.config import validate_document_type_config
 from briefcase.exceptions import BriefcaseConfigError
+from briefcase.platforms.macOS import utils
 
 
 @pytest.fixture
@@ -160,3 +163,80 @@ def test_validate_document_invalid_extension(invalid_extension, valid_document):
         match=r"The extension provided for document type .* is not alphanumeric.",
     ):
         validate_document_type_config("ext", valid_document)
+
+
+@pytest.mark.skipif(sys.platform != "darwin", reason="Test runs only on macOS")
+def test_document_type_macOS_config_with_mimetype_single(valid_document):
+    """Valid document types don't raise an exception when validated.
+
+    application/pdf is the only valid MIME type for PDF files.
+    """
+    valid_document["mime_type"] = "application/pdf"
+    validate_document_type_config("ext", valid_document)
+    assert "LSItemContentTypes" in valid_document["macOS"].keys()
+    assert valid_document["macOS"]["LSItemContentTypes"] == "com.adobe.pdf"
+
+
+@pytest.mark.skipif(sys.platform != "darwin", reason="Test runs only on macOS")
+def test_document_type_macOS_config_with_mimetype_list(valid_document):
+    """Valid document types don't raise an exception when validated.
+
+    text/vcard is _not_ the only valid MIME type for vCard files, others are
+    text/directory and text/x-vcard so a list if MIME types is returned
+    internally but should still resolve to public.vcard
+    """
+    valid_document["mime_type"] = "text/vcard"
+    validate_document_type_config("ext", valid_document)
+    assert "LSItemContentTypes" in valid_document["macOS"].keys()
+    assert valid_document["macOS"]["LSItemContentTypes"] == "public.vcard"
+
+
+@pytest.mark.skipif(sys.platform != "darwin", reason="Test runs only on macOS")
+def test_document_type_macOS_config_with_unknown_mimetype(valid_document):
+    """Valid document types don't raise an exception when validated.
+
+    Here, a MIME type is provided that is not known to be valid for any file.
+    That means that LSItemContentTypes should _not_ be set.
+    """
+    valid_document["mime_type"] = "custom/mytype"
+    validate_document_type_config("ext", valid_document)
+    assert "LSItemContentTypes" not in valid_document["macOS"].keys()
+
+
+@pytest.mark.skipif(sys.platform != "darwin", reason="Test runs only on macOS")
+def test_mime_type_to_uti_with_nonexisting_coretypes_file(monkeypatch):
+    """Test that mime_type_to_UTI returns None if the coretypes file doesn't exist."""
+    monkeypatch.setattr(utils, "CORETYPES_PATH", "/does/not/exist")
+    assert utils.mime_type_to_UTI("application/pdf") is None
+
+
+@pytest.mark.skipif(sys.platform != "darwin", reason="Test runs only on macOS")
+def test_document_type_macOS_config_with_list_of_content_types(valid_document):
+    """Multiple content types are not allowed.
+
+    If a document type has multiple content types, an exception is raised.
+    """
+    valid_document.setdefault("macOS", {})["LSItemContentTypes"] = [
+        "com.adobe.pdf",
+        "public.vcard",
+    ]
+    with pytest.raises(
+        BriefcaseConfigError,
+        match="Document type 'ext' has multiple content types.",
+    ):
+        validate_document_type_config("ext", valid_document)
+
+
+@pytest.mark.skipif(sys.platform != "darwin", reason="Test runs only on macOS")
+def test_document_type_macOS_config_with_list_of_single_content_type(valid_document):
+    """Single content type is allowed, even if a list is provided.
+
+    If a document type has a single content type, it is converted to a string.
+    """
+    valid_document.setdefault("macOS", {})["LSItemContentTypes"] = "com.adobe.pdf"
+    validate_document_type_config("ext", valid_document)
+    assert valid_document["macOS"]["LSItemContentTypes"] == "com.adobe.pdf"
+
+    valid_document["macOS"]["LSItemContentTypes"] = ["com.adobe.pdf"]
+    validate_document_type_config("ext", valid_document)
+    assert valid_document["macOS"]["LSItemContentTypes"] == "com.adobe.pdf"