Metadata-Version: 2.4
Name: linux-browser
Version: 0.1.3
Summary: A small Chromium-powered graphical web browser for Linux
Author: linux-browser contributors
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PySide6<7,>=6.6

# Linux Browser

A small graphical browser for Linux, packaged as a normal Python application. It uses Qt WebEngine, which embeds Chromium, so pages are rendered with their real HTML, CSS, JavaScript, images, and network behavior rather than being converted to terminal text.

## Debian 12 / Ubuntu Installation

### Dependencies

Install graphics and browser libraries:

```bash
sudo apt update
sudo apt install -y \
  libgl1 libegl1 \
  libxkbcommon-x11-0 libxcb-cursor0 \
  libxcomposite1 libxdamage1 libxrandr2 \
  libnss3 libxshmfence1 libxtst6 \
  libasound2t64 xvfb xdg-utils
```

The PyPI wheels provide the Qt and Chromium components. A working display or Xvfb (virtual framebuffer) is required to render pages.

### Usage

**With a graphical display (desktop/GUI environment):**
```bash
linux-browser https://example.com
```

**Headless (no display server):**
```bash
QT_QPA_PLATFORM=offscreen xvfb-run -a linux-browser https://example.com
```

**Via SSH or in a container:**
```bash
export DISPLAY=:99
Xvfb :99 &
linux-browser https://example.com
```

## Install and run

```bash
python3 -m venv .venv
.venv/bin/python -m pip install linux-browser
.venv/bin/linux-browser
```

Open a specific page directly:

```bash
linux-browser https://example.com
```

The address bar accepts URLs and search terms. Back, forward, reload, and common keyboard shortcuts are available in the toolbar.

## Development

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e . pytest build
.venv/bin/python -m pytest
```

The WebEngine test loads an in-memory page and checks that CSS and JavaScript execute (powered by PySide6's built-in WebEngine). It is skipped when PySide6 is not installed, which keeps package metadata checks usable in minimal build environments.

## Build and publish

Build the package and validate it before uploading:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip build twine
python -m build
python -m twine check dist/*
```

Publish with your PyPI API token:

```bash
export PYPI_API_TOKEN="pypi-xxxxxxxxxxxxxxxx"
TWINE_USERNAME="__token__" TWINE_PASSWORD="$PYPI_API_TOKEN" python -m twine upload --repository pypi dist/*
```

You can also use the helper script in this repo:

```bash
chmod +x scripts/publish.sh
export PYPI_API_TOKEN="pypi-xxxxxxxxxxxxxxxx"
./scripts/publish.sh
```

Use the token value from your PyPI account, not your account password. The `__token__` username is the standard PyPI format for API tokens.
