Merge branch 'main' into add-NSSupportsAutomaticGraphicsSwitching

.github/workflows/cla.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check CLA
-        uses: conda/actions/check-cla@f46142e89fa703cc69f0421ca1d313ab2d5bfff6
+        uses: conda/actions/check-cla@1e442e090ad28c9b0f85697105703a303320ffd1
         with:
           # [required]
           # A token with ability to comment, label, and modify the commit status

.github/workflows/docs.yml

@@ -45,6 +45,11 @@ jobs:
           # Upload entire repository
           path: 'docs/_build/dirhtml'
 
+      - name: Check links
+        run: |
+          cd docs
+          make linkcheck
+
   pages:
     runs-on: ubuntu-latest
     if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'

.github/workflows/labels.yml

@@ -19,7 +19,7 @@ jobs:
       GLOBAL: https://raw.githubusercontent.com/conda/infra/main/.github/global.yml
       LOCAL: .github/labels.yml
     steps:
-      - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b
       - id: has_local
         uses: andstor/file-existence-action@076e0072799f4942c8bc574a82233e1e4d13e9d6
         with:

.github/workflows/stale.yml

@@ -33,7 +33,7 @@ jobs:
             days-before-issue-stale: 90
             days-before-issue-close: 21
     steps:
-      - uses: conda/actions/read-yaml@f46142e89fa703cc69f0421ca1d313ab2d5bfff6
+      - uses: conda/actions/read-yaml@1e442e090ad28c9b0f85697105703a303320ffd1
         id: read_yaml
         with:
           path: https://raw.githubusercontent.com/conda/infra/main/.github/messages.yml

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ ci:
     autofix_prs: false
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v4.6.0
     hooks:
       - id: check-added-large-files
       - id: check-ast
@@ -25,7 +25,7 @@ repos:
     hooks:
       - id: isort
   - repo: https://github.com/psf/black
-    rev: 23.12.1
+    rev: 24.4.0
     hooks:
       - id: black
         args: [--skip-string-normalization]

docs/source/conf.py

@@ -74,6 +74,11 @@
     ("py:class", "menuinst._schema.ConstrainedStrValue"),
 ]
 
+linkcheck_anchors_ignore = [
+    r"^L[0-9]+$",
+    r"^L[0-9]+-L[0-9]+$",
+]
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

docs/source/defining-shortcuts.md

@@ -100,57 +100,7 @@ Note that setting `CFBundleTypeRole` will make the wrapper blip in the dock when
 opened. If you don't want that, do not set it.
 :::
 
