Merge branch 'ArchipelagoMW:main' into main

Author: EverydaySimpleDev

.gitignore

@@ -65,6 +65,8 @@ Output Logs/
 /datapackage
 /datapackage_export.json
 /custom_worlds
+# stubgen output
+/out/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

Generate.py

@@ -23,7 +23,7 @@
 from Utils import parse_yamls, version_tuple, __version__, tuplize_version
 
 
-def mystery_argparse(argv: list[str] | None = None):
+def mystery_argparse(argv: list[str] | None = None) -> argparse.Namespace:
     from settings import get_settings
     settings = get_settings()
     defaults = settings.generator
@@ -68,7 +68,7 @@ def mystery_argparse(argv: list[str] | None = None):
         args.weights_file_path = os.path.join(args.player_files_path, args.weights_file_path)
     if not os.path.isabs(args.meta_file_path):
         args.meta_file_path = os.path.join(args.player_files_path, args.meta_file_path)
-    args.plando: PlandoOptions = PlandoOptions.from_option_string(args.plando)
+    args.plando = PlandoOptions.from_option_string(args.plando)
 
     return args
 
@@ -135,7 +135,7 @@ def main(args=None) -> tuple[argparse.Namespace, int]:
                     else:
                         weights_for_file.append(yaml)
                 weights_cache[fname] = tuple(weights_for_file)
