Docs: datapackage typing (#1229)

* Docs: add ClassVar marker to World class

* Docs: add typing to network_data_package

WebHostLib/generate.py

@@ -92,7 +92,7 @@ def generate(race=False):
     return render_template("generate.html", race=race, version=__version__)
 
 
-def gen_game(gen_options, meta: Optional[Dict[str, Any]] = None, owner=None, sid=None):
+def gen_game(gen_options: dict, meta: Optional[Dict[str, Any]] = None, owner=None, sid=None):
     if not meta:
         meta: Dict[str, Any] = {}
 

worlds/AutoWorld.py

@@ -3,7 +3,8 @@ from __future__ import annotations
 import logging
 import sys
 import pathlib
-from typing import Dict, FrozenSet, Set, Tuple, List, Optional, TextIO, Any, Callable, Type, Union, TYPE_CHECKING
+from typing import Dict, FrozenSet, Set, Tuple, List, Optional, TextIO, Any, Callable, Type, Union, TYPE_CHECKING, \
+    ClassVar
 
 from Options import AssembleOptions
 from BaseClasses import CollectionState
@@ -130,24 +131,24 @@ class World(metaclass=AutoWorldRegister):
     """A World object encompasses a game's Items, Locations, Rules and additional data or functionality required.
     A Game should have its own subclass of World in which it defines the required data structures."""
 
-    option_definitions: Dict[str, AssembleOptions] = {}  # link your Options mapping
-    game: str  # name the game
-    topology_present: bool = False  # indicate if world type has any meaningful layout/pathing
+    option_definitions: ClassVar[Dict[str, AssembleOptions]] = {}  # link your Options mapping
+    game: ClassVar[str]  # name the game
+    topology_present: ClassVar[bool] = False  # indicate if world type has any meaningful layout/pathing
 
     # gets automatically populated with all item and item group names
-    all_item_and_group_names: FrozenSet[str] = frozenset()
+    all_item_and_group_names: ClassVar[FrozenSet[str]] = frozenset()
 
     # map names to their IDs
-    item_name_to_id: Dict[str, int] = {}
-    location_name_to_id: Dict[str, int] = {}
+    item_name_to_id: ClassVar[Dict[str, int]] = {}
+    location_name_to_id: ClassVar[Dict[str, int]] = {}
 
     # maps item group names to sets of items. Example: "Weapons" -> {"Sword", "Bow"}
-    item_name_groups: Dict[str, Set[str]] = {}
+    item_name_groups: ClassVar[Dict[str, Set[str]]] = {}
 
     # increment this every time something in your world's names/id mappings changes.
     # While this is set to 0 in *any* AutoWorld, the entire DataPackage is considered in testing mode and will be
     # retrieved by clients on every connection.
-    data_version: int = 1
+    data_version: ClassVar[int] = 1
 
     # override this if changes to a world break forward-compatibility of the client
     # The base version of (0, 1, 6) is provided for backwards compatibility and does *not* need to be updated in the
@@ -157,7 +158,7 @@ class World(metaclass=AutoWorldRegister):
     # update this if the resulting multidata breaks forward-compatibility of the server
     required_server_version: Tuple[int, int, int] = (0, 2, 4)
 
-    hint_blacklist: FrozenSet[str] = frozenset()  # any names that should not be hintable
+    hint_blacklist: ClassVar[FrozenSet[str]] = frozenset()  # any names that should not be hintable
 
     # NOTE: remote_items and remote_start_inventory are now available in the network protocol for the client to set.
     # These values will be removed.
@@ -176,24 +177,24 @@ class World(metaclass=AutoWorldRegister):
     forced_auto_forfeit: bool = False
 
     # Hide World Type from various views. Does not remove functionality.
-    hidden: bool = False
+    hidden: ClassVar[bool] = False
 
     # see WebWorld for options
-    web: WebWorld = WebWorld()
+    web: ClassVar[WebWorld] = WebWorld()
 
     # autoset on creation:
     multiworld: "MultiWorld"
     player: int
 
     # automatically generated
-    item_id_to_name: Dict[int, str]
-    location_id_to_name: Dict[int, str]
+    item_id_to_name: ClassVar[Dict[int, str]]
+    location_id_to_name: ClassVar[Dict[int, str]]
 
-    item_names: Set[str]  # set of all potential item names
-    location_names: Set[str]  # set of all potential location names
+    item_names: ClassVar[Set[str]]  # set of all potential item names
+    location_names: ClassVar[Set[str]]  # set of all potential location names
 
-    zip_path: Optional[pathlib.Path] = None  # If loaded from a .apworld, this is the Path to it.
-    __file__: str  # path it was loaded from
+    zip_path: ClassVar[Optional[pathlib.Path]] = None  # If loaded from a .apworld, this is the Path to it.
+    __file__: ClassVar[str]  # path it was loaded from
 
     def __init__(self, world: "MultiWorld", player: int):
         self.multiworld = world

worlds/__init__.py

@@ -20,6 +20,17 @@ if typing.TYPE_CHECKING:
     from .AutoWorld import World
 
 
+class GamesPackage(typing.TypedDict):
+    item_name_to_id: typing.Dict[str, int]
+    location_name_to_id: typing.Dict[str, int]
+    version: int
+
+
+class DataPackage(typing.TypedDict):
+    version: int
+    games: typing.Dict[str, GamesPackage]
+
+
 class WorldSource(typing.NamedTuple):
     path: str  # typically relative path from this module
     is_zip: bool = False
@@ -54,7 +65,7 @@ for world_source in world_sources:
 
 lookup_any_item_id_to_name = {}
 lookup_any_location_id_to_name = {}
-games = {}
+games: typing.Dict[str, GamesPackage] = {}
 
 from .AutoWorld import AutoWorldRegister
 
@@ -69,7 +80,7 @@ for world_name, world in AutoWorldRegister.world_types.items():
     lookup_any_item_id_to_name.update(world.item_id_to_name)
     lookup_any_location_id_to_name.update(world.location_id_to_name)
 
-network_data_package = {
+network_data_package: DataPackage = {
     "version": sum(world.data_version for world in AutoWorldRegister.world_types.values()),
     "games": games,
 }