Metadata-Version: 2.4
Name: urllib_gui
Version: 0.2.0
Summary: A gui for urllib. Something between curl and postman and a browser. Almost all stdlib
Project-URL: Repository, https://github.com/matthewdeanmartin/urllib_gui
Project-URL: Documentation, https://urllib_gui.readthedocs.io/en/latest/
Project-URL: Changelog, https://github.com/matthewdeanmartin/urllib_gui/blob/main/CHANGELOG.md
Project-URL: homepage, https://github.com/matthewdeanmartin/urllib_gui
Project-URL: issues, https://github.com/matthewdeanmartin/urllib_gui/issues/
Author-email: Matthew Martin <matthewdeanmartin@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: urllib_gui
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.12
Provides-Extra: all
Requires-Dist: do-i-need-to-upgrade>=0.0.1; extra == 'all'
Description-Content-Type: text/markdown

# urllib_gui

`urllib_gui` is a small desktop client built with Tkinter and Python's standard-library `urllib` stack. It sits somewhere between a text browser, an API scratchpad, and a lightweight request inspector: you can open `http`, `https`, and `file` URLs, adjust request settings, inspect responses, and save the parts you want to keep.

The current app is intentionally modest. It renders HTML into readable text, not a full browser engine. There is no JavaScript execution, no DOM inspector, and no headless automation layer. The value here is a simple GUI around `urllib`, with very little magic and very few dependencies.

## Current feature set

- Open `http`, `https`, and `file` URLs in tabs.
- Navigate with back, forward, reload, and open-in-new-tab flows.
- Render HTML into readable text and follow extracted links inside the app.
- Switch between **Rendered**, **Source**, **Headers**, and **Request** views.
- Use the request drawer to change method, headers, body, timeout, redirects, proxy, TLS verification, cookies, and auth.
- Preview the exact request before sending it.
- Copy the current request as generated `urllib` code or as a `curl` command.
- Save request templates to a scratchpad or export/import them as JSON.
- Save response bodies or rendered text to disk.
- Keep persistent browsing history, bookmarks, saved requests, and preferences.
- Inspect and clear cookies from the active cookie jar.
- Switch between light and dark themes and adjust rendering preferences.

## Installation

## Install from PyPI

With `pipx`:

```bash
pipx install urllib_gui
```

With `pip`:

```bash
pip install urllib_gui
```

Install the optional update-checking integration too:

```bash
pip install "urllib_gui[all]"
```

With `pipx`:

```bash
pipx install "urllib_gui[all]"
```

## Install from source

```bash
git clone https://github.com/matthewdeanmartin/urllib_gui.git
cd urllib_gui
uv sync --all-extras
```

## Requirements

- Python 3.13 or newer
- A working Tkinter desktop environment
- Network access for `http` and `https` requests

If you are on a minimal Linux install, you may need to install the OS package that provides Tk before launching the app.

## Running the app

Show CLI help:

```bash
urllib_gui --help
```

Launch the GUI:

```bash
urllib_gui
```

Open a URL immediately:

```bash
urllib_gui https://example.com
```

Start in dark mode:

```bash
urllib_gui --theme dark https://example.com
```

You can also launch it as a module:

```bash
python -m urllib_gui https://example.com
```

## How to use it

## Basic browsing

1. Start the app and type a URL into the location bar.
1. Press Enter or click **Go**.
1. Use **Back**, **Forward**, and **Reload** as you would in a simple browser.
1. Open local files with **File -> Open File**.

Supported schemes are currently limited to `http`, `https`, and `file`.

## Request editing

Open **View -> Toggle Request Options** to show the request drawer. That drawer is where the application becomes more than a basic browser tab.

From the drawer you can:

- choose standard HTTP methods or enter a custom one
- add or remove headers, including preset groups
- send raw text, form-urlencoded data, or JSON bodies
- change timeouts
- choose environment proxy settings, no proxy, or a manual proxy URL
- disable TLS verification when needed
- enable or disable cookies
- use Basic auth, Bearer auth, or a custom `Authorization` header
- preview the exact request before sending it

The CLI only launches the GUI and optionally seeds the starting URL and theme. Request customization happens inside the desktop app.

## Optional update checks

`urllib_gui` can integrate with `do_i_need_to_upgrade`, but that support is intentionally optional so the base install stays lean.

If installed with `urllib_gui[all]`:

- the GUI quietly checks for updates on startup and shutdown
- terminal notices can appear during normal app usage
- `urllib_gui upgrade`
- `urllib_gui check-updates`

If the extra is not installed, `urllib_gui` still runs normally and simply skips the update-check feature.

## Response inspection

Use the view selector or the **View** menu to switch between:

- **Rendered**: HTML converted to readable text with clickable links
- **Source**: decoded response body
- **Headers**: status line and response headers
- **Request**: a readable request preview

For HTML responses, the built-in renderers are:

- `stdlib_html_links`
- `stdlib_html_text`
- `plain`
- `html_source`

If compatible third-party packages are installed, additional renderers are discovered automatically.

## Saving and exporting

The app includes a few persistence and export tools:

- **Bookmarks** can be added, edited, searched, tagged, imported, and exported as JSON.
- **History** is stored in SQLite and can be searched or cleared.
- **Request scratchpad** stores named request templates in SQLite.
- **Request files** can be exported to JSON and loaded back later.
- **Copy as urllib Code** generates a Python snippet.
- **Copy as curl** generates a best-effort `curl` equivalent.
- **Save Response Body As...** writes raw bytes to disk.
- **Save Rendered Text As...** writes the rendered text view to disk.

## Preferences and stored data

Preferences are stored under `~/.urllib_gui/`, alongside the app's local data files:

- `config.ini`
- `history.sqlite3`
- `bookmarks.sqlite3`
- `saved_requests.sqlite3`

From the Preferences dialog you can change theme, font settings, link-opening behavior, default timeout, default user agent, cookie behavior, TLS verification, proxy defaults, auth defaults, render engine, and default encoding.

## Keyboard shortcuts

- `Ctrl+L` focus the location bar
- `Ctrl+T` new tab
- `Ctrl+W` close tab
- `Ctrl+R` reload
- `Alt+Left` back
- `Alt+Right` forward
- `Ctrl+D` bookmark current page
- `Ctrl+S` save the current response body
- `Ctrl+F` find in page
- `Ctrl++`, `Ctrl+-`, `Ctrl+0` zoom controls

## Documentation

Project docs live in [`docs/`](https://github.com/matthewdeanmartin/urllib_gui/tree/main/docs/) and are built with MkDocs for Read the Docs. The docs cover installation, day-to-day usage, request workflows, and contributing.

## Contributing

See [CONTRIBUTING.md](https://github.com/matthewdeanmartin/urllib_gui/blob/main/CONTRIBUTING.md) for the local workflow, quality gates, and how CI is wired.

## License

MIT - see [LICENSE](https://github.com/matthewdeanmartin/urllib_gui/blob/main/LICENSE).

## Changelog

See [CHANGELOG.md](https://github.com/matthewdeanmartin/urllib_gui/blob/main/CHANGELOG.md).

## Project Links

- [GitHub](https://github.com/matthewdeanmartin/urllib_gui)
- [PyPI](https://pypi.org/project/urllib-gui/)
- [Documentation](https://urllib_gui.readthedocs.io/en/latest/)
- [Bug Tracker](https://github.com/matthewdeanmartin/urllib_gui/issues)
- [Change Log](https://github.com/matthewdeanmartin/urllib_gui/blob/main/CHANGELOG.md)
