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

Switch to PyPi trusted publisher.

.github/workflows/documentation.yml

@@ -15,15 +15,16 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.11
+          python-version: 3.12
       - uses: abatilo/actions-poetry@v2
       - name: Install
-        run: |
-          poetry 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
+        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:

.github/workflows/linting.yml

@@ -10,15 +10,11 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.11
+          python-version: 3.12
       - uses: abatilo/actions-poetry@v2
       - name: Install
         run: |
           poetry install
       - name: Lint
         run: |
-          poetry run black src --check --diff
-          poetry run isort -c src
-          poetry run mypy src
-          poetry run ruff src
-          poetry run pyright src
+          poetry run poe lint

.github/workflows/pypi-publish.yml

@@ -1,16 +1,16 @@
 # 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
@@ -20,21 +20,38 @@ jobs:
           string: ${{ github.ref_name }}
           pattern: "v?([0-9][.][0-9][.][0-9]).*"
           replace-with: "$1"
-      - name: Set up Python
-        uses: actions/setup-python@v2
+      - uses: actions/setup-python@v2
         with:
-          python-version: "3.11"
-      - 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 }}
+          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
-          python setup.py sdist bdist_wheel
-          twine upload dist/*
+          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:
+      - 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

@@ -109,7 +109,6 @@ import mobase
 import mobase.widgets
 ```
 
-
 **Note:** Most classes in `mobase` cannot be instantiated, so this is mostly intended
 for MO2 developers.
 

docs/requirements.txt

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

docs/source/conf.py

@@ -27,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.
@@ -39,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 -------------------------------------------------
 

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.

pyproject.toml

@@ -11,51 +11,44 @@ packages = [{ include = "mo2", from = "src" }]
 mo2-stubs-generator = "mo2.stubs.generator.__main__:main"
 
 [tool.poetry.dependencies]
-python = "^3.11"
-pyqt6 = "^6.5.2"
+python = "^3.12"
+pyqt6 = "6.7.1"
 pyyaml = "^6.0.1"
-
+typing-extensions = "^4.12.2"
 
 [tool.poetry.group.dev.dependencies]
-black = "^23.9.1"
-mypy = "^1.5.1"
-pyright = "^1.1.327"
-isort = "^5.12.0"
-ruff = "^0.0.290"
-flake8 = "^6.1.0"
-flake8-black = "^0.3.6"
-flake8-pyproject = "^1.2.3"
-types-pyyaml = "^6.0.12.11"
-
+pyright = "^1.1.374"
+ruff = "^0.5.5"
+types-pyyaml = "^6.0.12.20240724"
+poethepoet = "^0.27.0"
 
 [tool.poetry.group.doc.dependencies]
-sphinx-rtd-theme = "^1.3.0"
-sphinx-autodoc-typehints = "^1.24.0"
-sphinx-automodapi = "^0.16.0"
-sphinx = "^7.2.6"
+sphinx-rtd-theme = "^2.0.0"
+sphinx-autodoc-typehints = "^2.2.3"
+sphinx-automodapi = "^0.17.0"
+sphinx = "<8"
+sphinx-autoapi = "^3.2.1"
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
-[tool.flake8]
-max-line-length = 88
-extend-ignore = ["E203"]
-
-[tool.isort]
-profile = "black"
-multi_line_output = 3
+[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]
-line-length = 88
-target-version = "py311"
+target-version = "py310"
 
-[tool.mypy]
-warn_return_any = true
-warn_unused_configs = true
-namespace_packages = true
+[tool.ruff.lint]
+extend-select = ["B", "Q", "I"]
 
 [tool.pyright]
-# reportMissingTypeStubs = true
-# reportUntypedBaseClass = false
 typeCheckingMode = "strict"
+reportMissingTypeStubs = true

src/mo2/stubs/generator/__main__.py

@@ -1,15 +1,14 @@
 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 .loader import load_mobase
-from .mtypes import Class, PyTyping
+from .mtypes import Class, Constant, Enum, Function, PyTyping
 from .parser import is_enum
 from .register import MobaseRegister
 from .utils import Settings, clean_class
@@ -18,7 +17,9 @@ from .writer import Writer, is_list_of_functions
 LOGGER = logging.getLogger(__package__)
 
 
-def extract_objects(module: object, skips: list[str] = []) -> list[tuple[str, type]]:
+def extract_objects(
+    module: object, skips: Sequence[str] = []
+) -> list[tuple[str, type]]:
     objects: list[tuple[str, type]] = []
 
     assert hasattr(module, "__name__")
@@ -56,12 +57,9 @@ def add_mobase_header(writer: Writer):
                     "Callable",
                     "Dict",
                     "Iterator",
-                    "List",
                     "Optional",
                     "overload",
                     "Sequence",
-                    "Set",
-                    "Tuple",
                     "Type",
                     "TypeVar",
                     "Union",
@@ -148,9 +146,12 @@ def main() -> None:
             [
                 # the "real" IPlugin is IPluginBase
                 "IPlugin",
+
+                # this is deprecated
+                "PluginSetting"
             ],
         ),
-        "mobase.widgets": extract_objects(getattr(mobase, "widgets")),
+        "mobase.widgets": extract_objects(mobase.widgets),  # type: ignore
     }
 
     for name, objects in module_objects.items():
@@ -173,6 +174,10 @@ def main() -> None:
             # Create the corresponding object:
             c = register.make_object(n, o)
 
+
+        for n, o in objects:
+            c = register.get_object(n)
+
             if isinstance(c, Class):
                 # Clean the class (e.g., remove duplicates methods due to wrappers):
                 clean_class(c)
@@ -180,7 +185,7 @@ def main() -> None:
                 # Path the class using the configuration:
                 settings.patch_class(c)
 
-            elif isinstance(c, PyTyping):
+            elif isinstance(c, (PyTyping, Constant)):
                 ...
 
             elif is_list_of_functions(c):
@@ -200,6 +205,21 @@ def main() -> None:
         # create directory if required
         output_folder.mkdir(parents=True, exist_ok=True)
 
+        # sort the stubs
+        def _key_fn(o: Class | Constant | list[Function] | PyTyping) -> tuple[int, ...]:
+            # order is PyTyping -> Constant -> Function -> Enum -> Top-Level Class -> Child Level Classes
+            return (
+                not isinstance(o, PyTyping),
+                not isinstance(o, Constant),
+                not isinstance(o, list),
+                not isinstance(o, Enum),
+                isinstance(o, Class) and len(o.all_bases),
+            )
+
+        stub_objects = sorted(
+            (register.get_object(n) for n, _o in objects), key=_key_fn
+        )
+
         # write everything
         with open(output_folder.joinpath("__init__.pyi"), "w") as output:
             writer = Writer(package=name, output=output, settings=settings)
@@ -210,19 +230,28 @@ def main() -> None:
 
             module_headers[name](writer)
 
-            for n, o in objects:
-                # Get the corresponding object:
-                c = register.get_object(n)
-
+            for c in stub_objects:
                 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",
+                "format",
+                "--silent",
+                output_folder.joinpath("__init__.pyi").as_posix(),
+            ]
+        )
+        subprocess.run(
+            [
+                "ruff",
+                "check",
+                "--silent",
+                "--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

@@ -33,7 +33,7 @@ def load_mobase(path: os.PathLike[Any]) -> Module:
         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())
+    sys.path.insert(1, path.joinpath("proxies", "python", "libs").as_posix())
 
     import mobase  # type: ignore
 

src/mo2/stubs/generator/mtypes.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Sequence
 from typing import Final, TypeVar
 
 
@@ -164,7 +165,6 @@ class Argument:
 
 
 class Exception:
-
     """
     Small class representing exception that can be raised from functions.
     """
@@ -313,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
@@ -385,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.
@@ -401,7 +400,6 @@ class PyClass(Class):
 
 
 class Enum(Class):
-
     """
     Class representing an enum.
     """

src/mo2/stubs/generator/parser.py

@@ -108,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
 
@@ -131,7 +134,6 @@ def is_enum(e: type) -> bool:
 
 
 class Overload:
-
     """Small class to avoid mypy issues..."""
 
     return_type: PyType
@@ -173,8 +175,8 @@ def parse_pybind11_function_docstring(e: type) -> list[Overload]:
 
         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
@@ -218,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
@@ -231,6 +234,8 @@ def make_class(e: type, register: MobaseRegister) -> Class:
     # members to exclude
     EXCLUDED_MEMBERS = [
         "__init_subclass__",
+        "__dict__",
+        "__doc__",
         "__module__",
         "__subclasshook__",
         "__hash__",
@@ -343,7 +348,7 @@ def make_class(e: type, register: MobaseRegister) -> Class:
 
     direct_bases: list[Class] = []
     for c in e.__bases__:
-        if c.__module__ != "pybind11_builtins":
+        if c.__module__ not in ("pybind11_builtins", "builtins"):
             b = register.get_object(c.__name__)
             assert isinstance(b, Class)
             direct_bases.append(b)

src/mo2/stubs/generator/register.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections import OrderedDict
 
-from .mtypes import Class, Function, PyTyping
+from .mtypes import Class, Constant, Function, PyType, PyTyping
 
 
 class MobaseRegister:
@@ -12,7 +12,7 @@ class MobaseRegister:
     Class that register classes.
     """
 
-    objects: dict[str, Class | list[Function] | PyTyping]
+    objects: dict[str, Class | Constant | list[Function] | PyTyping]
 
     def __init__(self) -> None:
         self.raw_objects: dict[str, type] = OrderedDict()
@@ -23,9 +23,9 @@ class MobaseRegister:
 
     def make_object(
         self, name: str, e: type | None = None
-    ) -> Class | list[Function] | PyTyping:
+    ) -> Class | list[Function] | Constant | PyTyping:
         """
-        Construct a Function, Class or Enum for the given object.
+        Construct a Function, Class, Constant or Enum for the given object.
 
         Args:
             name: The name of the object to inspect.
@@ -47,14 +47,14 @@ class MobaseRegister:
                 self.objects[name] = make_class(e, self)
             elif callable(e):
                 self.objects[name] = make_functions(e)
-
-            # typing stuff
             elif type(e).__module__ == "types" or type(e).__module__ == "typing":
                 self.objects[name] = PyTyping(name, e)
+            else:
+                self.objects[name] = Constant(name, type=PyType(type(e)), value=e)
 
         return self.objects[name]
 
-    def get_object(self, name: str) -> Class | list[Function] | PyTyping:
+    def get_object(self, name: str) -> Class | Constant | 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).

src/mo2/stubs/generator/utils.py

@@ -220,7 +220,9 @@ class Settings:
                             f"mobase.{setting_name}."
                         )
 
-                    for setting_arg, method_arg in zip(function_settings.args, fn.args):
+                    for setting_arg, method_arg in zip(
+                        function_settings.args, fn.args, strict=True
+                    ):
                         method_arg.doc = setting_arg.doc
                         if not setting_arg.type.is_none():
                             method_arg.type = setting_arg.type
@@ -371,7 +373,7 @@ class Settings:
                             )
 
                         for settings_arg, method_arg in zip(
-                            function_settings.args, method_arguments
+                            function_settings.args, method_arguments, strict=True
                         ):
                             method_arg.doc = settings_arg.doc
                             if (