chadselect 0.2.0__tar.gz

chadselect-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+# Rust
+**/target/
+**/*.rs.bk
+Cargo.lock
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+
+# IDE / Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+.venv/*

chadselect-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: chadselect
+Version: 0.2.0
+Summary: Unified data extraction — CSS, XPath, Regex, and JMESPath behind one query interface.
+Project-URL: Homepage, https://github.com/markjacksoncerberus/chadselect
+Project-URL: Repository, https://github.com/markjacksoncerberus/chadselect
+Project-URL: Issues, https://github.com/markjacksoncerberus/chadselect/issues
+Author: Mark Jackson
+License: MIT
+Keywords: css,extraction,jmespath,parsing,regex,scraping,xpath
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: jmespath>=1.0
+Requires-Dist: lxml>=5.0
+Requires-Dist: selectolax>=0.3.21
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ChadSelect
+
+Unified data extraction — CSS, XPath, Regex, and JMESPath behind one query interface.
+
+```python
+from chadselect import ChadSelect
+
+cs = ChadSelect()
+cs.add_html(html)
+cs.add_json(json_str)
+
+# One syntax, four engines
+title = cs.select(0, "css:h1.title")
+author = cs.select(0, "xpath://span[@class='author']/text()")
+vin = cs.select(0, r"regex:[A-HJ-NPR-Z0-9]{17}")
+name = cs.select(0, "json:data.products[0].name")
+
+# Function piping
+clean = cs.select(0, "css:.price >> trim >> uppercase()")
+```
+
+## Install
+
+```bash
+pip install chadselect
+```
+
+## Query Syntax
+
+Queries use a `engine:expression` prefix:
+
+| Prefix | Engine | Best For |
+|--------|--------|----------|
+| `css:` | CSS Selectors (selectolax) | HTML element selection |
+| `xpath:` | XPath 1.0 (lxml) | Complex HTML/XML traversal |
+| `regex:` | Regular Expressions (re) | Pattern matching on raw text |
+| `json:` | JMESPath (jmespath) | JSON field extraction |
+
+No prefix defaults to regex.
+
+## Function Piping
+
+Chain text transformations with `>>`:
+
+```python
+cs.select(0, "css:.price >> trim >> substring-after('$') >> uppercase()")
+```
+
+Available functions: `trim`, `uppercase()`, `lowercase()`, `normalize-space()`,
+`substring-after('delim')`, `substring-before('delim')`, `substring(start, len)`,
+`replace('old', 'new')`, `get-attr('name')`.
+
+## API
+
+```python
+cs = ChadSelect()
+
+# Load content
+cs.add_html(html_string)
+cs.add_json(json_string)
+cs.add_text(plain_text)
+
+# Query (index: 0=first, -1=all)
+results = cs.query(-1, "css:.price")          # List[str] — all matches
+value = cs.select(0, "css:.price")            # str — first match or ""
+
+# Multi-query
+first_hit = cs.select_first([(0, "css:#id"), (0, "xpath://fallback")])
+combined = cs.select_many([(-1, "css:.a"), (-1, "css:.b")])
+
+# Batch (fastest for many fields)
+results = cs.query_batch([(-1, "css:.title"), (-1, "json:data.name")])
+
+# With validators
+results = cs.select_where(0, "css:.vin", lambda v: len(v) == 17)
+```
+
+## License
+
+MIT

chadselect-0.2.0/README.md

@@ -0,0 +1,80 @@
+# ChadSelect
+
+Unified data extraction — CSS, XPath, Regex, and JMESPath behind one query interface.
+
+```python
+from chadselect import ChadSelect
+
+cs = ChadSelect()
+cs.add_html(html)
+cs.add_json(json_str)
+
+# One syntax, four engines
+title = cs.select(0, "css:h1.title")
+author = cs.select(0, "xpath://span[@class='author']/text()")
+vin = cs.select(0, r"regex:[A-HJ-NPR-Z0-9]{17}")
+name = cs.select(0, "json:data.products[0].name")
+
+# Function piping
+clean = cs.select(0, "css:.price >> trim >> uppercase()")
+```
+
+## Install
+
+```bash
+pip install chadselect
+```
+
+## Query Syntax
+
+Queries use a `engine:expression` prefix:
+
+| Prefix | Engine | Best For |
+|--------|--------|----------|
+| `css:` | CSS Selectors (selectolax) | HTML element selection |
+| `xpath:` | XPath 1.0 (lxml) | Complex HTML/XML traversal |
+| `regex:` | Regular Expressions (re) | Pattern matching on raw text |
+| `json:` | JMESPath (jmespath) | JSON field extraction |
+
+No prefix defaults to regex.
+
+## Function Piping
+
+Chain text transformations with `>>`:
+
+```python
+cs.select(0, "css:.price >> trim >> substring-after('$') >> uppercase()")
+```
+
+Available functions: `trim`, `uppercase()`, `lowercase()`, `normalize-space()`,
+`substring-after('delim')`, `substring-before('delim')`, `substring(start, len)`,
+`replace('old', 'new')`, `get-attr('name')`.
+
+## API
+
+```python
+cs = ChadSelect()
+
+# Load content
+cs.add_html(html_string)
+cs.add_json(json_string)
+cs.add_text(plain_text)
+
+# Query (index: 0=first, -1=all)
+results = cs.query(-1, "css:.price")          # List[str] — all matches
+value = cs.select(0, "css:.price")            # str — first match or ""
+
+# Multi-query
+first_hit = cs.select_first([(0, "css:#id"), (0, "xpath://fallback")])
+combined = cs.select_many([(-1, "css:.a"), (-1, "css:.b")])
+
+# Batch (fastest for many fields)
+results = cs.query_batch([(-1, "css:.title"), (-1, "json:data.name")])
+
+# With validators
+results = cs.select_where(0, "css:.vin", lambda v: len(v) == 17)
+```
+
+## License
+
+MIT

chadselect-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chadselect"
+version = "0.2.0"
+description = "Unified data extraction — CSS, XPath, Regex, and JMESPath behind one query interface."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Mark Jackson"},
+]
+keywords = ["scraping", "css", "xpath", "regex", "jmespath", "extraction", "parsing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Text Processing :: Markup :: HTML",
+    "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
+]
+dependencies = [
+    "selectolax>=0.3.21",
+    "lxml>=5.0",
+    "jmespath>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/markjacksoncerberus/chadselect"
+Repository = "https://github.com/markjacksoncerberus/chadselect"
+Issues = "https://github.com/markjacksoncerberus/chadselect/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chadselect"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

chadselect-0.2.0/src/chadselect/__init__.py

@@ -0,0 +1,40 @@
+"""
+ChadSelect — Unified data extraction.
+
+CSS Selectors, XPath 1.0, Regex, and JMESPath behind one query interface
+with chainable post-processing functions.
+
+Usage::
+
+    from chadselect import ChadSelect
+
+    cs = ChadSelect()
+    cs.add_html('<span class="price">$49.99</span>')
+    price = cs.select(0, "css:.price")
+    # "$49.99"
+
+Query prefixes::
+
+    css:       → CSS Selectors (selectolax/lexbor)
+    xpath:     → XPath 1.0 (lxml/libxml2)
+    json:      → JMESPath
+    regex:     → Regex (re stdlib)
+    (no prefix) → Regex (default)
+
+Post-processing functions (pipe with >>)::
+
+    cs.select(0, "css:.price >> normalize-space() >> uppercase()")
+"""
+
+from chadselect._chadselect import ChadSelect
+from chadselect._query import FUNCTION_PIPE, QueryType, parse_query
+from chadselect._functions import supported_text_functions
+
+__all__ = [
+    "ChadSelect",
+    "FUNCTION_PIPE",
+    "QueryType",
+    "parse_query",
+    "supported_text_functions",
+]
+__version__ = "0.2.0"

chadselect-0.2.0/src/chadselect/_chadselect.py

@@ -0,0 +1,218 @@
+"""
+ChadSelect — the main extraction class.
+
+API-compatible with the Rust ``chadselect`` crate.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, List, Optional, Sequence, Tuple
+
+from chadselect._query import ContentType, QueryType, parse_query, is_query_compatible
+from chadselect.engine import css as css_engine
+from chadselect.engine import xpath as xpath_engine
+from chadselect.engine import regex as regex_engine
+from chadselect.engine import json as json_engine
+
+logger = logging.getLogger(__name__)
+
+
+def _default_valid(s: str) -> bool:
+    """Default validator — non-empty, non-whitespace."""
+    return bool(s and s.strip())
+
+
+class _ContentItem:
+    """Internal content item with type tag."""
+
+    __slots__ = ("content", "content_type")
+
+    def __init__(self, content: str, content_type: ContentType) -> None:
+        self.content = content
+        self.content_type = content_type
+
+
+class ChadSelect:
+    """Unified data extraction — CSS, XPath, Regex, and JMESPath.
+
+    Load content, then query with a prefixed query string::
+
+        cs = ChadSelect()
+        cs.add_html('<span class="price">$49.99</span>')
+        price = cs.select(0, "css:.price")  # "$49.99"
+
+    Query prefixes:
+        - ``css:``   → CSS Selectors (selectolax / lexbor)
+        - ``xpath:`` → XPath 1.0 (lxml / libxml2)
+        - ``json:``  → JMESPath
+        - ``regex:`` → Python ``re``
+        - *(none)*   → Regex (default)
+
+    Post-processing via ``>>``::
+
+        cs.select(0, "css:.price >> normalize-space() >> uppercase()")
+    """
+
+    __slots__ = ("_content_list",)
+
+    def __init__(self) -> None:
+        self._content_list: List[_ContentItem] = []
+
+    # ── Content management ──────────────────────────────────────────────
+
+    def add_text(self, content: str) -> None:
+        """Add plain text content."""
+        self._content_list.append(_ContentItem(content, ContentType.TEXT))
+
+    def add_html(self, content: str) -> None:
+        """Add HTML content (compatible with CSS, XPath, and Regex)."""
+        self._content_list.append(_ContentItem(content, ContentType.HTML))
+
+    def add_json(self, content: str) -> None:
+        """Add JSON content (compatible with JMESPath and Regex)."""
+        self._content_list.append(_ContentItem(content, ContentType.JSON))
+
+    def content_count(self) -> int:
+        """Return the number of loaded content items."""
+        return len(self._content_list)
+
+    def clear(self) -> None:
+        """Remove all loaded content."""
+        self._content_list.clear()
+
+    # ── Querying ────────────────────────────────────────────────────────
+
+    def query(self, index: int, query_str: str) -> List[str]:
+        """Query all loaded content and return matching results.
+
+        Args:
+            index: ``-1`` returns **all** matches. ``>= 0`` returns the
+                match at that position (or empty list if out of bounds).
+            query_str: Prefixed query string (e.g. ``"css:.price"``).
+
+        Returns:
+            List of matched strings. Never raises — invalid queries or
+            out-of-bounds indices return ``[]``.
+        """
+        query_type, expression = parse_query(query_str)
+
+        all_results: List[str] = []
+
+        for item in self._content_list:
+            if not is_query_compatible(query_type, item.content_type):
+                continue
+
+            if query_type == QueryType.CSS:
+                results = css_engine.process(expression, item.content)
+            elif query_type == QueryType.XPATH:
+                results = xpath_engine.process(expression, item.content)
+            elif query_type == QueryType.REGEX:
+                results = regex_engine.process(expression, item.content)
+            elif query_type == QueryType.JSON:
+                results = json_engine.process(expression, item.content)
+            else:
+                results = []
+
+            all_results.extend(results)
+
+        return _select_by_index(all_results, index)
+
+    def select(self, index: int, query_str: str) -> str:
+        """Return a single result string (the first match), or ``""``.
+
+        A result is valid when it is non-empty and non-whitespace.
+        """
+        return self.select_where(index, query_str, _default_valid)
+
+    def select_where(
+        self,
+        index: int,
+        query_str: str,
+        valid: Callable[[str], bool],
+    ) -> str:
+        """Like :meth:`select` but with a custom validity check.
+
+        Args:
+            valid: Receives each candidate string, returns ``True`` to accept.
+        """
+        result = self.query(index, query_str)
+        if result and valid(result[0]):
+            return result[0]
+        return ""
+
+    def select_first(
+        self, queries: Sequence[Tuple[int, str]]
+    ) -> List[str]:
+        """Try multiple queries in order, return the first valid result set.
+
+        A result set is valid when all its elements are non-empty and
+        non-whitespace.
+        """
+        return self.select_first_where(queries, _default_valid)
+
+    def select_first_where(
+        self,
+        queries: Sequence[Tuple[int, str]],
+        valid: Callable[[str], bool],
+    ) -> List[str]:
+        """Like :meth:`select_first` but with a custom validity check."""
+        for index, query_str in queries:
+            result = self.query(index, query_str)
+            if result and all(valid(r) for r in result):
+                return result
+        return []
+
+    def select_many(
+        self, queries: Sequence[Tuple[int, str]]
+    ) -> List[str]:
+        """Run multiple queries and return combined unique results."""
+        return self.select_many_where(queries, _default_valid)
+
+    def select_many_where(
+        self,
+        queries: Sequence[Tuple[int, str]],
+        valid: Callable[[str], bool],
+    ) -> List[str]:
+        """Like :meth:`select_many` but with a custom validity check."""
+        seen: set[str] = set()
+        out: List[str] = []
+        for index, query_str in queries:
+            for r in self.query(index, query_str):
+                if valid(r) and r not in seen:
+                    seen.add(r)
+                    out.append(r)
+        return out
+
+    def query_batch(
+        self, queries: Sequence[Tuple[int, str]]
+    ) -> List[List[str]]:
+        """Execute multiple queries in one call.
+
+        Returns a list of result lists, one per input query, in order.
+        This is the most efficient way to extract many fields.
+        """
+        return [self.query(index, q) for index, q in queries]
+
+    # ── Dunder ──────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        return f"ChadSelect(content_count={self.content_count()})"
+
+    def __len__(self) -> int:
+        return self.content_count()
+
+
+def _select_by_index(results: List[str], index: int) -> List[str]:
+    """Select results by index — ``-1`` means 'all'."""
+    if index == -1:
+        return results
+    if index >= 0:
+        if index < len(results):
+            return [results[index]]
+        logger.warning(
+            "Index %d out of range (have %d results)", index, len(results)
+        )
+        return []
+    logger.warning("Invalid index: %d", index)
+    return []

chadselect-0.2.0/src/chadselect/_functions.py

@@ -0,0 +1,134 @@
+"""
+Post-processing text functions — shared by all engines.
+
+Functions are chained using the ``>>`` delimiter after a selector expression::
+
+    css:.price >> normalize-space() >> uppercase()
+    xpath://div/text() >> substring-after('VIN: ') >> substring(0, 3)
+
+Mirrors the Rust crate's ``functions.rs`` exactly.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+
+from chadselect._query import FUNCTION_PIPE
+
+
+def supported_text_functions() -> List[str]:
+    """Return the list of all supported text function signatures."""
+    return [
+        "normalize-space()",
+        "trim()",
+        "uppercase()",
+        "lowercase()",
+        "substring(start, length)",
+        "substring-after('delimiter')",
+        "substring-before('delimiter')",
+        "replace('find', 'replace')",
+        "get-attr('attribute')",
+    ]
+
+
+def split_functions(input_str: str) -> Tuple[str, str]:
+    """Split ``expression >> func1() >> func2()`` into ``(expression, func_chain_str)``.
+
+    Returns ``(expression, "")`` if no ``>>`` pipe is present.
+    """
+    pos = input_str.find(FUNCTION_PIPE)
+    if pos == -1:
+        return input_str.strip(), ""
+    return input_str[:pos].strip(), input_str[pos + len(FUNCTION_PIPE):]
+
+
+def parse_and_apply(results: List[str], func_chain_str: str) -> List[str]:
+    """Parse a function chain string and apply it to results."""
+    if not func_chain_str.strip():
+        return results
+
+    for func_str in func_chain_str.split(FUNCTION_PIPE):
+        func_str = func_str.strip()
+        if not func_str:
+            continue
+        results = _apply_one(results, func_str)
+        # Filter empty results after each step (matches Rust behavior)
+        results = [r for r in results if r]
+    return results
+
+
+def _apply_one(results: List[str], func_str: str) -> List[str]:
+    """Apply a single function to all results."""
+    paren = func_str.find("(")
+    if paren == -1:
+        # Shorthand without parens — e.g. "trim"
+        name = func_str.strip()
+        args_str = ""
+    else:
+        name = func_str[:paren].strip()
+        end = func_str.rfind(")")
+        args_str = func_str[paren + 1: end if end != -1 else len(func_str)]
+
+    if name == "normalize-space":
+        return [re.sub(r"\s+", " ", s).strip() for s in results]
+
+    if name == "trim":
+        return [s.strip() for s in results]
+
+    if name == "uppercase":
+        return [s.upper() for s in results]
+
+    if name == "lowercase":
+        return [s.lower() for s in results]
+
+    if name == "substring":
+        args = [a.strip() for a in args_str.split(",")]
+        if len(args) >= 2:
+            try:
+                start, length = int(args[0]), int(args[1])
+                return [s[start: start + length] for s in results]
+            except ValueError:
+                return results
+        return results
+
+    if name == "substring-after":
+        delim = args_str.strip().strip("\"'")
+        out = []
+        for s in results:
+            idx = s.find(delim)
+            out.append(s[idx + len(delim):] if idx != -1 else "")
+        # Filter out empty results (matches Rust behavior)
+        return [r for r in out if r]
+
+    if name == "substring-before":
+        delim = args_str.strip().strip("\"'")
+        out = []
+        for s in results:
+            idx = s.find(delim)
+            out.append(s[:idx] if idx != -1 else s)
+        return out
+
+    if name == "replace":
+        args = _parse_two_string_args(args_str)
+        if args:
+            find, repl = args
+            return [s.replace(find, repl) for s in results]
+        return results
+
+    if name == "get-attr":
+        # Handled specially by the CSS engine — pass through here
+        # (the attr name is extracted at the engine level)
+        return results
+
+    # Unknown function — skip silently
+    return results
+
+
+def _parse_two_string_args(args_str: str) -> Tuple[str, str] | None:
+    """Parse ``'find', 'replace'`` from an argument string."""
+    # Match 'x', 'y' or "x", "y"
+    m = re.match(r"""['"](.*?)['"],\s*['"](.*?)['"]""", args_str.strip())
+    if m:
+        return m.group(1), m.group(2)
+    return None