Metadata-Version: 2.4
Name: hbrowser
Version: 0.28.0
Summary: A tool for browsing tasks on e-h/exh-websites.
Project-URL: Homepage, https://github.com/Kuan-Lun/hbrowser
Project-URL: Tracker, https://github.com/Kuan-Lun/hbrowser/issues
Author: Kuan-Lun Wang
License: GNU Affero General Public License v3
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.11
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: fake-useragent>=2.2.0
Requires-Dist: h2h-galleryinfo-parser>=0.2.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: hv-bie>=0.5.3
Requires-Dist: ponychart-classifier>=0.6.1
Requires-Dist: zendriver>=0.15.3
Provides-Extra: dev
Requires-Dist: black>=26.5.1; extra == 'dev'
Requires-Dist: mypy>=2.1.0; extra == 'dev'
Requires-Dist: pymarkdownlnt>=0.9.37; extra == 'dev'
Requires-Dist: ruff>=0.15.16; extra == 'dev'
Description-Content-Type: text/markdown

# HBrowser (hbrowser)

## Setup

### Tor Proxy (Optional)

HBrowser can route all traffic through the Tor network for IP privacy. If Tor Browser is installed, HBrowser will automatically detect and use it. To install:

1. Download and install from <https://www.torproject.org/download/>
2. HBrowser will automatically locate the `tor` binary from the default installation path:
   - **macOS**: `/Applications/Tor Browser.app/Contents/MacOS/Tor/tor`
   - **Linux**: `/usr/bin/tor`
   - **Windows**: Searches common installation paths (`Desktop`, `AppData`, `Program Files`)
3. If Tor Browser is not installed, HBrowser will use a direct connection instead.
4. To force disable Tor even when installed, set `USE_TOR=0`.
5. If your Tor Browser is installed in a non-standard location, set the `TOR_BINARY_PATH` environment variable.

### FlareSolverr (Optional)

HBrowser can use [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) to automatically
solve Cloudflare's "managed challenge" (the plain JS challenge, not the interactive Turnstile
widget) without manual interaction. Set `FLARESOLVERR_URL` to your FlareSolverr instance's `/v1`
endpoint to enable it, e.g. `http://127.0.0.1:8191/v1`.

FlareSolverr's solved `cf_clearance` cookie is tied to the IP address it solved from, so it is
only used when Tor is **not** active — if both `USE_TOR` (or auto-detected Tor) and
`FLARESOLVERR_URL` are set, HBrowser ignores FlareSolverr and logs a warning, since the cookie
would not match the Tor exit IP anyway.

### Environment Variables

HBrowser requires the following environment variables:

- `EH_USERNAME`: Your E-Hentai account username
- `EH_PASSWORD`: Your E-Hentai account password
- `HBROWSER_LOG_LEVEL` (optional): Control logging verbosity (DEBUG, INFO, WARNING, ERROR). Default: INFO
- `USE_TOR` (optional): Set to `0` to disable Tor proxy even when Tor Browser is installed. Default: auto-detect
- `TOR_BINARY_PATH` (optional): Custom path to the `tor` binary if not installed in the default location
- `FLARESOLVERR_URL` (optional): FlareSolverr `/v1` endpoint used to auto-solve Cloudflare managed challenges. Ignored when Tor is active

Set the environment variables before running the script:

**Bash/Zsh:**

```bash
export EH_USERNAME=your_username
export EH_PASSWORD=your_password
export HBROWSER_LOG_LEVEL=INFO          # Optional
export USE_TOR=0                        # Optional: disable Tor proxy
export TOR_BINARY_PATH=/path/to/tor     # Optional: custom tor path
export FLARESOLVERR_URL=http://127.0.0.1:8191/v1  # Optional: auto-solve Cloudflare
```

**Fish:**

```fish
set -x EH_USERNAME your_username
set -x EH_PASSWORD your_password
set -x HBROWSER_LOG_LEVEL INFO          # Optional
set -x USE_TOR 0                        # Optional: disable Tor proxy
set -x TOR_BINARY_PATH /path/to/tor     # Optional: custom tor path
set -x FLARESOLVERR_URL http://127.0.0.1:8191/v1  # Optional: auto-solve Cloudflare
```

**Windows Command Prompt:**

```cmd
set EH_USERNAME=your_username
set EH_PASSWORD=your_password
set HBROWSER_LOG_LEVEL=INFO
set USE_TOR=0
set TOR_BINARY_PATH=C:\path\to\tor.exe
set FLARESOLVERR_URL=http://127.0.0.1:8191/v1
```

**Windows PowerShell:**

```powershell
$env:EH_USERNAME="your_username"
$env:EH_PASSWORD="your_password"
$env:HBROWSER_LOG_LEVEL="INFO"
$env:USE_TOR="0"
$env:TOR_BINARY_PATH="C:\path\to\tor.exe"
$env:FLARESOLVERR_URL="http://127.0.0.1:8191/v1"
```

When a Cloudflare or CAPTCHA challenge appears during login, HBrowser will first try
FlareSolverr (if configured and applicable), then fall back to waiting for you to solve it
manually in the browser window. Set `headless=False` when initialising the driver to see the
browser window.

## Logging

HBrowser uses Python's built-in `logging` module. You can control the log level using the `HBROWSER_LOG_LEVEL` environment variable:

- **DEBUG**: Detailed information for diagnosing problems (most verbose)
- **INFO**: Confirmation that things are working as expected (default)
- **WARNING**: Something unexpected happened, but the software is still working
- **ERROR**: A serious problem that prevented a function from executing

Example:

```bash
# Set log level to DEBUG for detailed output
export HBROWSER_LOG_LEVEL=DEBUG
python your_script.py

# Set log level to WARNING to see only warnings and errors
export HBROWSER_LOG_LEVEL=WARNING
python your_script.py
```

## Usage

Here's a quick example of how to use HBrowser:

```python
from hbrowser import EHDriver


if __name__ == "__main__":
    with EHDriver() as driver:
        driver.punchin()
```

Here's a quick example of how to use HVBrowser:

```python
from hvbrowser import HVDriver


if __name__ == "__main__":
    with HVDriver() as driver:
        driver.monstercheck()
```
