From b21b5cceb88419ee9c0ae5764f90f0b78fd2bd84 Mon Sep 17 00:00:00 2001
From: black-sliver <59490463+black-sliver@users.noreply.github.com>
Date: Sun, 25 Sep 2022 18:00:22 +0200
Subject: [PATCH] Doc, SoE: Logic mixin: no underscore for public members
 (#1049)

* Doc: logic mixin, drop underscore, clarify

conventionally, we added a leading underscore to logic mixins' function
names. This is noisy in the warning section of IDEs. Leading underscores
should only be used for private/protected functions.

In addition, the use of self.world and/or requirement to (no) pass in stuff
was not made clear earlier.

* SoE: fix _ warnings for logic mixin
---
 docs/world api.md      | 13 ++++++++-----
 worlds/soe/Logic.py    |  4 ++--
 worlds/soe/__init__.py |  4 ++--
 3 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/docs/world api.md b/docs/world api.md
index 0471cf1b..cf26cfd9 100644
--- a/docs/world api.md	
+++ b/docs/world api.md	
@@ -617,8 +617,10 @@ the name of the implementing world. This is due to sharing a namespace with all
 other logic mixins.
 
 Typical uses are defining methods that are used instead of `state.has`
-in lambdas, e.g.`state._mygame_has(custom, world, player)` or recurring checks
-like `state._mygame_can_do_something(world, player)` to simplify lambdas.
+in lambdas, e.g.`state.mygame_has(custom, player)` or recurring checks
+like `state.mygame_can_do_something(player)` to simplify lambdas.
+Private members, only accessible from mixins, should start with `_mygame_`,
+public members with `mygame_`.
 
 More advanced uses could be to add additional variables to the state object,
 override `World.collect(self, state, item)` and `remove(self, state, item)`
@@ -633,9 +635,10 @@ Please do this with caution and only when neccessary.
 from worlds.AutoWorld import LogicMixin
 
 class MyGameLogic(LogicMixin):
-    def _mygame_has_key(self, world: MultiWorld, player: int):
+    def mygame_has_key(self, player: int):
         # Arguments above are free to choose
-        # it may make sense to use World as argument instead of MultiWorld
+        # MultiWorld can be accessed through self.world, explicitly passing in
+        # MyGameWorld instance for easy options access is also a valid approach
         return self.has("key", player)  # or whatever
 ```
 ```python
@@ -648,7 +651,7 @@ class MyGameWorld(World):
     # ...
     def set_rules(self):
         set_rule(self.world.get_location("A Door", self.player),
-                 lamda state: state._mygame_has_key(self.world, self.player))
+                 lamda state: state.mygame_has_key(self.player))
 ```
 
 ### Generate Output
diff --git a/worlds/soe/Logic.py b/worlds/soe/Logic.py
index d08e6a3e..97c73a1b 100644
--- a/worlds/soe/Logic.py
+++ b/worlds/soe/Logic.py
@@ -35,7 +35,7 @@ class SecretOfEvermoreLogic(LogicMixin):
                 if pvd[1] == progress and pvd[0] > 0:
                     has = True
                     for req in rule.requires:
-                        if not self._soe_has(req[1], world, player, req[0]):
+                        if not self.soe_has(req[1], world, player, req[0]):
                             has = False
                             break
                     if has:
@@ -44,7 +44,7 @@ class SecretOfEvermoreLogic(LogicMixin):
                             return n
         return n
 
-    def _soe_has(self, progress: int, world: MultiWorld, player: int, count: int = 1) -> bool:
+    def soe_has(self, progress: int, world: MultiWorld, player: int, count: int = 1) -> bool:
         """
         Returns True if count of one of evermizer's progress steps is reached based on collected items. i.e. 2 * P_DE
         """
diff --git a/worlds/soe/__init__.py b/worlds/soe/__init__.py
index f86fc48e..a0dc41c3 100644
--- a/worlds/soe/__init__.py
+++ b/worlds/soe/__init__.py
@@ -283,7 +283,7 @@ class SoEWorld(World):
         self.world.completion_condition[self.player] = lambda state: state.has('Victory', self.player)
         # set Done from goal option once we have multiple goals
         set_rule(self.world.get_location('Done', self.player),
-                 lambda state: state._soe_has(pyevermizer.P_FINAL_BOSS, self.world, self.player))
+                 lambda state: state.soe_has(pyevermizer.P_FINAL_BOSS, self.world, self.player))
         set_rule(self.world.get_entrance('New Game', self.player), lambda state: True)
         for loc in _locations:
             location = self.world.get_location(loc.name, self.player)
@@ -292,7 +292,7 @@ class SoEWorld(World):
     def make_rule(self, requires: typing.List[typing.Tuple[int]]) -> typing.Callable[[typing.Any], bool]:
         def rule(state) -> bool:
             for count, progress in requires:
-                if not state._soe_has(progress, self.world, self.player, count):
+                if not state.soe_has(progress, self.world, self.player, count):
                     return False
             return True