bdo-toolkit 1.0.0__tar.gz

bdo_toolkit-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bdo-toolkit"
+dynamic = ["version"]
+description = "Passive, read-only BDO packet parsing toolkit for app developers."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "scapy>=2.5",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "bdo-toolkit contributors" },
+]
+keywords = ["bdo", "packets", "parse", "pcap", "passive"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "pytest-cov",
+  "mypy",
+]
+
+[project.urls]
+Homepage = "https://github.com/ychwu/bdo-toolkit"
+Documentation = "https://ychwu.github.io/bdo-toolkit/"
+Repository = "https://github.com/ychwu/bdo-toolkit.git"
+Issues = "https://github.com/ychwu/bdo-toolkit/issues"
+
+[project.scripts]
+bdo-toolkit = "bdo_toolkit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.package-data]
+bdo_toolkit = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "bdo_toolkit._version.__version__" }

bdo_toolkit-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bdo_toolkit-1.0.0/src/bdo_toolkit/__init__.py

@@ -0,0 +1,87 @@
+"""Public API for the passive bdo-toolkit."""
+
+from ._async_sessions import AsyncCalibrationSession, AsyncLiveCaptureSession
+from ._capture_options import LiveCaptureOptions, PacketCaptureOptions
+from ._capture_runtime import CaptureEndpoint
+from .capture import (
+    CaptureIntegrityError,
+    LiveCaptureHealth,
+    LiveCaptureSession,
+    capture_live,
+    replay_pcap,
+)
+from .events import BDOEvent, Flow
+from .diagnostics import DecoderDiagnostic, DecoderHealth
+from .filters import EventFilter
+from .profiles import (
+    OPCODE_PROFILE_SCHEMA_VERSION,
+    OpcodeProfile,
+    OriginCompanionFamily,
+    ProfileError,
+    load_opcode_profile,
+)
+from .remote_profiles import (
+    DEFAULT_REMOTE_PROFILE_MAX_BYTES,
+    DEFAULT_REMOTE_PROFILE_TIMEOUT_SECONDS,
+    ProfileFetchResult,
+    REMOTE_PROFILE_ENVELOPE_VERSION,
+    RemoteProfileError,
+    fetch_opcode_profile,
+)
+from ._protocol import StorageLocation, storage_location
+from .origin_learning import (
+    CompanionObservation,
+    DEFAULT_ORIGIN_LEARNING_MAX_CANDIDATES,
+    DEFAULT_ORIGIN_LEARNING_MAX_OBSERVATIONS,
+    OriginCompanionCandidate,
+    OriginLearner,
+    OriginLearningLimitError,
+    OriginPromotion,
+    promote_origin_candidates,
+)
+from .writers import ConsoleEventWriter, JsonlEventWriter
+from . import solare
+from ._version import __version__
+
+__all__ = [
+    "AsyncCalibrationSession",
+    "AsyncLiveCaptureSession",
+    "BDOEvent",
+    "CaptureEndpoint",
+    "CaptureIntegrityError",
+    "ConsoleEventWriter",
+    "DecoderDiagnostic",
+    "DecoderHealth",
+    "EventFilter",
+    "Flow",
+    "JsonlEventWriter",
+    "LiveCaptureOptions",
+    "LiveCaptureHealth",
+    "LiveCaptureSession",
+    "OPCODE_PROFILE_SCHEMA_VERSION",
+    "PacketCaptureOptions",
+    "OpcodeProfile",
+    "OriginCompanionFamily",
+    "CompanionObservation",
+    "DEFAULT_ORIGIN_LEARNING_MAX_CANDIDATES",
+    "DEFAULT_ORIGIN_LEARNING_MAX_OBSERVATIONS",
+    "DEFAULT_REMOTE_PROFILE_MAX_BYTES",
+    "DEFAULT_REMOTE_PROFILE_TIMEOUT_SECONDS",
+    "OriginCompanionCandidate",
+    "OriginLearner",
+    "OriginLearningLimitError",
+    "OriginPromotion",
+    "ProfileError",
+    "ProfileFetchResult",
+    "REMOTE_PROFILE_ENVELOPE_VERSION",
+    "RemoteProfileError",
+    "StorageLocation",
+    "__version__",
+    "capture_live",
+    "fetch_opcode_profile",
+    "load_opcode_profile",
+    "promote_origin_candidates",
+    "replay_pcap",
+    "storage_location",
+    "solare",
+]