From 009f1f34ed69c4b60733b8318c8ed877f8539e70 Mon Sep 17 00:00:00 2001
From: yashaka <yashaka@gmail.com>
Date: Mon, 3 Oct 2022 18:39:13 +0300
Subject: [PATCH] [#284] NEW: element.locate(), collection.locate()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

... as more human-readable aliases to element() and collection() correspondingly

also add entity.__raw__

It's a «dangled» property and so consider it an experimental/private feature.
For element and collection – it's same as `.locate()`.
For `browser` it's same as `.driver` ;)
---
 CHANGELOG.md          | 23 ++++++++++++++++--
 selene/core/entity.py | 54 ++++++++++++++++---------------------------
 2 files changed, 41 insertions(+), 36 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d17d0c81..060434da 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -91,9 +91,28 @@
 
 ### NEW: DEPRECATED: collection.filtered_by(condition) in favor of collection.by(condition)
 
-### NEW: BREAKING CHANGE: renamed collection.filtered_by_their(selector, condition) to collection.by_their(selector, condition) 
+### NEW: element.locate() -> WebElement, collection.locate() -> List[WebElement] [#284](https://github.com/yashaka/selene/issues/284)
 
-### NEW: BREAKING CHANGE: removed collection.should_each ... [#277](https://github.com/yashaka/selene/issues/277)
+... as more human-readable aliases to element() and collection() correspondingly
+
+### NEW: entity.__raw__
+
+It's a «dangled» property and so consider it an experimental/private feature. 
+For element and collection – it's same as `.locate()`.
+For `browser` it's same as `.driver` ;)
+
+Read more on it at this [comment to #284](https://github.com/yashaka/selene/issues/284#issuecomment-1265619606)
+
+... as aliases to element(), collection() correspondingly
+
+### NEW: BREAKING CHANGES
+
+#### removed earlier deprecated element.get_actual_webelement() in favor of element.locate()
+#### removed earlier collection.get_actual_webelements() in favor of collection.locate()
+
+#### renamed collection.filtered_by_their(selector, condition) to collection.by_their(selector, condition) 
+
+#### removed collection.should_each ... [#277](https://github.com/yashaka/selene/issues/277)
 
 - ... and ability to pass element_condition to `collection.should(HERE)`
 - Use instead: `collection.should(element_condition.each)`
diff --git a/selene/core/entity.py b/selene/core/entity.py
index 44d4bab2..a692874e 100644
--- a/selene/core/entity.py
+++ b/selene/core/entity.py
@@ -173,9 +173,16 @@ def with_(self, config: Config = None, **config_as_kwargs) -> Element:
     def __str__(self):
         return str(self._locator)
 
-    def __call__(self) -> WebElement:
+    def locate(self) -> WebElement:
         return self._locator()
 
+    @property
+    def __raw__(self):
+        return self.locate()
+
+    def __call__(self) -> WebElement:
+        return self.locate()
+
     # --- WaitingEntity --- #
 
     @property
@@ -563,38 +570,6 @@ def ss(self, css_or_xpath_or_by: Union[str, tuple]) -> Collection:
         #     SyntaxWarning)
         return self.all(css_or_xpath_or_by)
 
-    # TODO: consider renaming it to something more concise and handy in use...
-    #       some candidates:
-    #       * browser.element(...).get()
-    #         -- kind of tells that we get Element, not raw WebElement
-    #         + one of the concisest
-    #       * browser.element(...).find()
-    #         + tells that we actually finding something
-    #         - but a bit high-level for such low level thing like getting actual low-level webelement
-    #       * browser.element(...).locate()
-    #         ++ consistent with Element.locator
-    #         - not the concisest
-    #       * browser.element(...).raw
-    #         + !!! in fact it's "raw" in its nature, and the most concise
-    #         - maybe a bit "too technical", but for tech-guys probably pretty obvious
-    #           yeah, Selene is for users not for coders,
-    #           + but actual raw webelement is also not for users;)
-    #       * browser.element(...).__raw__
-    #         + same as .raw
-    #         + but emphasizing more its "technical" low level nature
-    #       - browser.element(...).invoke()
-    #         -- too technical
-    #       - browser.element(...).call()
-    #         -- we already have .__call__()
-    #         * and kind of similar to .invoke but more concise
-    def get_actual_webelement(self) -> WebElement:
-        warnings.warn(
-            "considering to be deprecated; use element as callable instead, like: browser.element('#foo')()",
-            PendingDeprecationWarning,
-        )
-
-        return self()
-
 
 class Collection(WaitingEntity, Iterable[Element]):
     def __init__(self, locator: Locator[List[WebElement]], config: Config):
@@ -609,9 +584,16 @@ def with_(self, config: Config = None, **config_as_kwargs) -> Collection:
     def __str__(self):
         return str(self._locator)
 
-    def __call__(self) -> List[WebElement]:
+    def locate(self) -> List[WebElement]:
         return self._locator()
 
+    @property
+    def __raw__(self):
+        return self.locate()
+
+    def __call__(self) -> List[WebElement]:
+        return self.locate()
+
     @property
     def cached(self) -> Collection:
         webelements = self()
@@ -1094,6 +1076,10 @@ def __str__(self):
     def driver(self) -> WebDriver:
         return self.config.driver
 
+    @property
+    def __raw__(self):
+        return self.config.driver
+
     # @property
     # def actions(self) -> ActionChains:
     #     """