Update everything to target Python 3.12.

Switch to PyPi trusted publisher.

.github/workflows/default.yml

@@ -1,36 +1,38 @@
 name: Build Documentation
 
 on:
+  pull_request:
   push:
     branches:
       - master
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-      with:
-        persist-credentials: false
-    # Standard drop-in approach that should work for most people.
-    - uses: ammaraskar/sphinx-action@master
-      env:
-        PYTHONPATH: .
-      with:
-        pre-build-command: "apt-get update -y && apt-get install -y libgl1-mesa-glx && cp stubs/2.4.0/mobase.pyi docs/mobase.py"
-        docs-folder: "docs/"
-
-    - name: Install SSH Client 🔑
-      uses: webfactory/ssh-agent@v0.4.1
-      with:
-        ssh-private-key: ${{ secrets.DEPLOY_KEY }}
-
-    - name: Deploy 🚀
-      uses: JamesIves/github-pages-deploy-action@3.7.1
-      with:
-        SSH: true
-        REPOSITORY_NAME: ModOrganizer2/python-plugins-doc
-        BRANCH: master
-        FOLDER: docs/build/html
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.12
+      - uses: abatilo/actions-poetry@v2
+      - name: Install
+        run: |
+          poetry install
+      - name: Install libgl1
+        run: sudo apt install -y libgl1 libegl1 libglib2.0-0 libxkbcommon0 libdbus-1-3
+      - name: Copy stubs
+        run: cp stubs/2.5.0/mobase-stubs/__init__.pyi docs/mobase.py
+      - name: Build
+        run: poetry run sphinx-build -b html docs/source docs/build
+        env:
+          PYTHONPATH: docs
+      - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        name: Deploy Documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          repository-name: ModOrganizer2/python-plugins-doc
+          branch: master
+          folder: docs/build

.github/workflows/linting.yml

@@ -5,20 +5,16 @@ on: [push, pull_request]
 jobs:
   checks:
     runs-on: ubuntu-latest
-    strategy:
-      max-parallel: 4
-      matrix:
-        python-version: [3.8]
-
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install tox
-    - name: Test with tox
-      run: tox -e py38-lint
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.12
+      - uses: abatilo/actions-poetry@v2
+      - name: Install
+        run: |
+          poetry install
+      - name: Lint
+        run: |
+          poetry run poe lint

.github/workflows/pull_request.yml

@@ -1,18 +0,0 @@
-name: Check Documentation
-
-on: [pull_request]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v1
-    # Standard drop-in approach that should work for most people.
-    - uses: ammaraskar/sphinx-action@master
-      env:
-        PYTHONPATH: .
-      with:
-        pre-build-command: "apt-get update -y && apt-get install -y libgl1-mesa-glx && cp stubs/2.4.0/mobase.pyi docs/mobase.py"
-        docs-folder: "docs/"

.github/workflows/pypi-publish.yml

@@ -1,41 +1,57 @@
 # This workflows will upload a Python Package using Twine when a release is created
 # For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
 
-name: Upload Python Package
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
 
 on:
   push:
     tags: ["*"]
 
 jobs:
