fix: correct type annotations for Plugin and event_handler (#369)

* fix: correct type annotations for Plugin class vars and event_handler decorator

Plugin class variables were typed as bare `None`, causing mypy to reject
string assignments in subclasses (e.g. `prefix = "MyPlugin"`). Add
proper `str | None`, `dict | None`, etc. annotations.

event_handler decorator stub returned `None` instead of a callable,
causing mypy func-returns-value and untyped-decorator errors. Add
@overload signatures for both `@event_handler` and
`@event_handler(priority=...)` usage patterns.

* fix: update type annotations in chart modules

* fix: add missing initialization checks

* fix: add missing checks across modules

* fix: add server UUID check and correct type ignore annotations in metrics config

* fix: update type annotations in stubs

Author: wu-vincent

endstone/actor/__init__.pyi

@@ -346,8 +346,8 @@ class ActorType:
     def __str__(self) -> str: ...
     def __repr__(self) -> str: ...
     def __hash__(self) -> int: ...
-    def __eq__(self, arg0: ActorType) -> bool: ...
-    def __ne__(self, arg0: ActorType) -> bool: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
 
 class Item(Actor):
     """

endstone/asyncio/__init__.py

@@ -34,7 +34,7 @@ def _lazy_init(self) -> None:
                 loop.set_debug(self._debug)
             self._loop = loop
 
-            def _thread_main():
+            def _thread_main() -> None:
                 asyncio.set_event_loop(loop)
                 self._started_evt.set()
                 loop.run_forever()
@@ -53,7 +53,7 @@ def shutdown(self, *, timeout: Optional[float] = None) -> None:
             loop = self._loop
             thread = self._thread
 
-            async def _shutdown():
+            async def _shutdown() -> None:
                 current = asyncio.current_task()
                 to_cancel = [t for t in asyncio.all_tasks() if t is not current]
                 for t in to_cancel:
@@ -86,6 +86,8 @@ def submit(self, coro: typing.Awaitable[_T]) -> concurrent.futures.Future[_T]:
         if not asyncio.iscoroutine(coro):
             raise TypeError(f"a coroutine object is required, got {coro!r}")
         self._lazy_init()
+        if self._loop is None:
+            raise RuntimeError("Event loop is not initialized")
         return asyncio.run_coroutine_threadsafe(coro, self._loop)
 
     def get_loop(self) -> asyncio.AbstractEventLoop:

endstone/cli/__init__.py

@@ -3,11 +3,13 @@
 import platform
 import sys
 import time
+from typing import Any, Callable, TypeVar, cast
 
 import click
 import colorlog
 
 from endstone._version import __version__
+from endstone.cli.base import Bootstrap
 
 handler = colorlog.StreamHandler()
 handler.setFormatter(
@@ -29,19 +31,21 @@
 
 __all__ = ["main"]
 
+_F = TypeVar("_F", bound=Callable[..., Any])
 
-def catch_exceptions(func):
+
+def catch_exceptions(func: _F) -> _F:
     """Decorator to catch and log exceptions."""
 
     @functools.wraps(func)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]
         try:
             return func(*args, **kwargs)
         except Exception as e:
             logger.exception(e)
             sys.exit(-1)
 
-    return wrapper
+    return cast(_F, wrapper)
 
 
 @click.group(invoke_without_command=True, help="Starts an endstone server.")
@@ -75,10 +79,11 @@ def wrapper(*args, **kwargs):
 @click.version_option(__version__)
 @click.pass_context
 @catch_exceptions
-def main(ctx, server_folder: str, no_confirm: bool, remote: str, interactive: bool) -> None:
+def main(ctx: click.Context, server_folder: str, no_confirm: bool, remote: str, interactive: bool) -> None:
     if ctx.invoked_subcommand is not None:
         return
 
+    cls: type[Bootstrap]
     system = platform.system()
     if system == "Windows":
         from .windows import WindowsBootstrap

endstone/cli/base.py

@@ -15,7 +15,7 @@
 import click
 import importlib_resources
 import requests
-import sentry_crashpad
+import sentry_crashpad  # type: ignore[import-untyped]
 import tomlkit
 from packaging.version import Version
 from rich.progress import BarColumn, DownloadColumn, Progress, TextColumn, TimeRemainingColumn
@@ -29,7 +29,7 @@ def __init__(self, server_folder: str, no_confirm: bool, remote: str, interactiv
         self._no_confirm = no_confirm
         self._remote = remote
         self._logger = logging.getLogger(self.name)
-        self._process: subprocess.Popen
+        self._process: subprocess.Popen[str]
         self._interactive = interactive
 
     @property
@@ -76,7 +76,7 @@ def _validate(self) -> None:
         if not self._endstone_runtime_path.exists():
             raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), str(self._endstone_runtime_path))
 
-    def _download(self, dst: Union[str, os.PathLike]) -> None:
+    def _download(self, dst: Union[str, os.PathLike[str]]) -> None:
         dst = Path(dst)
 
         self._logger.info("Loading index from the remote server...")
@@ -140,8 +140,8 @@ def _download(self, dst: Union[str, os.PathLike]) -> None:
 
         if should_modify_server_properties:
             properties = dst / "server.properties"
-            with properties.open("r", encoding="utf-8") as file:
-                in_lines = file.readlines()
+            with properties.open("r", encoding="utf-8") as f:
+                in_lines = f.readlines()
 
             out_lines = []
             for line in in_lines:
@@ -152,12 +152,12 @@ def _download(self, dst: Union[str, os.PathLike]) -> None:
                 else:
                     out_lines.append(line)
 
-            with properties.open("w", encoding="utf-8") as file:
-                file.writelines(out_lines)
+            with properties.open("w", encoding="utf-8") as f:
+                f.writelines(out_lines)
 
         version_file = dst / "version.txt"
-        with version_file.open("w", encoding="utf-8") as file:
-            file.writelines(str(self.minecraft_version))
+        with version_file.open("w", encoding="utf-8") as f:
+            f.writelines(str(self.minecraft_version))
 
     def _prepare(self) -> None:
         # ensure the plugin folder exists
@@ -200,7 +200,7 @@ def migrate_config(from_doc: tomlkit.TOMLDocument, to_doc: tomlkit.TOMLDocument)
                     else:
                         # if both are tables, dive deeper
                         if isinstance(val, tomlkit.TOMLDocument) and isinstance(to_doc[key], tomlkit.TOMLDocument):
-                            migrate_config(val, to_doc[key])
+                            migrate_config(val, to_doc[key])  # type: ignore[arg-type]
 
             migrate_config(default_config, config)
             with open(self.config_path, "w", encoding="utf-8") as f:
@@ -291,7 +291,7 @@ def _endstone_runtime_env(self) -> dict[str, str]:
             env["ENDSTONE_USE_INTERACTIVE_CONSOLE"] = "1"
         return env
 
-    def _run(self, *args, **kwargs) -> int:
+    def _run(self, *args, **kwargs) -> int:  # type: ignore[no-untyped-def]
         """
         Runs the server and returns its exit code.
 

endstone/cli/linux.py

@@ -36,8 +36,8 @@ def _prepare(self) -> None:
         os.chmod(self.executable_path, st.st_mode | stat.S_IEXEC)
         os.chmod(self.server_path / "crashpad_handler", st.st_mode | stat.S_IEXEC)
 
-    def _run(self, *args, **kwargs) -> int:
-        process = subprocess.Popen(
+    def _run(self, *args, **kwargs) -> int:  # type: ignore[no-untyped-def]
+        process = subprocess.Popen(  # type: ignore[call-overload]
             [str(self.executable_path.absolute())],
             text=True,
             encoding="utf-8",
@@ -46,4 +46,4 @@ def _run(self, *args, **kwargs) -> int:
             *args,
             **kwargs,
         )
-        return process.wait()
+        return int(process.wait())

endstone/cli/windows.py

@@ -4,19 +4,19 @@
 import subprocess
 import sys
 import warnings
-from subprocess import STARTUPINFO, Handle, list2cmdline
+from subprocess import STARTUPINFO, Handle, list2cmdline  # type: ignore[attr-defined]
 
-from endstone import _detours
+from endstone import _detours  # type: ignore[attr-defined]
 
 from .base import Bootstrap
 
 
-class PopenWithDll(subprocess.Popen):
-    def __init__(self, *args, **kwargs):
+class PopenWithDll(subprocess.Popen[str]):
+    def __init__(self, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]
         self.dll_names = kwargs.pop("dll_names", None)
         super().__init__(*args, **kwargs)
 
-    def _execute_child(
+    def _execute_child(  # type: ignore[no-untyped-def]
         self,
         args,
         executable,
@@ -34,16 +34,9 @@ def _execute_child(
         c2pwrite,
         errread,
         errwrite,
-        # unused_restore_signals,
-        # unused_gid,
-        # unused_gids,
-        # unused_uid,
-        # unused_umask,
-        # unused_start_new_session,
-        # unused_process_group,
         *unused_args,
         **unused_kwargs,
-    ):
+    ) -> None:
         """Execute program (MS Windows version)"""
 
         assert not pass_fds, "pass_fds not supported on Windows."
@@ -88,7 +81,7 @@ def _execute_child(
             if use_std_handles:
                 handle_list += [int(p2cread), int(c2pwrite), int(errwrite)]
 
-            handle_list[:] = self._filter_handle_list(handle_list)
+            handle_list[:] = self._filter_handle_list(handle_list)  # type: ignore[attr-defined]
 
             if handle_list:
                 if not close_fds:
@@ -120,7 +113,7 @@ def _execute_child(
                 dll_name=self.dll_names,
             )
         finally:
-            self._close_pipe_fds(p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite)
+            self._close_pipe_fds(p2cread, p2cwrite, c2pread, c2pwrite, errread, errwrite)  # type: ignore[attr-defined]
 
         # Retain the process handle, but close the thread handle
         self._child_created = True
@@ -178,7 +171,7 @@ def _check_python_distribution(self) -> None:
                 "from https://www.python.org/downloads/ ."
             )
 
-    def _run(self, *args, **kwargs) -> int:
+    def _run(self, *args, **kwargs) -> int:  # type: ignore[no-untyped-def]
         try:
             self._add_loopback_exemption()
         except Exception as e:

endstone/command/__init__.pyi

@@ -63,8 +63,8 @@ class CommandSenderWrapper(CommandSender):
     def __init__(
         self,
         sender: CommandSender,
-        on_message: collections.abc.Callable[[str | Translatable], None] = None,
-        on_error: collections.abc.Callable[[str | Translatable], None] = None,
+        on_message: collections.abc.Callable[[str | Translatable], None] | None = None,
+        on_error: collections.abc.Callable[[str | Translatable], None] | None = None,
     ) -> None: ...
 
 class ConsoleCommandSender(CommandSender):

endstone/enchantments/__init__.pyi

@@ -2,8 +2,6 @@
 Classes relating to the specialized enhancements to ItemStacks.
 """
 
-import typing
-
 from endstone.inventory import ItemStack
 
 __all__ = ["Enchantment"]
@@ -94,11 +92,5 @@ class Enchantment:
         ...
     def __str__(self) -> str: ...
     def __hash__(self) -> int: ...
-    @typing.overload
-    def __eq__(self, arg0: Enchantment) -> bool: ...
-    @typing.overload
-    def __eq__(self, arg0: str) -> bool: ...
-    @typing.overload
-    def __ne__(self, arg0: Enchantment) -> bool: ...
-    @typing.overload
-    def __ne__(self, arg0: str) -> bool: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...

endstone/event/__init__.py

@@ -1,7 +1,20 @@
+from collections.abc import Callable
+from typing import TypeVar, overload
+
 import lazy_loader as lazy
 
 from endstone._python.event import EventPriority
 
+_F = TypeVar("_F", bound=Callable[..., None])
+
+
+@overload
+def event_handler(__func: _F) -> _F: ...
+
+
+@overload
+def event_handler(*, priority: EventPriority = ..., ignore_cancelled: bool = ...) -> Callable[[_F], _F]: ...
+
 
 def event_handler(func=None, *, priority: EventPriority = EventPriority.NORMAL, ignore_cancelled: bool = False):
     def decorator(f):

endstone/event/__init__.pyi

@@ -3,6 +3,7 @@ Classes relating to handling triggered code executions.
 """
 
 import enum
+import typing
 
 from endstone import GameMode, Player, Skin
 from endstone.actor import Actor, Item, Mob
@@ -89,6 +90,8 @@ __all__ = [
     "event_handler",
 ]
 
+_F = typing.TypeVar("_F", bound=(typing.Callable[..., None]))
+
 class EventPriority(enum.IntEnum):
     """
     Listeners are called in following order: LOWEST -> LOW -> NORMAL -> HIGH -> HIGHEST -> MONITOR
@@ -1151,6 +1154,7 @@ class WeatherChangeEvent(WeatherEvent, Cancellable):
         """
         ...
 
-def event_handler(
-    func=None, *, priority: EventPriority = EventPriority.NORMAL, ignore_cancelled: bool = False
-) -> None: ...
+@typing.overload
+def event_handler(__func: _F) -> _F: ...
+@typing.overload
+def event_handler(*, priority: EventPriority = ..., ignore_cancelled: bool = ...) -> typing.Callable[[_F], _F]: ...