MSS: Add more way of customization to the output argument of save()

BoboTiG · web-flow · commit 0057532efc7a · 2017-11-27T20:39:54.000+01:00
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,11 +1,12 @@
 History:
 
-<see Git checkin messages for history>
+<see Git checking messages for history>
 
 dev     2017/xx/xx
       - add the 'Say Thanks' button
       - doc: several fixes (fix #22)
       - tests: a lot of tests added for better coverage
+      - MSS: add more way of customization to the output argument of save()
       - MSS: possibility to use custom class to handle screen shot data
       - Mac: handle screenshot's width not divisible by 16 (fix #14, #19, #21)
       - Mac: properly support all display scaling and resolutions (fix #23)
@@ -51,10 +52,10 @@ dev     2017/xx/xx
       - Linux: prevent segfault when DISPLAY is set but no X server started
       - Linux: prevent segfault when Xrandr is not loaded
       - Linux: get_pixels() insanely fast, use of MSS library (C code)
-      - Windows: fix #6, screenshot not correct on Windows 8
+      - Windows: fix #6, screen shot not correct on Windows 8
 
 1.0.2   2016/04/22
-      - MSS: fix inexistant alias
+      - MSS: fix non existent alias
 
 1.0.1   2016/04/22
       - MSS: fix #7, libpng warning (ignoring bad filter type)
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -37,7 +37,7 @@ Methods
 
     .. method:: grab(monitor) -> ScreenShot
 
-        :param dict monitor: monitor's informations.
+        :param dict monitor: monitor's information.
         :exception NotImplementedError: Subclasses need to implement this.
         :rtype: ScreenShot
 
@@ -46,22 +46,32 @@ Methods
         .. note::
 
             ``monitor`` can be a ``tuple`` like ``PIL.Image.grab()`` accepts,
-            it will be converted to the approriate ``dict``.
+            it will be converted to the appropriate ``dict``.
 
-    .. method:: save(mon=1, output='screenshot.png', callback=None) -> generator
+    .. method:: save(mon=1, output='mon-{mon}.png', callback=None) -> generator
 
         :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.
+        :param str output: the output's file name.
+        :param callable callback: callback called before saving the screen shot to a file. Takes the ``output`` argument as parameter.
         :return generator: Created file(s).
 
-        Grab a screenshot and save it to a file.
+        Grab a screen shot and save it to a file.
+        The ``output`` parameter can take several keywords to customize the filename:
+
+            - ``{mon}``: the monitor number
+            - ``{top}``: the screen shot y-coordinate of the upper-left corner
+            - ``{left}``: the screen shot x-coordinate of the upper-left corner
+            - ``{width}``: the screen shot's width
+            - ``{height}``: the screen shot's height
+            - ``{date}``: the current date using the default formatter
+
+        As it is using the `py::format()` function, you can specify formatting options like ``{date:%Y-%m-%s}``.
 
     .. method:: shot() -> str
 
         :return str: The created file.
 
-        Helper to save the screenshot of the first monitor, by default.
+        Helper to save the screen shot of the first monitor, by default.
         You can pass the same arguments as for ``save``.
 
         .. versionadded:: 3.0.0
@@ -83,7 +93,7 @@ Methods
         :param int height: the monitor's height.
         :rtype: ScreenShot
 
-        Instanciate a new class given only screenshot's data and size.
+        Instanciate a new class given only screen shot's data and size.
 
     .. method:: pixels(coord_x, coord_y) -> Tuple[int, int, int]
 
@@ -120,7 +130,7 @@ Properties
         If the monitor has rotation, you have to deal with it
         inside this method.
 
-        This method has to fill ``self._monitors`` with all informations
+        This method has to fill ``self._monitors`` with all information
         and use it as a cache:
 
         - ``self._monitors[0]`` is a dict of all monitors together
@@ -145,19 +155,19 @@ Properties
 
     .. attribute:: pos
 
-        The screen shot's coodinates.
+        The screen shot's coordinates.
 
         :type: NamedTuple
 
     .. attribute:: top
 
-        The screen shot's top coodinate.
+        The screen shot's top coordinate.
 
         :type: int
 
     .. attribute:: left
 
-        The screen shot's left coodinate.
+        The screen shot's left coordinate.
         :type: int
 
     .. attribute:: size
diff --git a/docs/source/developers.rst b/docs/source/developers.rst
@@ -33,7 +33,7 @@ Enable the developer mode::
 
     $ python -m pip install -e .
 
-Lauch the test suit::
+Launch the test suit::
 
     $ py.test
 
diff --git a/docs/source/examples/callback.py b/docs/source/examples/callback.py
@@ -25,5 +25,5 @@ def on_exists(fname):
 
 
 with mss.mss() as sct:
-    filename = sct.shot(output='mon-%d.png', callback=on_exists)
+    filename = sct.shot(output='mon-{mon}.png', callback=on_exists)
     print(filename)
diff --git a/docs/source/examples/custom_cls_image.py b/docs/source/examples/custom_cls_image.py
@@ -16,7 +16,7 @@ class SimpleScreenShot(object):
     or add new methods.
     """
 
-    def __init__(self, data, monitor):
+    def __init__(self, data, monitor, **kwargs):
         self.data = data
         self.monitor = monitor
 
diff --git a/docs/source/support.rst b/docs/source/support.rst
@@ -11,7 +11,7 @@ Feel free to try MSS on a system we had not tested, and let report us by creatin
 +----------+-----------+-------------+-----------+
 | **3.6**  | **True**  | **True**    | **True**  |
 +----------+-----------+-------------+-----------+
-|   3.5    | True      | True        | True      |
+| 3.5      | True      | True        | True      |
 +----------+-----------+-------------+-----------+
 | 3.4      | True      | True        | True      |
 +----------+-----------+-------------+-----------+
@@ -31,7 +31,7 @@ Future
 Others
 ======
 
-Tested succesfully on Pypy 5.1.0 on Windows, but speed is terrible.
+Tested successfully on Pypy 5.1.0 on Windows, but speed is terrible.
 
 
 Abandoned
diff --git a/docs/source/where.rst b/docs/source/where.rst
@@ -9,4 +9,4 @@ This is a non exhaustive list where MSS is integrated or has inspired:
     - `NativeShot <https://addons.mozilla.org/en-US/firefox/addon/nativeshot/>`_ (Mozilla Firefox module);
     - `Pombo <https://github.com/BoboTiG/pombo>`_;
     - `Stitch <https://nathanlopez.github.io/Stitch/>`_, a Python Remote Administration Tool (RAT);
-    - `and you pherhaps? <https://github.com/BoboTiG/python-mss/issues>`_
+    - `and you perhaps? <https://github.com/BoboTiG/python-mss/issues>`_
diff --git a/mss/base.py b/mss/base.py
@@ -4,6 +4,8 @@
 Source: https://github.com/BoboTiG/python-mss
 """
 
+from datetime import datetime
+
 from .exception import ScreenShotError
 from .screenshot import ScreenShot
 from .tools import to_png
@@ -59,28 +61,36 @@ def monitors(self):
         }
 
         Note: monitor can be a tuple like PIL.Image.grab() accepts,
-        it must be converted to the approriate dict.
+        it must be converted to the appropriate dict.
         """
 
         raise NotImplementedError('Subclasses need to implement this!')
 
-    def save(self, mon=0, output='monitor-%d.png', callback=None):
+    def save(self, mon=0, output='monitor-{mon}.png', callback=None):
         # type: (int, str, Callable[[str], None]) -> Iterator[str]
         """
-        Grab a screenshot and save it to a file.
+        Grab a screen shot and save it to a file.
 
-        :param int mon: The monitor to screenshot (default=0).
-                        -1: grab one screenshot of all monitors
-                         0: grab one screenshot by monitor
-                        N: grab the screenshot of the monitor N
+        :param int mon: The monitor to screen shot (default=0).
+                        -1: grab one screen shot of all monitors
+                         0: grab one screen shot by monitor
+                        N: grab the screen shot of the monitor N
 
         :param str output: The output filename.
-                           %d, if present, will be replaced by
-                           the monitor number.
 
-        :param callable callback: Callback called before saving
-                                  the screenshot to a file.
-                                  Take the ``output`` argument as parameter.
+            It can take several keywords to customize the filename:
+            - `{mon}`: the monitor number
+            - `{top}`: the screen shot y-coordinate of the upper-left corner
+            - `{left}`: the screen shot x-coordinate of the upper-left corner
+            - `{width}`: the screen shot's width
+            - `{height}`: the screen shot's height
+            - `{date}`: the current date using the default formatter
+
+            As it is using the `format()` function, you can specify
+            formatting options like `{date:%Y-%m-%s}`.
+
+        :param callable callback: Callback called before saving the
+            screen shot to a file.  Take the `output` argument as parameter.
 
         :return generator: Created file(s).
         """
@@ -90,27 +100,24 @@ def save(self, mon=0, output='monitor-%d.png', callback=None):
             raise ScreenShotError('No monitor found.')
 
         if mon == 0:
-            # One screenshot by monitor
-            for i, monitor in enumerate(monitors[1:], 1):
-                fname = output
-                if '%d' in output:
-                    fname = output.replace('%d', str(i))
+            # One screen shot by monitor
+            for idx, monitor in enumerate(monitors[1:], 1):
+                fname = output.format(mon=idx, date=datetime.now(), **monitor)
                 if callable(callback):
                     callback(fname)
                 sct = self.grab(monitor)
                 to_png(sct.rgb, sct.size, fname)
                 yield fname
         else:
-            # A screenshot of all monitors together or
-            # a screenshot of the monitor N.
-            mon_number = 0 if mon == -1 else mon
+            # A screen shot of all monitors together or
+            # a screen shot of the monitor N.
+            mon = 0 if mon == -1 else mon
             try:
-                monitor = monitors[mon_number]
+                monitor = monitors[mon]
             except IndexError:
                 raise ScreenShotError('Monitor does not exist.', locals())
 
-            if '%d' in output:
-                output = output.replace('%d', str(mon_number))
+            output = output.format(mon=mon, date=datetime.now(), **monitor)
             if callable(callback):
                 callback(output)
             sct = self.grab(monitor)
@@ -119,7 +126,7 @@ def save(self, mon=0, output='monitor-%d.png', callback=None):
 
     def shot(self, **kwargs):
         """
-        Helper to save the screenshot of the 1st monitor, by default.
+        Helper to save the screen shot of the 1st monitor, by default.
         You can pass the same arguments as for ``save``.
         """
 
diff --git a/mss/screenshot.py b/mss/screenshot.py
@@ -68,33 +68,33 @@ def __array_interface__(self):
     @classmethod
     def from_size(cls, data, width, height):
         # type: (bytearray, int, int) -> ScreenShot
-        """ Instanciate a new class given only screenshot's data and size. """
+        """ Instantiate a new class given only screen shot's data and size. """
 
         monitor = {'left': 0, 'top': 0, 'width': width, 'height': height}
         return cls(data, monitor)
 
     @property
     def top(self):
         # type: () -> int
-        """ Conveniant accessor to the top position. """
+        """ Convenient accessor to the top position. """
         return self.pos.top
 
     @property
     def left(self):
         # type: () -> int
-        """ Conveniant accessor to the left position. """
+        """ Convenient accessor to the left position. """
         return self.pos.left
 
     @property
     def width(self):
         # type: () -> int
-        """ Conveniant accessor to the width size. """
+        """ Convenient accessor to the width size. """
         return self.size.width
 
     @property
     def height(self):
         # type: () -> int
-        """ Conveniant accessor to the height size. """
+        """ Convenient accessor to the height size. """
         return self.size.height
 
     @property
diff --git a/tests/test_save.py b/tests/test_save.py
@@ -1,7 +1,7 @@
 # coding: utf-8
 
 import os.path
-import mss
+from datetime import datetime
 
 
 def test_at_least_2_monitors(sct):
@@ -31,3 +31,23 @@ def on_exists(fname):
 
     filename = sct.shot(output='mon1.png', callback=on_exists)
     assert os.path.isfile(filename)
+
+
+def test_output_format(sct):
+    filename = sct.shot(mon=1, output='mon-{mon}.png')
+    assert filename == 'mon-1.png'
+    assert os.path.isfile(filename)
+
+    fmt = 'sct-{top}x{left}_{width}x{height}.png'
+    filename = sct.shot(mon=1, output=fmt)
+    assert filename == fmt.format(**sct.monitors[1])
+    assert os.path.isfile(filename)
+
+    fmt = 'sct_{mon}-{date}.png'
+    filename = sct.shot(mon=1, output=fmt)
+    assert os.path.isfile(filename)
+
+    fmt = 'sct_{date:%Y-%m-%d}.png'
+    filename = sct.shot(mon=1, output=fmt)
+    assert filename == fmt.format(date=datetime.now())
+    assert os.path.isfile(filename)
