callbacks refactor

README.md

@@ -163,6 +163,8 @@ pip install geneticalgorithm2[full]
 - host the [code documentation](https://pasaopasen.github.io/geneticalgorithm2/)
 - rename `geneticalgorithm2` class to `GeneticAlgorithm2`
 - substantial package architecture refactor
+- add more docstrings
+- reduce documentation duplicates 
 
 ## 6.8.7 minor update
 
@@ -1308,7 +1310,7 @@ It's very simple to create your own `action` and `condition` functions. But ther
   * `ChangeRandomCrossover(available_crossovers: Sequence[Callable[[np.ndarray, np.ndarray], Tuple[np.ndarray, np.ndarray]]])` -- change another (random) crossover from list of crossovers
   * `ChangeRandomSelection(available_selections: Sequence[Callable[[np.ndarray, int], np.ndarray]])`
   * `ChangeRandomMutation(available_mutations: Sequence[Callable[[float, float, float], float]])`
-  * `RemoveDuplicates(oppositor = None, creator = None, converter = None)`; see [doc](geneticalgorithm2/callbacks.py)
+  * `RemoveDuplicates(oppositor = None, creator = None, converter = None)`; see [doc](geneticalgorithm2/callbacks/middle.py)
   * `CopyBest(by_indexes)` -- copies best population object values (from dimensions in `by_indexes`) to all population
   * `PlotPopulationScores(title_pattern = lambda data: f"Generation {data['current_generation']}", save_as_name_pattern = None)` -- plot population scores; needs 2 functions like `data`->string for title and file name (to save)
 * `conditions`:

geneticalgorithm2/callbacks/__init__.py

@@ -0,0 +1,4 @@
+
+from .data import MiddleCallbackFunc, SimpleCallbackFunc, MiddleCallbackData
+from .simple import Callbacks
+from .middle import MiddleCallbacks, Actions, ActionConditions

geneticalgorithm2/callbacks/data.py

@@ -0,0 +1,70 @@
+from typing import Optional, List, Callable, Tuple
+
+from dataclasses import dataclass
+from typing_extensions import TypeAlias
+
+from ..crossovers import CrossoverFunc
+
+from ..mutations import MutationFloatFunc, MutationIntFunc
+from ..selections import SelectionFunc
+from ..utils.aliases import array2D, array1D
+
+from ..data_types.generation import Generation
+from ..data_types.base import DictLikeGetSet
+
+
+@dataclass
+class MiddleCallbackData(DictLikeGetSet):
+    """
+    data object using in middle callbacks
+    """
+
+    # TODO use slots?
+
+    reason_to_stop: Optional[str]
+
+    last_generation: Generation
+
+    current_generation: int
+    report_list: List[float]
+
+    mutation_prob: float
+    mutation_discrete_prob: float
+
+    mutation: MutationFloatFunc
+    mutation_discrete: MutationIntFunc
+    crossover: CrossoverFunc
+    selection: SelectionFunc
+
+    current_stagnation: int
+    max_stagnation: int
+
+    parents_portion: float
+    elit_ratio: float
+
+    set_function: Callable[[array2D], array1D]
+
+
+SimpleCallbackFunc: TypeAlias = Callable[[int, List[float], array2D, array1D], None]
+"""
+Callback function perform any operations on 
+    (generation number, best scores report list, last population matrix, last scores vector)
+
+Notes: generation number cannot be changed
+"""
+
+MiddleCallbackConditionFunc: TypeAlias = Callable[[MiddleCallbackData], bool]
+"""Function (middle callback data) -> (bool value means whether to call middle callback action)"""
+
+
+MiddleCallbackActionFunc: TypeAlias = Callable[[MiddleCallbackData], MiddleCallbackData]
+"""Function which transforms and returns middle callback data or just uses it some way"""
+
+
+MiddleCallbackFunc: TypeAlias = Callable[[MiddleCallbackData], Tuple[MiddleCallbackData, bool]]
+"""
+Function (input middle callback data) -> (output callback data, changes flag)
+    where input and output data may be same 
+    and changes flag means whether the output data must be read back
+        to the optimization process (to update by flag only one time -- for acceleration purposes)
+"""