Skip to content

Commit 389a45e

Browse files
chrisrukchrisruk
authored
Docstrings updating (#143)
1 parent 9130da5 commit 389a45e

30 files changed

+498
-96
lines changed

‎.flake8

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
[flake8]
2+
docstring_style=sphinx
23
max-line-length = 127
3-
ignore = D, Q000, P101, W605, S311, PLW, PLC, PLR
4+
ignore = D400, Q000, P101, W605, S311, PLW, PLC, PLR
45
per-file-ignores =
56
buildhat/__init__.py:F401
67
exclude = docs/conf.py, docs/sphinxcontrib/cmtinc-buildhat.py, docs/sphinx_selective_exclude/*.py

‎.github/workflows/python-app.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ jobs:
3131
echo "PYTHONPATH=." >> $GITHUB_ENV
3232
- name: Lint with flake8
3333
run: |
34+
flake8 . --version
3435
# stop the build if there are Python syntax errors or undefined names
3536
flake8 . --count --show-source --statistics
3637
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide

‎buildhat/__init__.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
"""Provide all the classes we need for build HAT"""
2+
13
from .color import ColorSensor
24
from .colordistance import ColorDistanceSensor
35
from .distance import DistanceSensor

‎buildhat/color.py

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
"""Color sensor handling functionality"""
2+
13
import math
24
from collections import deque
35
from threading import Condition
@@ -11,16 +13,25 @@ class ColorSensor(Device):
1113
:param port: Port of device
1214
:raises DeviceError: Occurs if there is no color sensor attached to port
1315
"""
16+
1417
def __init__(self, port):
18+
"""
19+
Initialise color sensor
20+
21+
:param port: Port of device
22+
"""
1523
super().__init__(port)
1624
self.reverse()
1725
self.mode(6)
1826
self.avg_reads = 4
1927
self._old_color = None
2028

2129
def segment_color(self, r, g, b):
22-
"""Returns the color name from RGB
30+
"""Return the color name from RGB
2331
32+
:param r: Red
33+
:param g: Green
34+
:param b: Blue
2435
:return: Name of the color as a string
2536
:rtype: str
2637
"""
@@ -46,6 +57,9 @@ def rgb_to_hsv(self, r, g, b):
4657
4758
Based on https://www.rapidtables.com/convert/color/rgb-to-hsv.html algorithm
4859
60+
:param r: Red
61+
:param g: Green
62+
:param b: Blue
4963
:return: HSV representation of color
5064
:rtype: tuple
5165
"""
@@ -69,7 +83,7 @@ def rgb_to_hsv(self, r, g, b):
6983
return int(h), int(s * 100), int(v * 100)
7084

7185
def get_color(self):
72-
"""Returns the color
86+
"""Return the color
7387
7488
:return: Name of the color as a string
7589
:rtype: str
@@ -78,7 +92,7 @@ def get_color(self):
7892
return self.segment_color(r, g, b)
7993

8094
def get_ambient_light(self):
81-
"""Returns the ambient light
95+
"""Return the ambient light
8296
8397
:return: Ambient light
8498
:rtype: int
@@ -90,7 +104,7 @@ def get_ambient_light(self):
90104
return int(sum(readings) / len(readings))
91105

92106
def get_reflected_light(self):
93-
"""Returns the reflected light
107+
"""Return the reflected light
94108
95109
:return: Reflected light
96110
:rtype: int
@@ -115,7 +129,7 @@ def _avgrgbi(self, reads):
115129
return rgbi
116130

117131
def get_color_rgbi(self):
118-
"""Returns the color
132+
"""Return the color
119133
120134
:return: RGBI representation
121135
:rtype: list
@@ -127,7 +141,7 @@ def get_color_rgbi(self):
127141
return self._avgrgbi(reads)
128142

129143
def get_color_hsv(self):
130-
"""Returns the color
144+
"""Return the color
131145
132146
:return: HSV representation
133147
:rtype: tuple
@@ -160,7 +174,7 @@ def _cb_handle(self, lst):
160174
self._cond.notify()
161175

162176
def wait_until_color(self, color):
163-
"""Waits until specific color
177+
"""Wait until specific color
164178
165179
:param color: Color to look for
166180
"""
@@ -175,7 +189,10 @@ def wait_until_color(self, color):
175189
self.callback(None)
176190

177191
def wait_for_new_color(self):
178-
"""Waits for new color or returns immediately if first call
192+
"""Wait for new color or returns immediately if first call
193+
194+
:return: Name of the color as a string
195+
:rtype: str
179196
"""
180197
self.mode(5)
181198
if self._old_color is None:
@@ -192,7 +209,5 @@ def wait_for_new_color(self):
192209
return self._old_color
193210

194211
def on(self):
195-
"""
196-
Turns on the sensor and LED
197-
"""
212+
"""Turn on the sensor and LED"""
198213
self._write("port {} ; plimit 1 ; set -1\r".format(self.port))

‎buildhat/colordistance.py

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
"""Color distance sensor handling functionality"""
2+
13
import math
24
from collections import deque
35
from threading import Condition
@@ -11,16 +13,25 @@ class ColorDistanceSensor(Device):
1113
:param port: Port of device
1214
:raises DeviceError: Occurs if there is no colordistance sensor attached to port
1315
"""
16+
1417
def __init__(self, port):
18+
"""
19+
Initialise color distance sensor
20+
21+
:param port: Port of device
22+
"""
1523
super().__init__(port)
1624
self.on()
1725
self.mode(6)
1826
self.avg_reads = 4
1927
self._old_color = None
2028

2129
def segment_color(self, r, g, b):
22-
"""Returns the color name from HSV
30+
"""Return the color name from HSV
2331
32+
:param r: Red
33+
:param g: Green
34+
:param b: Blue
2435
:return: Name of the color as a string
2536
:rtype: str
2637
"""
@@ -46,6 +57,9 @@ def rgb_to_hsv(self, r, g, b):
4657
4758
Based on https://www.rapidtables.com/convert/color/rgb-to-hsv.html algorithm
4859
60+
:param r: Red
61+
:param g: Green
62+
:param b: Blue
4963
:return: HSV representation of color
5064
:rtype: tuple
5165
"""
@@ -69,7 +83,7 @@ def rgb_to_hsv(self, r, g, b):
6983
return int(h), int(s * 100), int(v * 100)
7084

7185
def get_color(self):
72-
"""Returns the color
86+
"""Return the color
7387
7488
:return: Name of the color as a string
7589
:rtype: str
@@ -78,7 +92,7 @@ def get_color(self):
7892
return self.segment_color(r, g, b)
7993

8094
def get_ambient_light(self):
81-
"""Returns the ambient light
95+
"""Return the ambient light
8296
8397
:return: Ambient light
8498
:rtype: int
@@ -90,7 +104,7 @@ def get_ambient_light(self):
90104
return int(sum(readings) / len(readings))
91105

92106
def get_reflected_light(self):
93-
"""Returns the reflected light
107+
"""Return the reflected light
94108
95109
:return: Reflected light
96110
:rtype: int
@@ -117,7 +131,7 @@ def _avgrgb(self, reads):
117131
return rgb
118132

119133
def get_color_rgb(self):
120-
"""Returns the color
134+
"""Return the color
121135
122136
:return: RGBI representation
123137
:rtype: list
@@ -139,7 +153,7 @@ def _cb_handle(self, lst):
139153
self._cond.notify()
140154

141155
def wait_until_color(self, color):
142-
"""Waits until specific color
156+
"""Wait until specific color
143157
144158
:param color: Color to look for
145159
"""
@@ -154,7 +168,10 @@ def wait_until_color(self, color):
154168
self.callback(None)
155169

156170
def wait_for_new_color(self):
157-
"""Waits for new color or returns immediately if first call
171+
"""Wait for new color or returns immediately if first call
172+
173+
:return: Name of the color as a string
174+
:rtype: str
158175
"""
159176
self.mode(6)
160177
if self._old_color is None:
@@ -171,7 +188,5 @@ def wait_for_new_color(self):
171188
return self._old_color
172189

173190
def on(self):
174-
"""
175-
Turns on the sensor and LED
176-
"""
191+
"""Turn on the sensor and LED"""
177192
self._write("port {} ; plimit 1 ; set -1\r".format(self.port))

0 commit comments

Comments
 (0)