* Fix .text() parameter names - rename seperator to separator (#2, thanks to @cmdlineluser).

awolverp · awolverp · commit 9c365f7f1198 · 2025-05-11T19:41:38.000+03:30
* Make `Parser` compatible with `BytesIO` and `TextIO` by adding new methods `.write()` and `.writable()`.
* Accept "html" and "xml" values as `options` in parsing.
* Set default value for `options` as "html".
* Update the docuemntation examples.
diff --git a/Cargo.toml b/Cargo.toml
@@ -17,7 +17,7 @@ crate-type = ["cdylib"]
 members = ["treedom", "matching"]
 
 [workspace.package]
-version = "0.2.1"
+version = "0.3.0"
 edition = "2021"
 readme = "README.md"
 license = "MIT"
diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@
 ![image](https://img.shields.io/pypi/l/markupever.svg)
 ![image](https://img.shields.io/pypi/pyversions/markupever.svg)
 ![python-test](https://github.com/awolverp/markupever/actions/workflows/test.yml/badge.svg)
+![download](https://img.shields.io/pypi/dm/markupever?style=flat-square&color=%23314bb5)
 
 ------
 
@@ -66,5 +67,8 @@ body = html.create_element("body")
 body.create_text("Hello Everyone ...")
 
 print(root.serialize())
-# <!DOCTYPE html><html lang="en"><body>Hello Everyone ...</body></html>
+# <!DOCTYPE html>
+# <html lang="en">
+#   <body>Hello Everyone ...</body>
+# </html>
 ```
diff --git a/docs/docs/more-examples.md b/docs/docs/more-examples.md
@@ -12,25 +12,38 @@ There's a collection of examples for markupever library.
     **This documentation is incomplete**. Documenting everything take a while.
 
 
-### Using markupever alongside HTTP clients
-How to use markupever alongside HTTP clients such as `httpx`, `requests` and `aiohttp`.
+### Using markupever alongside HTTPX
+How to use markupever alongside `httpx` library.
 
 === "httpx (traditional)"
 
     ```python
+    import markupever
+    import httpx
+
+    # Create a Client instance
     with httpx.Client() as client:
+        # Send a GET request to google
         response = client.get("https://www.example.com/")
+
+        # Parse the result using markupever
         dom = markupever.parse(response.content, markupever.HtmlOptions())
     ```
 
 === "httpx (recommended)"
 
     ```python
+    import markupever
+    import httpx
+
+    # Create a Client instance
     with httpx.Client() as client:
+        # Stream a GET request to google
         with client.stream(
             "GET",
             "https://www.example.com/",
         ) as stream:
+            # Parse the result using markupever
             parser = markupever.Parser(markupever.HtmlOptions())
 
             for content in stream.iter_bytes():
@@ -39,17 +52,63 @@ How to use markupever alongside HTTP clients such as `httpx`, `requests` and `ai
             dom = parser.finish().into_dom()
     ```
 
+### Using markupever alongside Requests
+How to use markupever alongside `requests` library.
+
 === "requests"
 
     ```python
+    import markupever
+    import requests
+
+    # Send a GET request to google
     response = requests.get("https://www.example.com/")
+
+    # Parse the result using markupever
     dom = markupever.parse(response.content, markupever.HtmlOptions())
     ```
 
+### Using markupever alongside AIOHttp
+How to use markupever alongside `aiohttp` library.
+
 === "aiohttp"
 
     ```python
+    # Create a ClientSession instance
     async with aiohttp.ClientSession() as session:
+        # Send a GET request to google
         async with session.get('https://www.google.com/') as resp:
+            # Parse the result using markupever
             dom = markupever.parse(await resp.read(), markupever.HtmlOptions())
     ```
+
+### Using markupever alongside PycURL
+How to use markupever alongside `PycURL` library.
+
+=== "pycurl (recommended & easy)"
+
+    ```python
+    import pycurl
+    import certifi
+    from io import BytesIO
+
+    # Create a PycURL instance
+    c = pycurl.Curl()
+
+    # Define Options ...
+    c.setopt(c.URL, 'https://www.google.com/')
+    c.setopt(c.CAINFO, certifi.where())
+
+    # Setup markupever to recieve response
+    parser = markupever.Parser()
+    c.setopt(c.WRITEDATA, parser)
+
+    # Send Request
+    c.perform()
+
+    # Close Connection
+    c.close()
+
+    # Use the parsed DOM
+    dom = parser.finish().into_dom()
+    ```
diff --git a/python/markupever/dom.py b/python/markupever/dom.py
@@ -340,14 +340,14 @@ def strings(self, strip: bool = False):
             else:
                 yield descendant.content
 
-    def text(self, seperator: str = "", strip: bool = False) -> str:
+    def text(self, separator: str = "", strip: bool = False) -> str:
         """
         Concatenates text from all descendant text nodes into a single string.
 
-        - seperator (str, optional): String used to join text nodes. Defaults to an empty string.
+        - separator (str, optional): String used to join text nodes. Defaults to an empty string.
         - strip (bool, optional): Whether to strip whitespace from text nodes. Defaults to False.
         """
-        return seperator.join(self.strings(strip=strip))
+        return separator.join(self.strings(strip=strip))
 
     def serialize_bytes(
         self, indent: int = 4, is_html: typing.Optional[bool] = None, include_self: bool = True
@@ -854,11 +854,11 @@ def __getitem__(self, index: int) -> typing.Tuple[_rustlib.QualName, str]: ...
 
     def __getitem__(self, index):
         if not isinstance(index, int):
-            _, index = self._find_by_key(index)
-            if index == -1:
+            _, index_i = self._find_by_key(index)
+            if index_i == -1:
                 raise KeyError(index)
 
-            _, val = self.__raw.get_by_index(index)
+            _, val = self.__raw.get_by_index(index_i)
             return val
 
         return self.__raw.get_by_index(index)
diff --git a/python/markupever/parser.py b/python/markupever/parser.py
@@ -6,7 +6,7 @@
 class Parser:
     __slots__ = ("__raw", "__state")
 
-    def __init__(self, options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptions]):
+    def __init__(self, options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptions, typing.Literal["html"], typing.Literal["xml"]] = "html"):
         """
         An HTML/XML parser, ready to receive unicode input.
 
@@ -16,13 +16,40 @@ def __init__(self, options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptio
         for `options`, If your input is a HTML document, pass a `HtmlOptions`;
         If your input is a XML document, pass `XmlOptions`.
         """
+        if isinstance(options, str):
+            if options == "html":
+                options = _rustlib.HtmlOptions()
+            elif options == "xml":
+                options = _rustlib.XmlOptions()
+            else:
+                raise ValueError(f"invalid parser options: {options!r}")
+        
         self.__raw = _rustlib.Parser(options)
 
         # 0 - processing
         # 1 - finished
         # 2 - converted
         self.__state = 0
 
+    def writable(self) -> bool:
+        """
+        Same as `Parser.is_finished`.
+
+        This function exists to make `Parser` like a `BytesIO` and `StringIO`.
+        You can pass the `Parser` to each function which needs a writable buffer or IO.
+        """
+        return self.is_finished
+
+    def write(self, content: typing.Union[str, bytes]) -> int:
+        """
+        Same as `Parser.process`.
+
+        This function exists to make `Parser` like a `BytesIO` and `StringIO`.
+        You can pass the `Parser` to each function which needs a writable buffer or IO.
+        """
+        self.__raw.process(content)
+        return len(content)
+
     def process(self, content: typing.Union[str, bytes]) -> "Parser":
         """
         Processes an input.
@@ -86,7 +113,7 @@ def __repr__(self) -> str:
 
 def parse(
     content: typing.Union[str, bytes],
-    options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptions],
+    options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptions, typing.Literal["html"], typing.Literal["xml"]] = "html",
 ) -> TreeDom:
     """
     Parses HTML or XML content and returns the parsed document tree.
@@ -105,7 +132,7 @@ def parse(
 
 def parse_file(
     path: typing.Union[str, typing.TextIO, typing.BinaryIO],
-    options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptions],
+    options: typing.Union[_rustlib.HtmlOptions, _rustlib.XmlOptions, typing.Literal["html"], typing.Literal["xml"]] = "html",
     *,
     chunk_size: int = 10240,
 ) -> TreeDom:
diff --git a/python/tests/test_dom.py b/python/tests/test_dom.py
@@ -149,7 +149,7 @@ def test_connect_node():
 
     assert p.text() == "\ncontent 1\ncontent 2"
     assert p.text(strip=True) == "content 1content 2"
-    assert p.text(seperator="\t", strip=True) == "content 1\tcontent 2"
+    assert p.text(separator="\t", strip=True) == "content 1\tcontent 2"
 
     assert text.has_siblings
     assert p.has_children
diff --git a/python/tests/test_parser.py b/python/tests/test_parser.py
@@ -54,6 +54,12 @@ def test_parser():  # this is a copy of test_rustlib.test_parser for markupever.
     with pytest.raises(RuntimeError):
         parser.errors()
 
+    _ = markupever.Parser("html")
+    _ = markupever.Parser("xml")
+
+    with pytest.raises(ValueError):
+        _ = markupever.Parser("invalid")
+
 
 def test_parse_function():
     assert isinstance(
