hungerbridge 1.0.dev4__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.
- hungerbridge/__init__.py +47 -0
- hungerbridge/auth.py +106 -0
- hungerbridge/bridge.py +30 -0
- hungerbridge/canonical.py +123 -0
- hungerbridge/client.py +353 -0
- hungerbridge/exceptions.py +81 -0
- hungerbridge/protocol.py +16 -0
- hungerbridge/py.typed +0 -0
- hungerbridge/stream.py +389 -0
- hungerbridge/transport.py +198 -0
- hungerbridge/units.py +55 -0
- hungerbridge-1.0.dev4.dist-info/METADATA +148 -0
- hungerbridge-1.0.dev4.dist-info/RECORD +16 -0
- hungerbridge-1.0.dev4.dist-info/WHEEL +5 -0
- hungerbridge-1.0.dev4.dist-info/licenses/LICENSE +674 -0
- hungerbridge-1.0.dev4.dist-info/top_level.txt +1 -0
hungerbridge/units.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
'''Unit conversion helpers (byte and time units).
|
|
2
|
+
|
|
3
|
+
Semantics match ``hungerlib.utils.convert``, which the original client imported:
|
|
4
|
+
values are converted through a base unit and returned as ``float`` (optionally
|
|
5
|
+
rounded).
|
|
6
|
+
'''
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from types import SimpleNamespace
|
|
11
|
+
|
|
12
|
+
__all__ = ['BYTE_UNITS', 'TIME_UNITS', 'convert_bytes', 'convert_time', 'convert']
|
|
13
|
+
|
|
14
|
+
BYTE_UNITS = {
|
|
15
|
+
'b': 1,
|
|
16
|
+
'kb': 1_000,
|
|
17
|
+
'mb': 1_000_000,
|
|
18
|
+
'gb': 1_000_000_000,
|
|
19
|
+
'tb': 1_000_000_000_000,
|
|
20
|
+
'kib': 1024,
|
|
21
|
+
'mib': 1024**2,
|
|
22
|
+
'gib': 1024**3,
|
|
23
|
+
'tib': 1024**4,
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
TIME_UNITS = {
|
|
27
|
+
'ns': 1e-9,
|
|
28
|
+
'us': 1e-6,
|
|
29
|
+
'ms': 1e-3,
|
|
30
|
+
's': 1.0,
|
|
31
|
+
'min': 60.0,
|
|
32
|
+
'h': 3600.0,
|
|
33
|
+
'day': 86400.0,
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _factor(table: dict, unit: str) -> float:
|
|
38
|
+
try:
|
|
39
|
+
return float(table[unit.lower()])
|
|
40
|
+
except (KeyError, AttributeError):
|
|
41
|
+
raise ValueError(f'Unknown unit: {unit!r} (expected one of {", ".join(table)})') from None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def convert_bytes(value, src: str = 'b', dst: str = 'mib', rounding: int | None = None) -> float:
|
|
45
|
+
result = float(value) * _factor(BYTE_UNITS, src) / _factor(BYTE_UNITS, dst)
|
|
46
|
+
return round(result, rounding) if rounding is not None else result
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def convert_time(value, src: str = 's', dst: str = 'ms', rounding: int | None = None) -> float:
|
|
50
|
+
result = float(value) * _factor(TIME_UNITS, src) / _factor(TIME_UNITS, dst)
|
|
51
|
+
return round(result, rounding) if rounding is not None else result
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
# Backwards-compatible namespace: ``convert.byte(value, 'b', 'mib')``.
|
|
55
|
+
convert = SimpleNamespace(byte=convert_bytes, time=convert_time)
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hungerbridge
|
|
3
|
+
Version: 1.0.dev4
|
|
4
|
+
Summary: Python client for the HungerBridge Minecraft (Paper/Folia/Fabric) HTTP bridge
|
|
5
|
+
Author: iFamished
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/HungerNet/HungerBridgePy
|
|
8
|
+
Project-URL: Source, https://github.com/HungerNet/HungerBridgePy
|
|
9
|
+
Project-URL: Issues, https://github.com/HungerNet/HungerBridgePy/issues
|
|
10
|
+
Project-URL: Server plugin, https://github.com/HungerNet/HungerBridge
|
|
11
|
+
Keywords: minecraft,paper,folia,fabric,automation,server-management,hungernet
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
20
|
+
Classifier: Operating System :: OS Independent
|
|
21
|
+
Classifier: Development Status :: 4 - Beta
|
|
22
|
+
Classifier: Intended Audience :: Developers
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
24
|
+
Classifier: Topic :: System :: Systems Administration
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Requires-Dist: requests>=2.28
|
|
30
|
+
Provides-Extra: test
|
|
31
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
32
|
+
Dynamic: license-file
|
|
33
|
+
|
|
34
|
+
# HungerBridgePy
|
|
35
|
+
|
|
36
|
+
Python client for [HungerBridge](https://github.com/HungerNet/HungerBridge), the HTTP
|
|
37
|
+
bridge plugin/mod for **Paper, Purpur, Folia and Fabric** Minecraft servers
|
|
38
|
+
(1.21.11, 26.1.2, 26.2, 26.3).
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pip install hungerbridge
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
> The distribution was previously configured as `hungerlib`, which is a different
|
|
45
|
+
> PyPI project. The import name has always been `hungerbridge`.
|
|
46
|
+
|
|
47
|
+
## Quick start
|
|
48
|
+
|
|
49
|
+
1. On the server console create a token for a policy from `policies.yaml`:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
/hb token create my-bot admin
|
|
53
|
+
Pickup passkey: …
|
|
54
|
+
Token created. Retrieve it at: /pickup/<uuid>?passkey=<hex>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
2. Redeem the single-use pickup and talk to the server:
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from hungerbridge import BridgeClient
|
|
61
|
+
|
|
62
|
+
client = BridgeClient.fromPickup("http://127.0.0.1:1913/pickup/<uuid>?passkey=<hex>")
|
|
63
|
+
# later: BridgeClient("http://127.0.0.1:1913", "my-bot", "<64 hex chars>")
|
|
64
|
+
# or: BridgeClient("http://127.0.0.1:1913", "my-bot:<64 hex chars>")
|
|
65
|
+
|
|
66
|
+
print(client.getServerMeta()) # platform, minecraft_version, bridge_version, port, protocol_version
|
|
67
|
+
print(client.getTPS("1m"), client.getMSPT())
|
|
68
|
+
print(client.runCommand("list")) # captured console output
|
|
69
|
+
client.log("hello from python", level="BRIDGE", thread="bot")
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## API
|
|
73
|
+
|
|
74
|
+
| Method | Endpoint | Returns |
|
|
75
|
+
|---|---|---|
|
|
76
|
+
| `isOk()`, `getServerTime()`, `getPing()` | `GET /ping` | bool, epoch ms, RTT ms |
|
|
77
|
+
| `getTokenInfo()` | `GET /auth/check` | `token_id`, `policy_id`, `permissions` |
|
|
78
|
+
| `getServerMeta()`, `getPlatform()`, `getMinecraftVersion()`, `getBridgeVersion()`, `getBridgePort()`, `getProtocolVersion()` | `GET /server/meta` | |
|
|
79
|
+
| `getPlayers('count'\|'list')`, `getMaxPlayers()` | `GET /players/list` | |
|
|
80
|
+
| `getTPS('current'\|'1m'\|'5m'\|'15m')` | `GET /world/tps` | float, `-1` if unavailable |
|
|
81
|
+
| `getMSPT()` | `GET /world/mspt` | float |
|
|
82
|
+
| `getWorldTime()`, `getWorldTimeInfo()` | `GET /world/time` | ticks of day (0–23999) / dict |
|
|
83
|
+
| `getWorldWeather()` | `GET /world/weather` | `clear`/`rain`/`thunder` |
|
|
84
|
+
| `getLoadedChunks()`, `getLoadedEntities()` | `GET /world/chunks`, `/world/entities` | `total`, `world`, `world_nether`, `world_the_end` |
|
|
85
|
+
| `getUptime()`, `getCPUStats()`, `getMemoryStats(unit)`, `getProcessMemory(unit)`, `getGCStats()`, `getThreadStats()`, `getNetworkStats()` | `GET /system/*` | |
|
|
86
|
+
| `runCommand(cmd, showConsole=False, silent=False, normalize=True)` | `POST /server/run` | output text / dict |
|
|
87
|
+
| `broadcast(msg, prefix=None)` | `POST /server/run` (`tellraw @a`) | |
|
|
88
|
+
| `log(message, level='info', thread=None)` | `POST /server/log` | dict |
|
|
89
|
+
| `stopServer()` | `POST /server/stop` | dict |
|
|
90
|
+
| `BridgeClient.redeemPickup(url)` / `fromPickup(url)` | `GET /pickup/<id>` | `(token_id, secret)` / client |
|
|
91
|
+
|
|
92
|
+
Constructor options: `max_retries`, `retry_backoff_sec`, `swallow_rate_limit`,
|
|
93
|
+
`static_delay` (minimum gap between requests), `timeout` (default `(5, 30)` seconds),
|
|
94
|
+
`session` (custom `requests.Session`).
|
|
95
|
+
|
|
96
|
+
### Log streaming (SSE)
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
def on_history(lines): ...
|
|
100
|
+
def on_line(line): print(client.stream.sanitize(line))
|
|
101
|
+
|
|
102
|
+
client = BridgeClient(url, token, history_handler=on_history, new_log_handler=on_line)
|
|
103
|
+
client.stream.connect(history=50, reconnect=True) # background thread
|
|
104
|
+
...
|
|
105
|
+
client.stream.disconnect()
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Without handlers lines are buffered in `getRaw()`, `getSanitized()` and `getTimestamped()`.
|
|
109
|
+
With `reconnect=True` the stream reconnects with exponential back-off and replays only
|
|
110
|
+
the history lines it has not seen yet.
|
|
111
|
+
|
|
112
|
+
### Errors
|
|
113
|
+
|
|
114
|
+
All errors derive from `HungerBridgeError` (with `.status`, `.code`, `.reason`):
|
|
115
|
+
`HungerBridgeAuthError` (401 — `reason` is one of `invalid_credentials`,
|
|
116
|
+
`timestamp_out_of_range`, `nonce_replay`, `token_expired`), `HungerBridgeForbidden` (403),
|
|
117
|
+
`HungerBridgeNotFound` (404), `HungerBridgeRateLimit` (429, `.retry_after`),
|
|
118
|
+
`HungerBridgeConnectionError` (unreachable/timeout), `InvalidModeError`.
|
|
119
|
+
|
|
120
|
+
## Protocol
|
|
121
|
+
|
|
122
|
+
Requests are signed with HMAC-SHA256 over
|
|
123
|
+
`METHOD\npath\ntimestamp\nnonce\ncanonical_json_body` (headers `X-Auth-Id`,
|
|
124
|
+
`X-Auth-Timestamp`, `X-Auth-Nonce`, `X-Auth-Signature`). The canonical JSON rules are
|
|
125
|
+
documented in `hungerbridge/canonical.py`; `tests/data/protocol-vectors.json` holds golden
|
|
126
|
+
vectors that are shared with (and verified by) the Java server test suite. The server
|
|
127
|
+
advertises its protocol version in the `X-HungerBridge-Protocol` header; the client warns
|
|
128
|
+
if it differs from `hungerbridge.PROTOCOL_VERSION`.
|
|
129
|
+
|
|
130
|
+
## Package layout
|
|
131
|
+
|
|
132
|
+
| Module | Responsibility |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `client.py` | `BridgeClient` endpoint wrappers, pickup redemption |
|
|
135
|
+
| `transport.py` | HTTP session, timeouts, throttling, 429 retry, error mapping |
|
|
136
|
+
| `auth.py` | credentials and HMAC signing |
|
|
137
|
+
| `canonical.py` | canonical JSON + path normalization (wire format) |
|
|
138
|
+
| `stream.py` | SSE parser and `Stream` |
|
|
139
|
+
| `exceptions.py`, `units.py`, `protocol.py` | errors, unit conversion, protocol constants |
|
|
140
|
+
| `bridge.py` | backwards-compatible re-exports of the old single-module API |
|
|
141
|
+
|
|
142
|
+
## Development
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
pip install -e .[test]
|
|
146
|
+
pytest # unit + protocol tests (no server needed)
|
|
147
|
+
HB_PICKUP_URL=http://127.0.0.1:1913/pickup/<id>?passkey=<hex> pytest -m live # against a real server
|
|
148
|
+
```
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
hungerbridge/__init__.py,sha256=1usaDICCyIrpW0c2cOxbCM1YoVwPR9VLps0-TyPVavo,1213
|
|
2
|
+
hungerbridge/auth.py,sha256=GSzLl-K3n4LNWYM7t9BUV3P4_imLh6oASuft9m7zpAs,3202
|
|
3
|
+
hungerbridge/bridge.py,sha256=uk8-hFfSHDFEPWjI0BX7Uyxs0IgQa103Kc1vmbpTt_Q,1177
|
|
4
|
+
hungerbridge/canonical.py,sha256=v-ewhw8uKGU7UT1wLCJeYEm8lfGM-Hz6BfhhTnjVM3M,4522
|
|
5
|
+
hungerbridge/client.py,sha256=sbW4XxXUehHc23jr15IF0-sNNn9sZRYr6f0HZe9t3MA,13497
|
|
6
|
+
hungerbridge/exceptions.py,sha256=OifZQUfR5UAxeuGJOCmtn408AeFdR-7FWkcOXncMZvM,2542
|
|
7
|
+
hungerbridge/protocol.py,sha256=WnU352AB96UHQWATnVyuMo8DJf1xvi5FfZSr2XlED1g,753
|
|
8
|
+
hungerbridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
hungerbridge/stream.py,sha256=9dwwpOrVqv9KD1Q3GsScPugDcpp_lRO1U8jnYQL4ZK4,14980
|
|
10
|
+
hungerbridge/transport.py,sha256=uiOo9GiCyxU70uiCWlm3aTiJl_t-Eg0-qBt2UHhKLMw,7376
|
|
11
|
+
hungerbridge/units.py,sha256=vNR14CnUV6T3uhqAf99vI3CrCHIPTuoiQQmE3Sjn1aU,1588
|
|
12
|
+
hungerbridge-1.0.dev4.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
|
|
13
|
+
hungerbridge-1.0.dev4.dist-info/METADATA,sha256=69mVhh4NcIdnCZ6J1LCRqDer3v_k5tC8X5jK8dzm9QU,6595
|
|
14
|
+
hungerbridge-1.0.dev4.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
15
|
+
hungerbridge-1.0.dev4.dist-info/top_level.txt,sha256=o2LUYqLwLBGN4wLwFXKYpmXyLbi4VY3cXdbXyYTHzGE,13
|
|
16
|
+
hungerbridge-1.0.dev4.dist-info/RECORD,,
|