PyPI - htmltree-view - Versions diffs - 0.2.1__py3-none-any.whl - Mend

htmltree-view 0.2.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

htmltree/__init__.py +29 -0
htmltree/cli.py +297 -0
htmltree/core.py +546 -0
htmltree_view-0.2.1.dist-info/METADATA +237 -0
htmltree_view-0.2.1.dist-info/RECORD +9 -0
htmltree_view-0.2.1.dist-info/WHEEL +5 -0
htmltree_view-0.2.1.dist-info/entry_points.txt +2 -0
htmltree_view-0.2.1.dist-info/licenses/LICENSE +21 -0
htmltree_view-0.2.1.dist-info/top_level.txt +1 -0

htmltree/__init__.py ADDED Viewed

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# File: htmltree/__init__.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-06-28
+# Description: htmltree-view — Visualize HTML DOM structure as a depth-limited, colorized ASCII tree.
+# License: MIT
+"""
+htmltree-view — Visualize HTML DOM structure as a depth-limited, colorized ASCII tree.
+Quick start
+-----------
+>>> from htmltree import HtmlTree
+>>> tree = HtmlTree(open("index.html").read(), max_depth=3)
+>>> tree.print()
+CLI
+---
+    htmltree index.html -d 3
+    htmltree https://example.com --no-text
+    echo '<div><p>hi</p></div>' | htmltree -
+"""
+from .core import HtmlTree, TreeStats
+from .cli import main
+__version__ = "0.2.0"
+__all__ = ["HtmlTree", "TreeStats", "main"]