-A multi-platform example:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://schemas.conda.io/menuinst-1.schema.json",
-  "menu_name": "File type handler example",
-  "menu_items": [
-    {
-      "name": "My CSV Reader",
-      "activate": true,
-      "command": ["{{ PREFIX }}/bin/open_menuinst_files.py"],
-      "icon": "{{ MENU_DIR }}/open_menuinst_files.{{ ICON_EXT }}",
-      "platforms": {
-        "linux": {
-          "command": ["{{ PREFIX }}/bin/open_menuinst_files.py", "%f"],
-          "MimeType": ["application/x-menuinst"],
-          "glob_patterns": {
-            "application/x-menuinst": ["*.menuinst"]
-          }
-        },
-        "osx": {
-          "CFBundleDocumentTypes": [
-            {
-              "CFBundleTypeName": "org.conda.menuinst.opener",
-              "CFBundleTypeRole": "Viewer",
-              "LSItemContentTypes": ["org.conda.menuinst.main-file-uti"],
-              "LSHandlerRank": "Default"
-            }
-          ],
-          "UTExportedTypeDeclarations": [
-            {
-              "UTTypeConformsTo": ["public.data", "public.content"],
-              "UTTypeIdentifier": "org.conda.menuinst.main-file-uti",
-              "UTTypeTagSpecification": [
-                {
-                  "public.filename-extension": ["menuinst"]
-                }
-              ]
-            }
-          ]
-        },
-        "windows": {
-          "command": ["{{ SCRIPTS_DIR }}/open_menuinst_files.py", "%1"],
-          "file_extensions": [".csv"]
-        }
-      }
-    }
-  ]
-}
-```
+A multi-platform example can be found at [`tests/data/jsons/file_types.json`](https://github.com/conda/menuinst/blob/main/tests/data/jsons/file_types.json).
 
 ### URL protocols
 
@@ -165,46 +115,7 @@ shortcut.
 - On macOS, use `CFBundleURLTypes`. Requires no placeholders. See
   {ref}`relevant note in File Types <macos-event-handler>`.
 
-```json
-{
-  "$schema": "https://json-schema.org/draft-07/schema",
-  "$id": "https://schemas.conda.io/menuinst-1.schema.json",
-  "menu_name": "Protocol handler example",
-  "menu_items": [
-    {
-      "name": "My custom menuinst:// handler",
-      "activate": true,
-      "command": ["{{ PREFIX }}/bin/my_protocol_handler.py"],
-      "icon": "{{ MENU_DIR }}/my_protocol_handler.{{ ICON_EXT }}",
-      "platforms": {
-        "linux": {
-          "command": ["{{ PREFIX }}/bin/my_protocol_handler.py", "%u"],
-          "MimeType": ["x-scheme-handler/menuinst"]
-        },
-        "osx": {
-          "command": [
-            "{{ PREFIX }}/bin/my_protocol_handler.py",
-            "--listen",
-            "4444"
-          ],
-          "CFBundleURLTypes": [
-            {
-              "CFBundleURLIconFile": "{{ MENU_DIR }}/my_protocol_handler",
-              "CFBundleURLName": "my-protocol-handler.menuinst.does-not-work-yet",
-              "CFBundleURLSchemes": ["menuinst"]
-            }
-          ],
-          "event_handler": "for i in 1 2 3 4 5; do echo \"$*\" | nc localhost 4444 && break || sleep 1; done"
-        },
-        "windows": {
-          "command": ["{{ SCRIPTS_DIR }}/my_protocol_handler.py", "%1"],
-          "url_protocols": ["menuinst"]
-        }
-      }
-    }
-  ]
-}
-```
+A multi-platform example can be found at [`tests/data/jsons/url_protocols.json`](https://github.com/conda/menuinst/blob/main/tests/data/jsons/url_protocols.json).
 
 ## Notes on Windows shortcuts
 

menuinst/_schema.py

@@ -86,27 +86,26 @@ class Windows(BasePlatformSpecific):
     particular application. If your shortcut produces duplicated icons, you need to define this
     field. If not set, it will default to ``Menuinst.<name>``.
 
-    See `AppUserModelID docs <aumi-docs>`__ for more information on the required string format.
-
-    .. aumi-docs: https://learn.microsoft.com/en-us/windows/win32/shell/appids#how-to-form-an-application-defined-appusermodelid
+    See `AppUserModelID docs
+    <https://learn.microsoft.com/en-us/windows/win32/shell/appids#how-to-form-an-application-defined-appusermodelid>`__
+    for more information on the required string format.
     """
 
 
 class Linux(BasePlatformSpecific):
     """
     Linux-specific instructions.
 
-    Check the `Desktop entry specification <desktop-entry-spec>`__ for more details.
-
-    .. desktop-entry-spec: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys
+    Check the `Desktop entry specification
+    <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys>`__
+    for more details.
     """
 
     Categories: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None
     """
     Categories in which the entry should be shown in a menu.
-    "See 'Registered categories' in the `Menu Spec <menu-spec>`__.
-
-    .. menu-spec: http://www.freedesktop.org/Standards/menu-spec
+    "See 'Registered categories' in the `Menu Spec
+    <http://www.freedesktop.org/Standards/menu-spec>`__.
     """
     DBusActivatable: Optional[bool] = None
     "A boolean value specifying if D-Bus activation is supported for this application."
@@ -119,9 +118,8 @@ class Linux(BasePlatformSpecific):
     "Disable shortcut, signaling a missing resource."
     Implements: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None
     """
