Skip to content

Commit a8288dd

Browse files
Schneck2004Schneck2004
committed
ftespnow: Added function docstrings
1 parent d34ef1d commit a8288dd

2 files changed

Lines changed: 219 additions & 4 deletions

File tree

‎micropython/ftespnow/ftespnow-client/ftespnow/client.py‎

Lines changed: 131 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,45 +14,161 @@ def connect(self, peer: str) -> None:
1414
self.esp.add_peer(self.peer)
1515

1616
def send_message(self, data: str) -> bool:
17+
"""
18+
Send a string
19+
20+
Args:
21+
22+
data (str): Data to be sent
23+
24+
Returns:
25+
26+
bool: Confirmation flag (`True` if data was received, `False` otherwise)
27+
"""
28+
1729
ack: bool = self.esp.send(self.peer, data)
1830
return ack
1931

2032
def receive_message(self, recv_timeout :int= 5) -> list | None:
33+
"""
34+
Receive a string
35+
36+
Args:
37+
38+
recv_timeout (int, optional): Reception timeout. Defaults to 5.
39+
40+
Returns:
41+
42+
list | None: `[<sender's mac address (str)>, <message (str)>]` | `None` if no message is received
43+
"""
44+
2145
received = self.esp.recv(recv_timeout)
2246
if received[0] == None: return
2347
return received
2448

2549
def send_txt(self, filename: str) -> bool:
50+
"""
51+
Parse and send a `.txt` file as a `string`
52+
53+
Args:
54+
55+
filename (str): Filepath of the desired file to be sent with file name and extention
56+
57+
Returns:
58+
59+
sent (bool): Confirmation flag (`True` if data was received, `False` otherwise)
60+
"""
61+
2662
with open(filename, 'r') as f:
2763
data: str = str(f.readlines())
2864
sent: bool = self.send_message(data)
2965
return sent
3066

3167
def send_json(self, filename: str, *, indent: int=4) -> bool:
68+
"""
69+
Parse and send a `.json` file as a `string`
70+
71+
Args:
72+
73+
filename (str): Filepath of the desired file to be sent with file name and extention
74+
75+
indent (int, optional): Desired indent of the resulting parsed `string` (for formatting purposes). Defaults to 4.
76+
77+
Returns:
78+
79+
sent (bool): Confirmation flag (`True` if data was received, `False` otherwise)
80+
"""
81+
3282
with open(filename, 'r') as f:
3383
unparsed = json.load(f)
3484
parsed: str = json.dumps(unparsed, indent=indent)
3585
sent: bool = self.send_message(parsed)
3686
return sent
3787

3888
def receive_to_txt(self, target_file: str, mode: str='a') -> bool:
89+
"""
90+
Write received `string` into a `.txt` file.
91+
92+
Args:
93+
94+
target_file (str): Filepath of the destination file for the received data with file name and extension.
95+
96+
mode (str, optional): Editing mode
97+
98+
- `r` - Read only
99+
100+
- `w` - Write only (truncates file before writing)
101+
102+
- `x` - Create a new file and open it for writing (raises `FileExistsError` if file already exists)
103+
104+
- `a` - Append to the end of the file (default)
105+
106+
- `b` - Binary mode
107+
108+
- `t` - Text mode
109+
110+
- `+` - Update (read and write)
111+
112+
Read `open()`_ for more information
113+
114+
Returns:
115+
116+
received (bool): Confirmation flag (`True` if data was received, `False` otherwise)
117+
118+
.. _open(): https://docs.python.org/3/library/functions.html#open
119+
"""
120+
39121
if ".txt" not in target_file: raise SyntaxError("File format must be .txt")
40122
try:
123+
received: bool = False
41124
data: list | None = self.receive_message()
42-
if data == None: return False
125+
if data == None: return received
43126
data_list: list[str] = str(data[-1]).split("\n")
44127
if data_list[-1] == "": data_list = data_list[:-1]
45128
with open(target_file, mode) as f:
46129
f.writelines(data_list)
47-
return True
130+
return not received
48131
except SyntaxError:
49132
raise
50133

