selectolax 0.3.24__cp313-cp313-macosx_10_13_universal2.whl → 0.3.26__cp313-cp313-macosx_10_13_universal2.whl

selectolax/parser.pyi

@@ -1,15 +1,28 @@
-from typing import Iterator, TypeVar, Literal
+from typing import Any, Iterator, TypeVar, Literal, overload
 
 DefaultT = TypeVar("DefaultT")
 
 class _Attributes:
     @staticmethod
-    def create(node: "Node", decode_errors: str) -> "_Attributes": ...
+    def create(node: Node, decode_errors: str) -> _Attributes: ...
     def keys(self) -> Iterator[str]: ...
-    def items(self) -> Iterator[tuple[str, str]]: ...
-    def values(self) -> Iterator[str]: ...
-    def get(self, key, default: DefaultT | None = None) -> str | DefaultT: ...
-    def sget(self, key, default: str = "") -> str | DefaultT: ...
+    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 Selector:
     """An advanced CSS selector that supports additional operations.
@@ -18,12 +31,12 @@ class Selector:
 
     Please note, this is an experimental feature that can change in the future."""
 
-    def __init__(self, node: "Node", query: str): ...
-    def css(self, query: str) -> "Node":
+    def __init__(self, node: Node, query: str): ...
+    def css(self, query: str) -> Node:
         """Evaluate CSS selector against current scope."""
         ...
     @property
-    def matches(self) -> list["Node"]:
+    def matches(self) -> list[Node]:
         """Returns all possible selector matches"""
         ...
     @property
@@ -32,7 +45,7 @@ class Selector:
         ...
     def text_contains(
         self, text: str, deep: bool = True, separator: str = "", strip: bool = False
-    ) -> "Selector":
+    ) -> Selector:
         """Filter all current matches given text."""
         ...
     def any_text_contains(
@@ -42,7 +55,7 @@ class Selector:
         ...
     def attribute_long_than(
         self, text: str, length: int, start: str | None = None
-    ) -> "Selector":
+    ) -> Selector:
         """Filter all current matches by attribute length.
 
         Similar to string-length in XPath."""
@@ -56,14 +69,15 @@ class Selector:
         ...
 
 class Node:
+    parser: HTMLParser
     @property
-    def attributes(self) -> dict[str, None | str]:
+    def attributes(self) -> dict[str, str | None]:
         """Get all attributes that belong to the current node.
 
         The value of empty attributes is None."""
         ...
     @property
-    def attrs(self) -> "_Attributes":
+    def attrs(self) -> _Attributes:
         """A dict-like object that is similar to the attributes property, but operates directly on the Node data."""
         ...
     @property
@@ -87,10 +101,10 @@ class Node:
     def text(self, deep: bool = True, separator: str = "", strip: bool = False) -> str:
         """Returns the text of the node including text of all its child nodes."""
         ...
-    def iter(self, include_text: bool = False) -> Iterator["Node"]:
+    def iter(self, include_text: bool = False) -> Iterator[Node]:
         """Iterate over nodes on the current level."""
         ...
-    def traverse(self, include_text: bool = False) -> Iterator["Node"]:
+    def traverse(self, include_text: bool = False) -> Iterator[Node]:
         """Iterate over all child and next nodes starting from the current level."""
         ...
     @property
@@ -98,30 +112,30 @@ class Node:
         """Return the name of the current tag (e.g. div, p, img)."""
         ...
     @property
-    def child(self) -> None | "Node":
+    def child(self) -> Node | None:
         """Return the child node."""
         ...
     @property
-    def parent(self) -> None | "Node":
+    def parent(self) -> Node | None:
         """Return the parent node."""
         ...
     @property
-    def next(self) -> None | "Node":
+    def next(self) -> Node | None:
         """Return next node."""
         ...
     @property
-    def prev(self) -> None | "Node":
+    def prev(self) -> Node | None:
         """Return previous node."""
         ...
     @property
-    def last_child(self) -> None | "Node":
+    def last_child(self) -> Node | None:
         """Return last child node."""
         ...
     @property
-    def html(self) -> None | str:
+    def html(self) -> str | None:
         """Return HTML representation of the current node including all its child nodes."""
         ...
-    def css(self, query: str) -> list["Node"]:
+    def css(self, query: str) -> list[Node]:
         """Evaluate CSS selector against current node and its child nodes."""
         ...
     def any_css_matches(self, selectors: tuple[str]) -> bool:
@@ -130,9 +144,18 @@ class Node:
     def css_matches(self, selector: str) -> bool:
         """Returns True if CSS selector matches a node."""
         ...
+    @overload
     def css_first(
-        self, query: str, default: DefaultT | None = None, strict: bool = False
-    ) -> "Node" | DefaultT:
+        self, query: str, default: Any = ..., strict: Literal[True] = ...
+    ) -> Node: ...
+    @overload
+    def css_first(
+        self, query: str, default: DefaultT, strict: bool = False
+    ) -> Node | DefaultT: ...
+    @overload
+    def css_first(
+        self, query: str, default: None = ..., strict: bool = False
+    ) -> Node | None:
         """Evaluate CSS selector against current node and its child nodes."""
         ...
     def decompose(self, recursive: bool = True) -> None:
@@ -161,13 +184,16 @@ class Node:
     def insert_after(self, value: str | bytes | None) -> None:
         """Insert a node after the current Node."""
         ...
+    def insert_child(self, value: str | bytes | None) -> None:
+        """Insert a node inside (at the end of) the current Node.."""
+        ...
     @property
     def raw_value(self) -> bytes:
         """Return the raw (unparsed, original) value of a node.
 
         Currently, works on text nodes only."""
         ...
-    def select(self, query: str | None = None) -> "Selector":
+    def select(self, query: str | None = None) -> Selector:
         """Select nodes given a CSS selector.
 
         Works similarly to the css method, but supports chained filtering and extra features.
@@ -204,14 +230,23 @@ class HTMLParser:
         use_meta_tags: bool = True,
         decode_errors: Literal["strict", "ignore", "replace"] = "ignore",
     ): ...
-    def css(self, query: str) -> list["Node"]:
+    def css(self, query: str) -> list[Node]:
         """A CSS selector.
 
         Matches pattern query against HTML tree."""
         ...
+    @overload
+    def css_first(
+        self, query: str, default: Any = ..., strict: Literal[True] = ...
+    ) -> Node: ...
+    @overload
     def css_first(
-        self, query: str, default: DefaultT | None = None, strict: bool = False
-    ) -> DefaultT | "Node":
+        self, query: str, default: DefaultT, strict: bool = False
+    ) -> Node | DefaultT: ...
+    @overload
+    def css_first(
+        self, query: str, default: None = ..., strict: bool = False
+    ) -> Node | None:
         """Same as css but returns only the first match."""
         ...
     @property
@@ -221,18 +256,18 @@ class HTMLParser:
         Returns unknown in case the encoding is not determined."""
         ...
     @property
-    def root(self) -> "Node" | None:
+    def root(self) -> Node | None:
         """Returns root node."""
         ...
     @property
-    def head(self) -> "Node" | None:
+    def head(self) -> Node | None:
         """Returns head node."""
         ...
     @property
-    def body(self) -> "Node" | None:
+    def body(self) -> Node | None:
         """Returns document body."""
         ...
-    def tags(self, name: str) -> list["Node"]:
+    def tags(self, name: str) -> list[Node]:
         """Returns a list of tags that match specified name."""
         ...
     def text(self, deep: bool = True, separator: str = "", strip: bool = False) -> str:
@@ -245,10 +280,10 @@ class HTMLParser:
         Works the same as th unwrap method, but applied to a list of tags."""
         ...
     @property
-    def html(self) -> None | str:
+    def html(self) -> str | None:
         """Return HTML representation of the page."""
         ...
-    def select(self, query: str | None = None) -> "Selector" | None:
+    def select(self, query: str | None = None) -> Selector | None:
         """Select nodes given a CSS selector.
 
         Works similarly to the css method, but supports chained filtering and extra features.
@@ -268,7 +303,7 @@ class HTMLParser:
         Caches values on the first call to improve performance."""
         ...
     def css_matches(self, selector: str) -> bool: ...
-    def clone(self) -> "HTMLParser":
+    def clone(self) -> HTMLParser:
         """Clone the current tree."""
         ...
     def merge_text_nodes(self):
@@ -276,3 +311,20 @@ class HTMLParser:
 
         This is useful for text extraction."""
         ...
+
+def create_tag(tag: str) -> Node:
+    """
+    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[Node]:
+    """
+    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.
+    """
+    ...

selectolax/parser.pyx

@@ -3,6 +3,7 @@ from cpython cimport bool
 
 include "modest/selection.pxi"
 include "modest/node.pxi"
+include "modest/util.pxi"
 include "utils.pxi"
 
 cdef class HTMLParser:

selectolax/utils.pxi

@@ -1,5 +1,11 @@
+from typing import Literal, Optional, Union, Type
+
 MAX_HTML_INPUT_SIZE = 250e+7
 
+ParserCls = Union[Type["HTMLParser"], Type["LexborHTMLParser"]]
+Parser = Union["HTMLParser", "LexborHTMLParser"]
+
+
 def preprocess_input(html, decode_errors='ignore'):
     if isinstance(html, (str, unicode)):
         bytes_html = html.encode('UTF-8', errors=decode_errors)
@@ -11,3 +17,91 @@ def preprocess_input(html, decode_errors='ignore'):
     if html_len > MAX_HTML_INPUT_SIZE:
         raise ValueError("The specified HTML input is too large to be processed (%d bytes)" % html_len)
     return bytes_html, html_len
+
+
+def do_create_tag(tag: str, parser_cls: ParserCls):
+    if not tag:
+        raise ValueError("Tag name cannot be empty")
+    return do_parse_fragment(f"<{tag}></{tag}>", parser_cls)[0]
+
+
+def get_fragment_type(
+    html: str,
+    parser_cls: ParserCls,
+    tree: Optional[Parser] = None,
+) -> Literal["document", "fragment", "head", "body", "head_and_body", "document_no_head", "document_no_body", "document_no_head_no_body"]:
+    if not tree:
+        tree = parser_cls(html)
+    
+    import re
+    html_re = re.compile(r"<html|<body|<head", re.IGNORECASE)
+
+    has_html = False
+    has_head = False
+    has_body = False
+    for match in html_re.finditer(html):
+        if match[0] == "<html":
+            has_html = True
+        elif match[0] == "<head":
+            has_head = True
+        elif match[0] == "<body":
+            has_body = True
+
+        if has_html and has_head and has_body:
+            break
+    
+    if has_html and has_head and has_body:
+        return "document"
+    elif has_html and not has_head and has_body:
+        return "document_no_head"
+    elif has_html and has_head and not has_body:
+        return "document_no_body"
+    elif has_html and not has_head and not has_body:
+        return "document_no_head_no_body"
+    elif has_head and not has_body:
+        return "head"
+    elif not has_head and has_body:
+        return "body"
+    elif has_head and has_body:
+        return "head_and_body"
+    else:
+        return "fragment"
+
+
+def do_parse_fragment(html: str, parser_cls: ParserCls):
+    """
+    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.
+    """
+    html = html.strip()
+    tree = parser_cls(html)
+    frag_type = get_fragment_type(html, parser_cls, tree)
+
+    if frag_type == "document":
+        return [tree.root]
+    if frag_type == "document_no_head":
+        tree.head.decompose(recursive=True)
+        return [tree.root]
+    if frag_type == "document_no_body":
+        tree.body.decompose(recursive=True)
+        return [tree.root]
+    if frag_type == "document_no_head_no_body":
+        tree.head.decompose(recursive=True)
+        tree.body.decompose(recursive=True)
+        return [tree.root]
+    elif frag_type == "head":
+        tree.body.decompose(recursive=True)
+        return [tree.head]
+    elif frag_type == "body":
+        tree.head.decompose(recursive=True)
+        return [tree.body]
+    elif frag_type == "head_and_body":
+        return [tree.head, tree.body]
+    else:
+        return [
+            *tree.head.iter(include_text=True),
+            *tree.body.iter(include_text=True),
+        ]

{selectolax-0.3.24.dist-info → selectolax-0.3.26.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: selectolax
-Version: 0.3.24
+Version: 0.3.26
 Summary: Fast HTML5 parser with CSS selectors.
 Home-page: https://github.com/rushter/selectolax
 Author: Artem Golubin
@@ -22,6 +22,7 @@ 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: Programming Language :: Python :: 3.13
 License-File: LICENSE
 Provides-Extra: cython
 Requires-Dist: Cython==3.0.11; extra == "cython"
@@ -122,6 +123,10 @@ Available backends
 Selectolax supports two backends: ``Modest`` and ``Lexbor``. By default, all examples use the Modest backend.
 Most of the features between backends are almost identical, but there are still some differences.
 
+As of 2024, the preferred backend is ``Lexbor``. The ``Modest`` backend is still available for compatibility reasons
+and the underlying C library that selectolax uses is not maintained anymore.
+
+
 To use ``lexbor``, just import the parser and use it in the similar way to the `HTMLParser`.
 
 .. code:: python
@@ -147,7 +152,7 @@ Simple Benchmark
 Package                       Time
 ============================ ===========
 Beautiful Soup (html.parser)  61.02 sec.
-lxml                          9.09 sec.
+lxml / Beautiful Soup (lxml)  9.09 sec.
 html5_parser                  16.10 sec.
 selectolax (Modest)           2.94 sec.
 selectolax (Lexbor)           2.39 sec.

selectolax-0.3.26.dist-info/RECORD

@@ -0,0 +1,26 @@
+selectolax-0.3.26.dist-info/RECORD,,
+selectolax-0.3.26.dist-info/LICENSE,sha256=kYggm2ZJzBgL79x1gCsYsx8rFIYP2IE-BdXRV3Rm0NU,1077
+selectolax-0.3.26.dist-info/WHEEL,sha256=pJyWwqOgS8-_dOw_-yPJJDauxCO1NJCkyPNqxURSoZw,115
+selectolax-0.3.26.dist-info/top_level.txt,sha256=e5MuEM2PrQzoDlWetkFli9uXSlxa_ktW5jJEihhaI1c,11
+selectolax-0.3.26.dist-info/METADATA,sha256=HqNPkDK0NqFA-N4HsTn3QtHYktNEwobUdCj7kw-e4VU,5928
+selectolax/lexbor.pyi,sha256=X2PMQR2XLd2rOPliKSpeFZ_VEf6mOQFTcFm0ChQbzsQ,6544
+selectolax/parser.pyx,sha256=o1HkYE_nQr3TS7EPlldJx2-ygU9B5FI2uWYFzdF-VaI,12953
+selectolax/__init__.py,sha256=r8TrGaSWTYcCt8yNkcf_pH1I7c7IPOMagr3wd9tCgy8,175
+selectolax/lexbor.pxd,sha256=PwygBdb1blWAQcxXubZS5uffhgcXaqgySNMPFMT02-c,20958
+selectolax/lexbor.pyx,sha256=ffEzBnZjGTsI-H5qck7bfjVRE9vteOhQnDp6RjVD7G0,10750
+selectolax/parser.pyi,sha256=kbR5eWvkJEy-9Hx3L_4JmGy3caIl0ki4SiagWz-fnhw,11557
+selectolax/utils.pxi,sha256=rPNMFqS0PRLkQPugwPfj-pnHCzkQzQ2cjIRMPZdR6R8,3453
+selectolax/lexbor.c,sha256=mDFnCQbjAav1zsNLpikrhF1nth0NnhlvHwFzo45-hIc,2353590
+selectolax/parser.cpython-313-darwin.so,sha256=kY8S34tGUaohfdBfzBYnoRFo6_ydkw-3WSKSMFrJUGM,6158936
+selectolax/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+selectolax/lexbor.cpython-313-darwin.so,sha256=mBSRyPhv-nJxeONweF1uRR3Ll2xljzrsOMnDanrGtd0,23079456
+selectolax/parser.c,sha256=W3VyTzjtoNJZAWLNSx9cFaJcn4D4gtQchsz3APG7iiY,2214752
+selectolax/base.pxi,sha256=eiPKlY9gG3l49qJoRQVLl1Ljza6z1k0A-met6sDPcqE,89
+selectolax/parser.pxd,sha256=zZlg1vHUg6o4MXaiwKAo5S5hO_DqBGc4_E10qJ2EcM4,24564
+selectolax/modest/selection.pxi,sha256=S55MMxEW2B1oPExB_DRwPM46WoWZU73J3rFRZU1URuQ,6393
+selectolax/modest/util.pxi,sha256=aX9UnRNTITImHVBTlIs9efOd3EyugLq_Lwuo0zVTiuQ,551
+selectolax/modest/node.pxi,sha256=NrMzJnQJDCmgTHpUxpMHDyAfQ_AS_n_Cr_2ryEKjyL0,32550
+selectolax/lexbor/selection.pxi,sha256=PqjvpL6H9uFcmcQWVGfML8FDsTO7tGoZujpA00g9pWk,6444
+selectolax/lexbor/util.pxi,sha256=Zq7S-zlyU3wOo49wGHQHnmmhpbkrcJm59ZCTPENcZQA,563
+selectolax/lexbor/node.pxi,sha256=1XNzUwCbTYXy4D6rZtHxMpoJ9M-xoprB9wjdsiaWhr0,29346
+selectolax/lexbor/attrs.pxi,sha256=-518D5v70GgMJhtsxWrWcgIMnXg8afECpUubzq8kqqs,3102

{selectolax-0.3.24.dist-info → selectolax-0.3.26.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.1.0)
+Generator: setuptools (75.3.0)
 Root-Is-Purelib: false
 Tag: cp313-cp313-macosx_10_13_universal2
 

selectolax-0.3.24.dist-info/RECORD

@@ -1,24 +0,0 @@
-selectolax-0.3.24.dist-info/RECORD,,
-selectolax-0.3.24.dist-info/LICENSE,sha256=kYggm2ZJzBgL79x1gCsYsx8rFIYP2IE-BdXRV3Rm0NU,1077
-selectolax-0.3.24.dist-info/WHEEL,sha256=Atbd32uHC5ud5B4JupjIDNKQgnXrL6njGq322U0ClSQ,115
-selectolax-0.3.24.dist-info/top_level.txt,sha256=e5MuEM2PrQzoDlWetkFli9uXSlxa_ktW5jJEihhaI1c,11
-selectolax-0.3.24.dist-info/METADATA,sha256=tTXFaywjSCLtoHn-mCX-jZCSuhWVZ8CVJocJit3e4Po,5681
-selectolax/lexbor.pyi,sha256=N2u6ru6bMnJWsjRmzoctM9AHju41FZVr6Iij-gbkNOs,4945
-selectolax/parser.pyx,sha256=2pKAUhY64htRxF5v64Ke7NRNSm1BHAS60wxrmmapJi0,12927
-selectolax/__init__.py,sha256=0DJWRFlhuIq2te-rSQYt7CZ4a7_wDJZFxi5tMdQTiHM,175
-selectolax/lexbor.pxd,sha256=PwygBdb1blWAQcxXubZS5uffhgcXaqgySNMPFMT02-c,20958
-selectolax/lexbor.pyx,sha256=HhP93LGdiUmRY3F1ybFQHgz7NG25Ae1RFqhxx7HE9BY,10724
-selectolax/parser.pyi,sha256=g8AED0DK6tpLxlgbYtmpzvuUQ1TMGX7hQBi6u5jlbHQ,9908
-selectolax/utils.pxi,sha256=BCIzfmduFEuCxu_9vIEmjzrcwawOtyW31lDmfEU1wk4,544
-selectolax/lexbor.c,sha256=r7XCW9QHJ5FQ4WD-XdHTfZGOlsVeAhjKrohfm_qcFR8,2134829
-selectolax/parser.cpython-313-darwin.so,sha256=lZybv0UkJeENZjcFRpihPTDaPBGpWojxL3ZAo7eQgSc,6054792
-selectolax/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-selectolax/lexbor.cpython-313-darwin.so,sha256=RJHXcSafauwSqez_UKyV-DcWKO3H4wdYd3ig5L6DYZo,22959168
-selectolax/parser.c,sha256=mKvGJLHhe2iXRBHj4VxBCfrjtfpnJpzODRx37_v51gA,1995872
-selectolax/base.pxi,sha256=eiPKlY9gG3l49qJoRQVLl1Ljza6z1k0A-met6sDPcqE,89
-selectolax/parser.pxd,sha256=zZlg1vHUg6o4MXaiwKAo5S5hO_DqBGc4_E10qJ2EcM4,24564
-selectolax/modest/selection.pxi,sha256=S55MMxEW2B1oPExB_DRwPM46WoWZU73J3rFRZU1URuQ,6393
-selectolax/modest/node.pxi,sha256=NrMzJnQJDCmgTHpUxpMHDyAfQ_AS_n_Cr_2ryEKjyL0,32550
-selectolax/lexbor/selection.pxi,sha256=PqjvpL6H9uFcmcQWVGfML8FDsTO7tGoZujpA00g9pWk,6444
-selectolax/lexbor/node.pxi,sha256=1XNzUwCbTYXy4D6rZtHxMpoJ9M-xoprB9wjdsiaWhr0,29346
-selectolax/lexbor/attrs.pxi,sha256=-518D5v70GgMJhtsxWrWcgIMnXg8afECpUubzq8kqqs,3102