pymarklet 0.1.0__py3-none-any.whl

pymarklet/__init__.py

@@ -0,0 +1,6 @@
+"""Create browser bookmarklets that run Python with Pyodide."""
+
+from .generator import build_bookmarklet, declared_pypi_packages, imported_package_modules
+
+__all__ = ["build_bookmarklet", "declared_pypi_packages", "imported_package_modules"]
+__version__ = "0.1.0"

pymarklet/cli.py

@@ -0,0 +1,35 @@
+"""Command-line interface for PyMarklet."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from pathlib import Path
+
+from .generator import generate_bookmarklet
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Generate a Pyodide-powered browser bookmarklet from a Python script.",
+    )
+    parser.add_argument("python_file", type=Path, help="UTF-8 Python source file to embed")
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path("bookmarklet.js"),
+        help="destination for the bookmarklet URL (default: bookmarklet.js)",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the PyMarklet CLI and return a process exit status."""
+    args = build_parser().parse_args(argv)
+    return 0 if generate_bookmarklet(args.python_file, args.output) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pymarklet/generator.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import ast
+import json
+import re
+from pathlib import Path
+from urllib.parse import quote
+
+PYODIDE_VERSION = "0.27.5"
+PYODIDE_BASE_URL = f"https://cdn.jsdelivr.net/pyodide/v{PYODIDE_VERSION}/full/"
+PYODIDE_SCRIPT_URL = f"{PYODIDE_BASE_URL}pyodide.js"
+
+
+# Final optimized, pre-minified JavaScript layout shell
+JAVASCRIPT_TEMPLATE = r"""(() => {
+const cId = "py-bookmarklet-container";
+if (document.getElementById(cId)) return;
+const c = document.createElement("section");
+c.id = cId;
+c.style.cssText = "position:fixed;top:10px;right:10px;width:400px;height:500px;z-index:2147483647;display:flex;flex-direction:column;overflow:hidden;box-sizing:border-box;border:1px solid #333;border-radius:8px;background:#1e1e1e;color:#f4f4f4;font-family:monospace;box-shadow:0 4px 15px rgba(0,0,0,.3)";
+const h = document.createElement("header");
+h.style.cssText = "display:flex;align-items:center;justify-content:space-between;padding:8px 12px;background:#2d2d2d;border-bottom:1px solid #333;cursor:grab;user-select:none;touch-action:none";
+const s = document.createElement("span");
+s.textContent = "Loading Pyodide...";
+s.style.cssText = "overflow:hidden;color:#6f6;font-size:12px;font-weight:bold;text-overflow:ellipsis;white-space:nowrap";
+const cb = document.createElement("button");
+cb.type = "button"; cb.textContent = "×"; cb.setAttribute("aria-label", "Close");
+cb.style.cssText = "margin-left:12px;border:0;background:transparent;color:#f66;cursor:pointer;font-size:20px;font-weight:bold;line-height:1";
+const ct = document.createElement("div");
+ct.style.cssText = "flex:1;min-height:0;display:flex;flex-direction:column;overflow:hidden";
+const cv = document.createElement("canvas");
+cv.id = "canvas"; cv.tabIndex = 0; cv.style.cssText = "display:block;max-width:100%;max-height:70%;margin:0 auto;background:#000;image-rendering:pixelated;outline:none";
+cv.addEventListener("pointerdown", () => cv.focus());
+const o = document.createElement("pre");
+o.style.cssText = "flex:1;min-height:0;overflow:auto;margin:0;padding:15px;box-sizing:border-box;white-space:pre-wrap;overflow-wrap:anywhere";
+h.append(s, cb); ct.append(cv, o); c.append(h, ct); document.body.appendChild(c);
+const setStatus = (msg, isErr = false) => { s.textContent = msg; s.style.color = isErr ? "#f66" : "#6f6"; };
+const log = (val) => { o.textContent += `${String(val)}\n`; o.scrollTop = o.scrollHeight; };
+cb.addEventListener("click", () => c.remove());
+let dx = 0, dy = 0;
+h.addEventListener("pointerdown", (e) => {
+  if (e.target === cb) return;
+  const b = c.getBoundingClientRect();
+  dx = e.clientX - b.left; dy = e.clientY - b.top;
+  h.setPointerCapture(e.pointerId); h.style.cursor = "grabbing";
+});
+h.addEventListener("pointermove", (e) => {
+  if (!h.hasPointerCapture(e.pointerId)) return;
+  const ml = Math.max(0, window.innerWidth - c.offsetWidth);
+  const mt = Math.max(0, window.innerHeight - c.offsetHeight);
+  const left = Math.min(ml, Math.max(0, e.clientX - dx));
+  const top = Math.min(mt, Math.max(0, e.clientY - dy));
+  c.style.left = `${left}px`; c.style.top = `${top}px`; c.style.right = "auto";
+});
+const stop = (e) => { if (h.hasPointerCapture(e.pointerId)) h.releasePointerCapture(e.pointerId); h.style.cursor = "grab"; };
+h.addEventListener("pointerup", stop); h.addEventListener("pointercancel", stop);
+
+__DATA_SPLICING_PLACEHOLDER__
+
+async function runPython() {
+  try {
+    setStatus("Starting Python...");
+    const pyodide = await globalThis.loadPyodide({ indexURL: "__PYODIDE_BASE_URL__", stdout: log, stderr: log });
+    pyodide._api._skip_unwind_fatal_error = true;
+    pyodide.canvas.setCanvas2D(cv);
+    
+    setStatus("Resolving Pyodide imports...");
+    await pyodide.loadPackagesFromImports(pyCode);
+
+    const installPyPiPackages = async (packages) => {
+      if (!packages.length) return;
+      setStatus(`Installing PyPI packages: ${packages.join(", ")}...`);
+      await pyodide.loadPackage("micropip");
+      const micropip = pyodide.pyimport("micropip");
+      try {
+        await micropip.install(packages);
+      } finally {
+        micropip.destroy();
+      }
+    };
+
+    // The optional first-line # PKGS: manifest specifies PyPI distribution
+    // names, covering cases such as `scikit-learn` -> `sklearn`.
+    await installPyPiPackages(declaredPackages);
+
+    // Check after both resolvers so conventional import names still install
+    // automatically when a script does not declare a distribution.
+    const pypiPackages = packageModules.filter((moduleName) => !pyodide.runPython(
+      `import importlib.util\nimportlib.util.find_spec(${JSON.stringify(moduleName)}) is not None`,
+    ));
+    await installPyPiPackages(pypiPackages);
+    
+    setStatus("Starting Python...");
+    await pyodide.runPythonAsync(pyCode);
+    setStatus("Execution finished.");
+  } catch (err) {
+    setStatus("Python execution failed.", true);
+    log(err instanceof Error ? err.stack || err.message : err);
+  }
+}
+function loadPyodideScript() {
+  if (typeof globalThis.loadPyodide === "function") { void runPython(); return; }
+  const scriptNode = document.createElement("script"); scriptNode.src = "__PYODIDE_SCRIPT_URL__"; scriptNode.async = true;
+  scriptNode.onload = () => void runPython();
+  scriptNode.onerror = () => setStatus("Could not load Pyodide (possibly blocked by CSP).", true);
+  document.body.appendChild(scriptNode);
+}
+loadPyodideScript();
+})();"""
+
+def clean_python_code(code: str) -> str:
+    """Preserve the user's program exactly; JSON encoding handles URL embedding."""
+    return code
+
+def declared_pypi_packages(python_code: str) -> list[str]:
+    """Read comma-separated PyPI requirements from a first-line # PKGS: header."""
+    first_line = python_code.split("\n", 1)[0].lstrip("\ufeff")
+    match = re.fullmatch(r"\s*#\s*PKGS\s*:\s*(.*)\s*", first_line, flags=re.IGNORECASE)
+    if not match or not match.group(1):
+        return []
+
+    packages = [package.strip() for package in match.group(1).split(",")]
+    return list(dict.fromkeys(package for package in packages if package))
+
+
+def imported_package_modules(python_code: str) -> list[str]:
+    """Return third-party top-level modules imported by *python_code*."""
+    try:
+        tree = ast.parse(python_code)
+    except SyntaxError:
+        # Let Pyodide report the original syntax error when the bookmarklet runs.
+        return []
+
+    imported_modules: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imported_modules.extend(alias.name.split(".", 1)[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            imported_modules.append(node.module.split(".", 1)[0])
+
+    return list(dict.fromkeys(imported_modules))
+
+
+def build_bookmarklet(python_code: str) -> str:
+    cleaned_py = clean_python_code(python_code)
+    package_modules = imported_package_modules(cleaned_py)
+    declared_packages = declared_pypi_packages(cleaned_py)
+
+    # Inject variables securely as valid JS.
+    js_variables = (
+        f"const pyCode = {json.dumps(cleaned_py)};\n"
+        f"const declaredPackages = {json.dumps(declared_packages)};\n"
+        f"const packageModules = {json.dumps(package_modules)};"
+    )
+
+    payload = JAVASCRIPT_TEMPLATE.replace('__DATA_SPLICING_PLACEHOLDER__', js_variables)
+    payload = payload.replace("__PYODIDE_BASE_URL__", PYODIDE_BASE_URL)
+    payload = payload.replace("__PYODIDE_SCRIPT_URL__", PYODIDE_SCRIPT_URL)
+
+    # Keep line breaks: collapsing them can make a `//` comment consume the
+    # remaining JavaScript. `quote` encodes them safely for a bookmarklet URL.
+    return f"javascript:{quote(payload, safe='')}"
+
+def generate_bookmarklet(python_file_path: Path, output_path: Path) -> bool:
+    """Generate a bookmarklet from *python_file_path* and write it to *output_path*."""
+    try:
+        python_code = python_file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        print(f"Error reading {python_file_path}: {error}")
+        return False
+
+    bookmarklet = build_bookmarklet(python_code)
+    try:
+        output_path.write_text(bookmarklet, encoding="utf-8")
+    except OSError as error:
+        print(f"Error writing {output_path}: {error}")
+        return False
+
+    print(f"Bookmarklet written to {output_path} ({len(bookmarklet)} characters).")
+    return True

pymarklet-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: pymarklet
+Version: 0.1.0
+Summary: Generate browser bookmarklets that run Python with Pyodide.
+Keywords: bookmarklet,browser,pyodide,python,webassembly
+Author: PyMarklet contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Block120/PyMarklet
+Project-URL: Repository, https://github.com/Block120/PyMarklet
+Project-URL: Issues, https://github.com/Block120/PyMarklet/issues
+Project-URL: Changelog, https://github.com/Block120/PyMarklet/releases
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# PyMarklet
+
+[![CI](https://github.com/Block120/PyMarklet/actions/workflows/ci.yml/badge.svg)](https://github.com/Block120/PyMarklet/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pymarklet.svg)](https://pypi.org/project/pymarklet/)
+[![Python](https://img.shields.io/pypi/pyversions/pymarklet.svg)](https://pypi.org/project/pymarklet/)
+
+Generate a browser bookmarklet that runs a Python script with [Pyodide](https://pyodide.org/). The generated bookmarklet adds a draggable output panel to the current page, loads Python in WebAssembly, and runs your embedded script in the browser.
+
+> **Experimental:** PyMarklet executes code in the context of the web page where the bookmarklet is activated. Read the [Security and privacy](#security-and-privacy) section before sharing or running a bookmarklet.
+
+## Installation
+
+```sh
+python -m pip install pymarklet
+```
+
+PyMarklet requires Python 3.11 or later to generate bookmarklets. The resulting bookmarklet runs Python in a supported modern browser; it does not use your local Python environment at runtime.
+
+## Quick start
+
+Create a Python script:
+
+```python
+# hello.py
+print("Hello from Python in your browser!")
+```
+
+Generate a bookmarklet URL:
+
+```sh
+pymarklet hello.py -o hello-bookmarklet.txt
+```
+
+1. Open `hello-bookmarklet.txt` and copy its complete contents.
+2. Create a browser bookmark named **PyMarklet: hello**.
+3. Paste the copied `javascript:` URL into the bookmark's URL/location field.
+4. Visit a webpage and activate the bookmark.
+
+A panel appears in the upper-right corner with status and Python output. Drag its header to move it, click **×** to remove it, and click the canvas before sending keyboard input to graphical applications.
+
+> Some browsers block pasting `javascript:` URLs into the address bar. Paste the URL into a bookmark's URL field instead.
+
+## Command line
+
+```text
+pymarklet [-h] [-o OUTPUT] python_file
+```
+
+| Argument | Description |
+| --- | --- |
+| `python_file` | UTF-8 Python source file to embed. |
+| `-o`, `--output` | Destination file for the bookmarklet URL. Defaults to `bookmarklet.js` in the current directory. |
+
+The command returns a nonzero status if it cannot read the source or write the output file.
+
+## Dependencies
+
+PyMarklet determines dependencies in two stages when the bookmarklet runs:
+
+1. It asks Pyodide to load packages it recognizes from normal `import` statements.
+2. For missing imports, it attempts to install a package with the same name using `micropip`.
+
+When a PyPI distribution name differs from its import name, declare it in a **first-line** manifest:
+
+```python
+# PKGS: python-dateutil, more-itertools
+from dateutil import parser
+from more_itertools import chunked
+
+print(parser.isoparse("2026-10-10T12:34:56Z"))
+print(list(chunked(range(6), 2)))
+```
+
+The manifest is comma-separated, case-insensitive (`# pkgs:` also works), trims duplicates, and accepts normal PyPI requirement specifiers such as `requests>=2.32`. Use it for every dependency whose import name is not its distribution name—for example, `scikit-learn` / `sklearn`.
+
+## How it works
+
+The generated URL embeds your source, creates a small page overlay, and loads **Pyodide 0.27.5** from jsDelivr. Standard output and errors appear in the overlay. The canvas is available to Pyodide-compatible graphical libraries such as Pygame.
+
+The source in [`examples/integration_stress_test.py`](examples/integration_stress_test.py) and the page in [`examples/sandbox.html`](examples/sandbox.html) are a manual integration example:
+
+```sh
+pymarklet examples/integration_stress_test.py
+```
+
+Open `examples/sandbox.html` in a browser, then use the generated bookmarklet on that page.
+
+## Limitations
+
+- **Network access is required.** The browser fetches Pyodide from jsDelivr and may fetch packages from PyPI-compatible hosts.
+- **Content Security Policy (CSP) can prevent execution.** Sites may block the injected Pyodide script, package downloads, or required browser APIs.
+- **Only Pyodide-compatible packages work.** Native packages without compatible WebAssembly wheels cannot be installed.
+- **Import detection is static and best-effort.** Dynamic imports and relative imports are not detected; use `# PKGS:` for dependencies that need explicit installation.
+- **Bookmark URLs have practical length limits.** The loader is already several thousand characters long, and the URL grows with your script. Keep scripts small.
+- Closing the overlay removes its UI but does not forcibly cancel Python work already scheduled in the page.
+
+## Security and privacy
+
+- A bookmarklet is executable code. Only run bookmarklets you trust.
+- Your Python source is embedded in the bookmarklet URL. **Never include secrets, credentials, private endpoints, or sensitive data.** Anyone with the URL can extract the source.
+- The bookmarklet executes with the permissions and network environment of the page where you activate it. Review site policies and do not use it on pages where injected code is inappropriate.
+- Dependencies are downloaded and executed in the browser. Pin or constrain declared requirements where reproducibility matters.
+- PyMarklet relies on jsDelivr to serve its pinned Pyodide runtime. Ad blockers, offline mode, proxies, or supply-chain policy may block it.
+
+See [`SECURITY.md`](SECURITY.md) for vulnerability reporting.
+
+## Development
+
+```sh
+uv sync
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Contributions are welcome; see [`CONTRIBUTING.md`](CONTRIBUTING.md). This project is licensed under the [MIT License](LICENSE).
+
+## Publishing checklist
+
+Before the first public release, confirm the `pymarklet` name is available on PyPI and configure PyPI Trusted Publishing for this repository and the `pypi` GitHub environment.

pymarklet-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pymarklet/__init__.py,sha256=L1JChUeGKvKgb3RcUq--UGvWzwq2Iyh_M8F-W0deTmU,265
+pymarklet/cli.py,sha256=FaCiDMbLvkdLVJIDHUnhuxTl0XznpPwiiYO9wEDz2wY,1047
+pymarklet/generator.py,sha256=0LFwOGnRM8dBvGR7uF0w0D5dHSQ_51CFR3Zzz0hEKvk,8374
+pymarklet-0.1.0.dist-info/licenses/LICENSE,sha256=CjOdOot5xuiS9QoMisbF2iNRVseoHihq8SAdwIdK6TE,1079
+pymarklet-0.1.0.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+pymarklet-0.1.0.dist-info/entry_points.txt,sha256=yu0HNdKBY0K5Xuzc3WVMlWqgSVZNdOlW9Pxx7qD3HXk,50
+pymarklet-0.1.0.dist-info/METADATA,sha256=kXwIdSMLmGO1-W1uKfCIG56SmHwkIFUfhSP5TASCxng,6949
+pymarklet-0.1.0.dist-info/RECORD,,

pymarklet-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pymarklet-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pymarklet = pymarklet.cli:main
+

pymarklet-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PyMarklet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.