Skip to content

Commit 2b31760

Browse files
BoboTiGBoboTiG
committed
doc: update examples
1 parent 2a1e6d9 commit 2b31760

6 files changed

Lines changed: 109 additions & 99 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ dist/
55
MANIFEST*
66
.DS_Store
77
*.orig
8+
*.jpg
89
*.png
910
*.png.old
1011
*.pyc

‎README.rst‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
1-
An ultra fast cross-platform multiple screenshots module in pure python using ctypes
2-
====================================================================================
1+
Python MSS
2+
==========
33

4-
Very basic, it will grab one screen shot by monitor or a screen shot of all monitors and save it to a PNG file, Python 2.6/3.5 compatible & PEP8 compliant.
5-
It could be easily embedded into games and other softwares which require fast and plateforme optimized methods to grab screenshots.
4+
An ultra fast cross-platform multiple screenshots module in pure python using ctypes.
65

7-
**MSS** stands for Multiple ScreenShots.
8-
9-
It's under MIT license and there is a `beautiful documentation <http://python-mss.readthedocs.io/>`_ :).
6+
- **Python 2.6/3.6** and PEP8` compliant, no dependency;
7+
- very basic, it will grab one screen shot by monitor or a screen shot of all monitors and save it to a PNG file;
8+
- but you can use PIL and benefit from all its formats (or add yours directly);
9+
- it could be easily embedded into games and other softwares which require fast and plateforme optimized methods to grab screenshots;
10+
- get the `source code on GitHub <https://github.com/BoboTiG/python-mss>`_;
11+
- you can `report a bug <https://github.com/BoboTiG/python-mss/issues>`_;
12+
- and there is a `complete, and beautiful, documentation <https://python-mss.readthedocs.io>`_ :)
13+
- **MSS** stands for Multiple ScreenShots;
14+
- insanely fast, did I said it?
1015

1116

1217
Installation

‎docs/source/api.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Methods
2727

2828
.. method:: bgra_to_rgb(raw) -> bytes
2929

30-
:param mixed raw: raw data containing BGRA values.
30+
:param bytearray raw: raw data containing BGRA values.
3131

3232
It converts pixels values from BGRA to RGB.
3333
This is the method called to populate :attr:`image` into :attr:`get_pixels`.

‎docs/source/examples.rst‎

Lines changed: 81 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,88 @@
22
Examples
33
========
44

5+
Basics
6+
======
7+
8+
One screenshot per monitor::
9+
10+
for filename in screenshotter.save():
11+
print(filename)
12+
13+
14+
Screenshot of the monitor 1::
15+
16+
next(screenshotter.save(mon=1))
17+
18+
19+
A screenshot to grab them all::
20+
21+
next(screenshotter.save(mon=-1, output='fullscreen.png'))
22+
23+
24+
Callback
25+
--------
26+
27+
Screenshot of the monitor 1 with callback::
28+
29+
from os import rename
30+
from os.path import isfile
31+
32+
33+
def on_exists(fname):
34+
''' Callback example when we try to overwrite an existing screenshot. '''
35+
36+
if isfile(fname):
37+
newfile = fname + '.old'
38+
print('{0} -> {1}'.format(fname, newfile))
39+
rename(fname, newfile)
40+
return True
41+
42+
next(screenshotter.save(mon=1, callback=on_exists))
43+
44+
45+
Into the Python's console
46+
-------------------------
47+
48+
::
49+
50+
>>> from mss import mss
51+
>>> sct = mss(display=':0')
52+
53+
# Retrieve monitors informations
54+
>>> displays = sct.enum_display_monitors()
55+
>>> displays
56+
[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]
57+
# You can access monitors list via `monitors`:
58+
>>> displays is sct.monitors
59+
True
60+
61+
# Retrieve pixels from the first monitor
62+
>>> pixels = sct.get_pixels(displays[1])
63+
>>> type(pixels)
64+
<class 'bytes'>
65+
# You can access pixels data via `image`:
66+
>>> pixels is sct.image
67+
True
68+
69+
# Save pixels to a PNG file: option 1
70+
>>> files = sct.save(mon=1)
71+
>>> next(files)
72+
'monitor-1.png'
73+
>>> next(files)
74+
Traceback (most recent call last):
75+
File "<stdin>", line 1, in <module>
76+
StopIteration
77+
78+
# Save pixels to a PNG file: option 2
79+
>>> mon = displays[1]
80+
>>> sct.to_png(data=pixels, width=mon['width'], height=mon['height'], output='monitor-1.png')
81+
82+
583
GNU/Linux
6-
---------
84+
=========
785

8-
Usage example with a specific display::
86+
On GNU/Linux, you can specify which display to use (useful for distant screenshots via SSH)::
987

