refactor: clarify scope rules. (Fixes #594)

cliboa/core/model.py

@@ -53,7 +53,7 @@ def _exec_shell_cmd(self, cmd: str):
 
     def _merge_static_vars(self, data: dict[str, str]) -> None:
         """
-        merge calc result
+        merge calc result (not overwrite)
         """
         self._with_static_vars = data | self._with_static_vars
 
@@ -92,6 +92,7 @@ def get_listeners(self) -> list[str]:
     def replace_vars(self) -> None:
         """
         Replace variable expressions in arguments.
+        This is need to be called after call calc.
         """
         self.arguments = self._replace_arguments(self.arguments)
 
@@ -134,6 +135,9 @@ class ParallelConfigModel(BaseModel):
     force_continue: bool | None = None
 
     def merge(self, model: Self) -> None:
+        """
+        Merge model's props (only when self value is None)
+        """
         if not isinstance(model, ParallelConfigModel):
             return
         for k, v in self.model_dump().items():
@@ -143,6 +147,9 @@ def merge(self, model: Self) -> None:
                     setattr(self, k, r)
 
     def fill_default(self) -> Self:
+        """
+        Set defalut values if they are None
+        """
         if self.multi_process_count is None:
             self.multi_process_count = 2
         if self.force_continue is None:
@@ -156,6 +163,9 @@ class ParallelStepModel(BaseModel):
     parallel_config: ParallelConfigModel = Field(default_factory=ParallelConfigModel)
 
     def _merge_parallel_config(self, data: ParallelConfigModel) -> None:
+        """
+        merge ParallelConfig to under this model.
+        """
         if not isinstance(data, ParallelConfigModel):
             return
         self.parallel_config.merge(data)
@@ -192,9 +202,17 @@ def _merge_step(self, step: StepModel, cmn: Self) -> None:
             return
 
     def setup(self) -> None:
+        """
+        Prepare to use scenario.
+
+        1. calc scenario's with_vars
+        2. calc step's  with_vars
+        3. propagate calculated with_vars and parallel_config from scenario to steps
+        4. replace step's arguments with calculated with_vars
+        """
         self.calc()
         self._calc_steps()
-        self.propagate()
+        self._propagate()
         self._replace_vars_steps()
 
     def _apply_steps(self, func: str, *args, **kwargs) -> None:
@@ -216,7 +234,7 @@ def _calc_steps(self) -> None:
         """
         self._apply_steps("calc")
 
-    def propagate(self) -> None:
+    def _propagate(self) -> None:
         """
         merge _with_static_vars and parallel_config to scenario steps.
         """

cliboa/listener/step.py

@@ -52,7 +52,7 @@ def before(self, step: AbstractStep) -> None:
             args = props_values.pop("_args")
             props_values.update(args.model_dump())
         for k, v in props_values.items():
-            if k in ("_di_map", "_di_kwargs", "_parent", "_args"):
+            if k in ("_di_map", "_di_kwargs", "_logger", "_parent", "_args"):
                 continue
             if v is not None and self._pattern is not None and self._pattern.search(k):
                 props_dict[k] = "****"

cliboa/util/state.py

@@ -1,4 +1,4 @@
-class StateManager:
+class _StateManager:
     def __init__(self):
         self._state: str = "_Initialized"
         self._steps_max: int = 0
@@ -37,4 +37,4 @@ def set_in_steps(self, value: bool):
         self._in_steps = value
 
 
-state = StateManager()
+state = _StateManager()

docs/developers/coding_style_guide.md

@@ -4,3 +4,21 @@ The coding style guide of cliboa refers to [Google Python Style Guide](https://g
 
 Basically, passing checks with black, isort, and flake8 is sufficient.
 Minimize and avoid global state as much as possible, and aim for naming conventions where the role is clear from the name.
+
+## Scope rules
+
+Cliboa references [PEP 8](https://peps.python.org/pep-0008/) regarding scope definitions.
+
+The definitions are as follows:
+
+- **Public classes and methods:** Any class or method that is not marked as private.
+- **Private classes and methods:** Names starting with an underscore (`_`).
+
+### Access Restrictions
+
+* **Private properties (including methods) of a public class:** For internal Cliboa use only.
+* **Private classes and methods:** For internal Cliboa use only.
+* **Private properties (including methods) of a private class:** Accessed only from within the class itself.
+
+> **Note on "Internal Cliboa use only":**
+> These interfaces are considered non-public APIs. They may be changed without notice or a major version update.