Version 2.0.22

.gitignore

@@ -2,6 +2,7 @@ build/
 .cache/
 dist/
 *.egg-info/
+.idea/
 MANIFEST*
 .DS_Store
 *.orig

.travis.yml

@@ -4,8 +4,8 @@ python:
   - 3.3
   - 3.4
   - 3.5
-  - 3.6-dev
-  - nightly # currently points to 3.7-dev
+  - 3.6
+#  - nightly # currently points to 3.7-dev
 
 addons:
   apt:
@@ -22,7 +22,7 @@ install:
 
 script:
   - py.test --display=":42.0"
-  - flake8
+  - flake8 mss
   - pylint mss
 
 after_script:

CHANGELOG

@@ -2,6 +2,13 @@ History:
 
 <see Git checkin messages for history>
 
+2.0.22  2017/04/29
+      - new contributors: David Becker, redodo
+      - add an example to capture only a part of the screen
+      - better use of exception mechanism
+      - Linux: use of hasattr to prevent Exception on early exit
+      - Mac: take into account extra black pixels added when screen with is not divisible by 16 (fix #14)
+
 2.0.18  2016/12/03
       - change license to MIT
       - new contributor: Jochen 'cycomanic' Schroeder

CONTRIBUTORS

@@ -15,6 +15,9 @@ bubulle [http://indexerror.net/user/bubulle]
 Condé 'Eownis' Titouan <[email protected]> <[email protected]> [https://titouan.co]
     - MacOS X tester
 
+David Becker [https://davide.me] and redodo [https://github.com/redodo]
+    - Mac: Take into account extra black pixels added when screen with is not divisible by 16
+
 Jochen 'cycomanic' Schroeder [https://github.com/cycomanic]
     - GNU/Linux: use errcheck instead of deprecated restype with callable, for enum_display_monitors()
 

LICENSE

@@ -1,5 +1,5 @@
 MIT License
-Copyright (c) 2016, Mickaël 'Tiger-222' Schoentgen
+Copyright (c) 2016-2017, Mickaël 'Tiger-222' Schoentgen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

docs/source/conf.py

@@ -51,15 +51,15 @@
 
 # General information about the project.
 project = 'Python MSS'
-copyright = '2016, Tiger-222'
+copyright = '2013-2017, Tiger-222'
 author = 'Tiger-222'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.0.18'
+version = '2.0.21'
 # The full version, including alpha/beta/rc tags.
 release = 'latest'
 
@@ -319,7 +319,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'PythonMSS', 'Python MSS Documentation',
-     author, 'PythonMSS', 'One line description of project.',
+     author, 'PythonMSS', 'An ultra fast cross-platform multiple screenshots module in pure python using ctypes.',
      'Miscellaneous'),
 ]
 

docs/source/examples.rst

@@ -130,3 +130,20 @@ This is an example using `frombytes() <http://pillow.readthedocs.io/en/latest/re
 
             # And save it!
             img.save('monitor-{0}.jpg'.format(num))
+
+
+Part of the screen
+==================
+
+You can capture only a part of the screen::
+
+    from mss import mss
+
+
+    with mss() as sct:
+        # The screen part to capture
+        mon = {'top': 160, 'left': 160, 'width': 222, 'height': 42}
+
+        # Save the picture
+        output = 'sct-{top}x{left}_{width}x{height}.png'.format(**mon)
+        sct.to_png(sct.get_pixels(mon), output)

examples/callback.py

@@ -1,8 +1,7 @@
-#!/usr/bin/env python
 # coding: utf-8
-''' This is part of the MSS Python's module.
+""" This is part of the MSS Python's module.
     Source: https://github.com/BoboTiG/python-mss
-'''
+"""
 
 from os import rename
 from os.path import isfile
@@ -13,13 +12,13 @@
 
 def main():
     # type: () -> int
-    ''' Usage example. '''
+    """ Usage example. """
 
     def on_exists(fname):
         # type: (str) -> None
-        ''' Callback example when we try to overwrite an existing
+        """ Callback example when we try to overwrite an existing
             screenshot.
-        '''
+        """
 
         if isfile(fname):
             newfile = fname + '.old'
@@ -28,8 +27,7 @@ def on_exists(fname):
 
     try:
         with mss() as sct:
-            # For MacOS X only
-            # sct.max_displays = 32
+            # sct.max_displays = 32  # macOS only
 
             print('One screenshot per monitor')
             for filename in sct.save():

examples/linux-display_keyword.py

@@ -1,16 +1,15 @@
-#!/usr/bin/env python
 # coding: utf-8
-''' This is part of the MSS Python's module.
+""" This is part of the MSS Python's module.
     Source: https://github.com/BoboTiG/python-mss
-'''
+"""
 
 from mss.exception import ScreenshotError
 from mss.linux import MSS
 
 
 def main():
     # type: () -> int
-    ''' Usage example with a specific display. '''
+    """ Usage example with a specific display. """
 
     display = ':0.0'
     print('Screenshot of display "{0}"'.format(display))

examples/part-of-screen.py

@@ -0,0 +1,32 @@
+# coding: utf-8
+""" This is part of the MSS Python's module.
+    Source: https://github.com/BoboTiG/python-mss
+"""
+
+from mss.exception import ScreenshotError
+from mss import mss
+
+
+def main():
+    # type: () -> int
+    """ Example to capture part of the screen. """
+
+    try:
+        with mss() as sct:
+            # The screen part to capture
+            mon = {'top': 160, 'left': 160, 'width': 160, 'height': 135}
+
+            # Save the picture
+            output = 'sct-{top}x{left}_{width}x{height}.png'.format(**mon)
+            sct.to_png(sct.get_pixels(mon), output)
+            print(output)
+
+            return 0
+    except ScreenshotError as ex:
+        print(ex)
+
+    return 1
+
+
+if __name__ == '__main__':
+    exit(main())

examples/pil.py

@@ -1,8 +1,7 @@
-#!/usr/bin/env python
 # coding: utf-8
-''' This is part of the MSS Python's module.
+""" This is part of the MSS Python's module.
     Source: https://github.com/BoboTiG/python-mss
-'''
+"""
 
 from mss.exception import ScreenshotError
 from mss.factory import mss
@@ -11,7 +10,7 @@
 
 def main():
     # type: () -> int
-    ''' PIL example using frombytes(). '''
+    """ PIL example using frombytes(). """
 
     try:
         with mss() as sct:
@@ -25,7 +24,7 @@ def main():
                 # and raw pixels into `image`.
                 sct.get_pixels(monitor)
 
-                # Create an Image:
+                # Create an Image
                 size = (sct.width, sct.height)
                 img = Image.frombytes('RGB', size, sct.image)
 

mss/__init__.py

@@ -1,28 +1,27 @@
-#!/usr/bin/env python
 # coding: utf-8
-''' An ultra fast cross-platform multiple screenshots module in pure python
+""" An ultra fast cross-platform multiple screenshots module in pure python
     using ctypes.
 
     This module is maintained by Mickaël Schoentgen <[email protected]>.
 
     You can always get the latest version of this module at:
         https://github.com/BoboTiG/python-mss
     If that URL should fail, try contacting the author.
-'''
+"""
 
 from .exception import ScreenshotError
 from .factory import mss
 
-__version__ = '2.0.18'
+__version__ = '2.0.22'
 __author__ = "Mickaël 'Tiger-222' Schoentgen"
-__copyright__ = '''
-    Copyright (c) 2013-2016, Mickaël 'Tiger-222' Schoentgen
+__copyright__ = """
+    Copyright (c) 2013-2017, Mickaël 'Tiger-222' Schoentgen
 
     Permission to use, copy, modify, and distribute this software and its
     documentation for any purpose and without fee or royalty is hereby
     granted, provided that the above copyright notice appear in all copies
     and that both that copyright notice and this permission notice appear
     in supporting documentation or portions thereof, including
     modifications, that you make.
-'''
+"""
 __all__ = ['ScreenshotError', 'mss']

mss/__main__.py

@@ -0,0 +1,20 @@
+# coding: utf-8
+""" This is part of the MSS Python's module.
+    Source: https://github.com/BoboTiG/python-mss
+"""
+
+from __future__ import print_function
+
+from .factory import mss
+
+
+def main():
+    """ Main logic. """
+
+    with mss() as sct:
+        for file_name in sct.save():
+            print(file_name)
+
+
+if __name__ == '__main__':
+    exit(main())

mss/base.py

@@ -1,8 +1,7 @@
-#!/usr/bin/env python
 # coding: utf-8
-''' This is part of the MSS Python's module.
+""" This is part of the MSS Python's module.
     Source: https://github.com/BoboTiG/python-mss
-'''
+"""
 
 from struct import pack
 from zlib import compress, crc32
@@ -12,30 +11,30 @@
 
 # C'est parti mon kiki !
 class MSSBase(object):
-    ''' This class will be overloaded by a system specific one. '''
+    """ This class will be overloaded by a system specific one. """
 
     monitors = []
     image = None
     width = 0
     height = 0
 
     def __enter__(self):
-        ''' For the cool call `with MSS() as mss:`. '''
+        """ For the cool call `with MSS() as mss:`. """
 
         return self
 
     def __exit__(self, *_):
-        ''' For the cool call `with MSS() as mss:`. '''
+        """ For the cool call `with MSS() as mss:`. """
 
     def bgra_to_rgb(self, raw):
-        ''' Converts pixels values from BGRA to RGB. '''
+        """ Converts pixels values from BGRA to RGB. """
 
         image = bytearray(self.height * self.width * 3)
         image[0::3], image[1::3], image[2::3] = raw[2::4], raw[1::4], raw[0::4]
         return bytes(image)
 
     def enum_display_monitors(self, force=False):
-        ''' Get positions of one or more monitors.
+        """ Get positions of one or more monitors.
             If the monitor has rotation, you have to deal with it
             inside this method.
 
@@ -51,12 +50,12 @@ def enum_display_monitors(self, force=False):
                 'width':  the width,
                 'height': the height
             }
-        '''
+        """
 
         raise NotImplementedError('Subclasses need to implement this!')
 
     def get_pixels(self, monitor):
-        ''' Retrieve screen pixels for a given monitor.
+        """ Retrieve screen pixels for a given monitor.
 
             This method has to define self.width and self.height.
 
@@ -67,12 +66,12 @@ def get_pixels(self, monitor):
                 'width':  the width,
                 'heigth': the height
             }
-        '''
+        """
 
         raise NotImplementedError('Subclasses need to implement this!')
 
     def save(self, mon=0, output='monitor-%d.png', callback=None):
-        ''' Grab a screenshot and save it to a file.
+        """ Grab a screenshot and save it to a file.
 
             mon (integer, default: 0)
                 -1: grab one screenshot of all monitors
@@ -88,7 +87,7 @@ def save(self, mon=0, output='monitor-%d.png', callback=None):
                 Take the 'output' argument as parameter.
 
             This is a generator which returns created files.
-        '''
+        """
 
         self.enum_display_monitors()
         if not self.monitors:
@@ -111,8 +110,7 @@ def save(self, mon=0, output='monitor-%d.png', callback=None):
             try:
                 monitor = self.monitors[mon_number]
             except IndexError:
-                err = 'Monitor {0} does not exist.'.format(mon)
-                raise ScreenshotError(err)
+                raise ScreenshotError('Monitor does not exist.', locals())
 
             if '%d' in output:
                 output = output.replace('%d', str(mon_number))
@@ -122,10 +120,10 @@ def save(self, mon=0, output='monitor-%d.png', callback=None):
             yield output
 
     def to_png(self, data, output):
-        ''' Dump data to the image file. Data is bytes(RGBRGB...RGB).
+        """ Dump data to the image file. Data is bytes(RGBRGB...RGB).
             Pure python PNG implementation.
             http://inaps.org/journal/comment-fonctionne-le-png
-        '''
+        """
 
         p__ = pack
         line = self.width * 3
@@ -159,5 +157,4 @@ def to_png(self, data, output):
             fileh.write(b''.join(iend))
             return
 
-        err = 'Error writing data to "{0}".'.format(output)
-        raise ScreenshotError(err)
+        raise ScreenshotError('Error writing data to file.', output)