htmltree/cli.py ADDED Viewed

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+# File: htmltree/cli.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-06-28
+# Description: htmltree CLI — visualize HTML structure as a depth-limited tree.
+# License: MIT
+"""htmltree CLI — visualize HTML structure as a depth-limited tree."""
+from __future__ import annotations
+import argparse
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Optional
+from .core import HtmlTree, VALID_PARSERS
+_VERSION = "0.2.0"
+_EPILOG = """
+Examples:
+  htmltree index.html
+  htmltree index.html -d 3
+  htmltree index.html -d 2 --no-text
+  htmltree index.html -s "body > main"
+  htmltree index.html -s "#app" --attrs id class href
+  htmltree https://example.com -d 4
+  echo '<div><p>hi</p></div>' | htmltree -
+  htmltree index.html --no-color | less
+  htmltree index.html --show-comments -d 5
+Selector examples:
+  -s body              top-level <body>
+  -s "main > article"  direct article children of main
+  -s "#root"           element with id="root"
+  -s ".container"      elements with class="container"
+  -s "table:first-of-type"
+"""
+def _read_html(source: Optional[str]) -> str:
+    """Load HTML from a file path, URL, or stdin. Returns raw HTML string."""
+    # stdin
+    if source is None or source == "-":
+        if sys.stdin.isatty() and source is None:
+            return ""   # caller will print help
+        try:
+            return sys.stdin.buffer.read().decode("utf-8", errors="replace")
+        except KeyboardInterrupt:
+            sys.exit(130)
+    # URL
+    if source.startswith(("http://", "https://")):
+        print(f"Fetching {source} …", file=sys.stderr)
+        req = urllib.request.Request(
+            source,
+            headers={"User-Agent": f"htmltree/{_VERSION} (python)"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=20) as resp:
+                charset = "utf-8"
+                ct = resp.headers.get_content_charset()
+                if ct:
+                    charset = ct
+                return resp.read().decode(charset, errors="replace")
+        except urllib.error.HTTPError as exc:
+            _die(f"HTTP {exc.code} fetching {source}: {exc.reason}")
+        except urllib.error.URLError as exc:
+            _die(f"Network error fetching {source}: {exc.reason}")
+        except Exception as exc:  # pragma: no cover
+            _die(f"Error fetching {source}: {exc}")
+    # File
+    path = Path(source)
+    if not path.exists():
+        _die(f"File not found: {source}")
+    if not path.is_file():
+        _die(f"Not a file: {source}")
+    try:
+        return path.read_bytes().decode("utf-8", errors="replace")
+    except OSError as exc:
+        _die(f"Cannot read {source}: {exc}")
+def _die(msg: str, code: int = 1) -> None:
+    print(f"htmltree: error: {msg}", file=sys.stderr)
+    sys.exit(code)
+def _positive_int(value: str) -> int:
+    try:
+        n = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{value!r} is not an integer")
+    if n < 0:
+        raise argparse.ArgumentTypeError(f"depth must be >= 0, got {n}")
+    return n
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="htmltree",
+        description=(
+            "Visualize HTML DOM structure as a depth-limited, colorized ASCII tree.\n"
+            "Supports files, URLs, and stdin."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EPILOG,
+    )
+    p.add_argument(
+        "source",
+        nargs="?",
+        metavar="SOURCE",
+        help=(
+            'HTML source: file path, http/https URL, or "-" for stdin. '
+            "Omit to read stdin (when piped)."
+        ),
+    )
+    # ── display ──────────────────────────────────────────────────────────────
+    display = p.add_argument_group("display")
+    display.add_argument(
+        "-d", "--depth",
+        type=_positive_int,
+        default=None,
+        metavar="N",
+        help="Max nesting depth to show (default: unlimited). Truncated levels show a child-count hint.",
+    )
+    display.add_argument(
+        "-s", "--selector",
+        default=None,
+        metavar="CSS",
+        help='CSS selector for the sub-tree root (e.g. "body", "#app", ".container").',
+    )
+    display.add_argument(
+        "--attrs",
+        nargs="*",
+        default=True,
+        metavar="NAME",
+        help=(
+            "Attributes to display. "
+            "Omit flag = show all. "
+            "Pass names = show only those (e.g. --attrs id class href). "
+            "--attrs with no names = hide all."
+        ),
+    )
+    display.add_argument(
+        "--no-text",
+        action="store_true",
+        help="Hide text nodes.",
+    )
+    display.add_argument(
+        "--show-comments",
+        action="store_true",
+        help="Show HTML comment nodes.",
+    )
+    display.add_argument(
+        "--text-limit",
+        type=_positive_int,
+        default=60,
+        metavar="N",
+        help="Max characters shown per text node before truncation (default: 60).",
+    )
+    display.add_argument(
+        "--attr-limit",
+        type=_positive_int,
+        default=80,
+        metavar="N",
+        help="Max characters shown per attribute value before truncation (default: 80).",
+    )
+    # ── output ───────────────────────────────────────────────────────────────
+    output = p.add_argument_group("output")
+    output.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI colors (auto-disabled when output is not a TTY).",
+    )
+    output.add_argument(
+        "--force-color",
+        action="store_true",
+        help="Force ANSI colors even when piped (e.g. for `less -R`).",
+    )
+    output.add_argument(
+        "--no-summary",
+        action="store_true",
+        help="Suppress the stats summary footer.",
+    )
+    output.add_argument(
+        "-o", "--output",
+        metavar="FILE",
+        default=None,
+        help="Write output to FILE instead of stdout.",
+    )
+    # ── parser ───────────────────────────────────────────────────────────────
+    misc = p.add_argument_group("misc")
+    misc.add_argument(
+        "--parser",
+        default="html.parser",
+        choices=sorted(VALID_PARSERS),
+        metavar="BACKEND",
+        help=(
+            f"BeautifulSoup parser backend. Choices: {sorted(VALID_PARSERS)}. "
+            "Default: html.parser (always available). "
+            "lxml is faster; html5lib is most spec-accurate."
+        ),
+    )
+    misc.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {_VERSION}",
+    )
+    return p
+def main(argv=None) -> int:
+    """
+    CLI entry point. Returns an exit code (0 = success).
+    Parameters
+    ----------
+    argv : list[str] | None
+        Argument list; defaults to sys.argv[1:].
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    # ── show_attrs resolution ─────────────────────────────────────────────────
+    if args.attrs is True:
+        show_attrs = True                    # flag not given → show all
+    elif args.attrs == []:
+        show_attrs = False                   # --attrs with no names → hide all
+    else:
+        show_attrs = list(args.attrs)        # --attrs id class → filter list
+    # ── read HTML ─────────────────────────────────────────────────────────────
+    html = _read_html(args.source)
+    if not html:
+        if args.source is None:
+            parser.print_help(sys.stderr)
+        else:
+            print("htmltree: warning: empty input", file=sys.stderr)
+        return 0
+    # ── build tree ────────────────────────────────────────────────────────────
+    try:
+        tree = HtmlTree(
+            html,
+            max_depth=args.depth,
+            show_text=not args.no_text,
+            show_comments=args.show_comments,
+            show_attrs=show_attrs,
+            parser=args.parser,
+            no_color=args.no_color,
+            force_color=args.force_color,
+            text_limit=args.text_limit,
+            attr_limit=args.attr_limit,
+        )
+    except ValueError as exc:
+        _die(str(exc))
+    # ── output ────────────────────────────────────────────────────────────────
+    out_file = None
+    try:
+        if args.output:
+            out_path = Path(args.output)
+            out_file = out_path.open("w", encoding="utf-8")
+        try:
+            tree.print(
+                root_selector=args.selector,
+                show_summary=not args.no_summary,
+                file=out_file,
+            )
+        except ValueError as exc:
+            # Bad CSS selector, invalid parser, etc.
+            _die(str(exc))
+        except BrokenPipeError:
+            # User piped to head/less and closed early — not an error
+            pass
+    finally:
+        if out_file is not None:
+            out_file.close()
+    return 0
+if __name__ == "__main__":
+    sys.exit(main())

htmltree/core.py ADDED Viewed

@@ -0,0 +1,546 @@
+#!/usr/bin/env python3
+# File: htmltree/core.py
+# Author: Hadi Cahyadi <cumulus13@gmail.com>
+# Date: 2026-06-28
+# Description: Core HTML tree visualization engine.
+# License: MIT
+"""Core HTML tree visualization engine."""
+from __future__ import annotations
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Iterator, List, Optional, Sequence, Union
+from bs4 import BeautifulSoup, Comment, NavigableString, Tag
+# ─── ANSI palette ────────────────────────────────────────────────────────────
+RESET = "\033[0m"
+BOLD  = "\033[1m"
+DIM   = "\033[2m"
+TAG_COLORS: dict[str, str] = {
+    # document root
+    "html": "\033[38;5;75m",
+    # head-section
+    "head": "\033[38;5;111m", "title": "\033[38;5;250m",
+    "meta": "\033[38;5;240m", "link":  "\033[38;5;240m",
+    "script": "\033[38;5;240m", "style": "\033[38;5;240m",
+    "noscript": "\033[38;5;240m", "base": "\033[38;5;240m",
+    # layout / landmark
+    "body": "\033[38;5;111m", "header": "\033[38;5;117m",
+    "footer": "\033[38;5;117m", "main":   "\033[38;5;117m",
+    "nav":  "\033[38;5;117m",  "section": "\033[38;5;81m",
+    "article": "\033[38;5;81m", "aside": "\033[38;5;81m",
+    "address": "\033[38;5;81m", "dialog": "\033[38;5;81m",
+    # headings
+    "h1": "\033[38;5;214m", "h2": "\033[38;5;220m",
+    "h3": "\033[38;5;226m", "h4": "\033[38;5;228m",
+    "h5": "\033[38;5;229m", "h6": "\033[38;5;230m",
+    # block text
+    "p": "\033[38;5;156m", "div": "\033[38;5;147m",
+    "blockquote": "\033[38;5;159m", "pre": "\033[38;5;159m",
+    "figure": "\033[38;5;159m", "figcaption": "\033[38;5;159m",
+    "details": "\033[38;5;159m", "summary": "\033[38;5;159m",
+    # inline text
+    "span": "\033[38;5;189m", "code": "\033[38;5;121m",
+    "em": "\033[38;5;189m", "strong": "\033[38;5;189m",
+    "small": "\033[38;5;189m", "mark": "\033[38;5;189m",
+    "abbr": "\033[38;5;189m", "cite": "\033[38;5;189m",
+    "time": "\033[38;5;189m", "kbd": "\033[38;5;121m",
+    "samp": "\033[38;5;121m", "var": "\033[38;5;121m",
+    "sub": "\033[38;5;189m", "sup": "\033[38;5;189m",
+    "del": "\033[38;5;189m", "ins": "\033[38;5;189m",
+    # links & media
+    "a": "\033[38;5;51m",
+    "img": "\033[38;5;208m", "video": "\033[38;5;208m",
+    "audio": "\033[38;5;208m", "picture": "\033[38;5;208m",
+    "source": "\033[38;5;208m", "track": "\033[38;5;208m",
+    "canvas": "\033[38;5;208m", "svg": "\033[38;5;208m",
+    "iframe": "\033[38;5;208m", "embed": "\033[38;5;208m",
+    "object": "\033[38;5;208m",
+    # forms
+    "form": "\033[38;5;204m", "input": "\033[38;5;210m",
+    "button": "\033[38;5;210m", "select": "\033[38;5;210m",
+    "textarea": "\033[38;5;210m", "label": "\033[38;5;216m",
+    "fieldset": "\033[38;5;216m", "legend": "\033[38;5;216m",
+    "datalist": "\033[38;5;210m", "output": "\033[38;5;210m",
+    "progress": "\033[38;5;210m", "meter": "\033[38;5;210m",
+    "option": "\033[38;5;210m", "optgroup": "\033[38;5;210m",
+    # lists
+    "ul": "\033[38;5;183m", "ol": "\033[38;5;183m",
+    "li": "\033[38;5;189m", "dl": "\033[38;5;183m",
+    "dt": "\033[38;5;189m", "dd": "\033[38;5;189m",
+    # tables
+    "table": "\033[38;5;178m", "caption": "\033[38;5;184m",
+    "colgroup": "\033[38;5;184m", "col": "\033[38;5;184m",
+    "thead": "\033[38;5;184m", "tbody": "\033[38;5;190m",
+    "tfoot": "\033[38;5;184m", "tr": "\033[38;5;192m",
+    "th": "\033[38;5;196m",   "td": "\033[38;5;202m",
+    # semantic / misc
+    "template": "\033[38;5;240m",
+    "slot": "\033[38;5;240m",
+}
+DEFAULT_TAG_COLOR = "\033[38;5;153m"
+COMMENT_COLOR     = "\033[38;5;238m"
+TEXT_COLOR        = "\033[38;5;242m"
+ATTR_KEY_COLOR    = "\033[38;5;180m"
+ATTR_VAL_COLOR    = "\033[38;5;222m"
+ERROR_COLOR       = "\033[38;5;196m"
+WARN_COLOR        = "\033[38;5;214m"
+LEVEL_COLORS = [
+    "\033[38;5;240m",
+    "\033[38;5;244m",
+    "\033[38;5;248m",
+    "\033[38;5;252m",
+]
+TREE_BRANCH = "├── "
+TREE_LAST   = "└── "
+TREE_PIPE   = "│   "
+TREE_SPACE  = "    "
+VALID_PARSERS = frozenset({"html.parser", "lxml", "html5lib", "lxml-xml"})
+# ─── Stats ───────────────────────────────────────────────────────────────────
+@dataclass
+class TreeStats:
+    """Accumulated metrics from the last render() call."""
+    total_tags: int = 0
+    total_text_nodes: int = 0
+    total_comments: int = 0
+    max_depth_seen: int = 0
+    tag_counts: dict = field(default_factory=dict)
+    def reset(self) -> None:
+        self.total_tags = 0
+        self.total_text_nodes = 0
+        self.total_comments = 0
+        self.max_depth_seen = 0
+        self.tag_counts.clear()
+    def record_tag(self, name: str, depth: int) -> None:
+        self.total_tags += 1
+        self.tag_counts[name] = self.tag_counts.get(name, 0) + 1
+        if depth > self.max_depth_seen:
+            self.max_depth_seen = depth
+    def record_text(self) -> None:
+        self.total_text_nodes += 1
+    def record_comment(self) -> None:
+        self.total_comments += 1
+# ─── Main class ──────────────────────────────────────────────────────────────
+class HtmlTree:
+    """
+    Render an HTML document (or fragment) as a colorized ASCII tree.
+    Parameters
+    ----------
+    html : str
+        Raw HTML string to parse and display.
+    max_depth : int | None
+        Maximum nesting depth to display (0 = root only; None = unlimited).
+        Negative values are treated as 0.
+    show_text : bool
+        Show text nodes in the tree (default True).
+    show_comments : bool
+        Show HTML comment nodes in the tree (default False).
+    show_attrs : list[str] | bool
+        * ``True``  – show all attributes (default)
+        * ``False`` – hide all attributes
+        * list/set/tuple of str – show only the named attributes
+    parser : str
+        BeautifulSoup parser backend. One of: ``"html.parser"`` (stdlib, always
+        available), ``"lxml"`` (fast, install separately), ``"html5lib"``
+        (most spec-accurate, install separately).
+    no_color : bool
+        Disable ANSI color codes.  Automatically set to ``True`` when stdout is
+        not a TTY (e.g. piped to a file) *unless* ``force_color=True``.
+    force_color : bool
+        Override the TTY check and always emit colors even when piped.
+    text_limit : int
+        Maximum characters shown per text node before truncation (min 1).
+    attr_limit : int
+        Maximum characters shown per attribute *value* before truncation (min 1).
+    Examples
+    --------
+    >>> from htmltree import HtmlTree
+    >>> tree = HtmlTree(open("index.html").read(), max_depth=3)
+    >>> tree.print()
+    >>> output = tree.render(root_selector="#main")
+    >>> for line in tree.iter_lines():
+    ...     print(line)
+    """
+    def __init__(
+        self,
+        html: str,
+        *,
+        max_depth: Optional[int] = None,
+        show_text: bool = True,
+        show_comments: bool = False,
+        show_attrs: Union[bool, Sequence[str]] = True,
+        parser: str = "html.parser",
+        no_color: bool = False,
+        force_color: bool = False,
+        text_limit: int = 60,
+        attr_limit: int = 80,
+    ) -> None:
+        # ── validate / normalize inputs ──────────────────────────────────────
+        if not isinstance(html, str):
+            raise TypeError(f"html must be str, got {type(html).__name__}")
+        if max_depth is not None:
+            max_depth = max(0, int(max_depth))  # clamp negatives to 0
+        if parser not in VALID_PARSERS:
+            raise ValueError(
+                f"Unknown parser {parser!r}. Valid choices: {sorted(VALID_PARSERS)}"
+            )
+        text_limit = max(1, int(text_limit))
+        attr_limit = max(1, int(attr_limit))
+        # Normalize show_attrs to bool | frozenset[str]
+        if isinstance(show_attrs, bool):
+            _show_attrs: Union[bool, frozenset] = show_attrs
+        elif isinstance(show_attrs, (list, tuple, set, frozenset)):
+            _show_attrs = frozenset(str(a) for a in show_attrs)
+        else:
+            raise TypeError(
+                f"show_attrs must be bool or a sequence of str, "
+                f"got {type(show_attrs).__name__}"
+            )
+        # Auto-detect TTY for color
+        _no_color = no_color
+        if not force_color and not no_color:
+            if not sys.stdout.isatty():
+                _no_color = True
+            # Also respect NO_COLOR env-var (https://no-color.org/)
+            if os.environ.get("NO_COLOR", ""):
+                _no_color = True
+            # Respect FORCE_COLOR env-var
+            if os.environ.get("FORCE_COLOR", ""):
+                _no_color = False
+        self.max_depth    = max_depth
+        self.show_text    = bool(show_text)
+        self.show_comments = bool(show_comments)
+        self._show_attrs  = _show_attrs
+        self.no_color     = _no_color
+        self.text_limit   = text_limit
+        self.attr_limit   = attr_limit
+        self.stats        = TreeStats()
+        try:
+            self.soup = BeautifulSoup(html, parser)
+        except Exception as exc:
+            raise ValueError(f"Failed to parse HTML with parser {parser!r}: {exc}") from exc
+    # ── Internal color helpers ────────────────────────────────────────────────
+    def _c(self, code: str, text: str) -> str:
+        if self.no_color:
+            return text
+        return f"{code}{text}{RESET}"
+    def _tag_color(self, name: str) -> str:
+        return TAG_COLORS.get(name.lower(), DEFAULT_TAG_COLOR)
+    def _pipe_color(self, depth: int) -> str:
+        return LEVEL_COLORS[depth % len(LEVEL_COLORS)]
+    # ── Attribute formatting ──────────────────────────────────────────────────
+    def _fmt_attrs(self, tag: Tag) -> str:
+        if not tag.attrs or self._show_attrs is False:
+            return ""
+        items = list(tag.attrs.items())
+        if isinstance(self._show_attrs, frozenset):
+            items = [(k, v) for k, v in items if k in self._show_attrs]
+        if not items:
+            return ""
+        parts: List[str] = []
+        for k, v in items:
+            if isinstance(v, (list, tuple)):
+                v = " ".join(str(x) for x in v)
+            else:
+                v = str(v)
+            # Truncate huge attribute values (e.g. inline base64 images)
+            if len(v) > self.attr_limit:
+                v = v[: self.attr_limit] + "…"
+            key = self._c(ATTR_KEY_COLOR, str(k))
+            val = self._c(ATTR_VAL_COLOR, f'"{v}"')
+            parts.append(f"{key}={val}")
+        return " " + " ".join(parts)
+    # ── Prefix / guide-line building ─────────────────────────────────────────
+    def _build_prefix(self, indent_guide: List[bool], is_last: bool) -> str:
+        """
+        Build the tree-art prefix string for a node.
+        indent_guide : list[bool]
+            One entry per ancestor level; True = draw a vertical pipe,
+            False = draw whitespace.
+        is_last : bool
+            Whether this node is the last sibling at its level.
+        """
+        parts: List[str] = []
+        for depth_idx, has_pipe in enumerate(indent_guide):
+            ch = TREE_PIPE if has_pipe else TREE_SPACE
+            parts.append(self._c(self._pipe_color(depth_idx), ch))
+        branch = TREE_LAST if is_last else TREE_BRANCH
+        parts.append(self._c(self._pipe_color(len(parts)), branch))
+        return "".join(parts)
+    # ── Node line renderers ───────────────────────────────────────────────────
+    def _render_tag_line(
+        self, tag: Tag, prefix: str, depth: int, child_count: int
+    ) -> str:
+        name  = self._c(BOLD + self._tag_color(tag.name), f"<{tag.name}>")
+        attrs = self._fmt_attrs(tag)
+        badge_parts = [self._c(DIM, "["), self._c("\033[38;5;245m", f"L{depth}")]
+        if child_count > 0:
+            badge_parts.append(self._c("\033[38;5;67m", f"{child_count}ch"))
+        else:
+            badge_parts.append(self._c("\033[38;5;238m", "empty"))
+        badge_parts.append(self._c(DIM, "]"))
+        badge = " ".join(badge_parts)
+        return f"{prefix}{name}{attrs}  {badge}"
+    def _render_text_line(self, raw: str, prefix: str) -> str:
+        text = raw.strip()
+        if not text:
+            return ""
+        # Collapse internal whitespace
+        text = " ".join(text.split())
+        if len(text) > self.text_limit:
+            text = text[: self.text_limit] + "…"
+        return prefix + self._c(TEXT_COLOR, f'"{text}"')
+    def _render_comment_line(self, raw: str, prefix: str) -> str:
+        text = raw.strip()
+        if not text:
+            return ""
+        text = " ".join(text.split())
+        if len(text) > self.text_limit:
+            text = text[: self.text_limit] + "…"
+        return prefix + self._c(COMMENT_COLOR, f"<!-- {text} -->")
+    # ── Visible-child collection ──────────────────────────────────────────────
+    def _visible_children(self, tag: Tag) -> List:
+        """
+        Return the list of child nodes that will actually be rendered,
+        respecting show_text and show_comments settings.
+        """
+        result = []
+        for child in tag.children:
+            if isinstance(child, Comment):
+                if self.show_comments:
+                    result.append(child)
+            elif isinstance(child, NavigableString):
+                if self.show_text and child.strip():
+                    result.append(child)
+            elif isinstance(child, Tag):
+                result.append(child)
+        return result
+    # ── Iterative tree walk (no recursion → no stack overflow) ───────────────
+    def _iter_lines(self, roots: List[Tag]) -> Iterator[str]:
+        """
+        Iterative DFS that yields rendered lines one by one.
+        Uses an explicit stack instead of recursion so that arbitrarily deep
+        HTML (e.g. 10,000-level nesting from a malformed document) never causes
+        a RecursionError.
+        Stack items: (node, depth, indent_guide, is_last)
+        """
+        # Push roots in reverse order so the first root is processed first
+        stack: List[tuple] = []
+        for i, root in enumerate(reversed(roots)):
+            is_last_root = (i == 0)  # reversed, so first-iterated = last root
+            stack.append((root, 0, [], is_last_root))
+        while stack:
+            node, depth, indent_guide, is_last = stack.pop()
+            # ── depth guard ──────────────────────────────────────────────────
+            if self.max_depth is not None and depth > self.max_depth:
+                continue
+            prefix = self._build_prefix(indent_guide, is_last) if depth > 0 else ""
+            # ── Comment node ─────────────────────────────────────────────────
+            if isinstance(node, Comment):
+                if self.show_comments:
+                    line = self._render_comment_line(str(node), prefix)
+                    if line:
+                        self.stats.record_comment()
+                        yield line
+                continue
+            # ── Text node ────────────────────────────────────────────────────
+            if isinstance(node, NavigableString):
+                if self.show_text:
+                    line = self._render_text_line(str(node), prefix)
+                    if line:
+                        self.stats.record_text()
+                        yield line
+                continue
+            # ── Skip unknown node types ──────────────────────────────────────
+            if not isinstance(node, Tag):
+                continue
+            # ── Tag node ─────────────────────────────────────────────────────
+            children = self._visible_children(node)
+            tag_children_count = sum(1 for c in children if isinstance(c, Tag))
+            self.stats.record_tag(node.name, depth)
+            yield self._render_tag_line(node, prefix, depth, tag_children_count)
+            # ── At depth limit: show ellipsis for hidden children ─────────────
+            if self.max_depth is not None and depth == self.max_depth:
+                if children:
+                    ellipsis_guide = indent_guide + ([not is_last] if depth > 0 else [])
+                    ellipsis_prefix = self._build_prefix(ellipsis_guide, True)
+                    n = len(children)
+                    label = f"… ({n} {'child' if n == 1 else 'children'} hidden)"
+                    yield ellipsis_prefix + self._c(COMMENT_COLOR, label)
+                continue
+            # ── Push children in reverse so first child is processed first ───
+            next_guide = indent_guide + ([not is_last] if depth > 0 else [])
+            for idx, child in enumerate(reversed(children)):
+                child_is_last = (idx == 0)  # reversed
+                stack.append((child, depth + 1, next_guide, child_is_last))
+    # ── Public API ────────────────────────────────────────────────────────────
+    def iter_lines(self, root_selector: Optional[str] = None) -> Iterator[str]:
+        """
+        Yield rendered tree lines one at a time (memory-efficient for large docs).
+        Parameters
+        ----------
+        root_selector : str | None
+            CSS selector used to pick the sub-tree root(s).  Supports any
+            selector that BeautifulSoup's ``select()`` understands.
+        Yields
+        ------
+        str
+            One rendered line per call (may include ANSI codes).
+        Raises
+        ------
+        ValueError
+            If ``root_selector`` is syntactically invalid.
+        """
+        self.stats.reset()
+        if root_selector:
+            try:
+                roots = self.soup.select(root_selector)
+            except Exception as exc:
+                raise ValueError(
+                    f"Invalid CSS selector {root_selector!r}: {exc}"
+                ) from exc
+            if not roots:
+                yield self._c(WARN_COLOR, f"⚠  No elements matched selector: {root_selector!r}")
+                return
+            yield from self._iter_lines(roots)
+        else:
+            root = self.soup.find("html") or self.soup
+            yield from self._iter_lines([root])
+    def render(self, root_selector: Optional[str] = None) -> str:
+        """
+        Return the complete tree as a single string.
+        Parameters
+        ----------
+        root_selector : str | None
+            CSS selector for a sub-tree root.
+        Returns
+        -------
+        str
+            Rendered tree (may contain ANSI codes unless ``no_color=True``).
+        """
+        return "\n".join(self.iter_lines(root_selector))
+    def summary(self) -> str:
+        """
+        Return a one-line stats summary (to be called *after* render/iter_lines).
+        Returns
+        -------
+        str
+            Formatted summary string.
+        """
+        s = self.stats
+        top5 = sorted(s.tag_counts.items(), key=lambda x: -x[1])[:5]
+        top5_str = ", ".join(f"{t}×{c}" for t, c in top5) or "(none)"
+        depth_info = (
+            f" (capped at {self.max_depth})" if self.max_depth is not None else ""
+        )
+        comment_info = f"  Comments: {s.total_comments}" if s.total_comments else ""
+        lines = [
+            "",
+            self._c(DIM, "─" * 52),
+            self._c(
+                "\033[38;5;245m",
+                f"  Tags: {s.total_tags}  "
+                f"Text nodes: {s.total_text_nodes}{comment_info}  "
+                f"Max depth: {s.max_depth_seen}{depth_info}",
+            ),
+            self._c("\033[38;5;240m", f"  Top tags: {top5_str}"),
+        ]
+        return "\n".join(lines)
+    def print(
+        self,
+        root_selector: Optional[str] = None,
+        *,
+        show_summary: bool = True,
+        file=None,
+    ) -> None:
+        """
+        Print the tree to *file* (default: ``sys.stdout``).
+        Parameters
+        ----------
+        root_selector : str | None
+            CSS selector for sub-tree root.
+        show_summary : bool
+            Whether to print the stats summary after the tree.
+        file : file-like | None
+            Output destination; defaults to ``sys.stdout``.
+        """
+        out = file or sys.stdout
+        # Stream line by line — avoids building the whole string in memory
+        for line in self.iter_lines(root_selector):
+            print(line, file=out)
+        if show_summary:
+            print(self.summary(), file=out)

htmltree_view-0.2.1.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: htmltree-view
+Version: 0.2.1
+Summary: Visualize HTML DOM structure as a depth-limited, colorized ASCII tree
+License: MIT
+Project-URL: Homepage, https://github.com/cumulus13/htmltree
+Project-URL: Repository, https://github.com/cumulus13/htmltree
+Project-URL: Issues, https://github.com/cumulus13/htmltree/issues
+Keywords: html,dom,tree,visualizer,beautifulsoup,cli,debug,structure,ascii
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.12
+Provides-Extra: lxml
+Requires-Dist: lxml; extra == "lxml"
+Provides-Extra: html5lib
+Requires-Dist: html5lib; extra == "html5lib"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: lxml; extra == "dev"
+Requires-Dist: html5lib; extra == "dev"
+Dynamic: license-file
+# htmltree-view
+> Visualize HTML DOM structure as a **depth-limited, colorized ASCII tree** — like the `tree` command, but for HTML files.
+```
+<html> lang="en"  [ L0 2ch ]
+├── <head>  [ L0 4ch ]
+│   ├── <meta> charset="utf-8"  [ L1 empty ]
+│   ├── <meta> name="viewport" content="width=device-width"  [ L1 empty ]
+│   ├── <title>  [ L1 empty ]
+│   │   └── "My Page"
+│   └── <link> rel="stylesheet" href="style.css"  [ L1 empty ]
+└── <body>  [ L1 3ch ]
+    ├── <header>  [ L2 2ch ]
+    │   └── … (2 children hidden)
+    ├── <main> id="main-content"  [ L2 2ch ]
+    │   └── … (2 children hidden)
+    └── <footer>  [ L2 2ch ]
+        └── … (2 children hidden)
+────────────────────────────────────────────────────
+  Tags: 8  Text nodes: 1  Max depth: 2 (capped at 2)
+  Top tags: meta×2, html×1, head×1, title×1, link×1
+```
+## Features
+- **Depth limiting** — `-d N` stops at level N; truncated sub-trees show a `… (X children hidden)` hint
+- **CSS selector zoom** — `-s "#app"` or `-s "body > main"` focuses any sub-tree
+- **Semantic tag colors** — headings in amber, structural in blue, forms in pink, links in cyan, etc.
+- **Depth-cycling pipe colors** — guide lines change shade per nesting level
+- **`[L3 5ch]` badges** — depth level + direct child-tag count on every node
+- **Text nodes** — quoted inline, with `--text-limit` truncation and whitespace collapsing
+- **Attribute filtering** — `--attrs id class href` shows only what you care about; `--attrs` hides all
+- **Attribute value truncation** — `--attr-limit 80` prevents base64/data-URI blowout
+- **HTML comments** — hidden by default, shown with `--show-comments`
+- **URL fetching** — `htmltree https://example.com -d 3`
+- **stdin pipe** — `curl ... | htmltree -` or `echo '<div/>' | htmltree -`
+- **Output to file** — `-o tree.txt` (auto-disables color)
+- **Auto color detection** — ANSI disabled when stdout is not a TTY; respects `NO_COLOR` / `FORCE_COLOR` env vars
+- **Streaming output** — `iter_lines()` yields one line at a time; never builds the full string unless you ask
+- **No recursion** — iterative DFS walk; handles arbitrarily deep HTML without `RecursionError`
+- **Stats summary** — total tags, text nodes, comments, max depth seen, top-5 tag frequencies
+## Install
+```bash
+pip install htmltree-view
+# With faster lxml parser:
+pip install "htmltree-view[lxml]"
+# With html5lib (most spec-accurate):
+pip install "htmltree-view[html5lib]"
+```
+## CLI
+```bash
+# Full tree
+htmltree index.html
+# Limit depth to 3 levels
+htmltree index.html -d 3
+# Focus on a CSS-selected sub-tree
+htmltree index.html -s "body > main"
+htmltree index.html -s "#app"
+htmltree index.html -s ".container"
+# Fetch from URL
+htmltree https://example.com -d 4
+# Read from stdin
+curl https://example.com | htmltree -
+echo '<div><p>hi</p></div>' | htmltree -
+# Show only id and class attributes
+htmltree index.html --attrs id class
+# Hide all attributes
+htmltree index.html --attrs
+# Hide text nodes (structure only)
+htmltree index.html --no-text
+# Show HTML comments
+htmltree index.html --show-comments
+# Truncate text/attr at 40 chars
+htmltree index.html --text-limit 40 --attr-limit 40
+# Save to file (color auto-disabled)
+htmltree index.html -o structure.txt
+# Pipe to less with color preserved
+htmltree index.html --force-color | less -R
+# Use lxml backend (faster)
+htmltree index.html --parser lxml
+# Plain output (no ANSI)
+htmltree index.html --no-color
+```
+## Python API
+```python
+from htmltree import HtmlTree
+html = open("index.html").read()
+# Basic usage
+tree = HtmlTree(html)
+tree.print()
+# Limit depth, filter attributes
+tree = HtmlTree(html, max_depth=3, show_attrs=["id", "class"])
+tree.print()
+# Zoom into a sub-tree
+tree = HtmlTree(html, max_depth=5, show_text=False)
+tree.print(root_selector="body > main")
+# Render to string
+tree = HtmlTree(html, max_depth=2, force_color=False)
+output = tree.render(root_selector="body")
+print(output)
+# Stream line by line (memory-efficient for large pages)
+tree = HtmlTree(html, max_depth=4)
+for line in tree.iter_lines(root_selector="#content"):
+    print(line)
+# Access stats after render
+tree.render()
+print(tree.stats.total_tags)
+print(tree.stats.tag_counts)      # dict: tag name → count
+print(tree.stats.max_depth_seen)
+print(tree.stats.total_text_nodes)
+print(tree.stats.total_comments)
+```
+## CLI reference
+| Flag | Default | Description |
+|------|---------|-------------|
+| `SOURCE` | — | HTML file path, http/https URL, or `-` for stdin |
+| `-d N` / `--depth N` | unlimited | Max depth; negatives clamped to 0 |
+| `-s CSS` / `--selector CSS` | `<html>` | CSS selector for tree root |
+| `--attrs [NAME …]` | all | Attributes to show; no names = hide all |
+| `--no-text` | off | Hide text nodes |
+| `--show-comments` | off | Show HTML comment nodes |
+| `--text-limit N` | 60 | Max chars per text node |
+| `--attr-limit N` | 80 | Max chars per attribute value |
+| `--no-color` | off | Disable ANSI colors |
+| `--force-color` | off | Force colors even when piped |
+| `--no-summary` | off | Suppress stats footer |
+| `-o FILE` / `--output FILE` | stdout | Write to file |
+| `--parser BACKEND` | `html.parser` | `html.parser`, `lxml`, `html5lib` |
+| `--version` | — | Print version and exit |
+## Tree legend
+| Symbol | Meaning |
+|--------|---------|
+| `[L3]` | Node is at depth 3 |
+| `[5ch]` | 5 direct tag children |
+| `[empty]` | No children |
+| `"text"` | Text node content (may be truncated) |
+| `<!-- … -->` | HTML comment (with `--show-comments`) |
+| `… (N children hidden)` | Sub-tree cut at depth limit |
+## Environment variables
+| Variable | Effect |
+|----------|--------|
+| `NO_COLOR` | Any non-empty value disables ANSI colors (https://no-color.org/) |
+| `FORCE_COLOR` | Any non-empty value forces ANSI colors even when piped |
+## Requirements
+- Python ≥ 3.8
+- `beautifulsoup4 ≥ 4.12`
+- Optional: `lxml`, `html5lib`
+## License
+[MIT](LICENSE)
+## 👤 Author
+[Hadi Cahyadi](mailto:cumulus13@gmail.com)
+[![Buy Me a Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/cumulus13)
+[![Donate via Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/cumulus13)
+[Support me on Patreon](https://www.patreon.com/cumulus13)

htmltree_view-0.2.1.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,9 @@
+htmltree/__init__.py,sha256=UEi0In0BwaPX41D97-F70VoArRwqp8EdUDC7lD9mwPk,724
+htmltree/cli.py,sha256=sJxlN604QPyUF0Fdw43l4vQ3p-1VORvgoD3lPLQqE88,9820
+htmltree/core.py,sha256=qu0pukgXY44dIt7tXEdSGsV9zDfyWuDf4sVNyjknuq4,21881
+htmltree_view-0.2.1.dist-info/licenses/LICENSE,sha256=YUZAmTZXLbSJqc2UabCY7nJH-s_jCegXkhfTpHrOSRU,1068
+htmltree_view-0.2.1.dist-info/METADATA,sha256=_OpIV_-E4NPmk8WpabVESOf_god_9n1laEA6q7HQW8k,8252
+htmltree_view-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+htmltree_view-0.2.1.dist-info/entry_points.txt,sha256=xaR5gaSXseq1n7CN8hJC-hnCa5COQKh7fPMsILecnE8,47
+htmltree_view-0.2.1.dist-info/top_level.txt,sha256=Fr8AeWjZj8vA2mCqzwVhp02VqBZIywXyKv2wZSnG-ro,9
+htmltree_view-0.2.1.dist-info/RECORD,,

htmltree_view-0.2.1.dist-info/WHEEL ADDED Viewed

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any

htmltree_view-0.2.1.dist-info/entry_points.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ [console_scripts]
2	+ htmltree = htmltree.cli:main

htmltree_view-0.2.1.dist-info/licenses/LICENSE ADDED Viewed

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

htmltree_view-0.2.1.dist-info/top_level.txt ADDED Viewed

	@@ -0,0 +1 @@
1	+ htmltree