Utils

class Utils.ByValue

Bases: object

Mixin for enums to pickle value instead of name (restores pre-3.11 behavior). Use as left-most parent. See https://github.com/python/cpython/pull/26658 for why this exists.

class Utils.DeprecateDict(message: str, error: bool = False)

Bases: dict

log_message: str
should_error: bool
class Utils.KeyedDefaultDict(default_factory: Callable[[Any], Any] = None, seq: Mapping | Iterable | None = None, **kwargs)

Bases: defaultdict

defaultdict variant that uses the missing key as argument to default_factory

class Utils.RepeatableChain(iterable: Iterable)

Bases: object

class Utils.RestrictedUnpickler(*args: Any, **kwargs: Any)

Bases: Unpickler

find_class(module: str, name: str) → type

Return an object from a specified module.

If necessary, the module will be imported. Subclasses may override this method (e.g. to restrict unpickling of arbitrary classes and functions).

This method is called whenever a class or a function object is needed. Both arguments passed are str objects.

generic_properties_module: object | None
class Utils.UniqueKeyLoader(stream)

Bases: CSafeLoader

construct_mapping(node, deep=False)
class Utils.Version(major, minor, build)

Bases: NamedTuple

as_simple_string() → str
build: int

Alias for field number 2

major: int

Alias for field number 0

minor: int

Alias for field number 1

exception Utils.VersionException

Bases: Exception

Utils.async_start(co: Coroutine[None, None, Any], name: str | None = None) → None

Use this to start a task when you don’t keep a reference to it or immediately await it, to prevent early garbage collection. “fire-and-forget”

Utils.build_sphinx_docs() → None

Build Sphinx autodocs.

Utils.cache_argsless(function: Callable[[], RetType]) → Callable[[], RetType]
Utils.cache_path(*path: str) → str

Returns path to a file in the user’s Archipelago cache directory.

Utils.cache_self1(function: Callable[[S, T], RetType]) → Callable[[S, T], RetType]

Specialized cache for self + 1 arg. Does not keep global ref to self and skips building a dict key tuple.

Utils.chaining_prefix(index: int, labels: Sequence[str]) → str
Utils.deprecate(message: str, add_stacklevels: int = 0)
Utils.format_SI_prefix(value, power=1000, power_labels=('', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y')) → str

Formats a value into a value + metric/si prefix. More info at https://en.wikipedia.org/wiki/Metric_prefix

Utils.freeze_support() → None

This behaves like multiprocessing.freeze_support but also works on Non-Windows.

Utils.get_adjuster_settings(game_name: str) → Namespace
Utils.get_adjuster_settings_no_defaults(game_name: str) → Namespace
Utils.get_cert_none_ssl_context()
Utils.get_default_adjuster_settings(game_name: str) → Namespace
Utils.get_file_safe_name(name: str) → str
Utils.get_fuzzy_results(input_word: str, word_list: Collection[str], limit: int | None = None) → List[Tuple[str, int]]
Utils.get_input_text_from_response(text: str, command: str) → str | None
Utils.get_intended_text(input_text: str, possible_answers) → Tuple[str, bool, str]
Utils.get_options() → Settings
Utils.get_public_ipv4() → RetType
Utils.get_public_ipv6() → RetType
Utils.get_text_after(text: str, start: str) → str
Utils.get_text_between(text: str, start: str, end: str) → str
Utils.get_unique_identifier() → RetType
Utils.home_path(*path: str) → str

Returns path to a file in the user home’s Archipelago directory.

Utils.init_logging(name: str, loglevel: str | int = 20, write_mode: str = 'w', log_format: str = '[%(name)s at %(asctime)s]: %(message)s', add_timestamp: bool = False, exception_logger: str | None = None)
Utils.int16_as_bytes(value: int) → List[int]
Utils.int32_as_bytes(value: int) → List[int]
Utils.is_frozen() → bool
Utils.is_iterable_except_str(obj: object) → TypeGuard[Iterable[Any]]

str is Iterable, but that’s not what we want

Utils.is_kivy_running() → bool
Utils.load_data_package_for_checksum(game: str, checksum: str | None) → Dict[str, Any]
Utils.local_path(*path: str) → str

Returns path to a file in the local Archipelago installation or source. This might be read-only and user_path should be used instead for ROMs, configuration, etc.

Utils.messagebox(title: str, text: str, error: bool = False) → None
Utils.open_directory(title: str, suggest: str = '') → str | None
Utils.open_file(filename: Union[str, 'pathlib.Path']) → None
Utils.open_filename(title: str, filetypes: Iterable[Tuple[str, Iterable[str]]], suggest: str = '') → str | None
Utils.output_path(*path: str) → str
Utils.pc_to_snes(value: int) → int
Utils.persistent_load() → Dict[str, Dict[str, Any]]
Utils.persistent_store(category: str, key: str, value: Any)
Utils.read_snes_rom(stream: BinaryIO, strip_header: bool = True) → bytearray

Reads rom into bytearray and optionally strips off any smc header

Utils.restricted_loads(s: bytes) → Any

Helper function analogous to pickle.loads().

Utils.snes_to_pc(value: int) → int
Utils.store_data_package_for_checksum(game: str, data: Dict[str, Any]) → None
Utils.stream_input(stream: TextIO, queue: Queue[str])
Utils.title_sorted(data: Iterable, key=None, ignore: AbstractSet[str] = frozenset({'a', 'the'}))

Sorts a sequence of text ignoring typical articles like “a” or “the” in the beginning.

Utils.tkinter_center_window(window: tkinter.Tk) → None
Utils.tuplize_version(version: str) → Version
Utils.user_path(*path: str) → str

Returns either local_path or home_path based on write permissions.

Utils.visualize_regions(root_region: Region, file_name: str, *, show_entrance_names: bool = False, show_locations: bool = True, show_other_regions: bool = True, linetype_ortho: bool = True, regions_to_highlight: set[Region] | None = None) → None

Visualize the layout of a world as a PlantUML diagram.

Parameters:

  • root_region – The region from which to start the diagram from. (Usually the “Menu” region of your world.)

  • file_name – The name of the destination .puml file.

  • show_entrance_names – (default False) If enabled, the name of the entrance will be shown near each connection.

  • show_locations – (default True) If enabled, the locations will be listed inside each region. Priority locations will be shown in bold. Excluded locations will be stricken out. Locations without ID will be shown in italics. Locked locations will be shown with a padlock icon. For filled locations, the item name will be shown after the location name. Progression items will be shown in bold. Items without ID will be shown in italics.

  • show_other_regions – (default True) If enabled, regions that can’t be reached by traversing exits are shown.

  • linetype_ortho – (default True) If enabled, orthogonal straight line parts will be used; otherwise polylines.

  • regions_to_highlight – Regions that will be highlighted in green if they are reachable.

Example usage in World code: from Utils import visualize_regions state = self.multiworld.get_all_state(False) state.update_reachable_regions(self.player) visualize_regions(self.get_region(“Menu”), “my_world.puml”, show_entrance_names=True,

regions_to_highlight=state.reachable_regions[self.player])

Example usage in Main code: from Utils import visualize_regions for player in multiworld.player_ids:

visualize_regions(multiworld.get_region(“Menu”, player), f”{multiworld.get_out_file_name_base(player)}.puml”)