Start working on stubs for 2.6.0 (extensions, etc.).

Switch to PyPi trusted publisher.

.github/workflows/default.yml

@@ -1,36 +0,0 @@
-name: Build Documentation
-
-on:
-  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

.github/workflows/documentation.yml

@@ -0,0 +1,39 @@
+name: Build Documentation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - 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: |
+          mkdir -p docs/src
+          cp -r stubs/2.5.2/mobase-stubs docs/src/mobase
+      - 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,40 +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:
-  release:
-    types: [published]
+  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.event.release.tag_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.8'
-    - 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 ../${{ steps.version.outputs.replaced }}/mobase.pyi 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

.gitignore

@@ -2,9 +2,10 @@
 .mypy_cache
 __pycache__
 .vscode
+**/*.egg-info
 
 # The 'bin/' directory:
 bin
 docs/build
 docs/mobase.py
-docs/source/api
+docs/source/api

README.md

@@ -16,23 +16,12 @@ MO2.
 You can install stubs for a specific version of MO2:
 
 ```bash
-pip install mobase-stubs==2.3.2.*
-```
-
-If you want development stubs, you can install them this way:
-```bash
-# Clone this repository:
-git clone https://github.com/ModOrganizer2/pystubs-generation.git
-
-# Install the stubs:
-cd pystubs-generation/stubs/setup
-pip install .
+pip install mobase-stubs==2.5.*
 ```
 
 Some words of warning:
+
 - The stubs are as correct as possible, but some errors are expected.
-- If you see a `InterfaceNotImplemented` class anywhere in the stubs, it means that
-  a proper interface is currently not available.
 - Some classes are said (in the stubs) to inherit `QWidget` or `QObject`. This is true
   on the C++ side but NOT on the python side. The inheritance is only added to help with
   auto-completion since these classes also override `__getattr__` to dispatch to the
@@ -44,35 +33,39 @@ Some words of warning:
 
 The stubs are generated using python by parsing the `mobase` module.
 You need the version of python that matches your current MO2 installation: e.g., if you
-have a `python38.dll` in your MO2 installation path, then you need **Python 3.8**.
+have a `python310.dll` in your MO2 installation path, then you need **Python 3.10**.
 
 To generate the stubs, you can run:
 
-```
-# Change the output folder to whatever you want:
-python main.py -c configs\config-2.4.yml ${MO2_INSTALL_PATH}
+```bash
+# 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}
 ```
 
-Where `${MO2_INSTALL_PATH}` is the path to your MO2 installation (the one containing `ModOrganizer.exe`).
+Where `${MO2_INSTALL_PATH}` is the path to your MO2 installation (the one
+containing `ModOrganizer.exe`).
 
-The stubs are generated under `stubs/setup/mobase-stubs/__init__.pyi`, you
-can change the output file by using the `-o` option
-The latest stubs are kept under `stubs/setup/mobase-stubs/__init__.pyi`,
-and when a new version is released, the stubs are backed-up under
-`stubs/x.y.z/mobase.pyi`.
+The stubs are generated under `stubs/setup/mobase-stubs` by default, you
+can change the output file by using the `-o` option.
+The stubs under `stubs/setup/mobase-stubs` should not be committed as these are
+generated from the version stubs under `stubs/${VERSION}/mobase-stubs`.
 
-A few options are available for `main.py`:
+A few options are available for `mo2-stubs-generator`:
 
-```
-usage: Stubs generator for the MO2 python interface [-h] [-o OUTPUT] [-v] [-c CONFIG] INSTALL_DIR
+```bash
+$ mo2-stubs-generator --help
+usage: stubs generator for the MO2 python interface [-h] [-o OUTPUT] [-v] [-c CONFIG] INSTALL_DIR
 
 positional arguments:
   INSTALL_DIR           installation directory of Mod Organizer 2
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -o OUTPUT, --output OUTPUT
-                        output file (default stubs/setup/mobase-stubs/__init__.pyi)
+                        output folder (default stubs/setup/mobase-stubs)
   -v, --verbose         verbose mode (all logs go to stderr)
   -c CONFIG, --config CONFIG
                         configuration file
@@ -81,19 +74,7 @@ optional arguments:
 The stubs generator will try hard to find a valid stubs for all classes
 and methods of `mobase`.
 A lot of information is available through the `-v` options. Without it,
-only conversions or fixes
-considered "strange" will be shown.
-For instance, here is the output with the current `config-2.4.yml` file:
-
-```
-WARNING: Replacing IOrganizer::FileInfo with FileInfo.
-WARNING: Replacing IOrganizer::FileInfo with FileInfo.
-WARNING: Replacing IPluginInstaller::EInstallResult with InstallResult.
-WARNING: Replacing IPluginInstaller::EInstallResult with InstallResult.
-```
-
-As you can see, only a few types were manually fixed (specified in
-`config-2.4.yml`).
+only conversions or fixes considered "strange" will be shown.
 
 ## Configuration file
 
@@ -102,20 +83,36 @@ deduced by `main` (or are too complex to deduce), and the documentation for ever
 
 ## Uploading the stubs to pypi
 
-The upload of the stubs to https://pypi.org/project/mobase-stubs/ should be
-done automatically when a new Github release is made.
+The upload of the stubs to [https://pypi.org/project/mobase-stubs/](https://pypi.org/project/mobase-stubs/)
+should be done automatically when a new Github tag is pushed.
 
-## Extras — Starts a python interpreter with `mobase`
+## Extras — Using `mobase` in a Python interpreter
 
-It is possible to start a (i)python interpret with `mobase` imported by running:
+It is possible to start a (i)python interpreter with `mobase` imported by running
 
-```
-python -im generator.loader ${MO2_INSTALL_PATH}
+```bash
+python -i -m mo2.stubs.generator.loader ${MO2_INSTALL_PATH}
 ```
 
-This has no real usage except for MO2 developers since most classes from the `mobase` module cannot be instantiated.
+You can also import `mobase` in your code using the following (after installing
+this package):
 
-# License
+```python
+from mo2.stubs.generator import load_mobase
+
+mobase = load_mobase(MO2_INSTALL_PATH)
+
+# the above will probably not give you type-completion in your IDE or typing, so
+# you can use the following (if the stubs are installed)
+load_mobase(MO2_INSTALL_PATH)
+import mobase
+import mobase.widgets
+```
+
+**Note:** Most classes in `mobase` cannot be instantiated, so this is mostly intended
+for MO2 developers.
+
+## License
 
 The MIT License (MIT)
 

configs/config-2.4.yml

@@ -642,7 +642,7 @@ mobase:
           The path to copy the entry to. If the path ends with / or \\, the entry will
           be copied in the corresponding directory instead of replacing it. If the
           given path is empty (`""`), the entry is copied directly under this tree.
-        policy: Policy to use to resolve conflicts.
+        insert_policy: Policy to use to resolve conflicts.
       returns: The new entry (copy of the specified entry).
       raises:
         RuntimeError: If the entry could not be copied.
@@ -2947,7 +2947,7 @@ mobase:
     getMissingAssets:
       __doc__: Retrieve missing assets from the save.
       args:
-        filepath: The save to find missing assets for.
+        save: The save to find missing assets for.
       returns: |
         A collection of missing assets and the modules that can supply those assets.
 
@@ -3095,7 +3095,7 @@ mobase:
       args:
         value: String to parse.
         scheme: Scheme to use to parse the string.
-        manual_input: True if the given string should be treated as user input.
+        is_manual: True if the given string should be treated as user input.
 
     scheme:
       returns: The version scheme in effect for this VersionInfo.

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 +0,0 @@
-sphinx-rtd-theme
-sphinx-autodoc-typehints
-sphinx-automodapi
-PyQt5

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 ---------------------------------------------------
 
@@ -35,8 +27,9 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx_autodoc_typehints",
     "sphinx.ext.napoleon",
+    "autoapi.extension",
     # "sphinx.ext.autosummary",
-    "sphinx_automodapi.automodapi",
+    # "sphinx_automodapi.automodapi",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -47,6 +40,9 @@ templates_path = ["_templates"]
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+autoapi_dirs = ["../src"]
+autoapi_member_order = "groupwise"
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -69,5 +65,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"]

docs/source/index.rst

@@ -18,7 +18,6 @@ This documentation is dedicated to writting MO2 **Python** plugins.
    plugin-types
    writing-plugins
    faq
-   mobase
 
 
 

docs/source/mobase.rst

@@ -1,11 +0,0 @@
-``mobase`` API
-==============
-
-.. currentmodule:: mobase
-
-.. automodapi:: mobase
-   :no-inheritance-diagram:
-   :no-heading:
-
-.. toctree::
-   :maxdepth: 4

docs/source/modules.rst

@@ -1,7 +0,0 @@
-mobase
-======
-
-.. toctree::
-   :maxdepth: 4
-
-   mobase

docs/source/plugin-types.rst

@@ -64,10 +64,8 @@ These plugins (shall eventually) implement all the game specific features and fu
 able to add support for further games.
 The plugin is also responsible to help MO determine if (and where) the game is installed in the first place.
 Since supporting a game properly requires extensions in many places of the UI.
-To allow this without creating one huge plugin interface that involves every aspect of MO, game plugins
-expose a *feature list*.
-The list of possible features can be found in the "game_features" project and each feature can itself be
-considered a plugin interface.
+To allow this without creating one huge plugin interface that involves every aspect of MO,
+game plugins can register only the features they need to MO2 using :meth:`registerFeature<mobase.IGameFeatures.registerFeature>`
 
 As an example for a game feature take BSA invalidation: If the game requires BSA invalidation it will implement
 this feature.
@@ -147,4 +145,4 @@ File Mappings
 
 This interface allows plugins to add virtual file (or directory) links to the virtual file system in addition to the
 mod files.
-Profile-local save games, ini-files and load-orders are all implemented this way in MO2.
+Profile-local save games, ini-files and load-orders are all implemented this way in MO2.

docs/source/setup-tools.rst

@@ -15,7 +15,7 @@ This guide assumes that:
   `Python extension <https://marketplace.visualstudio.com/items?itemName=ms-python.python>`_.
 - You have Python installed: https://www.python.org/downloads/.
 
-  - It is recommended but not mandatory to use the Python version that is used by MO2.
+  - You must use the Python version that used by MO2.
     You can check the ``pythonXX.dll`` in the MO2 installation folder to find the Python version used by MO2 (``python38.dll`` means Python 3.8).
 - You obviously need a valid MO2 installation: https://github.com/modorganizer2/modorganizer/releases
 
@@ -28,8 +28,8 @@ Preparation
 -----------
 
 **Note:** This part is optional but highly recommended if you want a proper environment to work with.
-Everything here is written to be as simple as possible but you can of course adapt it to your preferences: use a python virtual
-environment, use workspace settings instead of global ones, etc.
+Everything here is written to be as simple as possible but you can of course adapt it to your preferences:
+use a python virtual environment, use workspace settings instead of global ones, etc.
 
 1. Get the ``mobase`` stubs
 ...........................
@@ -39,11 +39,14 @@ as ``flake8`` or ``mypy``.
 Instead, we provide `stubs <https://stackoverflow.com/questions/59051631/what-is-the-use-of-stub-files-pyi-in-python>`_
 which can be used for auto-completion or type-checking.
 
-The stubs for ``mobase`` are available at https://github.com/ModOrganizer2/pystubs-generation/tree/master/stubs.
-You want to download the ``mobase.pyi`` file in the folder corresponding to your MO2 version and put it under ``$MO2DIR/plugins/data``.
+You can install the stubs for ``mobase`` using ``pip``:
+
+.. code::
+
+    pip install mobase-stubs
+
+This will install the stubs for ``mobase`` but also for PyQt5, which is heavily used by MO2.
 
-**Note:** It is possible to put the stubs in a different location, but we are going to use ``$MO2DIR/plugins/data`` for PyQt5,
-so we might as well use it for the stubs.
 
 2. Configure Visual Studio Code for ``mobase``
 ..............................................
@@ -57,32 +60,28 @@ Open ``settings.json`` (Ctrl+Shift+P, then "Open Settings (JSON)"), and add the
     "python.linting.enabled": true,
     "python.linting.mypyEnabled": true,
     "python.linting.flake8Enabled": true,
-    "python.autoComplete.extraPaths": [
-        "$MO2DIR\\plugins\\data",
-    ]
 
-3. Configure ``mypy`` to find the ``mobase`` stubs
-..................................................
+3. [Optional] Configure ``black`` to auto-format your source files
+..................................................................
 
-There are multiply way to configure ``mypy``:
+This step is optional for your own plugin but recent MO2 plugins use ``black``
+to get consistent formatting.
 
-1. You can create a ``mypy.ini`` file somewhere containing:
+You can install ``black`` with ``pip``:
 
-.. code-block:: ini
+.. code::
 
-    [mypy]
-    mypy_path = $MO2DIR\plugins\data
+    pip install black flake8-black
 
-And then add the following to ``settings.json`` (with the correct path):
+To configure Visual Studio Code to auto-format your code with ``black`` when saving, open ``settings.json``
+(Ctrl+Shift+P, then "Open Settings (JSON)"), and add the following entries:
 
 .. code-block:: json-object
 
-    "python.linting.mypyArgs": [
-        "--config-file=path-to-mypy.ini",
-    ]
+    "editor.formatOnSave": true,
+    "editor.formatOnPaste": true,
+    "python.formatting.provider": "black",
 
-2. You can set the ``MYPYPATH`` environment variable to ``$MO2DIR\plugins\data`` (this requires
-restarting VS code).
 
 4. [Optional] Automatically reload plugins during development
 .............................................................

generator/__init__.py

@@ -1,9 +0,0 @@
-# -*- encoding: utf-8 -*-
-
-import logging
-import sys
-
-
-logging.basicConfig(stream=sys.stderr, format="%(levelname)s: %(message)s")
-logger = logging.getLogger(__name__)
-logger.setLevel(logging.WARNING)