-  deploy:
-
+  build:
+    name: Build distribution 📦
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Replace string
+        uses: frabert/replace-string-action@v1.1
+        id: version
+        with:
+          string: ${{ github.ref_name }}
+          pattern: "v?([0-9][.][0-9][.][0-9]).*"
+          replace-with: "$1"
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.12
+      - uses: abatilo/actions-poetry@v2
+      - name: Build
+        run: |
+          cd stubs/setup
+          mkdir mobase-stubs
+          cp -r ../${{ steps.version.outputs.replaced }}/mobase-stubs/* mobase-stubs/
+          sed -i 's/__version__ = ".*"/__version__ = "${{ github.ref_name }}"/' mobase-stubs/__init__.pyi
+          TAG=${{ github.ref_name }}
+          poetry version ${TAG#v}
+          poetry build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v3
+        with:
+          name: python-package-distributions
+          path: stubs/setup/dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Replace string
-      uses: frabert/replace-string-action@v1.1
-      id: version
-      with:
-        string: ${{ github.ref_name }}
-        pattern: "v?([0-9][.][0-9][.][0-9]).*"
-        replace-with: "$1"
-    - name: Set up Python
-      uses: actions/setup-python@v2
-      with:
-        python-version: '3.10'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel twine
-    - name: Build and publish
-      env:
-        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
-        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-      run: |
-        cd stubs/setup
-        cp -r ../${{ steps.version.outputs.replaced }}/mobase-stubs/* mobase-stubs/
-        sed -i 's/__version__ = ".*"/__version__ = "${{ github.ref_name }}"/' mobase-stubs/__init__.pyi
-        python setup.py sdist bdist_wheel
-        twine upload dist/*
+      - name: Download all the dists
+        uses: actions/download-artifact@v3
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -16,7 +16,7 @@ MO2.
 You can install stubs for a specific version of MO2:
 
 ```bash
-pip install mobase-stubs==2.3.2.*
+pip install mobase-stubs==2.5.*
 ```
 
 Some words of warning:
@@ -38,8 +38,8 @@ have a `python310.dll` in your MO2 installation path, then you need **Python 3.1
 To generate the stubs, you can run:
 
 ```bash
-# install the package (-e if you want editable mode)
-pip install [-e] .
+# install the package
+poetry install
 
 # change the output folder to whatever you want
 mo2-stubs-generator -c configs/config-2.4.yml -o mobase-stubs ${MO2_INSTALL_PATH}

configs/config-2.5.yml

@@ -114,6 +114,12 @@ mobase:
     DATE:
     LITERAL:
 
+  GameFeature:
+    __doc__: |
+      Base class for all game features, cannot be inherited, used only for typing
+      purpose in Python.
+    __abstract__: true
+
   # TODO:
   BSAInvalidation:
     __doc__:
@@ -255,7 +261,7 @@ mobase:
         type: str
         desc: Full path to the file.
       origins:
-        type: List[str]
+        type: list[str]
         desc: |
           List of origins containing providing this file. The first origin in the list
           is the highest priority one (actually providing the file).
@@ -319,7 +325,7 @@ mobase:
         __doc__: |
           The parent tree containing this entry, or a `None` if this entry is the root
           or the parent tree is unreachable.
-        type: Optional[IFileTree]
+        type: IFileTree | None
 
     path:
       __doc__: |
@@ -349,6 +355,141 @@ mobase:
         The last extension of this entry, or an empty string if the file has no extension
         or is directory.
 
+  IGameFeatures:
+    __doc__: |
+      Interface for the game features, accessible through IOrganizer.gameFeatures().
+
+    gameFeature:
+      __doc__: Retrieve the given game feature, if one exists.
+      abstract: false
+      args:
+        feature_type:
+          __doc__: The class of feature to retrieve.
+          type: Type[GameFeatureType]
+      returns:
+        __doc__: |
+          The game feature corresponding to the given type, or `None` if the feature is
+          not available.
+        type: GameFeatureType
+
+    registerFeature.1:
+      __doc__: |
+        Register game feature for the specified game.
+
+        This method register a game feature to combine or replace with other features
+        of the same kind. Some features are merged (e.g., ModDataContent,
+        ModDataChecker), while other override previous features (e.g., SaveGameInfo).
+
+        For features that can be combined, the priority argument indicates the order of
+        priority (e.g., the order of the checks for ModDataChecker). For other features,
+        the feature with the highest priority will be used. The features provided by the
+        game plugin itself always have lowest priority.
+
+        The feature is associated to the plugin that registers it, if the plugin is
+        disabled, the feature will not be available.
+
+        This function will return True if the feature was registered, even if the
+        feature is not used du to its low priority.
+
+      args:
+        games: Names of the game to enable the feature for.
+        feature: Game feature to register.
+        priority: |
+          Priority of the game feature. If the plugin registering the feature
+          is a game plugin, this parameter is ignored.
+        replace: |
+          If True, remove features of the same kind registered by the current plugin,
+          otherwise add the feature alongside existing ones.
+
+      returns: True if the game feature was properly registered, False otherwise.
+
+    registerFeature.2:
+      __doc__: |
+        Register game feature for the specified game.
+
+        This method register a game feature to combine or replace with other features
+        of the same kind. Some features are merged (e.g., ModDataContent,
+        ModDataChecker), while other override previous features (e.g., SaveGameInfo).
+
+        For features that can be combined, the priority argument indicates the order of
+        priority (e.g., the order of the checks for ModDataChecker). For other features,
+        the feature with the highest priority will be used. The features provided by the
+        game plugin itself always have lowest priority.
+
+        The feature is associated to the plugin that registers it, if the plugin is
+        disabled, the feature will not be available.
+
+        This function will return True if the feature was registered, even if the
+        feature is not used du to its low priority.
+
+      args:
+        game: Game to enable the feature for.
+        feature: Game feature to register.
+        priority: |
+          Priority of the game feature. If the plugin registering the feature
+          is a game plugin, this parameter is ignored.
+        replace: |
+          If True, remove features of the same kind registered by the current plugin,
+          otherwise add the feature alongside existing ones.
+
+      returns: True if the game feature was properly registered, False otherwise.
+
+    registerFeature.3:
+      __doc__: |
+        Register game feature for all games.
+
+        This method register a game feature to combine or replace with other features
+        of the same kind. Some features are merged (e.g., ModDataContent,
+        ModDataChecker), while other override previous features (e.g., SaveGameInfo).
+
+        For features that can be combined, the priority argument indicates the order of
+        priority (e.g., the order of the checks for ModDataChecker). For other features,
+        the feature with the highest priority will be used. The features provided by the
+        game plugin itself always have lowest priority.
+
+        The feature is associated to the plugin that registers it, if the plugin is
+        disabled, the feature will not be available.
+
+        This function will return True if the feature was registered, even if the
+        feature is not used du to its low priority.
+
+      args:
+        feature: Game feature to register.
+        priority: |
+          Priority of the game feature. If the plugin registering the feature
+          is a game plugin, this parameter is ignored.
+        replace: |
+          If True, remove features of the same kind registered by the current plugin,
+          otherwise add the feature alongside existing ones.
+
+      returns: True if the game feature was properly registered, False otherwise.
+
+    unregisterFeature:
+      __doc__: |
+        Unregister the given game feature.
+
+        This function is safe to use even if the given feature was never registered.
+      args:
+        feature: Feature to unregister.
+      returns: True if the feature was successfully unregistered, False otherwise.
+
+    unregisterFeatures:
+      __doc__: |
+        Unregister all features of the given type registered by the calling plugin.
+
+        This function is safe to use even if the plugin has no feature of the given type
+        register.
+
+      args:
+        feature_type:
+          __doc__: The class of feature to unregister.
+          type: Type[GameFeatureType]
+
+      returns: The number of unregistered features.
+
+
+
+
   GamePlugins:
     __abstract__: true
     getLoadOrder:
@@ -356,6 +497,8 @@ mobase:
       returns:
     lightPluginsAreSupported:
       returns: True if light plugins are supported, False otherwise.
+    overridePluginsAreSupported:
+      returns: True if override plugins are supported, False otherwise.
     readPluginLists:
       __doc__:
       args:
@@ -663,7 +806,7 @@ mobase:
         __doc__: |
           The entry at the given location, or `None` if the entry was not found or
           was not of the correct type.
-        type: Optional[Union[IFileTree, FileTreeEntry]]
+        type: IFileTree | FileTreeEntry | None
 
     insert:
       __doc__: |
@@ -1226,7 +1369,7 @@ mobase:
             type: MoVariant
             desc: The data that was included in the request.
           result_data:
-            type: Dict[str, MoVariant]
+            type: dict[str, MoVariant]
             desc: The data included in the response.
 
       filesAvailable:
@@ -1242,7 +1385,7 @@ mobase:
             type: MoVariant
             desc: The data that was included in the request.
           result_data:
-            type: List[ModRepositoryFileInfo]
+            type: list[ModRepositoryFileInfo]
             desc: List of file information objects.
 
       fileInfoAvailable:
@@ -1269,7 +1412,7 @@ mobase:
             type: MoVariant
             desc: The data that was included in the request.
           result_data:
-            type: Dict[str, MoVariant]
+            type: dict[str, MoVariant]
             desc: The data included in the response.
 
       downloadURLsAvailable:
@@ -1291,7 +1434,7 @@ mobase:
             type: MoVariant
             desc: The data that was included in the request.
           result_data:
-            type: Dict[str, MoVariant]
+            type: dict[str, MoVariant]
             desc: The data included in the response.
 
       endorsementsAvailable:
@@ -1474,6 +1617,9 @@ mobase:
         pattern: The glob pattern to use to filter files.
       returns: The list of matching files.
 
+    gameFeatures:
+      returns: The interface to the game features.
+
     getFileOrigins:
       __doc__: |
         Retrieve the file origins for the specified file.
@@ -1529,17 +1675,36 @@ mobase:
     modsPath:
       returns: The (absolute) path to the mods directory.
 
-    onAboutToRun:
+    onAboutToRun.1:
       __doc__: |
         Install a new handler to be called when an application is about to run.
 
-        Multiple handlers can be installed. If any of the handler returns `False`, the application will
-        not run.
+        Multiple handlers can be installed. If any of the handler returns `False`, the
+        application will not run.
       args:
         callback: |
-          The function to call when an application is about to run. The parameter is the absolute path
-          to the application to run. The function can return False to prevent the application from running.
-      returns: True if the handler was installed properly (there are currently no reasons for this to fail).
+          The function to call when an application is about to run. The function
+          receives the absolute path to the application to run, the working directory
+          for the run and a string containing the arguments passed to the executable.
+          The function can return False to prevent the application from running.
+      returns: |
+        True if the handler was installed properly (there are currently no
+        reasons for this to fail).
+
+    onAboutToRun.2:
+      __doc__: |
+        Install a new handler to be called when an application is about to run.
+
+        Multiple handlers can be installed. If any of the handler returns `False`, the
+        application will not run.
+      args:
+        callback: |
+          The function to call when an application is about to run. The parameter
+          is the absolute path to the application to run. The function can return False
+          to prevent the application from running.
+      returns: |
+        True if the handler was installed properly (there are currently no reasons for
+        this to fail).
 
     onFinishedRun:
       __doc__: Install a new handler to be called when an application has finished running.
@@ -1547,7 +1712,19 @@ mobase:
         callback: |
           The function to call when an application has finished running. The first parameter is the absolute
           path to the application, and the second parameter is the exit code of the application.
-      returns: True if the handler was installed properly (there are currently no reasons for this to fail).
+      returns: |
+        True if the handler was installed properly (there are currently no reasons for
+        this to fail).
+
+    onNextRefresh:
+      __doc__: Install a new handler to be called on the next refresh or immediately.
+      args:
+        callback: Function to call on the next refresh (or immediately).
+        immediate_if_possible: |
+          If True, immediately run the callback if no refresh is currently running.
+      returns: |
+        True if the handler was installed properly (there are currently no reasons for
+        this to fail).
 
     onPluginDisabled.1:
       __doc__: Install a new handler to be called when a plugin is disabled.
@@ -1949,9 +2126,11 @@ mobase:
         See `IPlugin.init()` for more.
 
     CCPlugins:
+      abstract: false
       returns: The current list of active Creation Club plugins.
 
     DLCPlugins:
+      abstract: false
       returns: The list of esp/esm files that are part of known DLCs.
 
     binaryName:
@@ -1960,38 +2139,24 @@ mobase:
     dataDirectory:
       returns: The path to the directory containing data (absolute path).
 
+    displayGameName:
+      abstract: False
+      returns: The name of the game to user for display, default to gameName().
+
     documentsDirectory:
       returns: The directory of the documents folder where configuration files and such for this game reside.
 
+    enabledPlugins:
+      abstract: false
+      returns: A list of plugins enabled by the game but not in a strict load order.
+
     executableForcedLoads:
       returns: A list of automatically discovered libraries that can be force loaded with executables.
 
     executables:
+      abstract: false
       returns: A list of automatically discovered executables of the game itself and tools surrounding it.
 
-    feature:
-      __doc__: Retrieve a specified game feature from this plugin.
-      abstract: false
-      args:
-        feature_type:
-          __doc__: The class of feature to retrieve.
-          type: Type[GameFeatureType]
-      returns:
-        __doc__: |
-          The game feature corresponding to the given type, or `None` if the feature is
-          not implemented.
-        type: GameFeatureType
-
-    featureList:
-      __doc__: |
-        Retrieve the list of game features implemented for this plugin.
-
-        Python plugin should not implement this method but `_featureList()`.
-      abstract: false
-      returns:
-        __doc__: A mapping from feature type to actual game features.
-        type: Dict[Type[GameFeatureType], GameFeatureType]
-
     gameDirectory:
       returns: The directory containing the game installation.
 
@@ -1999,15 +2164,17 @@ mobase:
       returns: The icon representing the game.
 
     gameName:
-      returns: The name of the game (as displayed to the user).
+      returns: The name of the game (for internal usage).
 
     gameNexusName:
+      abstract: false
       returns: The name of the game identifier for Nexus.
 
     gameShortName:
       returns: The short name of the game.
 
     gameVariants:
+      abstract: false
       __doc__: |
         Retrieve the list of variants for this game.
 
@@ -2028,6 +2195,7 @@ mobase:
       returns: An URL for the support page of this game.
 
     iniFiles:
+      abstract: false
       returns: |
         The list of INI files this game uses. The first file in the list should be the
         'main' INI file.
@@ -2055,6 +2223,7 @@ mobase:
       returns: The list of game saves in the given folder.
 
     loadOrderMechanism:
+      abstract: false
       returns: The load order mechanism used by this game.
 
     looksValid:
@@ -2063,6 +2232,11 @@ mobase:
         directory: Directory to check.
       returns: True if the directory looks like a valid installation of this game, False otherwise.
 
+    lootGameName:
+      abstract: False
+      returns: |
+        The game name to use when calling LOOT from MO2, default to gameShortName().
+
     nexusGameID:
       __doc__: |
         Retrieve the Nexus game ID for this game.
@@ -2071,6 +2245,7 @@ mobase:
       returns: The Nexus game ID for this game.
 
     nexusModOrganizerID:
+      abstract: false
       __doc__: |
         Retrieve the Nexus mod ID of Mod Organizer for this game.
 
@@ -2079,9 +2254,11 @@ mobase:
       returns: The Nexus mod ID of Mod Organizer for this game.
 
     primaryPlugins:
+      abstract: false
       returns: The list of plugins that are part of the game and not considered optional.
 
     primarySources:
+      abstract: false
       __doc__: |
         Retrieve primary alternative 'short' names for this game.
 
@@ -2092,6 +2269,14 @@ mobase:
     savesDirectory:
       returns: The directory where save games are stored.
 
+    secondaryDataDirectories:
+      abstract: false
+      __doc__: |
+        Retrieve the list of secondary data directories. Each directories should be
+        assigned a unique name that differs from "data" which is the name of the main
+        data directory returned by dataDirectory().
+      returns: A mapping from unique name to secondary data directories.
+
     setGamePath:
       __doc__: |
         Set the path to the managed game.
@@ -2112,9 +2297,11 @@ mobase:
         variant: The game variant selected by the user.
 
     sortMechanism:
+      abstract: false
       returns: The sort mechanism for this game.
 
     steamAPPId:
+      abstract: false
       __doc__: |
         Retrieve the Steam app ID for this game.
 
@@ -2331,6 +2518,16 @@ mobase:
         True if the given file has a .esm extension, False otherwise or if the
         file does not exist.
 
+    hasNoRecords:
+      __doc__: |
+        Determine if a plugin has no records.
+      args:
+        name: Filename of the plugin (without path but with file extension).
+      returns: |
+        True if the given file plugin contains no records, False if it does OR if the
+        file does not exist.
+
+
     isLightFlagged:
       __doc__: |
         Determine if a plugin is flagged as light
@@ -2343,6 +2540,18 @@ mobase:
         True if the given plugin is a light plugin, False otherwise or if the
         file does not exist.
 
+    isOverlayFlagged:
+      __doc__: |
+        Determine if a plugin is flagged as overlay
+
+        This plugin flag was added in Starfield and signifies plugin records that
+        update existing records
+      args:
+        name: Filename of the plugin (without path but with file extension).
+      returns: |
+        True if the given plugin is an overlay plugin, False otherwise or if the
+        file does not exist.
+
     hasLightExtension:
       __doc__: |
         Determine if a plugin has a .esl extension.
@@ -2788,7 +2997,7 @@ mobase:
         filetree: The tree to try to fix. Can be modified during the process.
       returns:
         __doc__: The fixed tree, or a null pointer if the tree could not be fixed.
-        type: Optional["IFileTree"]
+        type: IFileTree | None
 
   ModDataContent:
     __doc__: |
@@ -2998,7 +3207,7 @@ mobase:
         parent: The parent widget.
       returns:
         __doc__: A SaveGameInfoWidget to display information about save game.
-        type: Optional[ISaveGameInfoWidget]
+        type: ISaveGameInfoWidget | None
 
   ScriptExtender:
     __doc__:
@@ -3175,7 +3384,7 @@ mobase.widgets:
         Display this dialog and wait for user-interaction to return. This is a blocking
         function.
 
-      returns:
+      returns: |
         The button clicked by the user. Without custom buttons, this return Ok,
         otherwise it returns the button set in the TaskDialogButton.
 

docs/Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs/requirements.txt

@@ -1,4 +1,4 @@
 sphinx-rtd-theme
 sphinx-autodoc-typehints
 sphinx-automodapi
-PyQt5
+PyQt6

docs/source/conf.py

@@ -10,21 +10,13 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath("../../stubs/2.4.0/"))
-
 
 # -- Project information -----------------------------------------------------
 
 project = "MO2 Python Plugin API"
-copyright = "2020, Holt59"
+copyright = "2023, Holt59"
 author = "Holt59"
 
-# The full version, including alpha/beta/rc tags
-release = "2.3rc1"
-
 
 # -- General configuration ---------------------------------------------------
 
@@ -69,5 +61,5 @@ html_favicon = "mo2.ico"
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 html_extra_path = [".nojekyll"]

pyproject.toml

@@ -0,0 +1,55 @@
+[tool.poetry]
+name = "mo2-pystubs-generation"
+version = "0.1.0"
+description = ""
+authors = ["Holt59 <capelle.mikael@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "mo2", from = "src" }]
+
+[tool.poetry.scripts]
+mo2-stubs-generator = "mo2.stubs.generator.__main__:main"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+pyqt6 = "^6.7.0"
+pyyaml = "^6.0.1"
+
+[tool.poetry.group.dev.dependencies]
+pyright = "^1.1.365"
+ruff = "^0.4.7"
+types-pyyaml = "^6.0.12.20240311"
+poethepoet = "^0.26.1"
+
+[tool.poetry.group.doc.dependencies]
+sphinx-rtd-theme = "^2.0.0"
+sphinx-autodoc-typehints = "^2.1.0"
+sphinx-automodapi = "^0.16.0"
+sphinx = "^7.3.7"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poe.tasks]
+format-imports = "ruff check --select I src --fix"
+format-ruff = "ruff format src"
+format.sequence = ["format-imports", "format-ruff"]
+lint-ruff = "ruff check src"
+lint-ruff-format = "ruff format --check src"
+lint-pyright = "pyright src"
+lint.sequence = ["lint-ruff", "lint-ruff-format", "lint-pyright"]
+lint.ignore_fail = "return_non_zero"
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+extend-select = ["B", "Q", "I"]
+
+[tool.ruff.lint.isort]
+known-first-party = ['tas']
+
+[tool.pyright]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = true

setup.cfg

@@ -1,40 +0,0 @@
-[flake8]
-# Use black line length:
-max-line-length = 88
-extend-ignore =
-    # See https://github.com/PyCQA/pycodestyle/issues/373
-    E203,
-per-file-ignores =
-  *.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F822
-  # Since typing.pyi defines "overload" this is not recognized by flake8 as typing.overload.
-  # Unfortunately, flake8 does not allow to "noqa" just a specific error inside the file itself.
-  typing.pyi: E301, E302, E305, E501, E701, E741, F401, F403, F405, F811, F822
-
-[mypy]
-warn_return_any = True
-warn_unused_configs = True
-namespace_packages = True
-
-[isort]
-profile = black
-multi_line_output = 3
-
-[tox:tox]
-skipsdist = true
-envlist = py310-lint
-
-[testenv:py310-lint]
-skip_install = true
-deps =
-    black
-    mypy
-    flake8
-    flake8-black
-    git+https://github.com/TilmanK/PyQt6-stubs.git
-    types-PyYAML
-    isort
-commands =
-    black src --check --diff
-    flake8 src
-    mypy src
-    isort -c src

setup.py

@@ -1,35 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-from setuptools import find_namespace_packages, setup
-
-install_requires = ["black", "isort"]
-
-dev_requires = [
-    "black",
-    "flake8-black",
-    "flake8",
-    "types-chardet",
-]
-
-setup(
-    name="mo2-stubs-generator",
-    version="1.0.0",
-    package_dir={"": "src"},
-    packages=find_namespace_packages(where="src", include=["mo2.*"]),
-    author="Holt59",
-    author_email="capelle.mikael@gmail",
-    description="Python stubs generator for mobase (MO2 Python API).",
-    long_description=open("README.md").read(),
-    url="https://github.com/ModOrganizer2/pystubs-generation",
-    classifiers=[
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.10",
-    ],
-    license="MIT",
-    install_requires=install_requires,
-    extras_require={"dev": dev_requires},
-    entry_points={
-        "console_scripts": ["mo2-stubs-generator=mo2.stubs.generator.__main__:main"],
-    },
-)

src/mo2/stubs/generator/__init__.py

@@ -1,7 +1,7 @@
-# -*- encoding: utf-8 -*-
-
 import logging
 
+from .loader import load_mobase
+
 LOGGER = logging.getLogger(__name__)
 
-from .loader import load_mobase  # noqa: F401
+__all__ = ["load_mobase", "LOGGER"]

src/mo2/stubs/generator/__main__.py

@@ -1,16 +1,12 @@
-# -*- encoding: utf-8 -*-
-
 import argparse
 import inspect
 import logging
+import subprocess
 import types
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Callable
 
-import black
-import isort
-
-from . import LOGGER
 from .loader import load_mobase
 from .mtypes import Class, PyTyping
 from .parser import is_enum
@@ -18,10 +14,13 @@ from .register import MobaseRegister
 from .utils import Settings, clean_class
 from .writer import Writer, is_list_of_functions
 
+LOGGER = logging.getLogger(__package__)
 
-def extract_objects(module: object, skips: list[str] = []) -> list[tuple[str, object]]:
 
-    objects: list[tuple[str, object]] = []
+def extract_objects(
+    module: object, skips: Sequence[str] = []
+) -> list[tuple[str, type]]:
+    objects: list[tuple[str, type]] = []
 
     assert hasattr(module, "__name__")
     module_name: str = module.__name__  # type: ignore
@@ -55,16 +54,12 @@ def add_mobase_header(writer: Writer):
             (
                 "typing",
                 [
-                    "Any",
                     "Callable",
                     "Dict",
                     "Iterator",
-                    "List",
                     "Optional",
                     "overload",
                     "Sequence",
-                    "Set",
-                    "Tuple",
                     "Type",
                     "TypeVar",
                     "Union",
@@ -91,8 +86,7 @@ def add_mobase_widgets_header(writer: Writer):
     )
 
 
-def main():
-
+def main() -> None:
     parser = argparse.ArgumentParser("stubs generator for the MO2 python interface")
     parser.add_argument(
         "install_dir",
@@ -146,7 +140,7 @@ def main():
     }
 
     # list of objects directly in mobase
-    module_objects: dict[str, list[tuple[str, object]]] = {
+    module_objects: dict[str, list[tuple[str, type]]] = {
         "mobase": extract_objects(
             mobase,
             [
@@ -154,11 +148,10 @@ def main():
                 "IPlugin",
             ],
         ),
-        "mobase.widgets": extract_objects(mobase.widgets),
+        "mobase.widgets": extract_objects(mobase.widgets),  # type: ignore
     }
 
     for name, objects in module_objects.items():
-
         # load settings from the configuration
         settings: Settings = Settings(register)
         if config_path is not None:
@@ -175,12 +168,10 @@ def main():
 
         # Process everything:
         for n, o in objects:
-
             # Create the corresponding object:
             c = register.make_object(n, o)
 
             if isinstance(c, Class):
-
                 # Clean the class (e.g., remove duplicates methods due to wrappers):
                 clean_class(c)
 
@@ -209,7 +200,6 @@ def main():
 
         # write everything
         with open(output_folder.joinpath("__init__.pyi"), "w") as output:
-
             writer = Writer(package=name, output=output, settings=settings)
 
             # the __future__ import must be at the beginning
@@ -218,20 +208,31 @@ def main():
 
             module_headers[name](writer)
 
-            for n, o in objects:
-
+            for n, _o in objects:
                 # Get the corresponding object:
                 c = register.get_object(n)
 
                 writer.print_object(c)
 
-        black.format_file_in_place(
-            output_folder.joinpath("__init__.pyi"),
-            fast=False,
-            mode=black.Mode(is_pyi=True),
-            write_back=black.WriteBack.YES,
+        subprocess.run(
+            [
+                "ruff",
+                "--silent",
+                "format",
+                output_folder.joinpath("__init__.pyi").as_posix(),
+            ]
+        )
+        subprocess.run(
+            [
+                "ruff",
+                "--silent",
+                "check",
+                "--select",
+                "I",
+                "--fix",
+                output_folder.joinpath("__init__.pyi").as_posix(),
+            ]
         )
-        isort.api.sort_file(output_folder.joinpath("__init__.pyi"))
 
 
 if __name__ == "__main__":

src/mo2/stubs/generator/loader.py

@@ -1,12 +1,11 @@
-# -*- encoding: utf-8 -*-
-
 import os
 import sys
 from modulefinder import Module
 from pathlib import Path
+from typing import Any
 
 
-def load_mobase(path: os.PathLike) -> Module:
+def load_mobase(path: os.PathLike[Any]) -> Module:
     """
     Load the mobase from the given MO2 installation path and
     returns it.
@@ -30,8 +29,8 @@ def load_mobase(path: os.PathLike) -> Module:
             [str(path), str(path.joinpath("dlls")), os.environ.get("PATH", "")]
         )
     else:
-        os.add_dll_directory(str(path))
-        os.add_dll_directory(str(path.joinpath("dlls")))
+        os.add_dll_directory(str(path))  # type: ignore
+        os.add_dll_directory(str(path.joinpath("dlls")))  # type: ignore
 
     # We need to add plugins/data to sys.path, mainly for PyQt6
     sys.path.insert(1, path.joinpath("plugins", "plugin_python", "libs").as_posix())
@@ -42,7 +41,6 @@ def load_mobase(path: os.PathLike) -> Module:
 
 
 if __name__ == "__main__":
-
     import argparse
 
     parser = argparse.ArgumentParser(

src/mo2/stubs/generator/mtypes.py

@@ -1,8 +1,7 @@
-# -*- encoding: utf-8 -*-
-
 from __future__ import annotations
 
 import re
+from collections.abc import Sequence
 from typing import Final, TypeVar
 
 
@@ -11,15 +10,6 @@ class PyType:
     Class representing a python type.
     """
 
-    # The `MoVariant` actual type - This should be list["MoVariant"] and
-    # Dict[str, "MoVariant"], but mypy (and other type checkers) do not
-    # handle recursive definition yet:
-    MO_VARIANT = """Union[None, bool, int, str, list[Any], dict[str, Any]]"""
-
-    # File/Directory wrappers
-    FILE_WRAPPER = """Union[str, PyQt6.QtCore.QFileInfo, Path]"""
-    DIRECTORY_WRAPPER = """Union[str, PyQt6.QtCore.QDir, Path]"""
-
     name: str
 
     def __init__(self, name: str | type):
@@ -48,6 +38,9 @@ class PyType:
         if self.name == "mobase.IPluginBase":
             return "IPlugin"
 
+        # PathLike should be [] in the stubs
+        self.name = self.name.replace("os.PathLike", "os.PathLike[str]")
+
         return self.name
 
     def is_none(self) -> bool:
@@ -128,7 +121,6 @@ class Argument:
 
     @property
     def value(self) -> str | None:
-
         value = self._value
 
         if value is None:
@@ -173,7 +165,6 @@ class Argument:
 
 
 class Exception:
-
     """
     Small class representing exception that can be raised from functions.
     """
@@ -322,20 +313,20 @@ class Class:
         self,
         package: str,
         name: str,
-        bases: list[Class],
-        methods: list[Method],
-        constants: list[Constant] = [],
-        properties: list[Property] = [],
-        inner_classes: list[Class] = [],
+        bases: Sequence[Class],
+        methods: Sequence[Method],
+        constants: Sequence[Constant] = [],
+        properties: Sequence[Property] = [],
+        inner_classes: Sequence[Class] = [],
         doc: str = "",
     ):
         self.package = package
         self.name = name
-        self.bases = bases
-        self.methods = methods
-        self.properties = properties
-        self.constants = constants
-        self.inner_classes = inner_classes
+        self.bases = list(bases)
+        self.methods = list(methods)
+        self.properties = list(properties)
+        self.constants = list(constants)
+        self.inner_classes = list(inner_classes)
         self.doc = ""
         self.abstract = False
         self.outer_class = None
@@ -347,7 +338,7 @@ class Class:
         for ic in self.inner_classes:
             ic.outer_class = self
 
-    def is_abstract(self):
+    def is_abstract(self) -> bool:
         """
         Returns:
             True if this class is abstract, False otherwise.
@@ -355,7 +346,7 @@ class Class:
         return self.abstract or any(bc.is_abstract() for bc in self.bases)
 
     @property
-    def canonical_name(self):
+    def canonical_name(self) -> str:
         """
         Returns:
             The canonical name of this class.
@@ -363,13 +354,13 @@ class Class:
         name = self.name
         oc = self.outer_class
         while oc is not None:
-            name = "{}.{}".format(oc.name, name)
+            name = f"{oc.name}.{name}"
             oc = oc.outer_class
 
         return name
 
     @property
-    def full_name(self):
+    def full_name(self) -> str:
         """
         Returns:
             The full name of this class, i.e., package.canonical_name.
@@ -394,7 +385,6 @@ class Class:
 
 
 class PyClass(Class):
-
     """
     Class use to wrap Python class to be used as parent class for some classes
     in mobase.
@@ -410,7 +400,6 @@ class PyClass(Class):
 
 
 class Enum(Class):
-
     """
     Class representing an enum.
     """

src/mo2/stubs/generator/parser.py

@@ -1,13 +1,11 @@
-# -*- encoding: utf-8 -*-
-
 import inspect
+import logging
 import re
 import types
 from collections import OrderedDict, defaultdict
 from itertools import chain
-from typing import Iterable, cast
+from typing import Any, Iterable, cast
 
-from . import LOGGER
 from .mtypes import (
     Argument,
     Class,
@@ -22,8 +20,12 @@ from .mtypes import (
 )
 from .register import MobaseRegister
 
+LOGGER = logging.getLogger(__package__)
 
-def magic_split(value: str, sep=",", open="(<[", close=")>]"):
+
+def magic_split(
+    value: str, sep: str = ",", open: str = "(<[", close: str = ")>]"
+) -> list[str]:
     """
     Split the value according to the given separator, but keeps together elements
     within the given separator. Useful to split C++ signature function since type names
@@ -42,8 +44,8 @@ def magic_split(value: str, sep=",", open="(<[", close=")>]"):
     Returns: The list of split parts from value.
     """
     i, j = 0, 0
-    s: list[str] = []
-    r = []
+    s: list[int] = []
+    r: list[str] = []
     while i < len(value):
         j = i + 1
         while j < len(value):
@@ -96,8 +98,8 @@ def parse_python_signature(s: str, name: str) -> tuple[PyType, list[Argument]]:
     args = magic_split(m.group(1).strip(), ",", open="[", close="]")
     return_type = m.group(2)
 
-    arguments = []
-    for i, pa in enumerate(args):
+    arguments: list[Argument] = []
+    for pa in args:
         m = re.search(
             r"(?P<name>[^:]+)\s*:\s*(?P<type>[^=]+)\s*(=\s*(?P<value>[^,]+))?",
             pa.strip(),
@@ -106,9 +108,12 @@ def parse_python_signature(s: str, name: str) -> tuple[PyType, list[Argument]]:
             raise ValueError(f"invalid argument: {pa}, {s}")
 
         matches = m.groupdict()
-        arguments.append(
-            Argument(matches["name"], PyType(matches["type"]), matches["value"])
-        )
+        type_ = matches["type"]
+        if matches["value"] == "None":
+            if "None" not in type_ and "MoVariant" not in type_:
+                type_ = type_ + " | None"
+
+        arguments.append(Argument(matches["name"], PyType(type_), matches["value"]))
 
     return PyType(return_type), arguments
 
@@ -129,7 +134,6 @@ def is_enum(e: type) -> bool:
 
 
 class Overload:
-
     """Small class to avoid mypy issues..."""
 
     return_type: PyType
@@ -140,7 +144,7 @@ class Overload:
         self.arguments = arguments
 
 
-def parse_pybind11_function_docstring(e) -> list[Overload]:
+def parse_pybind11_function_docstring(e: type) -> list[Overload]:
     """
     Parse the docstring of the given element.
 
@@ -150,7 +154,7 @@ def parse_pybind11_function_docstring(e) -> list[Overload]:
     Returns:
         A list of overloads for the given function.
     """
-    lines = e.__doc__.strip().split("\n")
+    lines = (e.__doc__ or "").strip().split("\n")
 
     signatures: list[str]
     if len(lines) == 1:
@@ -166,20 +170,19 @@ def parse_pybind11_function_docstring(e) -> list[Overload]:
     # them...
     overloads: list[Overload] = []
     for signature in signatures:
-
         # fix MOBase:: in some places to get proper Python types
         signature = signature.replace("MOBase::", "mobase.").replace("::", ".")
 
         try:
             return_type, arguments = parse_python_signature(signature, e.__name__)
-        except ValueError:
-            raise ValueError(f"invalid signature: {e.__name__}, {e.__doc__}")
+        except ValueError as err:
+            raise ValueError(f"invalid signature: {e.__name__}, {e.__doc__}") from err
         overloads.append(Overload(return_type=return_type, arguments=arguments))
 
     return overloads
 
 
-def make_functions(e) -> list[Function]:
+def make_functions(e: type) -> list[Function]:
     overloads = parse_pybind11_function_docstring(e)
 
     return [
@@ -217,7 +220,8 @@ def make_class(e: type, register: MobaseRegister) -> Class:
 
     # This contains ALL the parent classes, not the direct ones:
     base_classes: list[Class] = [
-        register.make_object(name) for name in base_classes_s  # type: ignore
+        register.make_object(name)
+        for name in base_classes_s  # type: ignore
     ]
 
     # retrieve all the attributes that are not in a base class
@@ -310,7 +314,9 @@ def make_class(e: type, register: MobaseRegister) -> Class:
                     for base_class in base_classes:
                         for biclass in base_class.inner_classes:
                             if isinstance(biclass, Enum) and biclass.name == base_name:
-                                arg._value = base_class.name + "." + value
+                                arg._value = (  # pyright: ignore[reportPrivateUsage]
+                                    base_class.name + "." + value
+                                )
 
             methods.append(
                 Method(
@@ -323,8 +329,8 @@ def make_class(e: type, register: MobaseRegister) -> Class:
             )
 
     # Retrieve the attributes:
-    constants = []
-    properties = []
+    constants: list[Constant] = []
+    properties: list[Property] = []
     for name, attr in all_attrs:
         if callable(attr) or isinstance(attr, type):
             continue
@@ -341,7 +347,9 @@ def make_class(e: type, register: MobaseRegister) -> Class:
     direct_bases: list[Class] = []
     for c in e.__bases__:
         if c.__module__ != "pybind11_builtins":
-            direct_bases.append(register.get_object(c.__name__))
+            b = register.get_object(c.__name__)
+            assert isinstance(b, Class)
+            direct_bases.append(b)
 
     # Forcing QWidget base for XWidget classes since these do not show up
     # and we use a trick:
@@ -356,7 +364,7 @@ def make_class(e: type, register: MobaseRegister) -> Class:
     # check if it an enum
     if is_enum(e):
         # all pybind11 enums have a .__entries attribute
-        values = e.__entries  # type: ignore
+        values = cast(dict[str, tuple[int, Any]], e.__entries)  # type: ignore
 
         # drop the __init__
         methods = [m for m in methods if m.name != "__init__"]

src/mo2/stubs/generator/register.py

@@ -12,16 +12,18 @@ class MobaseRegister:
     Class that register classes.
     """
 
-    objects: dict[str, Class | list[Function]]
+    objects: dict[str, Class | list[Function] | PyTyping]
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.raw_objects: dict[str, type] = OrderedDict()
         self.objects = {}
 
-    def add_object(self, name, object):
+    def add_object(self, name: str, object: type) -> None:
         self.raw_objects[name] = object
 
-    def make_object(self, name: str, e: type | None = None) -> Class | list[Function]:
+    def make_object(
+        self, name: str, e: type | None = None
+    ) -> Class | list[Function] | PyTyping:
         """
         Construct a Function, Class or Enum for the given object.
 
@@ -52,7 +54,7 @@ class MobaseRegister:
 
         return self.objects[name]
 
-    def get_object(self, name: str):
+    def get_object(self, name: str) -> Class | list[Function] | PyTyping:
         """
         Retrieve the object if the given name. Fails if no object with this
         name exists (if `make_object(name, ...)` has never been called).