byond-wire 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: byond-wire
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Small standard-library BYOND Topic client
|
|
5
|
+
Author: Wirewraith
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://github.com/Wirewraith/byond-wire
|
|
8
|
+
Requires-Python: >=3.9
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Dynamic: license-file
|
|
12
|
+
|
|
13
|
+
# BYOND Wire
|
|
14
|
+
|
|
15
|
+
Small, standard-library BYOND Topic client. MIT licensed.
|
|
16
|
+
|
|
17
|
+
Library calls return decoded text, numbers, or null. Raw calls preserve text bytes.
|
|
18
|
+
See [PROTOCOL.md](PROTOCOL.md) for encoding and wire details.
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
Requires Python 3.9 or later. Install the library and CLI with `python3 -m pip install byond-wire`.
|
|
22
|
+
Ports must be integers from `1` to `65535` (booleans are rejected).
|
|
23
|
+
Timeouts are positive numbers up to `2147483647` seconds;
|
|
24
|
+
invalid values raise `ValueError` before DNS or socket creation.
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
python3 cli.py 127.0.0.1 4999 status
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Import the installed module, or copy `byond_wire.py` onto your Python import path:
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
from byond_wire import topic, topic_raw
|
|
34
|
+
|
|
35
|
+
response = topic("127.0.0.1", 4999, "status", timeout=5)
|
|
36
|
+
# str, float, or None; failures raise exceptions, including TimeoutError.
|
|
37
|
+
raw = topic_raw("127.0.0.1", 4999, "status") # bytes, float, or None
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Run regression tests with `python3 -m unittest discover -s python`.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
byond_wire.py,sha256=5LLXpRbCza8rZjXB5Uu3QEOK9ZuOXE66JCIRfAIHQRU,4273
|
|
2
|
+
byond_wire-0.1.0.dist-info/licenses/LICENSE,sha256=81XA6MEULIOR1ppymPm6OudJQQPp4RPlumlbtwz-1fo,1067
|
|
3
|
+
byond_wire-0.1.0.dist-info/METADATA,sha256=APDYB6caS0C4Oghw_6ngKmzX4BYvxUYsg_Ed4q8Ts2Y,1292
|
|
4
|
+
byond_wire-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
5
|
+
byond_wire-0.1.0.dist-info/entry_points.txt,sha256=xiYXudQdRVanSyQqE53X9CBlhUrjQ52fe-w2IQRDqz4,47
|
|
6
|
+
byond_wire-0.1.0.dist-info/top_level.txt,sha256=LBhzZc62Gp59FMABvF4gyt2IOU8Tfm0LdMHqm3wCZss,11
|
|
7
|
+
byond_wire-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Wirewraith
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
byond_wire
|
byond_wire.py
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Standard library only. Exit: 0 value, 1 error, 2 null, 124 network timeout."""
|
|
3
|
+
import socket
|
|
4
|
+
import struct
|
|
5
|
+
import sys
|
|
6
|
+
import time
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def decode_text(data):
|
|
10
|
+
"""Remove tested BYOND markers and strictly decode the UTF-8 runs."""
|
|
11
|
+
if b'\xff' not in data:
|
|
12
|
+
return data.decode('utf-8')
|
|
13
|
+
parts = data.split(b'\xff')
|
|
14
|
+
text = [parts[0].decode('utf-8')]
|
|
15
|
+
for part in parts[1:]:
|
|
16
|
+
if not part or part[0] not in b'\x06\x07\x08\x09\x12\x15\x16\x17\x18\x19\x1f\x20\x21\x22\x23\x24\x25\x26':
|
|
17
|
+
raise ValueError('Unknown or truncated BYOND text marker')
|
|
18
|
+
text.append(part[1:].decode('utf-8'))
|
|
19
|
+
return ''.join(text)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def remaining(deadline):
|
|
23
|
+
seconds = deadline - time.monotonic()
|
|
24
|
+
if seconds <= 0:
|
|
25
|
+
raise TimeoutError('Topic request timed out')
|
|
26
|
+
return seconds
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def read_exact(sock, count, deadline):
|
|
30
|
+
chunks = []
|
|
31
|
+
while count:
|
|
32
|
+
sock.settimeout(remaining(deadline))
|
|
33
|
+
chunk = sock.recv(count)
|
|
34
|
+
if not chunk:
|
|
35
|
+
raise EOFError('Incomplete Topic response')
|
|
36
|
+
chunks.append(chunk)
|
|
37
|
+
count -= len(chunk)
|
|
38
|
+
return b''.join(chunks)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def connect(host, port, deadline):
|
|
42
|
+
remaining(deadline)
|
|
43
|
+
error = None
|
|
44
|
+
for family, kind, protocol, _, address in socket.getaddrinfo(host, port, 0, socket.SOCK_STREAM):
|
|
45
|
+
seconds = remaining(deadline)
|
|
46
|
+
sock = None
|
|
47
|
+
try:
|
|
48
|
+
sock = socket.socket(family, kind, protocol)
|
|
49
|
+
sock.settimeout(seconds)
|
|
50
|
+
sock.connect(address)
|
|
51
|
+
return sock
|
|
52
|
+
except BaseException as failure:
|
|
53
|
+
if sock is not None:
|
|
54
|
+
sock.close()
|
|
55
|
+
if not isinstance(failure, OSError):
|
|
56
|
+
raise
|
|
57
|
+
error = failure
|
|
58
|
+
raise error or OSError('Address resolved to no endpoints')
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def topic(host, port, query, timeout=5):
|
|
62
|
+
value = topic_raw(host, port, query, timeout)
|
|
63
|
+
return decode_text(value) if isinstance(value, bytes) else value
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def topic_raw(host, port, query, timeout=5):
|
|
67
|
+
if not host or type(port) is not int or not 1 <= port <= 65535:
|
|
68
|
+
raise ValueError('Invalid address or port')
|
|
69
|
+
if not isinstance(timeout, (int, float)) or not 0 < timeout <= 2147483647:
|
|
70
|
+
raise ValueError('Timeout must be positive and at most 2147483647 seconds')
|
|
71
|
+
if not query.startswith('?'):
|
|
72
|
+
query = '?' + query
|
|
73
|
+
query_bytes = query.encode('utf-8')
|
|
74
|
+
if b'\0' in query_bytes:
|
|
75
|
+
raise ValueError('Query contains NUL')
|
|
76
|
+
length = len(query_bytes) + 6
|
|
77
|
+
if length > 65535:
|
|
78
|
+
raise ValueError('Query exceeds two-byte frame length')
|
|
79
|
+
request = struct.pack('>HH5x', 0x83, length) + query_bytes + b'\0'
|
|
80
|
+
deadline = time.monotonic() + timeout
|
|
81
|
+
try:
|
|
82
|
+
with connect(host, port, deadline) as sock:
|
|
83
|
+
sock.settimeout(remaining(deadline))
|
|
84
|
+
sock.sendall(request)
|
|
85
|
+
header = read_exact(sock, 4, deadline)
|
|
86
|
+
if header[:2] != b'\0\x83':
|
|
87
|
+
raise ValueError('Non-Topic response')
|
|
88
|
+
length = struct.unpack('>H', header[2:])[0]
|
|
89
|
+
if length == 0:
|
|
90
|
+
raise ValueError('Empty Topic body')
|
|
91
|
+
body = read_exact(sock, length, deadline)
|
|
92
|
+
except socket.timeout as error:
|
|
93
|
+
raise TimeoutError('Topic request timed out') from error
|
|
94
|
+
if body == b'\0':
|
|
95
|
+
return None
|
|
96
|
+
if body[:1] == b'\x06' and len(body) >= 2 and body.endswith(b'\0'):
|
|
97
|
+
return body[1:-1]
|
|
98
|
+
if body[:1] == b'\x2a' and len(body) == 5:
|
|
99
|
+
return struct.unpack('<f', body[1:])[0]
|
|
100
|
+
raise ValueError('Invalid Topic response')
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def main():
|
|
104
|
+
try:
|
|
105
|
+
if len(sys.argv) != 4:
|
|
106
|
+
raise ValueError(f'Usage: {sys.argv[0]} <address> <port> <message>')
|
|
107
|
+
result = topic_raw(sys.argv[1], int(sys.argv[2]), sys.argv[3])
|
|
108
|
+
if result is None:
|
|
109
|
+
return 2
|
|
110
|
+
if isinstance(result, bytes):
|
|
111
|
+
sys.stdout.buffer.write(result)
|
|
112
|
+
else:
|
|
113
|
+
sys.stdout.buffer.write(format(result, '.9g').encode('ascii'))
|
|
114
|
+
sys.stdout.buffer.flush()
|
|
115
|
+
return 0
|
|
116
|
+
except TimeoutError:
|
|
117
|
+
print('Topic request timed out', file=sys.stderr)
|
|
118
|
+
return 124
|
|
119
|
+
except (OSError, ValueError, EOFError) as error:
|
|
120
|
+
print(error, file=sys.stderr)
|
|
121
|
+
return 1
|
|
122
|
+
|