-                        
+
             except Exception as e:
                 logging.exception(f"Exception reading weights in file {fname}")
                 player_errors.append(
@@ -205,7 +205,7 @@ def main(args=None) -> tuple[argparse.Namespace, int]:
                             else:
                                 yaml[category_name][key] = option
 
-    settings_cache: dict[str, tuple[argparse.Namespace, ...]] = {fname: None for fname in weights_cache}
+    settings_cache: dict[str, tuple[argparse.Namespace, ...] | None] = {fname: None for fname in weights_cache}
     if args.sameoptions:
         for fname, yamls in weights_cache.items():
             try:
@@ -225,7 +225,7 @@ def main(args=None) -> tuple[argparse.Namespace, int]:
     player_path_cache: dict[int, str] = {}
     for player in range(1, args.multi + 1):
         player_path_cache[player] = player_files.get(player, args.weights_file_path)
-    name_counter = Counter()
+    name_counter: Counter[str] = Counter()
     args.player_options = {}
 
     player = 1
@@ -241,13 +241,10 @@ def main(args=None) -> tuple[argparse.Namespace, int]:
             try:
                 # Use the cached settings object if it exists, otherwise roll settings within the try-catch
                 # Invariant: settings_cache[path] and weights_cache[path] have the same length
-                settingsObject: argparse.Namespace = (
-                    settings_cache[path][doc_index]
-                    if settings_cache[path]
-                    else roll_settings(yaml, args.plando)
-                )
-                
-                for k, v in vars(settingsObject).items():
+                cached = settings_cache[path]
+                settings_object: argparse.Namespace = (cached[doc_index] if cached else roll_settings(yaml, args.plando))
+
+                for k, v in vars(settings_object).items():
                     if v is not None:
                         try:
                             getattr(args, k)[player] = v
@@ -365,7 +362,7 @@ def get_value(self, key, args, kwargs):
             return kwargs.get(key, "{" + key + "}")
 
 
-def handle_name(name: str, player: int, name_counter: Counter):
+def handle_name(name: str, player: int, name_counter: Counter[str]):
     name_counter[name.lower()] += 1
     number = name_counter[name.lower()]
     new_name = "%".join([x.replace("%number%", "{number}").replace("%player%", "{player}") for x in name.split("%%")])
@@ -503,7 +500,7 @@ def roll_triggers(weights: dict, triggers: list, valid_keys: set) -> dict:
     return weights
 
 
-def handle_option(ret: argparse.Namespace, game_weights: dict, option_key: str, option: type(Options.Option), plando_options: PlandoOptions):
+def handle_option(ret: argparse.Namespace, game_weights: dict, option_key: str, option: type[Options.Option], plando_options: PlandoOptions):
     try:
         if option_key in game_weights:
             if not option.supports_weighting:

Options.py

@@ -523,9 +523,9 @@ def __ge__(self, other: typing.Union[Choice, int, str]):
 
 class TextChoice(Choice):
     """Allows custom string input and offers choices. Choices will resolve to int and text will resolve to string"""
-    value: typing.Union[str, int]
+    value: str | int
 
-    def __init__(self, value: typing.Union[str, int]):
+    def __init__(self, value: str | int):
         assert isinstance(value, str) or isinstance(value, int), \
             f"'{value}' is not a valid option for '{self.__class__.__name__}'"
         self.value = value
@@ -546,7 +546,7 @@ def from_text(cls, text: str) -> TextChoice:
         return cls(text)
 
     @classmethod
-    def get_option_name(cls, value: T) -> str:
+    def get_option_name(cls, value: str | int) -> str:
         if isinstance(value, str):
             return value
         return super().get_option_name(value)
@@ -891,7 +891,7 @@ def verify(self, world: typing.Type[World], player_name: str, plando_options: "P
     def __iter__(self) -> typing.Iterator[typing.Any]:
         return self.value.__iter__()
 
-    
+
 class OptionDict(Option[typing.Dict[str, typing.Any]], VerifyKeys, typing.Mapping[str, typing.Any]):
     default = {}
     supports_weighting = False
@@ -906,7 +906,8 @@ def from_any(cls, data: typing.Dict[str, typing.Any]) -> OptionDict:
         else:
             raise NotImplementedError(f"Cannot Convert from non-dictionary, got {type(data)}")
 
-    def get_option_name(self, value):
+    @classmethod
+    def get_option_name(cls, value):
         return ", ".join(f"{key}: {v}" for key, v in value.items())
 
     def __getitem__(self, item: str) -> typing.Any:
@@ -986,7 +987,8 @@ def from_any(cls, data: typing.Any):
             return cls(data)
         return cls.from_text(str(data))
 
-    def get_option_name(self, value):
+    @classmethod
+    def get_option_name(cls, value):
         return ", ".join(map(str, value))
 
     def __contains__(self, item):
@@ -1011,7 +1013,8 @@ def from_any(cls, data: typing.Any):
             return cls(data)
         return cls.from_text(str(data))
 
-    def get_option_name(self, value):
+    @classmethod
+    def get_option_name(cls, value):
         return ", ".join(sorted(value))
 
     def __contains__(self, item):
@@ -1656,7 +1659,7 @@ def __iter__(self) -> typing.Iterator[PlandoItem]:
     def __len__(self) -> int:
         return len(self.value)
 
-        
+
 class Removed(FreeText):
     """This Option has been Removed."""
     rich_text_doc = True

OptionsCreator.py

@@ -6,6 +6,7 @@
 
 from kvui import (ThemedApp, ScrollBox, MainLayout, ContainerLayout, dp, Widget, MDBoxLayout, TooltipLabel, MDLabel,
                   ToggleButton, MarkupDropdown, ResizableTextField)
+from kivy.clock import Clock
 from kivy.uix.behaviors.button import ButtonBehavior
 from kivymd.uix.behaviors import RotateBehavior
 from kivymd.uix.anchorlayout import MDAnchorLayout
@@ -269,34 +270,53 @@ def __init__(self):
         self.options = {}
         super().__init__()
 
-    def export_options(self, button: Widget):
-        if 0 < len(self.name_input.text) < 17 and self.current_game:
-            file_name = Utils.save_filename("Export Options File As...", [("YAML", ["*.yaml"])],
+    @staticmethod
+    def show_result_snack(text: str) -> None:
+        MDSnackbar(MDSnackbarText(text=text), y=dp(24), pos_hint={"center_x": 0.5}, size_hint_x=0.5).open()
+
+    def on_export_result(self, text: str | None) -> None:
+        self.container.disabled = False
+        if text is not None:
+            Clock.schedule_once(lambda _: self.show_result_snack(text), 0)
+
+    def export_options_background(self, options: dict[str, typing.Any]) -> None:
+        try:
+            file_name = Utils.save_filename("Export Options File As...", [("YAML", [".yaml"])],
                                             Utils.get_file_safe_name(f"{self.name_input.text}.yaml"))
+        except Exception:
+            self.on_export_result("Could not open dialog. Already open?")
+            raise
+
+        if not file_name:
+            self.on_export_result(None)  # No file selected. No need to show a message for this.
+            return
+
+        try:
+            with open(file_name, 'w') as f:
+                f.write(Utils.dump(options, sort_keys=False))
+                f.close()
+                self.on_export_result("File saved successfully.")
+        except Exception:
+            self.on_export_result("Could not save file.")
+            raise
+
+    def export_options(self, button: Widget) -> None:
+        if 0 < len(self.name_input.text) < 17 and self.current_game:
+            import threading
             options = {
                 "name": self.name_input.text,
                 "description": f"YAML generated by Archipelago {Utils.__version__}.",
                 "game": self.current_game,
                 self.current_game: {k: check_random(v) for k, v in self.options.items()}
             }
-            try:
-                with open(file_name, 'w') as f:
-                    f.write(Utils.dump(options, sort_keys=False))
-                    f.close()
-                    MDSnackbar(MDSnackbarText(text="File saved successfully."), y=dp(24), pos_hint={"center_x": 0.5},
-                               size_hint_x=0.5).open()
-            except FileNotFoundError:
-                MDSnackbar(MDSnackbarText(text="Saving cancelled."), y=dp(24), pos_hint={"center_x": 0.5},
-                           size_hint_x=0.5).open()
+            threading.Thread(target=self.export_options_background, args=(options,), daemon=True).start()
+            self.container.disabled = True
         elif not self.name_input.text:
-            MDSnackbar(MDSnackbarText(text="Name must not be empty."), y=dp(24), pos_hint={"center_x": 0.5},
-                       size_hint_x=0.5).open()
+            self.show_result_snack("Name must not be empty.")
         elif not self.current_game:
-            MDSnackbar(MDSnackbarText(text="You must select a game to play."), y=dp(24), pos_hint={"center_x": 0.5},
-                       size_hint_x=0.5).open()
+            self.show_result_snack("You must select a game to play.")
         else:
-            MDSnackbar(MDSnackbarText(text="Name cannot be longer than 16 characters."), y=dp(24),
-                       pos_hint={"center_x": 0.5}, size_hint_x=0.5).open()
+            self.show_result_snack("Name cannot be longer than 16 characters.")
 
     def create_range(self, option: typing.Type[Range], name: str):
         def update_text(range_box: VisualRange):

Utils.py

@@ -811,29 +811,32 @@ def open_filename(title: str, filetypes: typing.Iterable[typing.Tuple[str, typin
         except tkinter.TclError:
             return None  # GUI not available. None is the same as a user clicking "cancel"
         root.withdraw()
-        return tkinter.filedialog.askopenfilename(title=title, filetypes=((t[0], ' '.join(t[1])) for t in filetypes),
-                                                  initialfile=suggest or None)
+        try:
+            return tkinter.filedialog.askopenfilename(
+                title=title,
+                filetypes=((t[0], ' '.join(t[1])) for t in filetypes),
+                initialfile=suggest or None,
+            )
+        finally:
+            root.destroy()
 
 
 def save_filename(title: str, filetypes: typing.Iterable[typing.Tuple[str, typing.Iterable[str]]], suggest: str = "") \
         -> typing.Optional[str]:
     logging.info(f"Opening file save dialog for {title}.")
 
-    def run(*args: str):
-        return subprocess.run(args, capture_output=True, text=True).stdout.split("\n", 1)[0] or None
-
     if is_linux:
         # prefer native dialog
         from shutil import which
         kdialog = which("kdialog")
         if kdialog:
             k_filters = '|'.join((f'{text} (*{" *".join(ext)})' for (text, ext) in filetypes))
-            return run(kdialog, f"--title={title}", "--getsavefilename", suggest or ".", k_filters)
+            return _run_for_stdout(kdialog, f"--title={title}", "--getsavefilename", suggest or ".", k_filters)
         zenity = which("zenity")
         if zenity:
             z_filters = (f'--file-filter={text} ({", ".join(ext)}) | *{" *".join(ext)}' for (text, ext) in filetypes)
             selection = (f"--filename={suggest}",) if suggest else ()
-            return run(zenity, f"--title={title}", "--file-selection", "--save", *z_filters, *selection)
+            return _run_for_stdout(zenity, f"--title={title}", "--file-selection", "--save", *z_filters, *selection)
 
     # fall back to tk
     try:
@@ -856,8 +859,14 @@ def run(*args: str):
         except tkinter.TclError:
             return None  # GUI not available. None is the same as a user clicking "cancel"
         root.withdraw()
-        return tkinter.filedialog.asksaveasfilename(title=title, filetypes=((t[0], ' '.join(t[1])) for t in filetypes),
-                                                    initialfile=suggest or None)
+        try:
+            return tkinter.filedialog.asksaveasfilename(
+                title=title,
+                filetypes=((t[0], ' '.join(t[1])) for t in filetypes),
+                initialfile=suggest or None,
+            )
+        finally:
+            root.destroy()
 
 
 def _mp_open_directory(res: "multiprocessing.Queue[typing.Optional[str]]", *args: Any) -> None:

WebHostLib/README.md

@@ -1,46 +1,20 @@
 # WebHost
 
-## Contribution Guidelines
-**Thank you for your interest in contributing to the Archipelago website!**  
-Much of the content on the website is generated automatically, but there are some things
-that need a personal touch. For those things, we rely on contributions from both the core
-team and the community. The current primary maintainer of the website is Farrak Kilhn.
-He may be found on Discord as `Farrak Kilhn#0418`, or on GitHub as `LegendaryLinux`.
+## Asset License
+
+The image files used in the page design were specifically designed for archipelago.gg and are **not** covered by the top
+level LICENSE.
+See individual LICENSE files in `./static/static/**`.
 
-### Small Changes
-Little changes like adding a button or a couple new select elements are perfectly fine.
-Tweaks to style specific to a PR's content are also probably not a problem. For example, if
-you build a new page which needs two side by side tables, and you need to write a CSS file
-specific to your page, that is perfectly reasonable.
+You are only allowed to use them for personal use, testing and development.
+If the site is reachable over the internet, have a robots.txt in place (see `ASSET_RIGHTS` in `config.yaml`)
+and do not promote it publicly. Alternatively replace or remove the assets.
 
-### Content Additions
-Once you develop a new feature or add new content the website, make a pull request. It will
-be reviewed by the community and there will probably be some discussion around it. Depending
-on the size of the feature, and if new styles are required, there may be an additional step
-before the PR is accepted wherein Farrak works with the designer to implement styles.
+## Contribution Guidelines
 
-### Restrictions on Style Changes
-A professional designer is paid to develop the styles and assets for the Archipelago website.
-In an effort to maintain a consistent look and feel, pull requests which *exclusively*
-change site styles are rejected. Please note this applies to code which changes the overall
-look and feel of the site, not to small tweaks to CSS for your custom page. The intention
-behind these restrictions is to maintain a curated feel for the design of the site. If
-any PR affects the overall feel of the site but includes additive changes, there will
-likely be a conversation about how to implement those changes without compromising the
-curated site style. It is therefore worth noting there are a couple files which, if
-changed in your pull request, will cause it to draw additional scrutiny.
+Pages should preferably be rendered on the server side with Jinja. Features should work with noscript if feasible.
+Design changes have to fit the overall design.
 
-These closely guarded files are:
-- `globalStyles.css`
-- `islandFooter.css`
-- `landing.css`
-- `markdown.css`
-- `tooltip.css`
+Introduction of JS dependencies should first be discussed on Discord or in a draft PR.
 
-### Site Themes
-There are several themes available for game pages. It is possible to request a new theme in
-the `#art-and-design` channel on Discord. Because themes are created by the designer, they
-are not free, and take some time to create. Farrak works closely with the designer to implement
-these themes, and pays for the assets out of pocket. Therefore, only a couple themes per year
-are added. If a proposed theme seems like a cool idea and the community likes it, there is a
-good chance it will become a reality.
+See also [docs/style.md](/docs/style.md) for the style guide.

docs/apworld specification.md

@@ -41,7 +41,7 @@ There are also the following optional fields:
 If the APWorld is packaged as an `.apworld` zip file, it also needs to have `version` and `compatible_version`,
 which refer to the version of the APContainer packaging scheme defined in [Files.py](../worlds/Files.py).  
 These get automatically added to the `archipelago.json` of an .apworld if it is packaged using the 
-["Build apworlds" launcher component](#build-apworlds-launcher-component),
+["Build APWorlds" launcher component](#build-apworlds-launcher-component),
 which is the correct way to package your `.apworld` as a world developer. Do not write these fields yourself.
 
 ### "Build APWorlds" Launcher Component
@@ -50,7 +50,9 @@ In the Archipelago Launcher, there is a "Build APWorlds" component that will pac
 and add `archipelago.json` manifest files to them.  
 These .apworld files will be output to `build/apworlds` (relative to the Archipelago root directory).  
 The `archipelago.json` file in each .apworld will automatically include the appropriate
-`version` and `compatible_version`.
+`version` and `compatible_version`.  
+The component can also be called from the command line to allow for specifying a certain list of worlds to build.
+For example, running `Launcher.py "Build APWorlds" -- "Game Name"` will build only the game called `Game Name`.
 
 If a world folder has an `archipelago.json` in its root, any fields it contains will be carried over.  
 So, a world folder with an `archipelago.json` that looks like this:

docs/running from source.md

@@ -7,10 +7,9 @@ use that version. These steps are for developers or platforms without compiled r
 ## General
 
 What you'll need:
- * [Python 3.11.9 or newer](https://www.python.org/downloads/), not the Windows Store version
+ * [Python 3.11.9 or newer but less than 3.14](https://www.python.org/downloads/), not the Windows Store version
    * On Windows, please consider only using the latest supported version in production environments since security
      updates for older versions are not easily available.
-   * Python 3.13.x is currently the newest supported version
  * pip: included in downloads from python.org, separate in many Linux distributions
  * Matching C compiler
    * possibly optional, read operating system specific sections