Skip to content

Commit 9612254

Browse files
gvalkovgvalkov
committed
Docstring improvements
- Use numpy style docstrings with sphinx.ext.napoleon. - Consistency, grammar and spelling.
1 parent 9e457bc commit 9612254

5 files changed

Lines changed: 199 additions & 126 deletions

File tree

‎doc/conf.py‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,12 @@
3131

3232
# Add any Sphinx extension module names here, as strings. They can be extensions
3333
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
34-
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx']
34+
extensions = [
35+
'sphinx.ext.autodoc',
36+
'sphinx.ext.viewcode',
37+
'sphinx.ext.intersphinx',
38+
'sphinx.ext.napoleon',
39+
]
3540

3641
autodoc_member_order = 'bysource'
3742

@@ -49,7 +54,7 @@
4954

5055
# General information about the project.
5156
project = u'python-evdev'
52-
copyright = u'2012-2015, Georgi Valkov'
57+
copyright = u'2012-2016, Georgi Valkov'
5358

5459
# The version info for the project you're documenting, acts as replacement for
5560
# |version| and |release|, also used in various other places throughout the
@@ -246,7 +251,7 @@
246251
'Miscellaneous'),
247252
]
248253

249-
intersphinx_mapping = {'python': ('http://docs.python.org/3.3', None)}
254+
intersphinx_mapping = {'python': ('http://docs.python.org/3.5', None)}
250255

251256
# Documents to append as an appendix to all manuals.
252257
#texinfo_appendices = []

‎evdev/device.py‎

Lines changed: 113 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -21,59 +21,75 @@ class EvdevError(Exception):
2121

2222

2323
class AbsInfo(_AbsInfo):
24-
'''
25-
A ``namedtuple`` for storing absolut axis information -
24+
'''Absolute axis information.
25+
26+
A ``namedtuple`` used for storing absolute axis information -
2627
corresponds to the ``input_absinfo`` struct:
2728
28-
**value**
29-
Latest reported value for the axis.
29+
Attributes
30+
---------
31+
value
32+
Latest reported value for the axis.
3033
31-
**min**
32-
Specifies minimum value for the axis.
34+
min
35+
Specifies minimum value for the axis.
3336
34-
**max**
35-
Specifies maximum value for the axis.
37+
max
38+
Specifies maximum value for the axis.
3639
37-
**fuzz**
38-
Specifies fuzz value that is used to filter noise from the
39-
event stream.
40+
fuzz
41+
Specifies fuzz value that is used to filter noise from the
42+
event stream.
4043
41-
**flat**
42-
Values that are within this value will be discarded by joydev
43-
interface and reported as 0 instead.
44+
flat
45+
Values that are within this value will be discarded by joydev
46+
interface and reported as 0 instead.
4447
45-
**resolution**
46-
Specifies resolution for the values reported for the axis.
47-
Resolution for main axes (``ABS_X, ABS_Y, ABS_Z``) is reported
48-
in units per millimeter (units/mm), resolution for rotational
49-
axes (``ABS_RX, ABS_RY, ABS_RZ``) is reported in units per
50-
radian.
48+
resolution
49+
Specifies resolution for the values reported for the axis.
50+
Resolution for main axes (``ABS_X, ABS_Y, ABS_Z``) is reported
51+
in units per millimeter (units/mm), resolution for rotational
52+
axes (``ABS_RX, ABS_RY, ABS_RZ``) is reported in units per
53+
radian.
54+
55+
Note
56+
----
57+
The input core does not clamp reported values to the ``[minimum,
58+
maximum]`` limits, such task is left to userspace.
5159
52-
.. note: The input core does not clamp reported values to the
53-
``[minimum, maximum]`` limits, such task is left to userspace.
5460
'''
5561

5662
def __str__(self):
5763
return 'val {}, min {}, max {}, fuzz {}, flat {}, res {}'.format(*self)
5864

5965

6066
class KbdInfo(_KbdInfo):
61-
'''
62-
Keyboard repeat rate:
67+
'''Keyboard repeat rate.
6368
64-
**repeat**
65-
Keyboard repeat rate in characters per second.
69+
Attributes
70+
----------
71+
repeat
72+
Keyboard repeat rate in characters per second.
6673
67-
**delay**
68-
Amount of time that a key must be depressed before it will start
69-
to repeat (in milliseconds).
74+
delay
75+
Amount of time that a key must be depressed before it will start
76+
to repeat (in milliseconds).
7077
'''
7178

