HVBattle

HVBattle provides reusable HentaiVerse battle-domain APIs. It builds on hvbrowser for the authenticated Hentaiverse browser session and keeps the private command-line runner in a separate application workspace.

The package exposes a policy-neutral BattleSession, atomic battle actions, and a BattleRunner that runs exactly one already-active battle using a client-supplied BattleStrategy. It never repairs equipment, recovers stamina, or starts Arena/GrindFest on its own. Campaign policy and post-battle work belong to the calling application.

BattleSession preloads the PonyChart classifier and ONNX model before opening the browser, so a timed challenge never pays the first-load cost. The runner checks for and resolves PonyChart before parsing an ordinary battle turn or calling client strategy code.

import asyncio

from hvbattle import BattleCompleted, BattleRunner, BattleSession, TurnDecision


class MyStrategy:
    async def take_turn(self, session: BattleSession, /) -> TurnDecision:
        if await session.go_next_floor():
            return TurnDecision.ACTED
        if not session.alive_monster_ids:
            return TurnDecision.IDLE
        if await session.attack_monster(session.alive_monster_ids[0]):
            return TurnDecision.ACTED
        return TurnDecision.IDLE


async def after_battle(session: BattleSession, completed: BattleCompleted) -> None:
    print(completed)


async def main() -> None:
    async with BattleSession(headless=True) as session:
        result = await BattleRunner(session, MyStrategy()).run_current()
        if isinstance(result, BattleCompleted):
            await after_battle(session, result)


asyncio.run(main())

The example requires credentials through the normal EH_USERNAME and EH_PASSWORD indirection and an already-active server battle; otherwise run_current() returns None. TurnDecision.STOP deliberately returns a BattleStopped result. Leaving the battle page without positive final-round completion evidence raises BattleInterruptedError, so callers cannot mistake an expired login or unexpected navigation for a completed battle.

BattleDriver is only a transitional name alias for BattleSession, not an API-compatible implementation of the old driver. Migrate constructor strategy settings into a BattleStrategy, replace driver.battle() with BattleRunner(driver, strategy).run_current(), and perform maintenance, post-battle tasks, and next-battle selection after the returned BattleCompleted. Arena choice follows the same boundary: list_arena_options() returns data and start_arena(option) starts only the option explicitly selected by the caller. GrindFest uses the equivalent list_grindfest_options() and start_grindfest(option) pair; the package does not silently choose the first or last server option.

BaseControlPanel, ControlPanel, and NullControlPanel provide reusable pause, named-action, named-toggle, and validated integer mechanisms. The set_actions() API is the generic spelling; the older set_skills() spelling remains available as a compatibility alias. Integer edits become live only after Apply or Enter, so partially typed mutation amounts are never published. Closing the interactive window sets the pause flag before the GUI exits.

The package does not register campaign choices or choose their defaults: a calling application owns the control names, labels, initial values, and the policy that reads their committed state. Importing hvbattle does not import Tk or start a GUI process.

Development

Build a clean environment backed by PyPI releases:

bash scripts/rebuild-env.sh

For coordinated local development before all dependent releases are on PyPI, overlay editable checkouts in dependency order:

uv pip install --python .venv/bin/python --reinstall --no-deps --editable \
  /Users/kuanlun_wang/Desktop/git-repo/hbrowser.clone
uv pip install --python .venv/bin/python --reinstall --no-deps --editable \
  /Users/kuanlun_wang/Desktop/git-repo/hvbrowser.clone

Commands that must preserve these editable overlays use uv run --no-sync.

Project links

Data verified by PyPI on Aug 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.15.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kuan-lun from gravatar.com kuan-lun

Credits

Author: Kuan-Lun Wang

GitHub Statistics

Data verified by PyPI on Aug 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

AGPL-3.0-or-later
View SPDX License List

Requires

Python <3.15, >=3.14

Provides Extra

dev

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hvbattle-0.2.3.tar.gz (49.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hvbattle-0.2.3-py3-none-any.whl (43.5 kB view details)

Uploaded Python 3

File details

Details for the file hvbattle-0.2.3.tar.gz.

File metadata

  • Download URL: hvbattle-0.2.3.tar.gz
  • Upload date:
  • Size: 49.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hvbattle-0.2.3.tar.gz
Algorithm Hash digest
SHA256 7dd982b17df6eb4895b5279419d7a1be138730a7b32a6231224630af2e27cbb5
MD5 5c11f91e1e76bedbe65a68488b21bacb
BLAKE2b-256 b32827f8987e951702517f78c79393a06b73b3773a469bd607ea33d454f31570

See more details on using hashes here.

Provenance

The following attestation bundles were made for hvbattle-0.2.3.tar.gz:

Publisher: publish.yml on Kuan-Lun/hvbattle

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hvbattle-0.2.3-py3-none-any.whl.

File metadata

  • Download URL: hvbattle-0.2.3-py3-none-any.whl
  • Upload date:
  • Size: 43.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hvbattle-0.2.3-py3-none-any.whl
Algorithm Hash digest
SHA256 b9272927e0faee8104ff83b5b3586c8eff079eabcb47ca95b8b1752733d92ae5
MD5 83c514ddbdf1923abb4c6810e3469fc0
BLAKE2b-256 be820e75aa0a9bd17c4c6087f4cae0701a21bd79c7eabec03792d12a4923ee06

See more details on using hashes here.

Provenance

The following attestation bundles were made for hvbattle-0.2.3-py3-none-any.whl:

Publisher: publish.yml on Kuan-Lun/hvbattle

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.15.0

2 files

0.14.3

2 files

0.14.2

2 files

0.14.1

2 files

0.13.1

2 files

0.13.0

2 files

0.12.2

2 files

0.11.6

2 files

0.11.5

2 files

0.11.4

2 files

0.11.3

2 files

0.11.0

2 files

0.10.3

2 files

0.10.2

2 files

0.10.1

2 files

0.9.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

0.4.39

2 files

0.4.38

2 files

0.4.37

2 files

0.4.36

2 files

0.4.35

2 files

0.4.34

2 files

0.4.33

2 files

0.4.32

2 files

0.4.31

2 files

0.4.30

2 files

0.4.29

2 files

0.4.28

2 files

0.4.27

2 files

0.4.25

2 files

0.4.24

2 files

0.4.23

2 files

0.4.22

2 files

0.4.21

2 files

0.4.20

2 files

0.4.19

2 files

0.4.18

2 files

0.4.16

2 files

0.4.15

2 files

0.4.14

2 files

0.4.12

2 files

0.4.11

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.1

2 files

0.3.0

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

This release

0.2.3 This release

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page