perusal 0.0.5__tar.gz

perusal-0.0.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byteface
+
+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.

perusal-0.0.5/MANIFEST.in

@@ -0,0 +1 @@
+include README.md LICENSE VERSION

perusal-0.0.5/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: perusal
+Version: 0.0.5
+Summary: Read the web as Markdown: a CLI, a reader-browser GUI, and an optional MCP server, on the domonic Readability + Turndown ports
+Author-email: byteface <byteface@googlemail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/byteface/domonic-libs/tree/master/src/perusal
+Project-URL: Source, https://github.com/byteface/domonic-libs
+Project-URL: Documentation, https://github.com/byteface/domonic-libs/blob/master/docs/perusal.md
+Project-URL: Tracker, https://github.com/byteface/domonic-libs/issues
+Keywords: readability,turndown,markdown,reader,browser,web,domonic,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: domonic-libs>=0.0.5
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.12; extra == "mcp"
+Provides-Extra: browser
+Requires-Dist: pywebview>=5.0; extra == "browser"
+Provides-Extra: js
+Requires-Dist: myjs>=0.0.5; extra == "js"
+Dynamic: license-file
+
+# perusal
+
+The internet without all the 💩
+
+```bash
+pip install perusal
+
+perusal https://en.wikipedia.org/wiki/Domino    # -> clean Markdown on stdout
+perusal ./saved-page.html                        # a local HTML file works too
+perusal report https://example.com               # HTML-vs-Markdown size / token savings
+perusal url1 url2 url3                           # -> one combined Markdown digest
+echo '<h1>hi</h1>' | perusal -                   # read HTML from stdin
+```
+
+Pages pass through the domonic Readability and Turndown ports: fetch →
+readable-article extraction → Markdown → cleanup, with optional relevance
+ranking (`--query`) and a hard character budget (`--max-chars`).
+
+Pages that render client-side (an empty server response, "Enable JavaScript
+to view this content") need their own JavaScript actually run first:
+
+```bash
+pip install 'perusal[js]'
+perusal https://example.com/app --js             # runs the page's <script>s via myjs first
+```
+
+## The reader-browser
+
+```bash
+pip install 'perusal[browser]'
+perusal browse                                   # tabbed webview reader
+perusal browse https://en.wikipedia.org/wiki/Domino
+```
+
+A small tabbed reader-browser (history, incognito tabs, bookmarks, DevTools,
+adjustable type, Wikipedia math rendering, "save page as Markdown") with
+keyboard shortcuts: `⌘/Ctrl+T` new tab, `W` close tab, `R` reload, `D`
+bookmark, `B` toggle bookmarks, `U` view page source, `L` focus the URL bar.
+
+**DevTools** (the `</>` button): raw page **Source**, a static **Resources**
+inventory (every referenced script/stylesheet/image/iframe, each viewable in
+turn), and an **Info** tab with IP / reverse DNS / WHOIS / DNS records
+(hand-rolled clients, no new dependency) plus certificate-transparency-log
+subdomain discovery via crt.sh. Purely passive and manually triggered — no
+port scanning, no active brute-forcing, nothing sent to the site itself
+beyond the page fetch perusal already made.
+
+## MCP server (optional)
+
+```bash
+pip install 'perusal[mcp]'
+perusal mcp                                       # stdio MCP server
+```
+
+One read-only, idempotent tool — `web_read(url, query?, max_chars?, timeout?)` —
+built on the official Python MCP SDK. Point an MCP client at `perusal mcp`.
+
+See the [full documentation](https://github.com/byteface/domonic-libs/blob/master/docs/perusal.md).

perusal-0.0.5/README.md

@@ -0,0 +1,58 @@
+# perusal
+
+The internet without all the 💩
+
+```bash
+pip install perusal
+
+perusal https://en.wikipedia.org/wiki/Domino    # -> clean Markdown on stdout
+perusal ./saved-page.html                        # a local HTML file works too
+perusal report https://example.com               # HTML-vs-Markdown size / token savings
+perusal url1 url2 url3                           # -> one combined Markdown digest
+echo '<h1>hi</h1>' | perusal -                   # read HTML from stdin
+```
+
+Pages pass through the domonic Readability and Turndown ports: fetch →
+readable-article extraction → Markdown → cleanup, with optional relevance
+ranking (`--query`) and a hard character budget (`--max-chars`).
+
+Pages that render client-side (an empty server response, "Enable JavaScript
+to view this content") need their own JavaScript actually run first:
+
+```bash
+pip install 'perusal[js]'
+perusal https://example.com/app --js             # runs the page's <script>s via myjs first
+```
+
+## The reader-browser
+
+```bash
+pip install 'perusal[browser]'
+perusal browse                                   # tabbed webview reader
+perusal browse https://en.wikipedia.org/wiki/Domino
+```
+
+A small tabbed reader-browser (history, incognito tabs, bookmarks, DevTools,
+adjustable type, Wikipedia math rendering, "save page as Markdown") with
+keyboard shortcuts: `⌘/Ctrl+T` new tab, `W` close tab, `R` reload, `D`
+bookmark, `B` toggle bookmarks, `U` view page source, `L` focus the URL bar.
+
+**DevTools** (the `</>` button): raw page **Source**, a static **Resources**
+inventory (every referenced script/stylesheet/image/iframe, each viewable in
+turn), and an **Info** tab with IP / reverse DNS / WHOIS / DNS records
+(hand-rolled clients, no new dependency) plus certificate-transparency-log
+subdomain discovery via crt.sh. Purely passive and manually triggered — no
+port scanning, no active brute-forcing, nothing sent to the site itself
+beyond the page fetch perusal already made.
+
+## MCP server (optional)
+
+```bash
+pip install 'perusal[mcp]'
+perusal mcp                                       # stdio MCP server
+```
+
+One read-only, idempotent tool — `web_read(url, query?, max_chars?, timeout?)` —
+built on the official Python MCP SDK. Point an MCP client at `perusal mcp`.
+
+See the [full documentation](https://github.com/byteface/domonic-libs/blob/master/docs/perusal.md).

perusal-0.0.5/VERSION

@@ -0,0 +1 @@
+0.0.5

perusal-0.0.5/pyproject.toml

@@ -0,0 +1,64 @@
+# Build config for the standalone `perusal` distribution.
+#
+# `src` here is a symlink to ../../src, so src/perusal is the single source of
+# truth and this project packages only `perusal*`.
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "perusal"
+dynamic = ["version"]
+description = "Read the web as Markdown: a CLI, a reader-browser GUI, and an optional MCP server, on the domonic Readability + Turndown ports"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "byteface", email = "byteface@googlemail.com" },
+]
+requires-python = ">=3.10"
+keywords = ["readability", "turndown", "markdown", "reader", "browser", "web", "domonic", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+dependencies = [
+    "domonic-libs>=0.0.5",
+]
+
+[project.optional-dependencies]
+# `perusal mcp` -- the stdio MCP server
+mcp = ["mcp>=1.12,<2"]
+# `perusal browse` -- the reader-browser GUI
+browser = ["pywebview>=5.0"]
+# `perusal md --js` -- render a page's own JavaScript (via myjs) before reading it
+js = ["myjs>=0.0.5"]
+
+[project.scripts]
+perusal = "perusal.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/byteface/domonic-libs/tree/master/src/perusal"
+Source = "https://github.com/byteface/domonic-libs"
+Documentation = "https://github.com/byteface/domonic-libs/blob/master/docs/perusal.md"
+Tracker = "https://github.com/byteface/domonic-libs/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["perusal*"]
+
+[tool.setuptools.dynamic]
+version = { file = "VERSION" }

perusal-0.0.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

perusal-0.0.5/src/perusal/__init__.py

@@ -0,0 +1,15 @@
+"""perusal -- read the web as Markdown.
+
+A CLI (``perusal <url>``), a reader-browser GUI (``perusal browse``), and an
+optional MCP server (``perusal mcp``), all standing on the domonic Readability
+and Turndown ports.
+
+``core`` holds the fetch -> Readability -> Turndown -> Markdown pipeline shared
+by the CLI and the MCP tool. ``browser`` is the standalone GUI (it keeps its
+own richer, interactive extraction) and is imported lazily so the base package
+has no pywebview dependency.
+"""
+
+from .core import ReaderResult, web_read
+
+__all__ = ["ReaderResult", "web_read"]

perusal-0.0.5/src/perusal/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())