51134
def receive_to_json(self, target_file: str, mode: str='a') -> bool:
135+
"""
136+
Write received `string` into a `.json` file.
137+
138+
Args:
139+
140+
target_file (str): Filepath of the destination file for the received data with file name and extension.
141+
142+
mode (str, optional): Editing mode
143+
144+
- `r` - Read only
145+
146+
- `w` - Write only (truncates file before writing)
147+
148+
- `x` - Create a new file and open it for writing (raises `FileExistsError` if file already exists)
149+
150+
- `a` - Append to the end of the file (default)
151+
152+
- `b` - Binary mode
153+
154+
- `t` - Text mode
155+
156+
- `+` - Update (read and write)
157+
158+
Read `open()`_ for more information
159+
160+
Returns:
161+
162+
received (bool): Confirmation flag (`True` if data was received, `False` otherwise)
163+
164+
.. _open(): https://docs.python.org/3/library/functions.html#open
165+
"""
166+
52167
if ".json" not in target_file: raise SyntaxError("File format must be .json")
53168
try:
169+
received: bool = False
54170
data: list | None = self.receive_message()
55-
if data == None: return False
171+
if data == None: return received
56172
mac: str = str(data[0])
57173
message = json.loads(str(data[-1]))
58174
unparsed: dict = {
@@ -61,11 +177,22 @@ def receive_to_json(self, target_file: str, mode: str='a') -> bool:
61177
}
62178
with open(target_file, mode) as f:
63179
json.dump(unparsed, f)
64-
return True
180+
return not received
65181
except SyntaxError:
66182
raise
67183

68184
def receive_to_dict(self) -> dict:
185+
"""
186+
Unparses received `string` into a `dict` object
187+
188+
Args:
189+
190+
None:
191+
192+
Returns:
193+
194+
unparsed (dict): `dictionary` object containing unparsed equivalent of the received `.json`
195+
"""
69196
data: list | None = self.receive_message()
70197
if data == None: return {}
71198
mac: str = str(data[0])

‎micropython/ftespnow/ftespnow-server/ftespnow/server.py‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,28 +10,116 @@ def configure(self, *, timeout: int=5) -> None:
1010
self.timeout = timeout
1111

1212
def send_message(self, peer: str, data: str) -> bool:
13+
"""
14+
Send a string
15+
16+
Args:
17+
18+
peer (str): client's mac address
19+
20+
data (str): Data to be sent
21+
22+
Returns:
23+
24+
bool: Confirmation flag (`True` if data was received, `False` otherwise)
25+
"""
26+
1327
ack: bool = self.esp.send(peer, data)
1428
return ack
1529

1630
def receive_message(self, recv_timeout :int= 5) -> list | None:
31+
"""
32+
Receive a string
33+
34+
Args:
35+
36+
recv_timeout (int, optional): Reception timeout. Defaults to 5.
37+
38+
Returns:
39+
40+
list | None: `[<sender's mac address (str)>, <message (str)>]` | `None` if no message is received
41+
"""
42+
1743
received = self.esp.recv(recv_timeout)
1844
if received[0] == None: return
1945
return received
2046

2147
def send_txt(self, peer: str, filename: str) -> bool:
48+
"""
49+
Parse and send a `.txt` file as a `string`
50+
51+
Args:
52+
53+
peer (str): client's mac address
54+
55+
filename (str): Filepath of the desired file to be sent with file name and extention
56+
57+
Returns:
58+
59+
sent (bool): Confirmation flag (`True` if data was received, `False` otherwise)
60+
"""
61+
2262
with open(filename, 'r') as f:
2363
data: str = str(f.readlines())
2464
sent: bool = self.send_message(peer, data)
2565
return sent
2666

2767
def send_json(self, peer: str, filename: str, *, indent: int=4) -> bool:
68+
"""
69+
Parse and send a `.json` file as a `string`
70+
71+
Args:
72+
73+
peer (str): client's mac address
74+
75+
filename (str): Filepath of the desired file to be sent with file name and extention
76+
77+
indent (int, optional): Desired indent of the resulting parsed `string` (for formatting purposes). Defaults to 4.
78+
79+
Returns:
80+
81+
sent (bool): Confirmation flag (`True` if data was received, `False` otherwise)
82+
"""
83+
2884
with open(filename, 'r') as f:
2985
unparsed = json.load(f)
3086
parsed: str = json.dumps(unparsed, indent=indent)
3187
sent: bool = self.send_message(peer, parsed)
3288
return sent
3389

3490
def receive_to_txt(self, target_file: str, mode: str='a') -> bool:
91+
"""
92+
Write received `string` into a `.txt` file.
93+
94+
Args:
95+
96+
target_file (str): Filepath of the destination file for the received data with file name and extension.
97+
98+
mode (str, optional): Editing mode
99+
100+
- `r` - Read only
101+
102+
- `w` - Write only (truncates file before writing)
103+
104+
- `x` - Create a new file and open it for writing (raises `FileExistsError` if file already exists)
105+
106+
- `a` - Append to the end of the file (default)
107+
108+
- `b` - Binary mode
109+
110+
- `t` - Text mode
111+
112+
- `+` - Update (read and write)
113+
114+
Read `open()`_ for more information
115+
116+
Returns:
117+
118+
received (bool): Confirmation flag (`True` if data was received, `False` otherwise)
119+
120+
.. _open(): https://docs.python.org/3/library/functions.html#open
121+
"""
122+
35123
if ".txt" not in target_file: raise SyntaxError("File format must be .txt")
36124
try:
37125
data: list | None = self.receive_message()

0 commit comments

Comments
 (0)