Version 3.0.0

Also:
    - MSS: refactor, introducing the ScreenShot class and Numpy array interface support
    - More pythonic API (breaking the compatibility with version < 3.0.0)
    - More examples
    - Fixes BoboTiG#16.

Author: BoboTiG

.coafile

@@ -14,7 +14,7 @@ addons:
       - xserver-xorg-video-dummy
 
 before_install:
-  - xpra --xvfb="Xorg +extension RANDR -config `pwd`/tests/dummy.xorg.conf -logfile ${HOME}/.xpra/xorg.log" start :42
+  - xpra --xvfb="Xorg +extension RANDR -config `pwd`/tests/res/dummy.xorg.conf -logfile ${HOME}/.xpra/xorg.log" start :42
 
 install:
   - pip install flake8 pylint

.travis.yml

@@ -2,6 +2,14 @@ History:
 
 <see Git checkin messages for history>
 
+dev    2017/xx/xx
+
+
+3.0.0  2017/07/06
+      - big refactor, introducing the ScreenShot class
+      - add Numpy array interface support
+      - examples: add OpenCV/Numpy, PIL pixels, FPS
+
 2.0.22  2017/04/29
       - new contributors: David Becker, redodo
       - add an example to capture only a part of the screen

CHANGELOG

@@ -0,0 +1,27 @@
+3.0.0 (2017-07-06)
+==================
+
+base.py
+-------
+- Added the `ScreenShot` class containing data for a given screen shot (support the Numpy array interface [`ScreenShot.__array_interface__`])
+- Add `shot()` method to `MSSBase`. It takes the same arguments as the `save()` method.
+- Renamed `get_pixels` to `grab`. It now returns a `ScreenShot` object.
+- Moved `to_png` method to `tools.py`. It is now a simple function.
+- Removed `enum_display_monitors()` method. Use `monitors` property instead.
+- Removed `monitors` attribute. Use `monitors` property instead.
+- Removed `width` attribute. Use `ScreenShot.size[0]` attribute or `ScreenShot.width` property instead.
+- Removed `height` attribute. Use `ScreenShot.size[1]` attribute or `ScreenShot.height` property instead.
+- Removed `image`. Use the `ScreenShot.raw` attribute or `ScreenShot.rgb` property instead.
+- Removed `bgra_to_rgb()` method. Use `ScreenShot.rgb` property instead.
+
+darwin.py
+---------
+- Removed `_crop_width()` method. Screen shots are now using the width setted by the OS (rounded to 16).
+
+exception.py
+------------
+- Renamed `ScreenshotError` class to `ScreenShotError`
+
+tools.py
+--------
+- Changed signature of `to_png(data, monitor, output)` to `to_png(data, size, output)` where `size` is a `tuple(width, height)`

CHANGES.rst

@@ -4,17 +4,29 @@ Python MSS
 .. image:: https://travis-ci.org/BoboTiG/python-mss.svg?branch=dev
     :target: https://travis-ci.org/BoboTiG/python-mss
 
+
+.. code-block:: python
+
+    from mss import mss
+
+
+    # The simplest use, save a screenshot of the 1st monitor
+    with mss() as sct:
+        sct.shot()
+
+
 An ultra fast cross-platform multiple screenshots module in pure python using ctypes.
 
 - **Python 2 & 3** and PEP8 compliant, no dependency;
 - very basic, it will grab one screen shot by monitor or a screen shot of all monitors and save it to a PNG file;
 - but you can use PIL and benefit from all its formats (or add yours directly);
+- integrate well with Numpy and OpenCV;
 - it could be easily embedded into games and other softwares which require fast and plateforme optimized methods to grab screenshots;
 - get the `source code on GitHub <https://github.com/BoboTiG/python-mss>`_;
+- learn with a `bunch of examples <https://github.com/BoboTiG/python-mss/tree/master/examples>`_;
 - you can `report a bug <https://github.com/BoboTiG/python-mss/issues>`_;
 - and there is a `complete, and beautiful, documentation <https://python-mss.readthedocs.io>`_ :)
 - **MSS** stands for Multiple ScreenShots;