-    List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec <desktop-entry-spec>`__.
-
-    .. desktop-entry-spec: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#interfaces
+    List of supported interfaces. See 'Interfaces' in `Desktop Entry Spec
+    <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#interfaces>`__.
     """
     Keywords: Optional[Union[List[str], constr(regex=r"^.+;$")]] = None
     "Additional terms to describe this shortcut to aid in searching."
@@ -153,15 +151,13 @@ class Linux(BasePlatformSpecific):
     "Hint that the app prefers to be run on a more powerful discrete GPU if available."
     StartupNotify: Optional[bool] = None
     """
-    Advanced. See `Startup Notification spec <startup-notification-spec>`__.
-
-    .. startup-notification-spec: _https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/
+    Advanced. See `Startup Notification spec
+    <https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/>`__.
     """
     StartupWMClass: Optional[str] = None
     """
-    Advanced. See `Startup Notification spec <startup-notification-spec>`__.
-
-    .. startup-notification-spec: _https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/
+    Advanced. See `Startup Notification spec
+    <https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/>`__.
     """
     TryExec: Optional[str] = None
     """
@@ -180,13 +176,9 @@ class MacOS(BasePlatformSpecific):
     """
     Mac-specific instructions. Check these URLs for more info:
 
-    - ``CF*`` keys: see `Core Foundation Keys <cf-keys>`_
-    - ``LS*`` keys: see `Launch Services Keys <ls-keys>`_
-    - ``entitlements``: see `entitlements docs <entitlements-docs>`_
-
-    .. _cf-keys: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
-    .. _ls-keys: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html
-    .. _entitlements-docs: https://developer.apple.com/documentation/bundleresources/entitlements.
+    - ``CF*`` keys: see `Core Foundation Keys <https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html>`__
+    - ``LS*`` keys: see `Launch Services Keys <https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html>`__
+    - ``entitlements``: see `Entitlements documentation <https://developer.apple.com/documentation/bundleresources/entitlements>`__
     """
 
     class CFBundleURLTypesModel(BaseModel):
@@ -211,15 +203,13 @@ class CFBundleDocumentTypesModel(BaseModel):
         LSItemContentTypes: List[str] = ...
         """
         List of UTI strings defining a supported file type; e.g. for
-        PNG files, use 'public.png'. See `UTI Reference <uti-reference>`_
+        PNG files, use 'public.png'. See `UTI Reference
+        <https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html>`__
         for more info about the system-defined UTIs. Custom UTIs can be
         defined via 'UTExportedTypeDeclarations'. UTIs defined by other
         apps (not the system) need to be imported via 'UTImportedTypeDeclarations'.
 
-        See `Fun with UTIs <fun-with-utis>`_ for more info.
-
-        .. _uti-reference: https://developer.apple.com/library/archive/documentation/Miscellaneous/Reference/UTIRef/Articles/System-DeclaredUniformTypeIdentifiers.html
-        .. _fun-with-utis: https://www.cocoanetics.com/2012/09/fun-with-uti/
+        See `Fun with UTIs <https://www.cocoanetics.com/2012/09/fun-with-uti/>`__ for more info.
         """
         LSHandlerRank: Literal["Owner", "Default", "Alternate"] = ...
         """
@@ -304,13 +294,12 @@ class UTTypeDeclarationModel(BaseModel):
     entitlements: Optional[List[constr(regex=r"[a-z0-9\.\-]+")]] = None
     """
     List of permissions to request for the launched application.