7279
def __str__(self):
7380
return 'repeat {}, delay {}'.format(*self)
7481

7582

7683
class DeviceInfo(_DeviceInfo):
84+
'''
85+
Attributes
86+
----------
87+
bustype
88+
vendor
89+
product
90+
version
91+
'''
92+
7793
def __str__(self):
7894
msg = 'bus: {:04x}, vendor {:04x}, product {:04x}, version {:04x}'
7995
return msg.format(*self)
@@ -89,7 +105,10 @@ class InputDevice(object):
89105

90106
def __init__(self, dev):
91107
'''
92-
:param dev: path to input device
108+
Arguments
109+
---------
110+
dev : str
111+
Path to input device
93112
'''
94113

95114
#: Path to input device.
@@ -153,13 +172,18 @@ def _capabilities(self, absinfo=True):
153172
def capabilities(self, verbose=False, absinfo=True):
154173
'''
155174
Return the event types that this device supports as a mapping of
156-
supported event types to lists of handled event codes. Example::
175+
supported event types to lists of handled event codes.
157176
158-
{ 1: [272, 273, 274],
159-
2: [0, 1, 6, 8] }
177+
Example
178+
--------
179+
>>> device.capabilities()
180+
{ 1: [272, 273, 274],
181+
2: [0, 1, 6, 8] }
160182
161183
If ``verbose`` is ``True``, event codes and types will be resolved
162-
to their names. Example::
184+
to their names.
185+
186+
::
163187
164188
{ ('EV_KEY', 1): [('BTN_MOUSE', 272),
165189
('BTN_RIGHT', 273),
@@ -192,7 +216,7 @@ def capabilities(self, verbose=False, absinfo=True):
192216

193217
def need_write(func):
194218
'''
195-
Decorator that raises EvdevError() if there is no write access to the
219+
Decorator that raises :class:`EvdevError` if there is no write access to the
196220
input device.
197221
'''
198222
def wrapper(*args):
@@ -205,14 +229,17 @@ def wrapper(*args):
205229

206230
def leds(self, verbose=False):
207231
'''
208-
Return currently set LED keys. For example::
232+
Return currently set LED keys.
209233
210-
[0, 1, 8, 9]
234+
Example
235+
-------
236+
>>> device.leds()
237+
[0, 1, 8, 9]
211238
212239
If ``verbose`` is ``True``, event codes are resolved to their
213-
names. Unknown codes are resolved to ``'?'``. For example::
240+
names. Unknown codes are resolved to ``'?'``::
214241
215-
[('LED_NUML', 0), ('LED_CAPSL', 1), ('LED_MISC', 8), ('LED_MAIL', 9)]
242+
[('LED_NUML', 0), ('LED_CAPSL', 1), ('LED_MISC', 8), ('LED_MAIL', 9)]
216243
217244
'''
218245
leds = _input.ioctl_EVIOCG_bits(self.fd, ecodes.EV_LED)
@@ -224,27 +251,29 @@ def leds(self, verbose=False):
224251
@need_write
225252
def set_led(self, led_num, value):
226253
'''
227-
Set the state of the selected LED. For example::
228-
229-
device.set_led(ecodes.LED_NUML, 1)
254+
Set the state of the selected LED.
230255
231-
..
256+
Example
257+
-------
258+
>>> device.set_led(ecodes.LED_NUML, 1)
232259
'''
233260
self.set(ecodes.EV_LED, led_num, value)
234261

235262
@need_write
236263
def set(self, etype, code, value):
237264
'''
238-
Set the state of the selected component. For example::
239-
240-
device.set(ecodes.EV_LED, ecodes.LED_NUML, 1)
265+
Set the state of the selected component.
241266
242-
..
267+
Example
268+
-------
269+
>>> device.set(ecodes.EV_LED, ecodes.LED_NUML, 1)
243270
'''
244271
_uinput.write(self.fd, etype, code, value)
245272

246273
def __eq__(self, other):
247-
'''Two devices are equal if their :data:`info` attributes are equal.'''
274+
'''
275+
Two devices are equal if their :data:`info` attributes are equal.
276+
'''
248277
return isinstance(other, self.__class__) and self.info == other.info
249278

250279
def __str__(self):
@@ -264,10 +293,10 @@ def close(self):
264293

265294
def fileno(self):
266295
'''
267-
Return the file descriptor to the open event device. This
268-
makes it possible to pass pass ``InputDevice`` instances
269-
directly to :func:`select.select()` and
270-
:class:`asyncore.file_dispatcher`.'''
296+
Return the file descriptor to the open event device. This makes
297+
it possible to pass :class:`InputDevice` instances directly to
298+
:func:`select.select()` and :class:`asyncore.file_dispatcher`.
299+
'''
271300

