Metadata-Version: 2.4
Name: pywee
Version: 0.1.0
Summary: Python Web Engine for Chromium-based local applications.
Author-email: Patrik Kratochvíl <patrik@kratochvil.technology>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://gitlab.com/pywee/runtime
Project-URL: Documentation, https://pywee.org/
Project-URL: Repository, https://gitlab.com/pywee/runtime.git
Project-URL: Issues, https://gitlab.com/pywee/runtime/-/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: src/pywee/third_party_licenses/CHROMIUM_LICENSE.txt
License-File: src/pywee/third_party_licenses/CHROMIUM_SOURCE.txt
License-File: src/pywee/third_party_licenses/PLAYWRIGHT_LICENSE.txt
License-File: src/pywee/third_party_licenses/PLAYWRIGHT_NOTICE.txt
License-File: src/pywee/third_party_licenses/README.md
Dynamic: license-file

# PyWee

PyWee is a Python Web Engine built on Chromium for trusted local GUI
applications. Applications use standard HTML and CSS, while frontend behavior
can be written in Python through `<script type="python">`. JavaScript remains
available when an application enables it.

PyWee uses one locked, package-managed Chromium runtime. It never searches for
or falls back to a system browser. Chromium is downloaded automatically into
the PyWee cache on first run, or explicitly with `pywee chromium install`.
The runtime lock records browser identity, source provenance, per-platform
artifact URLs, sizes, and SHA256 checksums for deterministic installation.

## Install

Install PyWee from PyPI into the Python environment that should execute the
application code:

```bash
python3 -m pip install pywee
pywee chromium install
pywee chromium verify
```

Create and run an application:

```bash
pywee init my-app
pywee run my-app
```

PyWee uses the interpreter environment that launches the CLI. Application
dependencies declared in `pywee.toml` are installed into that same environment:

```bash
pywee pip my-app install-deps
```

There is no PyWee permission or filesystem sandbox for Python code. Python runs
as trusted local application code with the OS permissions of the launching user.

## Platform Status

| Platform | Release status |
| --- | --- |
| Linux x64 | Tested by the runtime test suite and Chromium integration smoke test. |
| Linux ARM64 | Locked artifact and packaging path are prepared; native ARM64 execution is not yet tested. |
| Windows x64 | Locked artifact and runtime path are prepared; **not tested yet**. |
| macOS x64/ARM64 | Locked artifacts are present; execution is not tested. |

The normal PyPI wheel is platform-independent and downloads only the exact
runtime selected for the host. A platform is considered tested only after its
native Chromium smoke job passes; the presence of an entry in the lock file is
not presented as execution validation.

CI exposes manual cross-platform archive audits for Linux ARM64 and Windows
x64. These jobs verify download availability, SHA256, ZIP extraction, and the
expected executable layout without incorrectly claiming native execution.
The separate manual Linux offline-wheel job builds the browser-containing wheel
and audits its exact metadata, generated credits, and static licenses.

## Application Manifest

Every application has one `pywee.toml` in its root:

```toml
[app]
name = "Hello World"
entry = "web/index.html"
trusted = true

[window]
mode = "window" # window, fullscreen, borderless

[python]
enabled = true
requirements = []

[javascript]
enabled = false
```

Small applications may keep Python directly in HTML:

```html
<strong id="status">starting</strong>

<script type="python">
from browser import document

document.querySelector("#status").textContent = "running from Python"
</script>
```

## Repositories

- [Documentation](https://pywee.org) contains installation,
  CLI, manifest, architecture, distribution, and roadmap documentation.
- [Examples](https://gitlab.com/pywee/examples) contains complete runnable
  applications for controls, 3D visualization, OpenCV, charts, and simulation.
- [Runtime](https://gitlab.com/pywee/runtime) is this installable Python package.

The generated documentation is published at
[pywee.org](https://pywee.org). Its source is maintained in
[`general/pywee`](https://git.rbtcz.cz/general/pywee).

## Development

```bash
git clone https://gitlab.com/pywee/runtime.git
cd runtime
python3 -m pip install -e .
python3 -m unittest discover -s tests
```

Build and inspect release artifacts in an isolated build environment:

```bash
python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*
python3 -m build_support.release_audit dist
```

## Project Layout

```text
build_support/                  Locked Chromium artifact build support
src/pywee/                      Runtime package, CLI, browser host, and DOM wrappers
src/pywee/third_party_licenses/ Canonical Chromium provider licenses
tests/                          Unit and Chromium integration tests
```

## License

PyWee is licensed under the GNU Lesser General Public License, version 3 only
(`LGPL-3.0-only`). See [LICENSE](LICENSE), [NOTICE](NOTICE), and
[third-party runtime licenses](src/pywee/third_party_licenses/README.md).

Every downloaded or offline-bundled Chromium directory contains the complete
top-level Chromium license, the Playwright provider license and attribution,
generated `CHROMIUM_CREDITS.html`, and exact artifact metadata. Verify this
evidence with `pywee chromium verify`.

Copyright (C) 2026 Patrik Kratochvíl <patrik@kratochvil.technology>.
