Skip to content

Commit e5ba717

Browse files
[PATCH] minore tweaks to comments and documentation.
Changes in file docs/FAQ.md: # assuming already did 'import multicast as multicast' # cd /MY-AWESOME-DEV-PATH # clean up some stuff # spawn a listening proc #### DONE #### Default Port Changes in file tests/__init__.py: - Suppress PYL-W0622
1 parent 3cf0712 commit e5ba717

File tree

2 files changed

+27
-39
lines changed

2 files changed

+27
-39
lines changed

docs/FAQ.md

Lines changed: 26 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ If all went well, `multicast` is now installed and working :tada:
4141

4242
```bash
4343
# cd /MY-AWESOME-DEV-PATH
44-
python3 -m multicast --daemon HEAR --use-std --port 59595 --group 224.0.0.1
44+
python3 -m multicast --daemon --use-std HEAR --port 59595 --group 224.0.0.1
4545
```
4646

4747
Most users will want to stick to using `HEAR` when receiving multicast from the CLI. Alternatively,
@@ -54,7 +54,7 @@ messages, no more than one at a time.
5454
```bash
5555
# cd /MY-AWESOME-DEV-PATH
5656
while true ; do # until user Ctrl+C interrupts
57-
python3 -m multicast RECV --use-std --port 59595 --group 224.0.0.1 --groups 224.0.0.1
57+
python3 -m multicast --use-std RECV --port 59595 --group 224.0.0.1 --groups 224.0.0.1
5858
done
5959
```
6060

@@ -71,22 +71,17 @@ python3 -m multicast SAY --group 224.0.0.1 --port 59595 --message "Hello World!"
7171

7272
> [!WARNING]
7373
> Caveat: this module is still a BETA
74-
75-
[Here is how it is tested right now](https://github.com/reactive-firewall/multicast/blob/cdd577549c0bf7c2bcf85d1b857c86135778a9ed/tests/test_usage.py#L251-L554)
74+
(https://github.com/reactive-firewall/multicast/blob/389c93eb86e012a38edb88b3b81c7d4aa55e843a/tests/test_hear_cleanup.py#L54C2-L96C43)
75+
[Here is how it is tested right now]
7676

7777
```python3
7878
import multicast
79-
from multiprocessing import Process as Process
79+
import random # for random port
8080

8181
# set up some stuff
82-
_fixture_PORT_arg = int(59595)
82+
_fixture_PORT_arg = int(random.SystemRandom().randint(49152, 65535))
8383
_fixture_mcast_GRP_arg = """224.0.0.1""" # only use dotted notation for multicast group addresses
8484
_fixture_host_BIND_arg = """224.0.0.1"""
85-
_fixture_HEAR_args = [
86-
"""--port""", _fixture_PORT_arg,
87-
"""--groups""", _fixture_mcast_GRP_arg,
88-
"""--group""", _fixture_host_BIND_arg
89-
]
9085

9186
# spawn a listening proc
9287

@@ -109,14 +104,22 @@ def inputHandler():
109104
inputHandler()
110105

111106
# alternatively listen as a server
107+
# import multicast # if not already done.
108+
from multiprocessing import Process as Process
112109

110+
_fixture_HEAR_kwargs = {
111+
"""is_daemon""": True,
112+
"""port""": _fixture_PORT_arg,
113+
"""group""": _fixture_host_BIND_arg
114+
}
113115
p = Process(
114-
target=multicast.__main__.McastDispatch().doStep,
115-
name="HEAR", args=("--daemon", "HEAR", _fixture_HEAR_args,)
116-
)
116+
target=multicast.hear.McastHEAR().doStep,
117+
name="HEAR", kwargs=_fixture_HEAR_kwargs
118+
)
119+
p.daemon = _fixture_HEAR_kwargs["""is_daemon"""]
117120
p.start()
118121

119-
# ... probably will return with nothing outside a handler function in a loop
122+
# ... use CTL+C (or signal 2) to shutdown the server 'p'
120123
```
121124

122125
_and elsewhere (like another function or even module) for the sender:_
@@ -131,7 +134,7 @@ _fixture_SAY_args = [
131134
"""--message""", """'test message'"""
132135
]
133136
try:
134-
multicast.__main__.McastDispatch().doStep("SAY", _fixture_SAY_args)
137+
multicast.__main__.McastDispatch().doStep(["SAY", _fixture_SAY_args])
135138
# Hint: use a loop to repeat or different arguments to vary message.
136139
except Exception:
137140
p.join()
@@ -147,6 +150,11 @@ didWork = (int(p.exitcode) <= int(0)) # if you use a loop and need to know the e
147150
> Caveat: the above examples assume the reader is knowledgeable about general `IPC` theory and
148151
> the standard python `multiprocessing` module and its use.
149152
153+
> [!TIP]
154+
> Another
155+
> [more CLI focused way to test](https://github.com/reactive-firewall/multicast/blob/389c93eb86e012a38edb88b3b81c7d4aa55e843a/tests/test_usage.py#L385C2-L432C43)
156+
> is another example of how to use the module.
157+
150158
### What are the defaults?
151159

152160
#### Default Multicast Group
@@ -200,33 +208,13 @@ From the
200208
> It is best to specify the port in use at this time as the default has yet to be properly
201209
> assigned ( see related reactive-firewall/multicast#62 )
202210
203-
### What does exit code _x_ mean?
204-
205-
#### Python function return code meanings
206-
207-
`0` is the default and implies _success_, and means the process has essentially (or actually)
208-
returned nothing (or `None`)
209-
210-
`1` is used when a _single_ result is returned (caveat: functions may return a single `tuple`
211-
instead of `None` to indicate exit code `1` by returning a `boolean` success value, and result
212-
(which may also be encapsulated as an iterable if needed) )
213-
214-
`2` is used to indicate a _value and reason_ are returned (caveat: functions may return a single
215-
`tuple` with a single value and reason and the value can be a `tuple`)
216-
217-
`-1` is used to mean _many_ of unspecified length and otherwise functions as `1`
218-
219-
* these values loosely map to the principle of _none-one-many_, 0 is none, 1 is, unsurprisingly,
220-
one, and everything else is many. From this practice it is possible to infer how to handle the
221-
result, (ie `(int(length-hint), None if len([*result-values])==0 else *result-values)` ).
222-
223-
#### CLI exit code meanings
211+
### CLI exit code meanings
224212

225213
`0` **success**
226214

227215
`1` **non-success** - and is often accompanied by warnings or errors
228216

229-
`2 <` **failure** of specific reason
217+
`2`-`225` **failure** of specific reason
230218

231219
* Any exit value outside the range of `0-255` inclusive should be decoded with the formula:
232220
`| input % 256 |` which will yield the correct exit code.

tests/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
4040
"""
4141

42-
__package__ = """tests"""
42+
__package__ = """tests""" # skipcq: PYL-W0622
4343
"""This is multicast testing package."""
4444

4545
__module__ = """tests"""

0 commit comments

Comments
 (0)