272301
return self.fd
273302

@@ -286,10 +315,12 @@ def read_one(self):
286315
return InputEvent(*event)
287316

288317
def read_loop(self):
289-
'''Enter an endless ``select()`` loop that yields input events.'''
318+
'''
319+
Enter an endless :func:`select.select()` loop that yields input events.
320+
'''
290321

291322
while True:
292-
r, w, x = select([self.fd], [], [])
323+
r, w, x = select.select([self.fd], [], [])
293324
for event in self.read():
294325
yield event
295326

@@ -312,37 +343,48 @@ def grab(self):
312343
be unable to receive events until the device is released. Only
313344
one process can hold a ``EVIOCGRAB`` on a device.
314345
315-
.. warning:: Grabbing an already grabbed device will raise an
316-
``IOError``.'''
346+
Warning
347+
-------
348+
Grabbing an already grabbed device will raise an ``IOError``.
349+
'''
317350

318351
_input.ioctl_EVIOCGRAB(self.fd, 1)
319352

320353
def ungrab(self):
321-
'''Release device if it has been already grabbed (uses
322-
`EVIOCGRAB`).
354+
'''
355+
Release device if it has been already grabbed (uses `EVIOCGRAB`).
323356
324-
.. warning:: Releasing an already released device will raise an
325-
``IOError('Invalid argument')``.'''
357+
Warning
358+
-------
359+
Releasing an already released device will raise an
360+
``IOError('Invalid argument')``.
361+
'''
326362

327363
_input.ioctl_EVIOCGRAB(self.fd, 0)
328364

329365
def upload_effect(self, effect):
330-
'''Upload a force feedback effect to a force feedback device.'''
366+
'''
367+
Upload a force feedback effect to a force feedback device.
368+
'''
331369

332370
data = bytes(buffer(effect)[:])
333371
ff_id = _input.upload_effect(self.fd, data)
334372
return ff_id
335373

336374
def erase_effect(self, ff_id):
337-
'''Erase a force effect from a force feedback device. This
338-
also stops the effect.'''
375+
'''
376+
Erase a force effect from a force feedback device. This also
377+
stops the effect.
378+
'''
339379

340380
_input.erase_effect(self.fd, ff_id)
341381

342382
@property
343383
def repeat(self):
344-
'''Get or set the keyboard repeat rate (in characters per
345-
minute) and delay (in milliseconds).'''
384+
'''
385+
Get or set the keyboard repeat rate (in characters per
386+
minute) and delay (in milliseconds).
387+
'''
346388

347389
return KbdInfo(*_input.ioctl_EVIOCGREP(self.fd))
348390

@@ -352,9 +394,13 @@ def repeat(self, value):
352394

353395
def active_keys(self, verbose=False):
354396
'''
355-
Return currently active keys. Example::
397+
Return currently active keys.
398+
399+
Example
400+
-------
356401
357-
[1, 42]
402+
>>> device.active_keys()
403+
[1, 42]
358404
359405
If ``verbose`` is ``True``, key codes are resolved to their
360406
verbose names. Unknown codes are resolved to ``'?'``. For

0 commit comments

Comments
 (0)