[#530] REFACTOR: privatize Condition actual & by, make test positiona…

…l + ...

... DOCS: update condition.py docstrings guides

CHANGELOG.md

@@ -137,79 +137,32 @@ taking into account its callable based on Entity nature, and "name" vs "descript
 
 consider `str | Callable[[...], str]` vs `str | Callable[[...], str]` as type for name
 
-## 2.0.0rc10: «copy&paste, frames, shadow & texts_like» (to be released on DD.05.2024)
-
-### TODO: consider regex support via .pattern prop (similar to .ignore_case) (#537)
-
-### TODO: consider renaming Condition `test` arg to `match` for consistency with Match
-
-Compare current:
-
-```python
-from selene.core.condition import Condition, Match
-from selene.core.exceptions import ConditionMismatch
-
-has_positive_number = Condition(
-    'has positive number',
-    test=ConditionMismatch._to_raise_if_not(
-        actual=lambda entity: entity.number,
-        by=lambda number: number > 0,
-    )
-)
-# =>
-has_positive_number_ = Match(
-    'has positive number',
-    actual=lambda entity: entity.number,
-    by=lambda number: number > 0,
-)
-```
+### TODO: Can we ensure type errors on element.should(collection_condition), etc.?
 
-to:
+currently there are no type errors... :(
 
-```python
-from selene.core.condition import Condition, Match
-from selene.core.exceptions import ConditionMismatch
-
-has_positive_number = Condition(
-    'has positive number',
-    match=ConditionMismatch._to_raise_if_not(
-        actual=lambda entity: entity.number,
-        by=lambda number: number > 0,
-    )
-)
-# =>
-has_positive_number_ = Match(
-    'has positive number',
-    actual=lambda entity: entity.number,
-    by=lambda number: number > 0,
-)
-```
+check vscode pylance, mypy, jetbrains qodana...
 
-Then the reason of Match existence becomes easier to understand:)
-Who knows, maybe we even have to remove `actual` and by `args` of Condition, 
-or, at least, not remove, but make them private (`_actual`, `_by`) and reveal them for usage only in `Match` as `actual` and `by`...
+### TODO: consider renaming _describe_actual_result to _describe_actual and...
 
-Then we have to consider rething condition.__call__ aliases... And corresponding `test` vs `match` naming...  We have some kind of conflict between `entity.matching(condition)` and `condition.match(entity)`, because the term is same, but meaning different – predicate vs assertion... But also the gramatic form is different `*ing` vs `*`... So maybe it's ok...
+... providing `lambda it: it` as default to actual
+... and so making _describe_actual work also when actual is not provided
 
-`Test` might be also a good candidate over `Match` ... But `Test` does not correlate in `entity.should(Test(actual=..., by=...))
+(speaking about all: ConditionMismatch, Condition, Match...)
 
-### TODO: Ensure no type errors on element.should(collection_condition), etc.
+### TODO: consider removing experimantal mark from `ConditionMismatch._to_raise_if_not`
 
-check vscode pylance, mypy, jetbrains qodana...
+## 2.0.0rc10: «copy&paste, frames, shadow & texts_like» (to be released on DD.05.2024)
 
-### TODO: check if there are no type errors on passing be._empty to should
+### TODO: consider regex support via .pattern prop (similar to .ignore_case) (#537)
 
 ### TODO: decide on ... vs (...,) as one_or_more
 
 consider customizing them via config
 
-### TODO: Consider passing Condition instance as by in Match
-
-like in `clickable = Match('clickable', by=be.visible.and_(be.enabled))`
-
-### TODO: Consider privatizing Condition actual and by params
+### TODO: when to Match we pass by as Condition, that has its own _falsy_exceptions...
 
-should we even refactor out them from Condition and move to Match only?
+should not we take them to set below, or at least override our default?
 
 ### Deprecated conditions
 

docs/reference/exceptions.md

@@ -5,7 +5,7 @@
 ::: selene.core.exceptions
     options:
         show_root_toc_entry: false
-        show_if_no_docstring: false
+        show_if_no_docstring: true
         members_order: alphabetical
         filters:
             - "!__.*"

docs/reference/match.md

@@ -0,0 +1,17 @@
+#
+
+{% include-markdown 'warn-from-next-release.md' %}
+
+::: selene.core.match
+    options:
+        show_root_toc_entry: false
+        show_if_no_docstring: true
+        members_order: alphabetical
+        filters:
+            - "!E$"
+            - "!__.*"
+            - "!_step"
+            - "!_steps"
+            - "!_inner"
+            - "!_inside"
+            - "!_content"

mkdocs.yml

@@ -28,6 +28,7 @@ nav:
     - Config: reference/configuration.md
     - command.*: reference/command.md
     - query.*: reference/query.md
+    - match.* predefined conditions: reference/match.md
     - Expected Conditions: reference/condition.md
     - Selene Exceptions: reference/exceptions.md
   - Contribution: