selectolax 0.3.30__cp311-cp311-macosx_11_0_arm64.whl

selectolax/lexbor.pyi

@@ -0,0 +1,177 @@
+from typing import Any, Iterator, Literal, TypeVar, NoReturn, overload
+
+DefaultT = TypeVar("DefaultT")
+
+class LexborAttributes:
+    @staticmethod
+    def create(node: LexborAttributes) -> LexborAttributes: ...
+    def keys(self) -> Iterator[str]: ...
+    def items(self) -> Iterator[tuple[str, str | None]]: ...
+    def values(self) -> Iterator[str | None]: ...
+    def __iter__(self) -> Iterator[str]: ...
+    def __len__(self) -> int: ...
+    def __getitem__(self, key: str) -> str | None: ...
+    def __setitem__(self, key: str, value: str) -> None: ...
+    def __delitem__(self, key: str) -> None: ...
+    def __contains__(self, key: str) -> bool: ...
+    def __repr__(self) -> str: ...
+    @overload
+    def get(self, key: str, default: DefaultT) -> DefaultT | str | None: ...
+    @overload
+    def get(self, key: str, default: None = ...) -> str | None: ...
+    @overload
+    def sget(self, key: str, default: str | DefaultT) -> str | DefaultT: ...
+    @overload
+    def sget(self, key: str, default: str = "") -> str: ...
+
+class LexborSelector:
+    def __init__(self, node: LexborNode, query: str): ...
+    def css(self, query: str) -> NoReturn: ...
+    @property
+    def matches(self) -> list[LexborNode]: ...
+    @property
+    def any_matches(self) -> bool: ...
+    def text_contains(
+        self, text: str, deep: bool = True, separator: str = "", strip: bool = False
+    ) -> LexborSelector: ...
+    def any_text_contains(
+        self, text: str, deep: bool = True, separator: str = "", strip: bool = False
+    ) -> bool: ...
+    def attribute_longer_than(
+        self, attribute: str, length: int, start: str | None = None
+    ) -> LexborSelector: ...
+    def any_attribute_longer_than(
+        self, attribute: str, length: int, start: str | None = None
+    ) -> bool: ...
+
+class LexborCSSSelector:
+    def __init__(self): ...
+    def find(self, query: str, node: LexborNode) -> list[LexborNode]: ...
+    def any_matches(self, query: str, node: LexborNode) -> bool: ...
+
+class LexborNode:
+    parser: LexborHTMLParser
+    @property
+    def mem_id(self) -> int: ...
+    @property
+    def child(self) -> LexborNode | None: ...
+    @property
+    def first_child(self) -> LexborNode | None: ...
+    @property
+    def parent(self) -> LexborNode | None: ...
+    @property
+    def next(self) -> LexborNode | None: ...
+    @property
+    def prev(self) -> LexborNode | None: ...
+    @property
+    def last_child(self) -> LexborNode | None: ...
+    @property
+    def html(self) -> str | None: ...
+    def __hash__(self) -> int: ...
+    def text_lexbor(self) -> str: ...
+    def text(
+        self, deep: bool = True, separator: str = "", strip: bool = False
+    ) -> str: ...
+    def css(self, query: str) -> list[LexborNode]: ...
+    @overload
+    def css_first(
+        self, query: str, default: Any = ..., strict: Literal[True] = ...
+    ) -> LexborNode: ...
+    @overload
+    def css_first(
+        self, query: str, default: DefaultT, strict: bool = False
+    ) -> LexborNode | DefaultT: ...
+    @overload
+    def css_first(
+        self, query: str, default: None = ..., strict: bool = False
+    ) -> LexborNode | None: ...
+    def any_css_matches(self, selectors: tuple[str]) -> bool: ...
+    def css_matches(self, selector: str) -> bool: ...
+    @property
+    def tag_id(self) -> int: ...
+    @property
+    def tag(self) -> str | None: ...
+    def decompose(self, recursive: bool = True) -> None: ...
+    def strip_tags(self, tags: list[str], recursive: bool = False) -> None: ...
+    @property
+    def attributes(self) -> dict[str, str | None]: ...
+    @property
+    def attrs(self) -> LexborAttributes: ...
+    @property
+    def id(self) -> str | None: ...
+    def iter(self, include_text: bool = False) -> Iterator[LexborNode]: ...
+    def unwrap(self) -> None: ...
+    def unwrap_tags(self, tags: list[str], delete_empty : bool = False) -> None: ...
+    def traverse(self, include_text: bool = False) -> Iterator[LexborNode]: ...
+    def replace_with(self, value: bytes | str | LexborNode) -> None: ...
+    def insert_before(self, value: bytes | str | LexborNode) -> None: ...
+    def insert_after(self, value: bytes | str | LexborNode) -> None: ...
+    def insert_child(self, value: bytes | str | LexborNode) -> None: ...
+    @property
+    def raw_value(self) -> NoReturn: ...
+    def scripts_contain(self, query: str) -> bool: ...
+    def scripts_srcs_contain(self, queries: tuple[str]) -> bool: ...
+    def remove(self, recursive: bool = True) -> None: ...
+    def select(self, query: str | None = None) -> LexborSelector: ...
+    @property
+    def text_content(self) -> str | None: ...
+
+class LexborHTMLParser:
+    def __init__(self, html: str| bytes ): ...
+    @property
+    def selector(self) -> "LexborCSSSelector": ...
+    @property
+    def root(self) -> LexborNode | None: ...
+    @property
+    def body(self) -> LexborNode | None: ...
+    @property
+    def head(self) -> LexborNode | None: ...
+    def tags(self, name: str) -> list[LexborNode]: ...
+    def text(
+        self, deep: bool = True, separator: str = "", strip: bool = False
+    ) -> str: ...
+    @property
+    def html(self) -> str | None: ...
+    def css(self, query: str) -> list[LexborNode]: ...
+    @overload
+    def css_first(
+        self, query: str, default: Any = ..., strict: Literal[True] = ...
+    ) -> LexborNode: ...
+    @overload
+    def css_first(
+        self, query: str, default: DefaultT, strict: bool = False
+    ) -> LexborNode | DefaultT: ...
+    @overload
+    def css_first(
+        self, query: str, default: None = ..., strict: bool = False
+    ) -> LexborNode | None: ...
+    def strip_tags(self, tags: list[str], recursive: bool = False) -> None: ...
+    def select(self, query: str | None = None) -> LexborSelector | None: ...
+    def any_css_matches(self, selectors: tuple[str]) -> bool: ...
+    def scripts_contain(self, query: str) -> bool: ...
+    def scripts_srcs_contain(self, queries: tuple[str]) -> bool: ...
+    def css_matches(self, selector: str) -> bool: ...
+    def clone(self) -> LexborHTMLParser: ...
+    def unwrap_tags(self, tags: list[str], delete_empty : bool = False) -> None: ...
+
+def create_tag(tag: str) -> LexborNode:
+    """
+    Given an HTML tag name, e.g. `"div"`, create a single empty node for that tag,
+    e.g. `"<div></div>"`.
+    """
+    ...
+
+def parse_fragment(html: str) -> list[LexborNode]:
+    """
+    Given HTML, parse it into a list of Nodes, such that the nodes
+    correspond to the given HTML.
+
+    For contrast, HTMLParser adds `<html>`, `<head>`, and `<body>` tags
+    if they are missing. This function does not add these tags.
+    """
+    ...
+
+
+class SelectolaxError(Exception):
+    """An exception that indicates error."""
+    pass

