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/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,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+