-    See `the entitlements docs <entitlements>`__ for a full list of possible values.
-
-    .. entitlements: https://developer.apple.com/documentation/bundleresources/entitlements
+    See `the entitlements docs <https://developer.apple.com/documentation/bundleresources/entitlements>`__
+    for a full list of possible values.
     """
-    link_in_bundle: Optional[
-        Dict[constr(min_length=1), constr(regex=r"^(?!\/)(?!\.\./).*")]
-    ] = None
+    link_in_bundle: Optional[Dict[constr(min_length=1), constr(regex=r"^(?!\/)(?!\.\./).*")]] = (
+        None
+    )
     """
     Paths that should be symlinked into the shortcut app bundle.
     It takes a mapping of source to destination paths. Destination paths must be

menuinst/data/menuinst.schema.json

@@ -43,7 +43,7 @@
   "definitions": {
     "Linux": {
       "title": "Linux",
-      "description": "Linux-specific instructions.\n\nCheck the `Desktop entry specification <desktop-entry-spec>`__ for more details.\n\n.. desktop-entry-spec: https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys",
+      "description": "Linux-specific instructions.\n\nCheck the `Desktop entry specification\n<https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys>`__\nfor more details.",
       "type": "object",
       "properties": {
         "name": {
@@ -354,7 +354,7 @@
     },
     "MacOS": {
       "title": "MacOS",
-      "description": "Mac-specific instructions. Check these URLs for more info:\n\n- ``CF*`` keys: see `Core Foundation Keys <cf-keys>`_\n- ``LS*`` keys: see `Launch Services Keys <ls-keys>`_\n- ``entitlements``: see `entitlements docs <entitlements-docs>`_\n\n.. _cf-keys: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html\n.. _ls-keys: https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html\n.. _entitlements-docs: https://developer.apple.com/documentation/bundleresources/entitlements.",
+      "description": "Mac-specific instructions. Check these URLs for more info:\n\n- ``CF*`` keys: see `Core Foundation Keys <https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html>`__\n- ``LS*`` keys: see `Launch Services Keys <https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html>`__\n- ``entitlements``: see `Entitlements documentation <https://developer.apple.com/documentation/bundleresources/entitlements>`__",
       "type": "object",
       "properties": {
         "name": {

menuinst/platforms/base.py

@@ -1,5 +1,6 @@
 """
 """
+
 import json
 import os
 import sys

menuinst/platforms/linux.py

@@ -1,5 +1,6 @@
 """
 """
+
 import os
 import shlex
 import shutil

menuinst/platforms/osx.py

@@ -1,5 +1,6 @@
 """
 """
+
 import os
 import platform
 import plistlib

menuinst/platforms/win.py

@@ -1,5 +1,6 @@
 """
 """
+
 import os
 import shutil
 import warnings

menuinst/platforms/win_utils/registry.py

@@ -13,6 +13,7 @@
 
 Mnemonic: SetValueEx for "excalars" (scalars, named values)
 """
+
 import winreg
 from logging import getLogger
 
@@ -44,9 +45,9 @@ def register_file_extension(extension, identifier, command, icon=None, mode="use
                 command/: "the command to be executed when opening a file with this extension"
     """
     with winreg.OpenKeyEx(
-        winreg.HKEY_LOCAL_MACHINE  # HKLM
-        if mode == "system"
-        else winreg.HKEY_CURRENT_USER,  # HKCU
+        (
+            winreg.HKEY_LOCAL_MACHINE if mode == "system" else winreg.HKEY_CURRENT_USER  # HKLM
+        ),  # HKCU
         r"Software\Classes",
     ) as key:
         # First we associate an extension with a handler

news/190-fix-docs-linkx

@@ -0,0 +1,19 @@
+### Enhancements
+
+* <news item>
+
+### Bug fixes
+
+* <news item>
+
+### Deprecations
+
+* <news item>
+
+### Docs
+
+* Fix API Reference hyperlinks. (#190)
+
+### Other
+
+* <news item>

tests/test_api.py

@@ -1,4 +1,5 @@
 """"""
+
 import json
 import os
 import plistlib

tests/test_conda.py

@@ -1,6 +1,7 @@
 """
 Integration tests with conda
 """
+
 import json
 import os
 import sys