selectolax/lexbor.pyx

@@ -0,0 +1,357 @@
+from cpython cimport bool
+
+_ENCODING = 'UTF-8'
+
+include "base.pxi"
+include "utils.pxi"
+include "lexbor/attrs.pxi"
+include "lexbor/node.pxi"
+include "lexbor/selection.pxi"
+include "lexbor/util.pxi"
+
+# We don't inherit from HTMLParser here, because it also includes all the C code from Modest.
+
+cdef class LexborHTMLParser:
+    """The lexbor HTML parser.
+
+    Use this class to parse raw HTML.
+
+    This parser mimics most of the stuff from ``HTMLParser`` but not inherits it directly.
+
+    Parameters
+    ----------
+
+    html : str (unicode) or bytes
+    """
+    def __init__(self, html):
+
+        cdef size_t html_len
+        cdef char* html_chars
+
+        bytes_html, html_len = preprocess_input(html)
+        self._parse_html(bytes_html, html_len)
+        self.raw_html = bytes_html
+        self._selector = None
+
+    @property
+    def selector(self):
+        if self._selector is None:
+            self._selector = LexborCSSSelector()
+        return self._selector
+
+
+    cdef _parse_html(self, char *html, size_t html_len):
+        cdef lxb_status_t status
+
+        with nogil:
+            self.document = lxb_html_document_create()
+
+        if self.document == NULL:
+            raise SelectolaxError("Failed to initialize object for HTML Document.")
+
+        with nogil:
+            status = lxb_html_document_parse(self.document, <lxb_char_t *> html, html_len)
+        if status != 0x0000:
+            raise SelectolaxError("Can't parse HTML.")
+
+        assert self.document != NULL
+
+    def __dealloc__(self):
+        if self.document != NULL:
+            lxb_html_document_destroy(self.document)
+
+    def __repr__(self):
+        return '<LexborHTMLParser chars=%s>' % len(self.root.html)
+
+    @property
+    def root(self):
+        """Returns root node."""
+        if self.document == NULL:
+            return None
+        return LexborNode()._cinit(<lxb_dom_node_t *> lxb_dom_document_root(&self.document.dom_document), self)
+
+    @property
+    def body(self):
+        """Returns document body."""
+        cdef lxb_html_body_element_t* body
+        body = lxb_html_document_body_element_noi(self.document)
+        if body == NULL:
+            return None
+        return LexborNode()._cinit(<lxb_dom_node_t *> body, self)
+
+    @property
+    def head(self):
+        """Returns document head."""
+        cdef lxb_html_head_element_t* head
+        head = lxb_html_document_head_element_noi(self.document)
+        if head == NULL:
+            return None
+        return LexborNode()._cinit(<lxb_dom_node_t *> head, self)
+
+    def tags(self, str name):
+        """Returns a list of tags that match specified name.
+
+        Parameters
+        ----------
+        name : str (e.g. div)
+
+        """
+
+        if not name:
+            raise ValueError("Tag name cannot be empty")
+        if len(name) > 100:
+            raise ValueError("Tag name is too long")
+
+        cdef lxb_dom_collection_t* collection = NULL
+        cdef lxb_status_t status
+        pybyte_name = name.encode('UTF-8')
+
+        result = list()
+        collection = lxb_dom_collection_make(&self.document.dom_document, 128)
+
+        if collection == NULL:
+            return result
+        status = lxb_dom_elements_by_tag_name(
+            <lxb_dom_element_t *> self.document,
+            collection,
+            <lxb_char_t *> pybyte_name,
+            len(pybyte_name)
+        )
+        if status != 0x0000:
+            lxb_dom_collection_destroy(collection, <bint> True)
+            raise SelectolaxError("Can't locate elements.")
+
+        for i in range(lxb_dom_collection_length_noi(collection)):
+            node = LexborNode()._cinit(
+                <lxb_dom_node_t*> lxb_dom_collection_element_noi(collection, i),
+                self
+            )
+            result.append(node)
+        lxb_dom_collection_destroy(collection, <bint> True)
+        return result
+
+    def text(self, bool deep=True, str separator='', bool strip=False):
+        """Returns the text of the node including text of all its child nodes.
+
+        Parameters
+        ----------
+        strip : bool, default False
+            If true, calls ``str.strip()`` on each text part to remove extra white spaces.
+        separator : str, default ''
+            The separator to use when joining text from different nodes.
+        deep : bool, default True
+            If True, includes text from all child nodes.
+
+        Returns
+        -------
+        text : str
+
+        """
+        if self.body is None:
+            return ""
+        return self.body.text(deep=deep, separator=separator, strip=strip)
+
+    @property
+    def html(self):
+        """Return HTML representation of the page."""
+        if self.document == NULL:
+            return None
+        node = LexborNode()._cinit(<lxb_dom_node_t *> &self.document.dom_document, self)
+        return node.html
+
+    def css(self, str query):
+        """A CSS selector.
+
+        Matches pattern `query` against HTML tree.
+        `CSS selectors reference <https://www.w3schools.com/cssref/css_selectors.asp>`_.
+
+        Parameters
+        ----------
+        query : str
+            CSS selector (e.g. "div > :nth-child(2n+1):not(:has(a))").
+
+        Returns
+        -------
+        selector : list of `Node` objects
+        """
+        return self.root.css(query)
+
+    def css_first(self, str query, default=None, strict=False):
+        """Same as `css` but returns only the first match.
+
+        Parameters
+        ----------
+
+        query : str
+        default : bool, default None
+            Default value to return if there is no match.
+        strict: bool, default True
+            Set to True if you want to check if there is strictly only one match in the document.
+
+
+        Returns
+        -------
+        selector : `LexborNode` object
+        """
+        return self.root.css_first(query, default, strict)
+
+    def strip_tags(self, list tags, bool recursive = False):
+        """Remove specified tags from the node.
+
+        Parameters
+        ----------
+        tags : list of str
+            List of tags to remove.
+        recursive : bool, default True
+            Whenever to delete all its child nodes
+
+        Examples
+        --------
+
+        >>> tree = LexborHTMLParser('<html><head></head><body><script></script><div>Hello world!</div></body></html>')
+        >>> tags = ['head', 'style', 'script', 'xmp', 'iframe', 'noembed', 'noframes']
+        >>> tree.strip_tags(tags)
+        >>> tree.html
+        '<html><body><div>Hello world!</div></body></html>'
+
+        """
+        cdef lxb_dom_collection_t* collection = NULL
+        cdef lxb_status_t status
+
+        for tag in tags:
+            pybyte_name = tag.encode('UTF-8')
+
+            collection = lxb_dom_collection_make(&self.document.dom_document, 128)
+
+            if collection == NULL:
+                raise SelectolaxError("Can't initialize DOM collection.")
+
+            status = lxb_dom_elements_by_tag_name(
+                <lxb_dom_element_t *> self.document,
+                collection,
+                <lxb_char_t *> pybyte_name,
+                len(pybyte_name)
+            )
+            if status != 0x0000:
+                lxb_dom_collection_destroy(collection, <bint> True)
+                raise SelectolaxError("Can't locate elements.")
+
+            for i in range(lxb_dom_collection_length_noi(collection)):
+                if recursive:
+                    lxb_dom_node_destroy_deep( <lxb_dom_node_t*> lxb_dom_collection_element_noi(collection, i))
+                else:
+                    lxb_dom_node_destroy(<lxb_dom_node_t *> lxb_dom_collection_element_noi(collection, i))
+            lxb_dom_collection_destroy(collection, <bint> True)
+
+    def select(self, query=None):
+        """Select nodes give a CSS selector.
+
+        Works similarly to the ``css`` method, but supports chained filtering and extra features.
+
+        Parameters
+        ----------
+        query : str or None
+            The CSS selector to use when searching for nodes.
+
+        Returns
+        -------
+        selector : The `Selector` class.
+        """
+        cdef LexborNode node
+        node = self.root
+        if node:
+            return LexborSelector(node, query)
+
+    def any_css_matches(self, tuple selectors):
+        """Returns True if any of the specified CSS selectors matches a node."""
+        return self.root.any_css_matches(selectors)
+
+    def scripts_contain(self, str query):
+        """Returns True if any of the script tags contain specified text.
+
+        Caches script tags on the first call to improve performance.
+
+        Parameters
+        ----------
+        query : str
+            The query to check.
+
+        """
+        return self.root.scripts_contain(query)
+
+
+    def script_srcs_contain(self, tuple queries):
+        """Returns True if any of the script SRCs attributes contain on of the specified text.
+
+        Caches values on the first call to improve performance.
+
+        Parameters
+        ----------
+        queries : tuple of str
+
+        """
+        return self.root.script_srcs_contain(queries)
+
+    def css_matches(self, str selector):
+        return self.root.css_matches(selector)
+
+    @staticmethod
+    cdef LexborHTMLParser from_document(lxb_html_document_t *document, bytes raw_html):
+        obj = <LexborHTMLParser> LexborHTMLParser.__new__(LexborHTMLParser)
+        obj.document = document
+        obj.raw_html = raw_html
+        obj.cached_script_texts = None
+        obj.cached_script_srcs = None
+        obj._selector = None
+        return obj
+
+    def clone(self):
+        """Clone the current tree."""
+        cdef lxb_html_document_t* cloned_document
+        cdef lxb_dom_node_t* cloned_node
+
+        with nogil:
+            cloned_document = lxb_html_document_create()
+
+        if cloned_document == NULL:
+            raise SelectolaxError("Can't create a new document")
+
+        cloned_document.ready_state = LXB_HTML_DOCUMENT_READY_STATE_COMPLETE
+
+        with nogil:
+            cloned_node = lxb_dom_document_import_node(
+                &cloned_document.dom_document,
+                <lxb_dom_node_t *> lxb_dom_document_root(&self.document.dom_document),
+                <bint> True
+            )
+
+        if cloned_node == NULL:
+            raise SelectolaxError("Can't create a new document")
+
+        with nogil:
+            lxb_dom_node_insert_child(<lxb_dom_node_t * > cloned_document, cloned_node)
+
+        cls = LexborHTMLParser.from_document(cloned_document, self.raw_html)
+        return cls
+    def unwrap_tags(self, list tags, delete_empty = False):
+        """Unwraps specified tags from the HTML tree.
+
+        Works the same as the ``unwrap`` method, but applied to a list of tags.
+
+        Parameters
+        ----------
+        tags : list
+            List of tags to remove.
+        delete_empty : bool
+            Whenever to delete empty tags.
+
+        Examples
+        --------
+
+        >>> tree = LexborHTMLParser("<div><a href="">Hello</a> <i>world</i>!</div>")
+        >>> tree.body.unwrap_tags(['i','a'])
+        >>> tree.body.html
+        '<body><div>Hello world!</div></body>'
+        """
+        if self.root is not None:
+            self.root.unwrap_tags(tags, delete_empty=delete_empty)