1088
from mss.linux import MSS
1189

@@ -20,7 +98,7 @@ Usage example with a specific display::
2098

2199

22100
Using PIL
23-
---------
101+
=========
24102

25103
You can use the Python Image Library (aka Pillow) to do whatever you want with raw pixels.
26104
This is an example using `frombytes() <http://pillow.readthedocs.io/en/latest/reference/Image.html#PIL.Image.frombytes>`_::

‎docs/source/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ An ultra fast cross-platform multiple screenshots module in pure python using ct
88
- but you can use PIL and benefit from all its formats (or add yours directly);
99
- it could be easily embedded into games and other softwares which require fast and plateforme optimized methods to grab screenshots;
1010
- get the `source code on GitHub <https://github.com/BoboTiG/python-mss>`_;
11-
- and `report a bug <https://github.com/BoboTiG/python-mss/issues>`_;
11+
- you can `report a bug <https://github.com/BoboTiG/python-mss/issues>`_;
1212
- **MSS** stands for Multiple ScreenShots;
1313
- insanely fast, did I said it?
1414

‎docs/source/usage.rst‎

Lines changed: 13 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -2,108 +2,34 @@
22
Usage
33
=====
44

5-
Instance the good class
6-
-----------------------
5+
Import
6+
======
77

88
So MSS can be used as simply as::
99

1010
from mss import mss
1111

12-
with mss() as screenshotter:
13-
# ...
1412

15-
16-
Or import the good one (choose one)::
13+
Or import the good one::
1714

1815
# MacOS X
19-
from mss.darwin import MSS
16+
from mss.darwin import MSS as mss
2017

2118
# GNU/Linux
22-
from mss.linux import MSS
19+
from mss.linux import MSS as mss
2320

2421
# Microsoft Windows
25-
from mss.windows import MSS
26-
27-
with MSS() as screenshotter:
28-
# ...
29-
30-
31-
Of course, you can use it the old way::
32-
33-
from mss import mss
34-
# or from mss.linux import MSS as mss
35-
36-
screenshotter = mss()
37-
38-
39-
Examples
40-
--------
41-
42-
One screenshot per monitor::
43-
44-
for filename in screenshotter.save():
45-
print(filename)
22+
from mss.windows import MSS as mss
4623

47-
Screenshot of the monitor 1::
4824

49-
print(next(screenshotter.save(mon=1)))
25+
Instance
26+
========
5027

51-
Screenshot of the monitor 1, with callback::
28+
So the module can be used as simply as::
5229

53-
def on_exists(fname):
54-
''' Callback example when we try to overwrite an existing
55-
screenshot.
56-
'''
57-
58-
from os import rename
59-
from os.path import isfile
60-
61-
if isfile(fname):
62-
newfile = fname + '.old'
63-
print('{0} -> {1}'.format(fname, newfile))
64-
rename(fname, newfile)
65-
return True
66-
67-
print(next(screenshotter.save(mon=1, callback=on_exists)))
68-
69-
A screenshot to grab them all::
70-
71-
print(next(screenshotter.save(mon=-1, output='fullscreen.png')))
72-
73-
74-
Into the Python's console
75-
-------------------------
76-
77-
.. code:: python
78-
79-
>>> from mss import mss
80-
>>> sct = mss(display=':0')
81-
82-
# Retrieve monitors informations
83-
>>> displays = sct.enum_display_monitors()
84-
>>> displays
85-
[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]
86-
# You can access monitors list via `monitors`:
87-
>>> sct.monitors
88-
[{'width': 1920, 'top': 0, 'height': 1080, 'left': 0}, {'width': 1920, 'top': 0, 'height': 1080, 'left': 0}]
89-
90-
# Retrieve pixels from the first monitor
91-
>>> pixels = sct.get_pixels(displays[1])
92-
>>> pixels
93-
<ctypes.c_char_Array_6220800 object at 0x7fe82e9007a0>
94-
# You can access pixels data via `image`:
95-
>>> sct.image
96-
<ctypes.c_char_Array_6220800 object at 0x7fe82e9007a0>
30+
with mss() as screenshotter:
31+
# ...
9732

98-
# Save pixels to a PNG file: option 1
99-
>>> files = sct.save(mon=1)
100-
>>> next(files)
101-
'monitor-1.png'
102-
>>> next(files)
103-
Traceback (most recent call last):
104-
File "<stdin>", line 1, in <module>
105-
StopIteration
33+
Or::
10634

107-
# Save pixels to a PNG file: option 2
108-
>>> mon = displays[1]
109-
>>> sct.to_png(data=pixels, width=mon['width'], height=mon['height'], output='monitor-1.png')
35+
screenshotter = mss()

0 commit comments

Comments
 (0)