-- insanely fast, did I say it?
 
 
 Installation

README.rst

@@ -5,9 +5,6 @@ MSS API
 Classes
 =======
 
-``MSSBase`` is the parent's class for every OS implementation.
-
-
 GNU/Linux
 ---------
 
@@ -21,12 +18,12 @@ GNU/Linux
 
         GNU/Linux initializations.
 
+    .. method:: grab(monitor) -> ScreenShot
 
-    .. method:: get_pixels(monitor) -> bytes
-
-        :exception ScreenshotError: When color depth is not 32 (rare).
+        :exception ScreenShotError: When color depth is not 32 (rare).
+        :rtype: ScreenShot
 
-        See :attr:`mss.base.MSSBase.get_pixels` for details.
+        See :attr:`mss.base.MSSBase.grab` for details.
 
 
 Methods
@@ -36,104 +33,159 @@ Methods
 
 .. class:: MSSBase
 
-    .. method:: bgra_to_rgb(raw) -> bytes
+    The parent's class for every OS implementation.
 
-        :param bytearray raw: raw data containing BGRA values.
+    .. method:: grab(monitor) -> ScreenShot
 
-        It converts pixels values from BGRA to RGB.
-        This is the method called to populate :attr:`image` into :attr:`get_pixels`.
+        :param dict monitor: monitor's informations.
+        :exception NotImplementedError: Subclasses need to implement this.
+        :rtype: ScreenShot
 
+        Retrieve screen pixels for a given monitor.
 
-    .. method:: enum_display_monitors(force=False) -> list(dict)
+    .. method:: save(mon=1, output='screenshot.png', callback=None) -> generator
 
-        :param bool force: force rescan of monitors informations.
-        :exception NotImplementedError: Subclasses need to implement this.
+        :param int mon: the monitor's number.
+        :param str output: the output's file name. ``%d``, if present, will be replaced by the monitor number.
+        :param callable callback: callback called before saving the screenshot to a file. Takes the ``output`` argument as parameter.
+        :return generator: Created file(s).
 
-        Get positions of one or more monitors.
-        If the monitor has rotation, you have to deal with it inside this method.
+        Grab a screenshot and save it to a file.
 
-        This method has to fill :attr:`monitors` with all informations and use it as a cache:
+    .. method:: shot() -> str
 
-        - ``monitors[0]`` is a dict of all monitors together;
-        - ``monitors[N]`` is a dict of the monitor N (with N > 0).
+        :return str: The created file.
 
-        Each monitor is a dict with::
+        Helper to save the screenshot of the first monitor, by default.
+        You can pass the same arguments as for ``save``.
 
-            {
-                'left':   the x-coordinate of the upper-left corner,
-                'top':    the y-coordinate of the upper-left corner,
-                'width':  the width,
-                'height': the height
-            }
+.. class:: ScreenShot
 
+    Screen shot object.
 
-    .. method:: get_pixels(monitor) -> bytes
+    .. note::
 
-        :param dict monitor: monitor's informations generated by :attr:`enum_display_monitors()`.
-        :exception NotImplementedError: Subclasses need to implement this.
+        A better name would have been *Image*, but to prevent collisions
+        with ``PIL.Image``, it has been decided to use *ScreenShot*.
 
-        Retrieve screen pixels for a given monitor.
-        This method has to define :attr:`width` and :attr:`height`.
-        It stocks pixels data into :attr:`image` (RGB) and returns it.
+    .. classmethod:: from_size(cls, data, width, height) -> ScreenShot
 
+        :param bytearray data: raw BGRA pixels retrieved by ctype
+                               OS independent implementations.
+        :param int width: the monitor's width.
+        :param int height: the monitor's height.
+        :rtype: ScreenShot
 
-    .. method:: save(mon=0, output='monitor-%d.png', callback=None) -> generator
+        Instanciate a new class given only screenshot's data and size.
 
