bdo-toolkit 1.0.0__py3-none-any.whl

bdo_toolkit/writers.py

@@ -0,0 +1,30 @@
+"""Output writers for decoded events."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TextIO
+
+from .events import BDOEvent
+
+
+class ConsoleEventWriter:
+    """Write human-readable one-line events."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self.stream = stream if stream is not None else sys.stdout
+
+    def write(self, event: BDOEvent) -> None:
+        print(event.format_human(), file=self.stream)
+
+
+class JsonlEventWriter:
+    """Write newline-delimited JSON events."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self.stream = stream if stream is not None else sys.stdout
+
+    def write(self, event: BDOEvent) -> None:
+        print(json.dumps(event.to_dict(), sort_keys=True), file=self.stream)
+

bdo_toolkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: bdo-toolkit
+Version: 1.0.0
+Summary: Passive, read-only BDO packet parsing toolkit for app developers.
+Author: bdo-toolkit contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ychwu/bdo-toolkit
+Project-URL: Documentation, https://ychwu.github.io/bdo-toolkit/
+Project-URL: Repository, https://github.com/ychwu/bdo-toolkit.git
+Project-URL: Issues, https://github.com/ychwu/bdo-toolkit/issues
+Keywords: bdo,packets,parse,pcap,passive
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scapy>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# bdo-toolkit
+
+[![CI](https://img.shields.io/github/actions/workflow/status/ychwu/bdo-toolkit/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/ychwu/bdo-toolkit/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://github.com/ychwu/bdo-toolkit/blob/main/pyproject.toml)
+![Tested on NA/EU](https://img.shields.io/badge/tested-NA%2FEU-5b61a8?style=flat-square)
+[![Package: Stable](https://img.shields.io/badge/package-stable-2f855a?style=flat-square)](https://ychwu.github.io/bdo-toolkit/#stability)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2f855a?style=flat-square)](https://github.com/ychwu/bdo-toolkit/blob/main/LICENSE)
+
+Passive, read-only Python tooling that turns live or recorded Black Desert
+traffic into structured, application-ready data.
+
+[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
+[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
+[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
+[Report an issue](https://github.com/ychwu/bdo-toolkit/issues)
+
+> **Passive, read-only boundary.** bdo-toolkit observes local traffic or saved
+> captures. It does not send or modify packets, replay traffic to the game,
+> automate gameplay, inspect process memory, or bypass anti-cheat software.
+
+## Capabilities
+
+| In-game task | Python result | Status | Guide |
+| --- | --- | --- | --- |
+| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed `BDOEvent` objects | Stable | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
+| Log in or switch characters | One observational `ItemStateSnapshot` of inventory, known balances, and town storage | Beta | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
+| Load the Arena of Solare Leaderboard | One `SolareCaptureResult`; a complete result contains a leaderboard snapshot | Beta | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+
+Testing and validation cover **NA/EU only**. Compatibility with other regional
+services is unknown.
+
+## Installation
+
+```powershell
+python -m pip install bdo-toolkit
+```
+
+Python 3.10 or newer is required. Before live capture, complete
+[Installation & setup](https://ychwu.github.io/bdo-toolkit/#capture-foundation),
+including Npcap on Windows and permission to capture on the selected interface.
+Offline PCAP and PCAPNG replay does not require Npcap.
+
+## Get started
+
+1. Complete [Installation & setup](https://ychwu.github.io/bdo-toolkit/#capture-foundation).
+2. For item events or item state, prepare a current local profile through
+   [Opcode profile setup](https://ychwu.github.io/bdo-toolkit/#profiles).
+3. Run the [Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) or
+   choose a task from the [Examples](https://ychwu.github.io/bdo-toolkit/#item-examples)
+   index.
+
+Local calibration is the dependable patch-day path because maintained profiles
+require manual verification and may lag a weekly update. The
+[Calibration guide](https://ychwu.github.io/bdo-toolkit/#calibration-workflow)
+walks through rebuilding one. Arena of Solare uses structural classification
+and does not require an item opcode profile.
+
+## Runnable examples
+
+The source checkout includes maintained, run-ready lessons. They are not
+installed with the Python wheel.
+
+| Workflow | Representative script |
+| --- | --- |
+| Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
+| Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
+| Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
+| Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
+
+See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)
+for every script, its prerequisites, and the guide that explains it.
+
+## Documentation
+
+The documentation separates task-focused guides from the symbol-first API
+reference. Exact signatures, fields, lifecycle behavior, and failure contracts
+live there rather than in this README.
+
+| Goal | Start here |
+| --- | --- |
+| Understand the package | [Overview](https://ychwu.github.io/bdo-toolkit/#overview) |
+| Build with live item events | [Item events](https://ychwu.github.io/bdo-toolkit/#item-overview) |
+| Query character inventory and town storage | [Inventory & town storage](https://ychwu.github.io/bdo-toolkit/#item-state-overview) |
+| Rebuild item decoding after a patch | [Calibration](https://ychwu.github.io/bdo-toolkit/#calibration-workflow) |
+| Capture and query an Arena of Solare leaderboard | [Arena of Solare](https://ychwu.github.io/bdo-toolkit/#solare-overview) |
+| Integrate with an asyncio application | [Asyncio integration](https://ychwu.github.io/bdo-toolkit/#asyncio) |
+| Look up a class, function, or model | [API index](https://ychwu.github.io/bdo-toolkit/#api-index) |
+| Use the terminal interface | [Command line](https://ychwu.github.io/bdo-toolkit/#cli) |
+| Diagnose a problem | [Troubleshooting](https://ychwu.github.io/bdo-toolkit/#errors) |
+| Review data handling and project boundaries | [Safety & privacy](https://ychwu.github.io/bdo-toolkit/#stability) |
+
+## Support
+
+For questions, contact me on Discord: `._.__.__._._.__._____.__._.___.`
+
+For bugs and feature requests, [open a GitHub issue](https://github.com/ychwu/bdo-toolkit/issues).
+
+## Development
+
+```powershell
+git clone https://github.com/ychwu/bdo-toolkit.git
+cd bdo-toolkit
+python -m pip install -e ".[dev]"
+python -m pytest -q -W error
+python -m mypy src/bdo_toolkit
+python -m pip wheel . --no-deps --wheel-dir dist
+```
+
+CI runs tests, type checking, wheel construction, and a CLI smoke test on
+Ubuntu and Windows with Python 3.10 and 3.14. Tests that require private
+game-session captures skip when those local fixtures are absent.
+
+## License
+
+bdo-toolkit is available under the
+[MIT License](https://github.com/ychwu/bdo-toolkit/blob/main/LICENSE).

bdo_toolkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+bdo_toolkit/__init__.py,sha256=IHHF-M0Kej4hJseFCoifUzqNCUMGUpkQgdepExpMeiI,2426
+bdo_toolkit/_async_sessions.py,sha256=Bivq2z6meNg9js7Cfl_tl0DZcIxpWLhxuSFvzzshIac,23526
+bdo_toolkit/_capture_backend.py,sha256=jIDrwcZlDAkbxnDykygKIhWrfXuvrqzyV_T14GpQWqQ,6309
+bdo_toolkit/_capture_options.py,sha256=V4yXghywFI5ryABa4y2f4-J8cwRLpGDkYelhg0Z5orA,2599
+bdo_toolkit/_capture_runtime.py,sha256=7mtmZO1RG_3JeC2W5kmzLr14-9dY7xEEOqljcOjqlKE,23158
+bdo_toolkit/_deposit_origin.py,sha256=pvTP8EbqplwkYa7UEDfWhdh_CljapRBbg1DGitf2Pqc,65498
+bdo_toolkit/_engine.py,sha256=5vA6C9pFV2RQX3Qu-4IoaEtss_p9NLwVUAtt_Q6swq4,11465
+bdo_toolkit/_framing.py,sha256=jW052Z9emzuJgoFQLUzgjPS_KwZqmLA3T_Y0G4N_UlI,35838
+bdo_toolkit/_profile_runtime.py,sha256=SITpl3lYAsJAZTV6yGQxGF93GNtiPDZA3LTz5cOK3Mw,5370
+bdo_toolkit/_protocol.py,sha256=qNlz1i0TwjPDYclt2GoLFLZs2YVbmAh0oBpI4mPISsM,14784
+bdo_toolkit/_reassembly.py,sha256=z-AHz9DE3FCN_9dSUrfyEtSqJCEKUWP7QaPJw-Y7LZ0,24695
+bdo_toolkit/_specs.py,sha256=ivYMusVRoKfL8NKef3kWXLRmgSN2qj_NLaRUnLU8huY,10447
+bdo_toolkit/_storage_destination_validation.py,sha256=ddZsl90PoWcrAskaFztkhDUkmI2Ny2RRp5qncJA_PzA,5972
+bdo_toolkit/_storage_hydration.py,sha256=YcI6XM--Xlr3u2yompwFneHmZGd2zDZdKWDWdLAZw9Y,9193
+bdo_toolkit/_version.py,sha256=HH494g2Nndp-6bbDaaespNyaGP_MwltdAVHldX5e40Q,89
+bdo_toolkit/calibration.py,sha256=BtUV4uAtwGaKzYRTIParnS_Ln-k3oapAZVRqjn4sSOI,119749
+bdo_toolkit/capture.py,sha256=rD88UINPSm1UkCmL4n514XqGl1Rujlciy2d1PUzHK3M,67827
+bdo_toolkit/character_state.py,sha256=mUzSnNeMXUiSnvA24kDHH_G00nzcFUl5Y2_FkKeJ-e0,133342
+bdo_toolkit/cli.py,sha256=YvbGi2wUlAgh_OG_ELJDIPl51SNEKr_Z6H8-v5AhjEA,30161
+bdo_toolkit/diagnostics.py,sha256=9AIeMjRvhHu6WsOzGN27jVGY3HRJaiyVFJexvaiSGcI,1533
+bdo_toolkit/events.py,sha256=TUC34zzyx7x1Yn2m6I7Op7za5v5OAoWt3xBwVTE8sm8,7863
+bdo_toolkit/filters.py,sha256=xIo51ZlzaiGn-zSnASoqwgfEwgogA7TYSkUzRuOJFG0,3520
+bdo_toolkit/item_state.py,sha256=VGGNmDrxnS3Yp9Qsmdl3WD--KHHQwkHQ4uGgHszwLOg,1420
+bdo_toolkit/origin_learning.py,sha256=cok8NdlriW57SdzFEy1jJvrKm75tk__KqGcXQeMXRP4,30513
+bdo_toolkit/profiles.py,sha256=C9o5QnIBGJJ8aUZybl-fesR_4d6FleBAcyaknGpaei8,13535
+bdo_toolkit/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+bdo_toolkit/remote_profiles.py,sha256=8hp1yy51aRMp1A-xPXciWMBPUhYqmMu9MzPV6LT4F54,12393
+bdo_toolkit/writers.py,sha256=kDSsbjgRaqSbudnff_ZOTZZldseYe-lsRF45Qjogki0,795
+bdo_toolkit/solare/__init__.py,sha256=SYp35eP1KAJJemq3CAM8WbuL41eXU4s0EQtN4NrsLtY,1357
+bdo_toolkit/solare/_constants.py,sha256=mkBFbCEC4qzyxIKjXUHOeZI9T07p9KfguaiE7jc_jsM,2519
+bdo_toolkit/solare/_detail_learning.py,sha256=lRqvCfWocoAuRomTMlAYXb-s-XRZJPnPfPnMmLHJdgE,48167
+bdo_toolkit/solare/_details.py,sha256=60sfUzwckxODQAdSDKqkDPCZP8l3mkDL5_PJY4NBIzg,25307
+bdo_toolkit/solare/_discovery.py,sha256=_MNxRjRj3tM_j8XCpHXAAWgMj_2CT0gqGsgiC93ArKw,41783
+bdo_toolkit/solare/_live_tracker.py,sha256=2B39t0YRMuRIIPazL-by88YxO48yR_ETDbc_4aVSIdc,16882
+bdo_toolkit/solare/_replay_capture.py,sha256=3CdQmNJvITRGCpHMbPvwtJm8NMWXzs3dCsSx2SUdeOk,6496
+bdo_toolkit/solare/_result.py,sha256=5NOlF7meWb9RNOIiwtY7FrH5xSHlc-li8WnGB9nFqCA,14812
+bdo_toolkit/solare/_scanner.py,sha256=ZT8k7YQfh08jwViHlLEYcaQgq01rqjYp611v1WdUeSQ,7362
+bdo_toolkit/solare/_validation.py,sha256=t0VKdqtE5CmMAG0IZmGf0QXnWkCsFpotK_MVm4IX0eg,368
+bdo_toolkit/solare/async_session.py,sha256=Iv46B-HtUCbpkf0ajj4BOxGahXWAcjo9wXHPkrJMP0Q,16171
+bdo_toolkit/solare/models.py,sha256=LeZZap5uMomma75r0uFViqn-3lvtzEnGLYVYBDQQZEo,28430
+bdo_toolkit/solare/replay.py,sha256=2QscwgSKusDOP7UFS9IDS7HjS8IwpM5MiAxaYxk5MZo,2294
+bdo_toolkit/solare/session.py,sha256=oDwHy8p0bEbW5IeKPk-31ki4GmyWNT26Yks2IHwr6Jw,40844
+bdo_toolkit-1.0.0.dist-info/licenses/LICENSE,sha256=l6s0mOHPy4FbEBRHkIutumdsQ9Pnvje39r8kMK5GEqM,1081
+bdo_toolkit-1.0.0.dist-info/METADATA,sha256=jXr_sVqdsWtgNgP9gcZl6t0nn8J6cjry4yZZd-WOpSo,7437
+bdo_toolkit-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+bdo_toolkit-1.0.0.dist-info/entry_points.txt,sha256=ZB5mucU2MHptLvVEwxHA8aatxic87jI-2kqChu2N9Io,53
+bdo_toolkit-1.0.0.dist-info/top_level.txt,sha256=GePLVxjtrl4i5e3gKwUEzqxYW0_6dFI2rydrFykiXdk,12
+bdo_toolkit-1.0.0.dist-info/RECORD,,

bdo_toolkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bdo_toolkit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bdo-toolkit = bdo_toolkit.cli:main

bdo_toolkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bdo-toolkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bdo_toolkit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bdo_toolkit