feat(try_grab): clean up Python API and update readme

Author: modelflat

README.md

@@ -22,14 +22,14 @@ Alternatively, you can install suitable wheel from [releases page](https://githu
 from zbl import Capture
 
 with Capture(window_name='visual studio code') as cap:
-    frame = next(cap.frames())
-    print(frame.shape)
+    # grab a single frame (numpy.ndarray) and print its shape
+    print(cap.grab().shape)
 ```
 
-The snippet above will capture a window which title contains the string `visual studio code`, take one frame (which is represented as a `numpy` array) and print its shape.
+The snippet above will capture a window which title contains the string `visual studio code`,
+grab one frame and print its shape.
 
-See `Capture` constructor for more options. It is possible to capture the entire screen using `display_id` argument,
-for example.
+See [Capture](https://github.com/modelflat/zbl/blob/master/zbl_py/zbl/__init__.py) for other API methods.
 
 To run an example using OpenCV's `highgui`:
 

zbl_py/zbl/__init__.py

@@ -46,7 +46,13 @@ def __init__(
     def handle(self) -> int:
         return self._inner.handle()
 
-    def grab(self) -> Frame:
+    def grab(self) -> numpy.ndarray:
+        """
+        Same as `grab_raw`, but converts captured frame to numpy array.
+        """
+        return frame_to_numpy_array(self.grab_raw())
+
+    def grab_raw(self) -> Frame:
         """
         Grab the next frame from the capture.
 
@@ -55,7 +61,16 @@ def grab(self) -> Frame:
         """
         return self._inner.grab()
 
-    def try_grab(self) -> Optional[Frame]:
+    def try_grab(self) -> Optional[numpy.ndarray]:
+        """
+        Same as `try_grab_raw`, but converts captured frame to numpy array.
+        """
+        frame = self.try_grab_raw()
+        if frame is None:
+            return None
+        return frame_to_numpy_array(frame)
+
+    def try_grab_raw(self) -> Optional[Frame]:
         """
         Try grabbing the next frame from the capture.
 
@@ -64,16 +79,28 @@ def try_grab(self) -> Optional[Frame]:
         """
         return self._inner.try_grab()
 
-    def raw_frames(self) -> Iterator[Frame]:
+    def frames(self) -> Iterator[numpy.ndarray]:
+        """
+        Returns an iterator over numpy frames in this capture. 
+        """
+        for frame in self.frames_raw():
+            yield frame_to_numpy_array(frame)
+
+    def frames_raw(self) -> Iterator[Frame]:
+        """
+        Returns an iterator over frames in this capture.
+        """
         while True:
             try:
-                yield self.grab()
-            except StopIteration:
-                break
+                yield self.grab_raw()
+            except StopIteration as _:
+                return
 
-    def frames(self) -> Iterator[numpy.ndarray]:
-        for frame in self.raw_frames():
-            yield frame_to_numpy_array(frame)
+    def raw_frames(self) -> Iterator[Frame]:
+        """
+        Deprecated, prefer `frames_raw` instead.
+        """
+        yield from self.frames_raw()
 
     def __enter__(self) -> "Capture":
         self._inner.start()