-        :param int mon: the monitor's number.
-        :param str output: the output's file name. ``%d``, if present, will be replaced by the monitor number.
-        :param callable callback: callback called before saving the screenshot to a file. Takes the ``output`` argument as parameter.
+    .. method:: pixels(coord_x, coord_y) -> Tuple[int, int, int]
+
+        :param int coord_x: The x coordinate.
+        :param int coord_y: The y coordinate.
+        :rtype: Tuple[int, int, int]
 
-        Grab a screenshot and save it to a file. This is a generator which returns created files.
+        Get the pixel value at the given position.
 
+.. module:: mss.tools
 
-    .. method:: to_png(data, output) -> None
+    .. method:: to_png(data, size, output) -> None
 
-        :param bytes data: raw pixels (RGBRGB...RGB) fom :attr:`get_pixels()`.
-        :param str output: output's file name.
-        :exception ScreenshotError: On error when writing ``data`` to ``output``.
+    :param bytes data: RGBRGB...RGB data.
+    :param tuple size: The (width, height) pair.
+    :param str output: output's file name.
+    :exception ScreenShotError: On error when writing ``data`` to ``output``.
 
-        Dump data to the image file. Pure Python PNG implementation.
+    Dump data to the image file. Pure Python PNG implementation.
 
 
-Attributes
+Properties
 ==========
 
 .. class:: MSSBase
 
-    .. attribute:: image
+    .. attribute:: monitors
 
-        :getter: Raw pixels of a monitor.
-        :setter: See :attr:`get_pixels`.
-        :type: bytes
+        Positions of all monitors.
+        If the monitor has rotation, you have to deal with it
+        inside this method.
 
+        This method has to fill ``self._monitors`` with all informations
+        and use it as a cache:
 
-    .. attribute:: monitors
+        - ``self._monitors[0]`` is a dict of all monitors together
+        - ``self._monitors[N]`` is a dict of the monitor N (with N > 0)
 
-        :getter: The list of all monitors.
-        :setter: See :attr:`enum_display_monitors()`.
-        :type: list(dict)
+        Each monitor is a dict with:
 
+        - ``left``: the x-coordinate of the upper-left corner
+        - ``top``: the y-coordinate of the upper-left corner
+        - ``width``: the width
+        - ``height``: the height
 
-    .. attribute:: width
+        :type:  List[Dict[str, int]]
+
+.. class:: ScreenShot
+
+    .. attribute:: __array_interface__()
+
+        Numpy array interface support. It uses raw data in BGRA form.
+
+        :type: Dict[str, Any]
 
-        :getter: Width of a monitor.
-        :setter: See :attr:`get_pixels()`.
+    .. attribute:: pos
+
+        The screen shot's coodinates.
+
+        :type: NamedTuple
+
+    .. attribute:: top
+
+        The screen shot's top coodinate.
+
+        :type: int
+
+    .. attribute:: left
+
+        The screen shot's left coodinate.
         :type: int
 
+    .. attribute:: size
+
+        The screen shot's size.
+
+        :type: NamedTuple
+
+    .. attribute:: width
+
+        The screen shot's width.
+
+        :type: int
 
     .. attribute:: height
 
-        :getter: Height of a monitor.
-        :setter: See :attr:`get_pixels()`.
+        The screen shot's height.
+
         :type: int
 
+    .. attribute:: pixels
+
+        List of RGB tuples.
+
+        :type: List[Tuple[int, int, int]]
+
+    .. attribute:: rgb
+
+        Computed RGB values from the BGRA raw pixels.
+
+        :type: bytes
+
 
 Exception
 =========
 
 .. module:: mss.exception
 
-.. exception:: ScreenshotError
+.. exception:: ScreenShotError
 
     Base class for MSS exceptions.
 

docs/source/api.rst

@@ -59,7 +59,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.0.21'
+version = '3.0.0'
 # The full version, including alpha/beta/rc tags.
 release = 'latest'